ub

module
v0.3.12 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 11, 2026 License: MIT

README ΒΆ

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

δΈ­ζ–‡

πŸ‘€ See it

ub demo

🎯 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 /v1) Β· 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), six-way approval modal, Claude-style project command 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

Optional checksum, signature, and SBOM verification steps are in docs/install.md.

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

🧱 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/app/ub/tui/model.go through internal/app/ub/agent/, internal/pkg/tool/, internal/pkg/runtime/permission/, into internal/pkg/workspace/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 δΈ­ζ–‡ζ–‡ζ‘£
CONTRIBUTING.md Contributor workflow, tests, commit style, PR checklist
AGENTS.md AI-agent collaboration notes

πŸ›£οΈ Status

V1 scope (docs/roadmap.md) is feature-complete and tagged releases are available. Current releases are still v0.x, so expect rough edges and API churn before v1.0.0.

If something looks wrong, open an issue. PRs welcome β€” see CONTRIBUTING.md for conventions.

πŸ™ Acknowledgments

ub stands on the shoulders of:

πŸ“„ 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

Directories ΒΆ

Path Synopsis
cmd
ub command
Package main is the entry point for the ub CLI.
 Package main is the entry point for the ub CLI.
internal
app/ub/agent
Package agent implements ub's headless provider/tool loop.
 Package agent implements ub's headless provider/tool loop.
app/ub/cli
Package cli wires the cobra command tree for the ub binary.
 Package cli wires the cobra command tree for the ub binary.
app/ub/tui
Package tui contains the Bubble Tea terminal interface for ub.
 Package tui contains the Bubble Tea terminal interface for ub.
app/ub/tui/dialog/permission
Package permissiondialog renders the TUI permission approval modal.
 Package permissiondialog renders the TUI permission approval modal.
app/ub/tui/diffview
Package diffview renders unified diffs for terminal UI surfaces.
 Package diffview renders unified diffs for terminal UI surfaces.
app/ub/tui/slash
Package slash parses TUI slash commands.
 Package slash parses TUI slash commands.
app/ub/tui/tuitheme
Package tuitheme contains the small built-in visual theme used by the TUI.
 Package tuitheme contains the small built-in visual theme used by the TUI.
pkg/core/config
Package config provides layered YAML configuration loading for ub.
 Package config provides layered YAML configuration loading for ub.
pkg/core/execution
Package execution defines session execution modes and mode-level gates.
 Package execution defines session execution modes and mode-level gates.
pkg/core/message
Package message defines ub's provider-neutral message model.
 Package message defines ub's provider-neutral message model.
pkg/core/reasoning
Package reasoning defines provider-neutral reasoning controls.
 Package reasoning defines provider-neutral reasoning controls.
pkg/integration/lsp
Package lsp implements ub's minimal Language Server Protocol client.
 Package lsp implements ub's minimal Language Server Protocol client.
pkg/integration/mcp
Package mcp implements ub's Model Context Protocol client.
 Package mcp implements ub's Model Context Protocol client.
pkg/llm/context
Package context estimates and prepares model context windows.
 Package context estimates and prepares model context windows.
pkg/llm/modelinfo
Package modelinfo resolves model capability metadata.
 Package modelinfo resolves model capability metadata.
pkg/llm/provider
Package provider defines ub's SDK-neutral LLM provider runtime.
 Package provider defines ub's SDK-neutral LLM provider runtime.
pkg/llm/provider/anthropic
Package anthropic implements ub's Anthropic provider adapter.
 Package anthropic implements ub's Anthropic provider adapter.
pkg/llm/provider/compat
Package compat registers OpenAI-compatible chat providers.
 Package compat registers OpenAI-compatible chat providers.
pkg/llm/provider/fake
Package fake implements a deterministic script-driven provider.
 Package fake implements a deterministic script-driven provider.
pkg/llm/provider/openai
Package openai implements ub's OpenAI provider adapter.
 Package openai implements ub's OpenAI provider adapter.
pkg/llm/vcr
Package vcr records and replays HTTP interactions using JSONL cassettes.
 Package vcr records and replays HTTP interactions using JSONL cassettes.
pkg/runtime/approval
Package approval defines the secondary approval-agent interface used by auto execution mode.
 Package approval defines the secondary approval-agent interface used by auto execution mode.
pkg/runtime/hook
Package hook runs shell hooks at agent lifecycle points (pre/post tool call, pre/post user turn) so users can attach gofmt, audit logging, lint gates etc.
 Package hook runs shell hooks at agent lifecycle points (pre/post tool call, pre/post user turn) so users can attach gofmt, audit logging, lint gates etc.
pkg/runtime/log
Package logx configures process-wide structured logging.
 Package logx configures process-wide structured logging.
pkg/runtime/maintenance
Package maintenance runs low-frequency startup cleanup tasks.
 Package maintenance runs low-frequency startup cleanup tasks.
pkg/runtime/permission
Package permission implements execution-mode-aware tool approval.
 Package permission implements execution-mode-aware tool approval.
pkg/tool
Package tool defines ub's local tool surface: a Tool interface, risk taxonomy, preview protocol and a Registry for assembling the set of tools an agent loop can call.
 Package tool defines ub's local tool surface: a Tool interface, risk taxonomy, preview protocol and a Registry for assembling the set of tools an agent loop can call.
pkg/tool/fs
Package fs implements the workspace file-system tool group (read, ls, glob, write, edit).
 Package fs implements the workspace file-system tool group (read, ls, glob, write, edit).
pkg/tool/job
Package job implements the long-running background process tools: job_run, job_output and job_kill.
 Package job implements the long-running background process tools: job_run, job_output and job_kill.
pkg/tool/lsp
Package lsp exposes language-server queries as ub tools.
 Package lsp exposes language-server queries as ub tools.
pkg/tool/mcp
Package mcp adapts remote MCP tools to ub's local tool interface.
 Package mcp adapts remote MCP tools to ub's local tool interface.
pkg/tool/memory
Package memory implements the `remember` and `recall` tools that let an agent write and search durable facts.
 Package memory implements the `remember` and `recall` tools that let an agent write and search durable facts.
pkg/tool/plan
Package plan implements the plan-then-execute artifact workflow: agents (or users) write a structured markdown plan to the user's state directory ($XDG_STATE_HOME/ub/plans/<project-key>/), and later mark individual steps done / skipped / failed as work proceeds.
 Package plan implements the plan-then-execute artifact workflow: agents (or users) write a structured markdown plan to the user's state directory ($XDG_STATE_HOME/ub/plans/<project-key>/), and later mark individual steps done / skipped / failed as work proceeds.
pkg/tool/procgroup
Package procgroup encapsulates POSIX process-group creation and signalling for tool implementations that need to reliably kill an entire subprocess tree (the child plus any grandchildren it spawns).
 Package procgroup encapsulates POSIX process-group creation and signalling for tool implementations that need to reliably kill an entire subprocess tree (the child plus any grandchildren it spawns).
pkg/tool/search
Package search implements the grep code-search tool.
 Package search implements the grep code-search tool.
pkg/tool/shell
Package shell implements the bash shell-command tool.
 Package shell implements the bash shell-command tool.
pkg/tool/task
Package task implements the `task` tool: dispatch a sub-agent to do one focused sub-prompt (e.g.
 Package task implements the `task` tool: dispatch a sub-agent to do one focused sub-prompt (e.g.
pkg/tool/todo
Package todo implements the short-lived execution todo view used by plan-then-execute workflows.
 Package todo implements the short-lived execution todo view used by plan-then-execute workflows.
pkg/workspace/filehistory
pkg/workspace/memory
Package memory persists durable, agent-visible facts about the user's workspace ("build command is X", "issue #42 root cause is Y") and the user's broader environment ("prefer pnpm over npm", "VPN URL is Z").
 Package memory persists durable, agent-visible facts about the user's workspace ("build command is X", "issue #42 root cause is Y") and the user's broader environment ("prefer pnpm over npm", "VPN URL is Z").
pkg/workspace/paths
Package paths centralizes all XDG-based and project-keyed directory calculations for ub.
 Package paths centralizes all XDG-based and project-keyed directory calculations for ub.
pkg/workspace/rollout
Package rollout persists the event log for ub sessions.
 Package rollout persists the event log for ub sessions.
pkg/workspace/store
Package store provides SQLite-backed persistence for ub sessions.
 Package store provides SQLite-backed persistence for ub sessions.
pkg/workspace/tooloutput
Package tooloutput limits model-visible tool results and manages spillover files for full outputs.
 Package tooloutput limits model-visible tool results and manages spillover files for full outputs.
tools
gen-schema command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.