README.md

---
title: SoniCoder
emoji: 🚀
colorFrom: purple
colorTo: green
sdk: gradio
sdk_version: 6.14.0
python_version: '3.11'
app_file: app.py
pinned: false
hf_oauth: true
hf_oauth_scopes:
  - read-repos
  - write-repos
  - manage-repos
---

## SoniCoder

An AI-powered **autonomous coding agent** running entirely locally with no external API dependencies. Powered by [MiniCPM5-1B](https://huggingface.co/openbmb/MiniCPM5-1B) (2.17 GB).

Inspired by [Claude Code](https://github.com/anthropics/claude-code), SoniCoder adds:

- 🤖 **Agent Loop** — model calls tools (read/write/edit/glob/grep/bash/todos) in a feedback loop
- 🎯 **Skills System** — load markdown skill files at runtime (frontend-design, feature-dev, code-review, debugging, fullstack-scaffold, commit-workflow)
- ⚡ **Slash Commands** — `/commit`, `/review`, `/feature`, `/design`, `/explain`, `/test`, `/refactor`, `/skill`, `/agent`, `/github`, `/help`
- 🧠 **Custom Agents** — describe a specialized agent in natural language and the AI generates a full persona (system prompt + tool whitelist + auto-loaded skills + temperature + max iterations). Activate via `/agent use <name>` or the Agents panel. Built-ins: `code-reviewer`, `test-writer`.
- 📥 **GitHub Import** — paste any GitHub URL (or use `/github <url>`) to shallow-clone a repo into the workspace. Heavy dirs (`.git`, `node_modules`, `__pycache__`, `.venv`, `dist`) are stripped automatically. Supports `branch`, `subdir`, and `target_subdir` options.
- 📦 **GitHub Push** — push the current workspace to any GitHub repo with just 3 inputs: repo name, GitHub API token, and username. Uses `--force-with-lease` so the workspace is the source of truth. Available in the Deploy tab.
- 🪝 **Hooks System** — pre/post tool execution rules (block dangerous commands, warn on debug code/secrets)
- 📁 **Sandboxed Workspace** — agent manipulates files in `./workspace/` (path-escape protected)
- ✅ **Todo Lists** — track multi-step tasks Claude Code-style
- 🚀 **HuggingFace Deploy** — push generated projects directly to HuggingFace Spaces

### Features (original)

- **Local Inference**: MiniCPM5-1B via `transformers` — no API keys
- **Multi-Language**: Python, JavaScript, TypeScript, Java, Go, Rust, PHP, Ruby, C#, Swift, Kotlin
- **Frameworks**: React, Vue, Next.js, Express, Flask, Django, FastAPI, Spring Boot, and more
- **Live Preview**: sandboxed iframe preview of generated web apps
- **Code Execution**: run generated Python and see output
- **Project Download**: ZIP the generated project
- **HuggingFace Deploy**: one-click push to HF Spaces (Static/Gradio/Streamlit/Docker)

### Supported Languages & Frameworks

| Language | Frameworks |
|----------|-----------|
| Python | Flask, Django, FastAPI, Streamlit, Gradio, Plain Python |
| JavaScript | React, Vue.js, Next.js, Express.js, Node.js, Vanilla JS |
| TypeScript | React, Next.js, Express.js, NestJS |
| HTML/CSS/JS | Tailwind CSS, Bootstrap, Vanilla |
| Java | Spring Boot, Maven, Gradle |
| Go | Gin, Fiber, Echo, Plain Go |
| Rust | Actix, Axum, Rocket |
| PHP | Laravel, Symfony, Plain PHP |
| Ruby | Rails, Sinatra |
| C# | ASP.NET, Blazor |
| Swift | Vapor, SwiftUI |
| Kotlin | Ktor, Spring Boot |

### Agent Tools

The agent can call these tools (Claude Code-style):

| Tool | Description |
|------|-------------|
| `read_file` | Read a file from the workspace |
| `write_file` | Write content to a file |
| `edit_file` | Replace text in a file (with uniqueness check) |
| `multi_edit` | Apply multiple edits atomically |
| `list_dir` | List directory contents |
| `glob` | Find files matching a pattern |
| `grep` | Search file contents with regex |
| `bash` | Run a shell command (sandboxed) |
| `todo_write` | Replace the todo list |
| `todo_read` | Read the current todo list |
| `todo_update` | Update a single todo |

### Slash Commands

| Command | Description |
|---------|-------------|
| `/commit [msg]` | Create a git commit with a generated message |
| `/review [file]` | Review changes for bugs and quality |
| `/feature <desc>` | Guided feature development |
| `/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 a natural-language description** |
| `/agent use <name>` | Activate a saved agent for subsequent prompts |
| `/agent list` | List all saved agents |
| `/agent show <name>` | Display 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** (shallow clone, heavy dirs stripped) |
| `/help` | Show available commands and skills |

### GitHub Import

SoniCoder can clone any public GitHub repository into the sandboxed workspace so the agent can read, edit, extend, or refactor it. Imported repos are shallow-cloned (depth 1) and stripped of heavy directories (`.git`, `node_modules`, `__pycache__`, `.venv`, `dist`, `build`, etc.) to keep the workspace lean.

**Accepted URL formats:**

- `https://github.com/<owner>/<repo>`
- `https://github.com/<owner>/<repo>.git`
- `https://github.com/<owner>/<repo>/tree/<branch>` — checkout a specific branch
- `https://github.com/<owner>/<repo>/tree/<branch>/<subdir>` — import only a sub-directory
- `git@github.com:<owner>/<repo>.git` — SSH form (rewritten to HTTPS internally)

**Two ways to import:**

1. **Via the Agent tab UI**: Open the **Agent** tab, paste the GitHub URL into the "Import Project from GitHub" box at the top, optionally specify `branch`, `subdir`, or `into path`, then click **⬇ Import**. The workspace tree and todo list refresh automatically, and agent mode is enabled if it wasn't already.
2. **Via the `/github` slash command** (Agent mode): Type `/github https://github.com/owner/repo` in chat. The agent runs the import, lists the top-level files, and suggests next steps. Flags: `--branch <name>`, `--into <path>`, `--depth <N>`.

**Examples:**

```
/github https://github.com/fastapi/fastapi
/github https://github.com/vercel/next.js examples/with-typescript --into next-ts-demo
/github https://github.com/pallets/flask --branch 2.3.x
```

**API endpoints:**

| Endpoint | Description |
|----------|-------------|
| `import_github(url, branch, subdir, target_subdir, depth, timeout)` | Clone a GitHub repo into the workspace |
| `github_url_examples()` | Return accepted URL formats and notes |

**Security:** Only `github.com` URLs are accepted (HTTPS or SSH form). The clone happens in a temp directory and is then *copied* into the workspace — the upstream repo is never modified. Path-escape protection on `target_subdir` prevents writing outside the workspace.

### GitHub Push (Update a GitHub repo)

Push the current SoniCoder workspace back to a GitHub repo as a commit. Designed to be minimal — only **3 required inputs**:

1. **Repository name** — either `my-app` (combined with your username) or `username/my-app`.
2. **GitHub API token** — a Personal Access Token (PAT) with `repo` scope. [Create one here](https://github.com/settings/tokens/new?scopes=repo&description=SoniCoder).
3. **Username** — the GitHub user (or org) that owns the repo and matches the token.

**How to use:**

1. Open the **Deploy** tab.
2. Scroll to the **"Push Update to GitHub"** section (below the HuggingFace section).
3. Fill in the 3 required fields (optionally expand "Advanced" to set `branch` or `commit message`).
4. Click **📦 Push to GitHub**. A confirmation dialog shows the target repo + branch.
5. On success, the status box shows the commit SHA, commit URL, and repo URL.

**How it works (under the hood):**

1. The workspace is snapshotted (via `snapshot_workspace()` — same function used for HuggingFace deploy).
2. A fresh git repo is created in a temp dir; the snapshot files are written in.
3. `git init -b <branch>` → `git add -A` → `git commit -m <message>`.
4. `git push --force-with-lease https://<username>:<token>@github.com/<owner>/<repo>.git <branch>`.
5. If `--force-with-lease` fails because the remote has no refs yet (brand-new empty repo), it retries with a plain `git push`.
6. The temp dir is deleted. The token is never logged; error messages scrub it before being returned to the UI.

**API endpoint:**

| Endpoint | Description |
|----------|-------------|
| `push_github(repo_name, github_token, username, branch?, commit_message?, timeout?)` | Snapshot workspace → commit → push to GitHub |

**Security notes:**

- The 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 to the frontend.
- `--force-with-lease` is used instead of `--force` so the push fails loudly if the remote moved (rather than silently overwriting someone else's commits). For a brand-new empty repo, it falls back to a plain push.
- The push happens from a temp dir — your local SoniCoder workspace is never turned into a git repo, and the workspace's `.git` (if any) is never read.

### Custom Agents

Custom agents are AI-generated personas that layer on top of the base SoniCoder system prompt. Each agent defines:

- A **system-prompt extension** (persona, workflow, output format)
- A **tool whitelist** (e.g. a read-only reviewer gets `read_file`, `grep`, `bash` but not `write_file`)
- **Auto-loaded skills** (e.g. `code-review` for a reviewer agent)
- A **temperature** and **max_iterations** override

**Two ways to create one:**

1. **AI-generated** (recommended): Type `/agent create <natural-language description>` in chat, or use the "AI-Generate a Custom Agent" box in the Agent tab. The model authors an `AGENT.md` file for you.
2. **Manual**: Click "Write manually" in the Agents panel and fill in the fields directly.

**Built-in agents:**

- `code-reviewer` — read-only reviewer that produces a structured issues table
- `test-writer` — generates pytest/jest tests, runs them, and iterates until green

Agent files are saved to `workspace/.sonicoder/agents/<name>/AGENT.md`. Built-ins live in `code/agents/builtins/` and cannot be deleted.

### Built-in Skills

- **frontend-design** — distinctive visual design guidance (palette, typography, signature)
- **feature-dev** — 7-phase guided feature implementation
- **code-review** — high-signal review focusing on bugs and security
- **debugging** — systematic 6-phase debugging workflow
- **fullstack-scaffold** — project structure rules for any framework
- **commit-workflow** — conventional commits best practices

Add custom skills in `workspace/.sonicoder/skills/<name>/SKILL.md`.

### 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()`

Add custom hooks in `workspace/.sonicoder/hooks/<name>.local.md`.

### Local Run

```bash
pip install -r requirements.txt
python app.py
```

The model (MiniCPM5-1B, ~2.17 GB) downloads automatically on first run.

### Project Memory

The `CLAUDE.md` file at the project root is the agent's persistent memory. Edit it freely to override defaults and document project-specific conventions.

### HuggingFace Deploy

1. Generate your application
2. Go to the "Deploy" tab
3. Sign in with HuggingFace OAuth (or paste a token)
4. Select the Space SDK (Auto, Docker, Static, Gradio, Streamlit)
5. Click "Push to HuggingFace"

### No External APIs

This application does not use any external API calls. All model inference runs locally using `transformers` with MiniCPM5-1B. Web search uses DuckDuckGo/Google HTML scraping (no API key).