"Right away, Guv'nor."
A blazingly fast, 100% Rust-native AI coding agent built for your terminal.
GuvCode acts as your hyper-competent right-hand fixer, designed to parse massive codebases instantly, plan architectures, and surgically apply AST-aware code edits. No single-prompt guessing. No memory crashes. Just pure, multi-model vibecoding.
- Why GuvCode?
- Features
- Getting Started
- Usage
- Supported Models & Providers
- Web Dashboard
- Project Structure
- Contributing
- License
Current terminal-based AI agents suffer from their underlying runtimes. We built GuvCode to solve three major pain points:
| Constraint | The Problem (Other Agents) | The GuvCode Solution | Impact |
|---|---|---|---|
| Memory | Node.js/V8 heap limits cause Out-Of-Memory (OOM) crashes on large codebases. | Rust-native memory management. No garbage collection overhead. | Ingests massive enterprise codebases without crashing. |
| Concurrency | Python's GIL blocks true parallelism, making AST parsing and file searching sluggish. | Multithreaded execution. Uses ripgrep-style directory walking. |
Maps 10,000+ files in milliseconds. Starts in 0.001s. |
| Distribution | Python agents force users into dependency hell (pipx, venv, conflicting system libraries). |
Statically compiled. Distributed as a single, self-contained executable. | Zero dependencies. Installs and runs instantly. |
| Cost | Vendor lock-in forces using expensive "God Models" for simple search tasks, burning cash. | Multi-Agent Routing. Low-cost high-context models search; high-reasoning models code. | Maximizes API budget efficiency and prevents rate limits. |
GuvCode is distributed as a single, statically linked Rust binary.
| Category | Feature | Mechanism | Benefit |
|---|---|---|---|
| Performance | 🚀 Blazing Fast Execution | Pure Rust, multi-threaded codebase architecture. | Zero bloat, zero OOMs, and instant startup times. |
| Intelligence | 🧠 Multi-Agent Routing | Delegates tasks to Scout, Coder, Architect, and Reviewer models. | Cost-effective, specialized, and highly accurate code generation. |
| Integrity | 🌳 Bulletproof AST Diffs | Native tree-sitter bindings parse code syntax structurally. |
LLM logic is surgically injected without breaking formatting or indentation. |
| Safety | 🛡️ Git-Safe & Budgeted | Auto-commits before edits and strictly enforces hard token limits. | Instant guv undo rollback and zero risk of runaway loop billing. |
| Privacy | 🔒 BYOK (Bring Your Own Key) | Local configuration via TOML. No external proxy servers or middle-men. | You completely own your data, your API keys, and your usage budget. |
Stop wrestling with dependencies and start vibing.
- A terminal. That's it. (If building from source, you'll need the Rust toolchain).
Option 1: Quick Install (Recommended)
curl -fsSL https://bit.ly/install-guv | bashOption 2: Install via Cargo
cargo install guv-codeHand Guv your keys (BYOK). Your keys are stored locally and securely.
guv auth set --provider google "AIZA..."
guv auth set --provider anthropic "sk-ant..."Tell GuvCode what you need to be done. It will automatically scout the codebase, formulate a plan, and execute the changes.
guv "Refactor the auth middleware in src/ to use JWTs instead of sessions."Click to see more commands
Set a session budget:
guv budget set $5Undo the last AI edit:
guv undoStart an interactive chat session:
guv chatGuvCode strictly enforces BYOK (Bring Your Own Key). You configure your providers, and GUV automatically routes tasks to the best-suited model.
| Provider | Recommended Model | Internal Agent Role | Why We Use It |
|---|---|---|---|
gemini-2.5-pro / flash |
The Scout | Massive 2M+ token context window. Best for ingesting the entire codebase index and pinpointing relevant files instantly. | |
| Anthropic | claude-3-opus / 3.7-sonnet |
The Coder | Industry-leading deep reasoning and precise AST-aware diff generation. |
gemini-3.1-pro |
The Architect | High-level system design, multi-file execution planning, and complex refactoring logic. | |
| OpenAI | o3 / gpt-4o |
The Coder (Fallback) | General purpose execution and syntax writing. |
| Local | qwen-2.5-coder (via Ollama) |
The Reviewer | Fast, free, local syntax validation and post-edit linting. |
(See MODELS.md for instructions on adding new providers and adjusting routing weights).
GuvCode includes a web dashboard for managing your account, API keys, and usage quotas. It is not a code editor — the CLI is the coding interface.
The dashboard is a Next.js 16 app located in the web/ directory.
Running locally:
cd web
bun install
bun run dev
# → http://localhost:3000See the Web Dashboard README for more details.
guv-code/
├── src/ # Rust CLI agent source
│ ├── main.rs # CLI entrypoint (clap)
│ ├── llm.rs # LLM provider routing & streaming
│ ├── orchestrator.rs # Multi-agent task orchestration
│ ├── index.rs # Fast-resume codebase indexer
│ ├── config.rs # TOML config & API key management
│ ├── git.rs # Git auto-commit & undo
│ ├── agent_logic/ # Scout, Architect, Coder, Reviewer logic
│ └── ui/ # TUI with ratatui
├── web/ # Next.js web dashboard
├── Cargo.toml # Rust dependencies
├── MODELS.md # Model routing docs
└── CONTRIBUTING.md # Contributor guide
We welcome contributions! Want to help make the Guv'nor even better? Check out our Contribution Guidelines to get started.
This project is licensed under the MIT License - see the LICENSE file for details.
