README.md

metadata

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 (2.17 GB).

Inspired by 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.
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

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).