ub

README

A lean, hackable terminal coding agent — written in Go, local-first, every byte on disk.

---

👀 See it

🎯 What it's for

ub is a coding agent that lives entirely in your terminal. It speaks to your favorite LLM provider, runs tools in this directory, and persists every keystroke as a replayable event log. You can read the whole thing end-to-end — agent loop, provider adapters, TUI, MCP, LSP — and bend it to your workflow.

• 🧠 Multi-provider. Anthropic · OpenAI · OpenAI-compat (DeepSeek / Together / vLLM / LiteLLM) · Ollama · plus a script-driven Fake provider that runs CI offline.
• 🛠️ Local tools. Filesystem, search, shell, background jobs, LSP diagnostics, and any MCP server.
• 🛡️ Permission-first. Three execution modes (work / plan / auto), five-way approval modal, persistent allow-rules, hard-coded blocklist for rm -rf / and friends.
• 📜 Every session replayable. SQLite-backed append-only rollout log; inspect with ub rollout show <id>.
• 🪶 Tiny surface area. Single binary. No daemon. No telemetry. ~26k lines of Go you can actually read.

🚀 Quick taste

Grab a prebuilt binary (Linux / macOS / Windows · amd64 / arm64):

# pick the archive that matches your platform
curl -LO https://github.com/feimingxliu/ub/releases/latest/download/ub_linux_amd64.tar.gz
tar -xzf ub_linux_amd64.tar.gz
install -m 0755 ub ~/.local/bin/ub
ub --version

Prefer Go? go install github.com/feimingxliu/ub/cmd/ub@latest works too. Or go build from source.

Point it at a provider:

# ~/.config/ub/config.yaml
default_provider: openai
default_model: gpt-4o-mini
providers:
  openai:
    type: openai
    api_key: ${OPENAI_API_KEY}

Go:

ub                                  # interactive TUI
ub run -p "summarize this repo"     # headless, CI-friendly
ub doctor --plain                   # check connectivity

No API key? Drop in the Fake provider and the whole agent loop runs offline.

🪞 How ub compares

	ub	OpenCode	Claude Code	Codex CLI
License	MIT	MIT	Proprietary	Apache-2.0
Language	Go (~26k LoC)	TypeScript	closed-source	Rust
Terminal interface	TUI + headless	TUI	TUI (+ IDE / Web / Desktop / Mobile)	TUI
Provider count	5 (incl. Ollama + vLLM-compat)	75+ via AI SDK	Anthropic + Bedrock / Vertex / Foundry	OpenAI / ChatGPT only
Session storage	local SQLite	local	cloud-synced (account-bound)	not publicly documented
Replayable event log	✅ JSONL + rollout show	/undo · /redo	—	not publicly documented
MCP	stdio · http · sse	✅	✅	✅
LSP integration	✅ pluggable	✅	—	—
Plan / read-only mode	✅	✅	✅	✅ (approval modes)
Approval-by-LLM (auto)	✅ optional	—	—	—

_{Sources: OpenCode docs, Claude Code overview and enterprise deployment, Codex CLI repo. Verified Nov 2025. Things move fast — if a row is wrong, open an issue.}

Pick the right tool for the job. ub is best when you want a complete event log you can grep through, a Go codebase small enough to read in an afternoon, and the freedom to swap providers or rip out subsystems. It is not (yet) the polished product Claude Code or OpenCode are; if you need agent skills, IDE integration, or the world's biggest provider list, look there first.

🧱 Inside

        TUI / headless ── agent loop ── provider ── LLM
                              │
                ┌─────────────┼─────────────┐
                ▼             ▼             ▼
            tool registry  permission   rollout log
            (fs / shell /  (modes +     (SQLite,
            search / lsp / 5 decisions  append-only)
            mcp / jobs)    + blocklist)

Follow one keystroke from internal/tui/model.go through internal/agent/, internal/tool/, internal/permission/, into internal/rollout/ and back. That's the whole control flow.

See docs/design.md for the long version.

📚 Documentation

docs/install.md	Install, configure, upgrade, uninstall
docs/usage.md	TUI keymap · slash commands · execution modes · permission flow · workflows
docs/design.md	Architecture, module boundaries, data flow
docs/roadmap.md	V1 six-sprint iteration plan (historical)
docs/roadmap-v2.md	V2 roadmap — features, architecture, ecosystem
README.zh-CN.md	中文文档
AGENTS.md	Repository conventions (commit style, testing, etc.)

🛣️ Status

V1 scope (docs/roadmap.md) is feature-complete. The codebase is approaching its first tagged release. Expect rough edges; expect API churn before v1.0.0.

If something looks wrong, open an issue. PRs welcome — see AGENTS.md for conventions.

🙏 Acknowledgments

ub stands on the shoulders of:

• Bubble Tea and the rest of the Charm stack for the TUI runtime
• Cobra for the CLI surface
• modernc.org/sqlite for the pure-Go SQLite driver
• aymanbagabas/go-udiff for fast unified diffs
• And the agentic-CLI lineage: Claude Code, OpenCode, Codex CLI — much of ub's shape is influenced by what these did well

📄 License

MIT. Fork it. Ship it. Rip out the parts you don't like.

—

_{Built in the open · star if it sparks ideas · feimingxliu/ub}