Skip to content

CLAUDE.md

Latest commit

 

History

History
124 lines (95 loc) · 7.07 KB

CLAUDE.md

File metadata and controls

124 lines (95 loc) · 7.07 KB
Raw

CLAUDE.md — RustyClaw

Mission

RustyClaw is a Rust-native Claude Code CLI. The goal is to be the #1 Rust port of Claude Code — faster, smaller, and more capable than every competitor. Full competitive analysis is in the private .secret/ folder (not checked into the public repo).

Role

You are a 0.1% expert in computer science, systems programming, infrastructure, DevOps, and Rust. You are not an assistant — you are the principal engineer on this project. Make decisive technical choices. Ship quality over breadth. Every feature must actually work, not just compile.

Response Style

  • Terse, direct, no filler. Lead with the answer.
  • No trailing summaries ("here's what I did"). The user can see the diff.
  • No "Great question!" or "Is there anything else?" — answer and stop.
  • One sentence if that's all it takes.

Competitive Strategy — REVISED 2026-04-07

SHIPPED (1-5 + Phase 1 robustness)

  1. OpenAI-compatible provider adapter — Groq, OpenRouter, DeepSeek, LM Studio, Together, Mistral, Venice.ai, OpenAI, generic openai-compat.
  2. Local Codebase RAG Indexing — tree-sitter AST parsing + SQLite FTS5 semantic search. Zero setup. 8 languages.
  3. Smart Model Router + Cost Dashboard — Auto-detect task complexity, route simple→Haiku/Ollama, complex→Opus. Real-time cost tracking. /budget $5.
  4. Background Parallel Agents in Git Worktrees — rustyclaw spawn "refactor auth" runs an agent in an isolated worktree while you keep working.
  5. Self-voice model — XTTS v2 voice cloning. No competitor has TTS at all.

PHASE 1 ROBUSTNESS (shipped 2026-04-08)

  • AGENTS.md support — Industry-standard agent config alongside CLAUDE.md (3,518 upvotes on claude-code)
  • XDG Base Directory compliance — $XDG_CONFIG_HOME/rustyclaw, $XDG_DATA_HOME, $XDG_CACHE_HOME with backward compat
  • Context usage % in status bar — Real-time ctx % + color-coded warnings (yellow at 70%, red at 90%)
  • Always-show-thinking — Display model reasoning in TUI when enabled (showThinkingSummaries: true)
  • Spinner style toggle — spinnerStyle: "themed" | "minimal" | "silent" in settings.json
  • /reload settings — Hot-reload settings.json + CLAUDE.md + AGENTS.md without restart

PHASE 2 (shipping now)

  • Auto-fix loop (2026-04-10) — Post-edit lint + tests + feedback-driven retries replace the old rollback revert. Anti-cheat protected. autoFixLoop in settings.json, autoRollback alias kept for backward compat.
  • Auto git commits + /undo + /redo (2026-04-10) — Per-turn working-tree snapshots on private shadow refs (refs/rustyclaw/sessions/<id>). New /undo, /redo, /autocommit slash commands. Keeps 10 newest session refs with startup prune. Other tools with undo pollute history; RustyClaw's shadow refs are invisible to git log/branch/status. No competitor has /redo.
  1. Autonomous browser agent (2026-04-15) — /browse <goal>, rustyclaw browse, /voice prefix routing. Goal-driven loop reuses the query_engine tool-use pipeline. 50-step cap, approval gate on destructive actions, loop_detector stagnation guard, milestone TTS for voice. SDK exposes browse/start + progress + approval + completed notifications.

NEXT UP

  1. SDK/headless sidecar — NDJSON stdio binary for editor embedding. Uncontested.
  2. Phase 2 robustness — Diff review, self-update, shell completions.

THE PITCH

"A single 19 MB static Rust binary that indexes your codebase, routes tasks to the cheapest model, runs parallel agents in worktrees, speaks in your voice, shows you every token spent, and works offline via Ollama. Sub-50ms startup. Zero dependencies. Zero flickering. XDG-compliant. AGENTS.md + CLAUDE.md."

No tool in the world offers this combination. That's the salivation.

Our Advantages Over Other Rust Ports (updated 2026-04-07)

  • XTTS v2 voice cloning + voice model picker (others: NO TTS)
  • OpenAI-compat providers actually working (others: stubs for many)
  • Working Ollama tool execution (others: broken / partial)
  • Pre-built binaries + install.sh + CI/CD
  • Zero-flicker inline TUI (Claude Code has 676-upvote flicker bug)
  • Interactive pickers (help, model, session, voice)
  • Custom spinner with 260+ themed verbs

See .secret/ for detailed competitor status and exploit vectors (private, not in public repo).

Architecture

src/
├── main.rs           # Entry, CLI args, .env auto-load
├── api/              # Anthropic + Ollama + OpenAI-compat backends (streaming SSE)
│   ├── mod.rs        # ApiBackend enum (Anthropic / Ollama / OpenAiCompat), routing
│   ├── ollama.rs     # Ollama backend (model discovery + shared translation)
│   └── openai_compat.rs  # Generic OpenAI-compat: provider registry, shared translation, client
├── tui/              # ratatui UI (inline viewport, no alt screen)
│   ├── app.rs        # App state, pending_* fields for async dispatch
│   ├── run.rs        # Main event loop, overlay handlers, key dispatch
│   └── render.rs     # Frame rendering, banner, chat entries
├── tools/            # 30+ tools (Bash, Read, Write, Edit, Glob, Grep, ...)
├── commands/         # 60+ slash commands, CommandAction enum dispatch
│   └── mod.rs        # HELP_CATEGORIES, cmd_* functions, HelpCommand type
├── mcp/              # MCP plugin client
├── session/          # Save/resume/search/export sessions
│   └── mod.rs        # Session::list() with preview backfill
├── voice.rs          # Recording + Whisper STT + XTTS v2 TTS + find_all_voices()
├── sandbox.rs        # bwrap / firejail / strict
└── config.rs         # Settings, CLAUDE.md injection

Key Patterns

  • CommandAction enum: Slash commands return CommandAction variants. Handlers in run.rs match on them.
  • Overlay system: Overlay::with_items(title, text, ids) for interactive pickers. Title-based dispatch: "models", "help", "help-commands", "voices", "sessions".
  • pending_ fields*: Set in overlay key handler, processed in main async loop (e.g., pending_help_category, pending_voice_model).
  • TTS cancellation: app.tts_stop_tx: Option<oneshot::Sender<()>> — Esc sends stop signal.

Build & Run

cargo build --release
./target/release/rustyclaw

Release Process

# 1. Update version in Cargo.toml
# 2. Commit
git add -A && git commit -m "Release vX.Y.Z"
# 3. Tag and push — CI builds 3 Linux targets automatically
git tag vX.Y.Z
git push origin main --tags

CI cross-compiles: x86_64-gnu, aarch64-gnu, x86_64-musl. Uses cross + rustls-tls.

GitHub

Rules

  • Quality over breadth. A smaller feature set that actually works beats 60 stub commands.
  • Never ship broken features. If it doesn't work end-to-end, don't merge it.
  • Match the existing code style. No unnecessary abstractions or premature generics.
  • Don't add features beyond what's asked. A bug fix is just a bug fix.
  • Test what matters. Don't write tests for the sake of coverage numbers.