rust-code: Instructions file for Claude Code

CLAUDE.md — rust-code

AI-powered terminal coding agent written in Rust.

Stack

• Rust (Edition 2024), Tokio async runtime
• Ratatui + Crossterm (TUI), tui-textarea (input)
• sgr-agent (LLM client + agent framework + session + tools + providers)
• Nucleo (fuzzy search, from Helix editor)
• rmcp (MCP client — Model Context Protocol)
• tmux (background task execution)

Architecture

• crates/sgr-agent-core/ — minimal core: Tool trait, FileBackend trait, AgentContext (typed store), ToolError (5 variants), schema (6 deps)
• crates/sgr-agent-tools/ — 14 tools + LocalFs + MockFs, generic over FileBackend trait (shell, apply_patch, indentation read, eval)
• crates/sgr-agent/ — LLM client + agent framework + session/memory/providers/OpenAPI (re-exports core + tools)
• crates/rc-cli/ — main binary: TUI (app.rs), headless mode (main.rs), agent loop (agent.rs), 27 tools (backend.rs + tools/)
• crates/sgr-agent-tui/ — shared TUI shell: chat panel, streaming, agent loop integration, fuzzy picker
• crates/solograph/ — MCP server for code intelligence
• crates/genai/ — local fork of rust-genai (multi-provider LLM client: Gemini, OpenAI, Anthropic, Ollama, etc.)

Crate dependency graph

sgr-agent-core 0.2      <- Tool, FileBackend, AgentContext (typed store), ToolError (6 deps)
    ^              ^
sgr-agent-tools    sgr-agent 0.7
0.4                LLM framework + parallel tool execution
14 tools +         re-exports core + optional tools
LocalFs + MockFs        ^
                   rc-cli, agent-bit, souffleur, video-analyzer

Agent loop: user message → Agent::decide() → model returns Decision { situation, task, tool_calls } → execute tools → feed result back → repeat until finish_task or completion.

sgr-agent Framework

• Core (sgr-agent-core): Tool trait, ToolOutput, ToolError, AgentContext, ToolDef, json_schema_for
• Tools (sgr-agent-tools, or sgr-agent feature "tools"): 14 file-system tools generic over FileBackend:
  • Core: ReadTool (+ indentation mode), WriteTool (JSON repair), DeleteTool (batch), SearchTool (smart), ListTool, TreeTool, ReadAllTool
  • Deferred: MkDirTool, MoveTool, FindTool
  • Optional: EvalTool ("eval"), ShellTool ("shell"), ApplyPatchTool ("patch" — Codex-compatible diff DSL)
  • All-in-one: "tools-all" enables eval + shell + patch
• LLM Client: GeminiClient, OpenAIClient — structured output + function calling + flexible parse
• Agent framework (feature = "agent"):
  • Tool trait → ToolRegistry (builder, case-insensitive lookup, fuzzy resolve)
  • Agent trait → Decision { situation, task, tool_calls, completed }
  • 6 variants: SgrAgent (structured output), ToolCallingAgent (native FC), FlexibleAgent (text parse), HybridAgent (2-phase), Clarification, Planning
  • run_loop() — generic agent loop with 4-tier loop detection
  • ToolFilter — progressive discovery (keyword + fuzzy scoring)
• Session (feature = "session"): Session, LoopDetector (4-tier), MemoryContext, hints, tasks, intent guard
• App tools (feature = "app-tools"): bash, fs, git, apply_patch
• OpenAPI (always available): parse any OpenAPI 3.x spec → fuzzy search endpoints → HTTP call
  • ApiRegistry — load multiple APIs, search across all, call by endpoint name
  • 10 popular APIs pre-configured: github, stripe, openai, supabase, posthog, slack, linear, cloudflare, vercel, sentry
  • APIs.guru fallback — 2800+ APIs searchable by name
  • Auto-cache specs to ~/.sgr-agent/openapi-cache/, auto-detect auth from env vars
  • $ref resolution for parameters and schemas, path-level param inheritance
• Providers (feature = "providers"): TOML config, auth, CLI proxy, Codex proxy
• Telemetry (feature = "telemetry"): OTEL file telemetry
• Llm (feature = "genai"): provider-agnostic LLM facade — LlmConfig::auto("gpt-4o") / LlmConfig::endpoint(key, url, model)
• Demo: cargo run -p sgr-agent --features agent --example agent_demo
• Tests: cargo test -p sgr-agent --all-features — 510+ tests (sgr-agent), 82 tests (sgr-agent-tools), 15 tests (sgr-agent-core)