GeezerVison

  ██╗     ██╗██████╗  ██████╗ ██████╗ ██████╗ ███████╗
  ██║     ██║██╔══██╗██╔════╝██╔═══██╗██╔══██╗██╔════╝
  ██║     ██║██████╔╝██║     ██║   ██║██║  ██║█████╗
  ██║     ██║██╔═══╝ ██║     ██║   ██║██║  ██║██╔══╝
  ███████╗██║██║     ╚██████╗╚██████╔╝██████╔╝███████╗
  ╚══════╝╚═╝╚═╝      ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝

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

lipcode --update

Quick Start

lipcode

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

If lipcode saves you time, star the repo ⭐

Website · Releases · Report an Issue

GeezerVison

Latest commit

History

Folders and files

Repository files navigation