CLAUDE.md

SoniCoder v2.1 — 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 v2.1 is a local-first AI coding agent that can:

Core Capabilities

• Generate complete fullstack applications in any language/framework
• Read, write, and edit files in a sandboxed workspace
• Run shell commands (git, npm, pip, tests) with enhanced safety
• 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
• Manage and export conversation sessions
• Use code templates for rapid development

v2.1 Enhancements

• Session Management: Persistent conversations with JSON/Markdown/HTML export
• Code Templates: Pre-built templates for Flask, React, Gradio, Express
• Performance: Response caching, model optimization, progress tracking
• Security: Enhanced command blocking, input validation, audit logging
• Metrics: Inference statistics, token counting, performance monitoring
• New Models: DeepSeek-Coder-1.3B support for advanced reasoning

Architecture

app.py                              ← Entry point: launches Gradio Server
code/
├── config/constants.py             ← App config, system prompt, templates (ENHANCED)
├── model/
│   ├── loader.py                   ← Model loading with progress & memory optimization
│   └── inference.py                ← Streaming inference with caching & metrics
├── 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 (ENHANCED - audit trail)
│   ├── 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)
├── 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/
    ├── routes.py                   ← All HTTP + API endpoints
    ├── chat_helpers.py             ← Chat history + prompt building (ENHANCED)
    ├── session_manager.py          ← Session persistence & export (NEW)
    └── __init__.py                 ← Server utilities & helpers
index.html                          ← Frontend (single-file SPA)
workspace/                          ← Sandboxed agent workspace (auto-created)
downloads/                          ← Exported files directory (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.
• Graceful shutdown on SIGTERM/SIGINT

Model Configuration

Model	Type	Size	Best For
Qwen2.5-Coder-1.5B	Text	3.0 GB	Tool-calling, code generation
MiniCPM5-1B	Text	2.17 GB	Fast inference
MiniCPM-V-4.6	VLM	2.8 GB	Image understanding
DeepSeek-Coder-1.3B	Text	2.6 GB	Advanced reasoning

• Default: Qwen/Qwen2.5-Coder-1.5B-Instruct
• Loaded in background thread on startup
• Streaming inference via TextIteratorStreamer
• One model loaded at a time (memory conservation)

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
/github <url> [subdir] [--branch <name>] [--into <path>]	Import a GitHub repo into the workspace
/help	Show available commands and skills

Code Templates

Templates provide quick-start code for common patterns:

Template ID	Name	Language	Framework
python-flask-api	Flask REST API	Python	Flask
react-todo-app	React Todo App	JavaScript	React
gradio-image-app	Gradio Image Processor	Python	Gradio
express-js-server	Express.js Server	JavaScript	Express.js

Access via API: GET /api/templates or GET /api/templates/{id}

Session Management

Sessions are automatically created and persisted:

• Storage: CONFIG_DIR/sessions/*.json
• Auto-save: On each message
• Export formats: JSON, Markdown, HTML
• Cleanup: Sessions older than 30 days are auto-removed

Session API Endpoints

Endpoint	Description
POST /api/sessions/create	Create new session
GET /api/sessions/{id}	Get session details
PUT /api/sessions/{id}	Update session metadata
DELETE /api/sessions/{id}	Delete session
GET /api/sessions	List sessions (with search)
POST /api/sessions/{id}/export	Export session

Performance Features

Response Caching

• Similar prompts are cached for faster responses
• Configurable TTL (default: 5 minutes)
• Automatic cache invalidation
• Cache stats available via /api/cache/stats

Model Optimization

• Automatic precision selection (bfloat16 > float16 > float32)
• Better Transformer structure when available
• Torch compile support (PyTorch 2.0+)
• Memory-efficient loading with offload support

Metrics Tracking

Each inference call tracks:

• Time to first token (TTFT)
• Tokens per second
• Total generation time
• Cache hit/miss status
• Error information

Security Enhancements

Command Safety (Enhanced)

Additional blocked patterns:

• Regex-based pattern matching
• Fork bomb detection (:(){:|:&};:)
• Pipe-to-shell prevention (curl ... | bash)
• Root filesystem protection
• Character validation (null bytes, etc.)

Input Validation

• Maximum prompt length: 10,000 characters
• Maximum file size: 10 MB
• Rate limiting: 30 requests/minute
• Environment variable scrubbing (secrets removal)

Audit Trail

All bash commands are logged with:

• Timestamp
• Full command (truncated to 500 chars)
• Success/failure status
• Return code
• Timeout flag
• Execution duration

Access via: GET /api/audit/log or code.tools.bash.get_command_history()

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)

Testing

Run the test suite:

# Install test dependencies
pip install pytest pytest-cov

# Run tests
pytest tests/ -v --cov=code --cov-report=html

# Run specific test file
pytest tests/test_bash_safety.py -v

Troubleshooting

Common Issues

Model fails to load (OOM)

• Try a smaller model (MiniCPM5-1B)
• Close other applications using GPU memory
• Check available RAM (need ~4GB for text models)

Slow response times

• Enable caching (default: on)
• Use smaller max_tokens for testing
• Consider CPU-only mode if GPU transfer is slow

Commands being blocked

• Review blocked patterns in code/tools/bash.py
• Check hook rules in code/hooks/
• Use /help for allowed operations

Version History

v2.1.0 (Current)

• Added DeepSeek-Coder-1.3B model support
• Implemented session management with persistence
• Added code template system
• Enhanced security with regex-based command blocking
• Added response caching and performance metrics
• Improved error handling and recovery
• Added export functionality (JSON/Markdown/HTML)

v2.0.0

• Initial release with Gradio 6.x architecture
• Multi-model support (Qwen2.5-Coder, MiniCPM5, MiniCPM-V)
• Agent loop with tool calling
• Skills and commands system
• GitHub integration
• HuggingFace deployment