██╗ ██╗██████╗ ██████╗ ██████╗ ██████╗ ███████╗
██║ ██║██╔══██╗██╔════╝██╔═══██╗██╔══██╗██╔════╝
██║ ██║██████╔╝██║ ██║ ██║██║ ██║█████╗
██║ ██║██╔═══╝ ██║ ██║ ██║██║ ██║██╔══╝
███████╗██║██║ ╚██████╗╚██████╔╝██████╔╝███████╗
╚══════╝╚═╝╚═╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝
A coding agent that lives in your terminal. Local-first. Zero config.
Install · Quick Start · How It Works · Docs
The Pitch
- $ open claude.ai
- $ paste your code
- $ copy the response
- $ paste it back
- $ debug why it broke
+ $ lipcode
+ > fix the race condition in src/pool.rs
+ ● file_read — src/pool.rs (142 lines)
+ ● file_edit — wrapped counter access in Mutex
+ ● bash — cargo test --lib pool
+ Done. 3 tests pass. Fixed in src/pool.rs:67.
lipcode is a coding agent, not a chatbot. It reads your files, edits code, runs tests, and iterates on errors — all without leaving your terminal and without your code ever touching a cloud API.
Install
One-liner (Linux / macOS)
curl -fsSL https://raw.githubusercontent.com/jongha/lipcode/main/install.sh | bash
From Source
git clone https://github.com/jongha/lipcode.git
cd lipcode && cargo build --release
cp target/release/lipcode ~/.local/bin/
Update in place
Quick Start
That's it. On first launch:
- Ollama is detected (or started if installed)
- The default model (
qwen3-coder:30b-a3b-q4_K_M) is pulled with a live progress bar
- The TUI opens — your coding agent is ready
Don't have Ollama? Install it first — or set OPENROUTER_API_KEY to use cloud models instead.
Why lipcode?
|
lipcode |
Cursor / Copilot |
ChatGPT / Claude.ai |
| Runs 100% locally |
✅ |
❌ |
❌ |
| Your code never leaves your machine |
✅ |
❌ |
❌ |
| Reads your filesystem autonomously |
✅ |
✅ |
❌ |
| Edits files and runs tests |
✅ |
✅ |
❌ |
| Single binary, <20ms startup |
✅ |
❌ |
❌ |
| Free to run |
✅ |
❌ |
❌ |
| Works offline |
✅ |
❌ |
❌ |
| Cloud fallback available |
✅ |
✅ |
— |
What makes it different
- Local-first by design. The default model runs on your machine via Ollama. No API keys, no credit card, no data leaving localhost. Cloud providers are purely opt-in.
- Cost-aware routing. When you do add cloud providers, lipcode estimates task complexity and picks the cheapest model that fits. Simple questions hit Light models; complex refactors get routed to Heavy.
- Real multi-agent orchestration. An orchestrator analyzes your request and delegates to specialized sub-agents —
coder (writes), explorer (reads), oracle (advises) — each with scoped tools and permissions.
- Safety baked in.
rm -rf /, git push --force, chmod 777 — auto-blocked via regex. Writes outside your project directory — denied. Everything else asks before running.
- Rust, single binary. No Node, no Python, no Docker. One executable. Under 20ms cold start.
How It Works
┌────────────────────────────────────────────────────────────────────┐
│ User types: "add error handling to src/config.rs" │
└────────────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────┐
│ CostAwareRouter │
│ ├─ Estimates complexity: Medium │
│ ├─ Tries Medium-tier candidates → falls back to Light if needed │
│ └─ Picks cheapest: qwen3-coder (local, $0.00) │
└────────────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────┐
│ Orchestrator │
│ └─ delegate(agent: "coder", task: "add error handling to ...") │
└────────────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────┐
│ Coder agent — tool-use loop │
│ ├─ file_read src/config.rs (with line numbers) │
│ ├─ file_edit wrap parse() in Result │
│ ├─ file_edit add thiserror variants │
│ └─ bash cargo check │
└────────────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────┐
│ Result streams back to the TUI in real time │
└────────────────────────────────────────────────────────────────────┘
Every step is visible. Every file write asks permission. Every dangerous command is blocked.
Configuration
Local (Ollama) — default
# Optional overrides
export OLLAMA_MODEL="qwen3-coder:30b-a3b-q4_K_M"
export OLLAMA_HOST="http://localhost:11434"
Cloud (OpenRouter) — optional
export OPENROUTER_API_KEY="sk-or-..."
Or persist in ~/.config/lipcode/credentials.toml:
[openrouter]
api_key = "sk-or-..."
More providers coming. Anthropic, OpenAI, Google, and additional OpenAI-compatible backends are in active development. Provider work is ongoing — expect new backends to land regularly.
Settings
- Global:
~/.config/lipcode/config.toml
- Per-project:
.lipcode/config.toml (overrides global)
providers = ["openrouter"]
Keyboard Shortcuts
| Key |
Context |
Action |
Enter |
Input |
Submit message |
Ctrl+C / Esc |
Running |
Cancel LLM request |
Ctrl+C |
Input |
Clear input (twice to quit) |
Ctrl+D |
Input |
Quit (if empty) |
↑ / ↓ |
Input |
History navigation |
Ctrl+U |
Input |
Clear line |
Project Structure
lipcode/
├── src/
│ ├── main.rs CLI entry (clap)
│ ├── self_update.rs --update: self-updater via GitHub Releases
│ ├── types.rs Message, ContentBlock, Role
│ │
│ ├── cli/
│ │ ├── tui.rs Ratatui event loop + Ollama pull progress
│ │ ├── repl.rs Provider loader
│ │ └── history.rs Input history
│ │
│ ├── agent/
│ │ ├── core.rs Agent loop: stream → tools → execute → repeat
│ │ ├── role.rs Orchestrator / Coder / Explorer / Oracle
│ │ ├── event.rs AgentEvent enum
│ │ └── conversation.rs In-memory message history
│ │
│ ├── pipeline/
│ │ ├── router.rs CostAwareRouter (tier → model selection + fallback)
│ │ ├── permission.rs Trusted dirs + dangerous pattern blocklist
│ │ └── budget.rs Token / cost accounting
│ │
│ ├── provider/
│ │ ├── traits.rs LlmProvider trait
│ │ ├── types.rs ModelInfo, ModelTier, StreamEvent
│ │ ├── openai_compat.rs Shared OpenAI-compatible SSE client
│ │ ├── ollama.rs Ollama (auto-setup + pull progress streaming)
│ │ └── openrouter.rs OpenRouter (cloud, multi-model)
│ │
│ └── tools/
│ ├── traits.rs Tool trait + ToolResult
│ ├── executor.rs Parallel reads, sequential writes
│ ├── file_read.rs Line-numbered read with offset/limit/truncation
│ ├── file_write.rs Create new files
│ ├── file_edit.rs Find-and-replace with uniqueness check
│ ├── bash.rs Shell commands with timeout
│ ├── grep.rs Content search (rg/grep)
│ ├── glob.rs File pattern matching
│ └── list_dir.rs Directory listing
│
├── docs/
│ └── index.html GitHub Pages landing page
├── install.sh curl | bash installer
├── Cargo.toml
└── LICENSE
Design Principles
| Choice |
Rationale |
| Rust, single binary |
<20ms startup, no runtime deps, one file to distribute |
| Ollama as default |
Privacy, zero cost, works offline, no API keys |
| OpenAI-compatible layer |
One client covers Ollama + OpenRouter + any compatible provider |
| Tier fallback chain |
Ollama-only setups still work for Medium/Heavy tasks |
| Read-only tools run in parallel |
grep + glob + file_read execute concurrently; writes serialize |
| file_edit requires unique match |
Prevents silent corruption when old_string is ambiguous |
| Line numbers in file_read |
LLM can cite exact line numbers when editing |
| Regex blocklist, not allowlist |
Blocks known-dangerous patterns; everything else asks |
| Streaming everywhere |
Text appears as the LLM generates it |
Roadmap
lipcode is under active development. Current focus areas:
- More providers — Anthropic, OpenAI, Google Gemini, and other OpenAI-compatible backends are being added.
- Expanded tool set — more language-aware tools and editor integrations.
- Agent improvements — smarter delegation, better context management.
PRs and issue reports for new providers are especially welcome.
Requirements
- Ollama — recommended, for local inference
- Rust 1.75+ — only for building from source
- OpenRouter API key — optional, for cloud models
Contributing
Issues and PRs welcome. Before submitting:
cargo fmt
cargo clippy
cargo test
License
MIT © Jong-Ha Ahn