CLAUDE.md

SoniCoder — Project Memory

This file is the project's persistent memory. The agent reads it on every session. Edit it freely — it overrides defaults.

What is SoniCoder?

SoniCoder is a local-first AI coding agent that can:

• Generate complete fullstack applications in any language/framework
• Read, write, and edit files in a sandboxed workspace
• Run shell commands (git, npm, pip, tests)
• Apply specialized skills (frontend-design, feature-dev, code-review, debugging, fullstack-scaffold, commit-workflow)
• Respond to slash commands (/commit, /review, /feature, /design, /explain, /test, /refactor, /skill, /help)
• Deploy to HuggingFace Spaces with one click

Architecture

app.py                          ← Entry point: launches Gradio Server
code/
├── config/constants.py         ← App config, system prompt, language options
├── model/
│   ├── loader.py               ← Dual model loading (text + VLM)
│   └── inference.py            ← Streaming inference (text + VLM)
├── agent/__init__.py           ← Agent loop (model ↔ tools, supports custom agents)
├── tools/
│   ├── fs.py                   ← read_file, write_file, edit_file, glob, grep, list_dir
│   ├── bash.py                 ← Sandboxed shell execution
│   ├── todos.py                ← Todo list management
│   └── github.py               ← GitHub repo import (shallow clone + strip heavy dirs)
├── skills/
│   ├── __init__.py             ← Skill discovery + loading
│   └── builtins/               ← Built-in skills (markdown)
├── agents/                     ← Custom Agent system (AI-generated personas)
│   ├── __init__.py             ← Agent CRUD + system-prompt builder
│   └── builtins/               ← Built-in agents (code-reviewer, test-writer)
├── commands/
│   ├── __init__.py             ← Slash command parser + expander
│   └── builtins/               ← Built-in commands (markdown, includes /agent and /github)
├── hooks/
│   ├── __init__.py             ← Hook rule engine
│   └── builtins/               ← Built-in hook rules (markdown)
├── execution/
│   ├── code_extractor.py       ← Code extraction from model output
│   ├── python_runner.py        ← Sandboxed Python execution
│   └── gradio_runner.py        ← Gradio app subprocess runner
├── huggingface/
│   ├── dockerfile_gen.py       ← Auto Dockerfile/package.json for JS
│   └── push.py                 ← HF Hub push + ZIP packaging
├── websearch/google_scraper.py ← DuckDuckGo + Google scraping (no API)
└── server/
    ├── chat_helpers.py         ← Chat history + prompt building
    └── routes.py               ← All HTTP + API endpoints
index.html                      ← Frontend (single-file SPA)
workspace/                      ← Sandboxed agent workspace (auto-created)

Conventions

• Python: 3.11+, type hints everywhere, from __future__ import annotations
• Style: Black formatting, 4-space indent, 100 char line limit
• Docstrings: Google style for modules, functions, classes
• Error handling: catch specific exceptions, never bare except:
• Logging: use logging.getLogger(__name__), never print()
• Tests: pytest, in tests/ directory, test_*.py naming
• Frontend: single-file HTML with inline CSS/JS, no build step

Server rules

• All servers bind to 0.0.0.0 (never localhost)
• Default port: 7860 (HF Spaces convention)
• Sub-servers use 7861, 7862, etc.

Model

• Default: openbmb/MiniCPM5-1B (text-only, 2.17 GB)
• Optional: openbmb/MiniCPM-V-4.6 (vision + text, 2.8 GB)
• Loaded in background thread on startup
• Streaming inference via TextIteratorStreamer

Tool call format

The model calls tools by emitting fenced code blocks with tool as the language:

read_file
path: src/app.py

Multi-line values use YAML block scalars:

write_file
path: src/new.py
content: |
  import os
  def main():
      pass

Slash commands

Command	Description
/commit	Create a git commit with a generated message
/review	Review current changes for bugs and quality
/feature <desc>	Guided feature development workflow
/design <brief>	Generate a distinctive frontend design
/explain <target>	Explain how code works
/test <target>	Generate tests
/refactor <target>	Refactor code for clarity
/skill <name>	Load and apply a skill
/agent create <desc>	AI generates a custom agent from natural-language description
/agent use <name>	Activate a saved agent
/agent list	List all saved agents
/agent show <name>	Show an agent's full definition
/agent delete <name>	Delete a user-defined agent
/agent reset	Reset to default SoniCoder persona
/github <url> [subdir] [--branch <name>] [--into <path>]	Import a GitHub repo into the workspace
/help	Show available commands and skills

Custom Agents

Custom agents are AI-generated personas layered on top of the base SoniCoder system prompt. They can restrict the tool whitelist, auto-load skills, and override temperature / max-iterations.

Agent file format

Agents live in workspace/.sonicoder/agents/<name>/AGENT.md (built-ins in code/agents/builtins/<name>/AGENT.md). Format:

---
name: my-agent
description: One-line description
tools: read_file, list_dir, grep, bash
skills: code-review
temperature: 0.2
max_iterations: 12
tags: review, quality
author: AI-generated
created: 2026-06-20
---

# My Agent

Full system-prompt extension here. Define the persona, workflow, output format,
and any hard rules.

How /agent create works

1. User runs /agent create a security reviewer that flags hardcoded secrets.
2. The slash-command expansion substitutes AGENT_GENERATION_PROMPT (defined in code/agents/__init__.py) into the prompt.
3. The base SoniCoder model (NOT a custom agent) authors an AGENT.md file via write_file and saves it under .sonicoder/agents/<name>/.
4. The user can then /agent use <name> or click the agent in the UI.

Built-in agents

Agent	Description
code-reviewer	Read-only reviewer, structured issues table output
test-writer	Generates pytest/jest tests, runs them, iterates until green

API endpoints

Endpoint	Description
list_agents	List all agents (builtins + user) and the active one
get_agent(name)	Get a single agent's full definition
save_agent(...)	Create or overwrite a user agent (manual save)
delete_agent(name)	Delete a user agent (built-ins protected)
set_active_agent(name)	Set/clear the active agent for subsequent prompts
import_github(url, branch, subdir, target_subdir, depth, timeout)	Clone a GitHub repo into the workspace (shallow, heavy dirs stripped)
github_url_examples()	Return accepted GitHub URL formats
push_github(repo_name, github_token, username, branch?, commit_message?, timeout?)	Snapshot workspace → commit → push to a GitHub repo

The agent_run endpoint also intercepts /agent use|reset|delete|list and dispatches them directly to the agents module, bypassing the model entirely for instant session-state updates.

GitHub Import

SoniCoder can clone any public GitHub repo into the workspace, allowing the agent to read, edit, extend, or refactor real-world code.

How it works

1. User submits a GitHub URL via the Agent tab UI box (or via /github <url> slash command in chat while Agent mode is ON).
2. The backend (code/tools/github.py::import_github_repo) parses the URL (supports HTTPS, SSH, and /tree/<branch>/<subdir> forms) and validates that the host is github.com.
3. The repo is shallow-cloned (git clone --depth 1 --single-branch) into a temp directory.
4. Files are copied into the workspace (root or target_subdir) with these directories stripped: .git, .hg, .svn, node_modules, __pycache__, .venv, venv, env, .tox, .mypy_cache, .pytest_cache, .ruff_cache, dist, build, .next, .nuxt, .cache, .gradle, target, Pods. .DS_Store and Thumbs.db are also dropped.
5. The workspace tree refreshes; Agent mode auto-enables if it wasn't already.

Security

• Only github.com URLs are accepted (HTTPS or SSH form).
• target_subdir is sanitized — no path escapes.
• The upstream repo is never modified (clone happens in temp dir, then copied). The .git directory is stripped so the agent doesn't walk it.
• Default clone timeout: 120s (UI uses 180s). Max: 600s.

Slash command

/github <url> [subdir] [--branch <name>] [--into <path>] [--depth <N>] [--timeout <s>]

The slash command (defined in code/commands/builtins/github.md) instructs the agent to invoke import_github_repo via bash, then list the top-level files and suggest next steps based on what was imported.

GitHub Push

Push the current workspace back to a GitHub repo as a commit. Only 3 inputs are required: repo name, GitHub token, username.

How it works (code/tools/github.py::push_to_github)

1. Snapshot the workspace via snapshot_workspace() (returns a {relative_path: content} dict).
2. Create a temp dir, git init -b <branch> inside it, write the snapshot files in, git add -A + git commit -m <message>.
3. Build a push URL of the form https://<username>:<token>@github.com/<owner>/<repo>.git and run git push --force-with-lease <url> <branch>.
4. If --force-with-lease fails because the remote has no refs yet (brand-new empty repo), retry with a plain git push.
5. Delete the temp dir. The token is never logged; error messages scrub it before being returned.

Why --force-with-lease

SoniCoder treats the workspace as the source of truth. --force-with-lease replaces the remote tip with the workspace snapshot, but fails loudly (rather than silently clobbering) if someone else pushed commits in the meantime — because the temp repo has no reflog of the remote tip, the lease fails and the user is told to pull first.

UI

Located in the Deploy tab, in a "Push Update to GitHub" section below the HuggingFace section. Only 3 fields are required: repo name, token, username. An "Advanced" <details> exposes optional branch and commit_message fields.

Security

• Token is sent over HTTPS to the SoniCoder backend, used once for the push, then dropped (not stored, not logged).
• Error messages are scrubbed to remove the token before being returned.
• The temp repo is deleted at the end of the call (context manager).
• The local SoniCoder workspace is never turned into a git repo; the workspace's .git (if any, e.g. after an import — though imports strip .git) is never read.

Skills

Skill	Description
frontend-design	Distinctive visual design guidance
feature-dev	Guided feature implementation workflow
code-review	High-signal code review
debugging	Systematic debugging workflow
fullstack-scaffold	Project structure scaffolding rules
commit-workflow	Git commit best practices

Hooks

Hooks are markdown rules that fire on events (bash, file, prompt, stop). They can warn (show a message) or block (prevent the action).

Built-in hooks:

• block-dangerous-rm — blocks rm -rf /, ~, $HOME, ..
• warn-debug-code — warns on console.log, debugger, print, alert
• warn-secrets-in-code — warns on hardcoded API_KEY/SECRET/TOKEN/PASSWORD
• warn-eval-exec — warns on eval() and exec()

Users can add custom hooks in workspace/.sonicoder/hooks/*.local.md.

Workspace

The agent's sandboxed filesystem lives at ./workspace/ (configurable via SONICODER_WORKSPACE env var). All file tools refuse paths that escape this root.

Deploy

Generated projects can be pushed to HuggingFace Spaces via the Deploy tab. Supported SDKs:

• static — HTML/CSS/JS
• gradio — Python Gradio apps
• streamlit — Python Streamlit apps
• docker — JS/TS frameworks (auto-generates Dockerfile + package.json)