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:

```tool
read_file
path: src/app.py
```

Multi-line values use YAML block scalars:

```tool
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:

```bash
# 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