ub

module
v0.3.11 Latest Latest
Warning

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

 Go to latest Published: Jun 10, 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/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 δΈ­ζ–‡ζ–‡ζ‘£
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
gen-schema command
ub command
Package main is the entry point for the ub CLI.
 Package main is the entry point for the ub CLI.
internal
agent
Package agent implements ub's headless provider/tool loop.
 Package agent implements ub's headless provider/tool loop.
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.
cli
Package cli wires the cobra command tree for the ub binary.
 Package cli wires the cobra command tree for the ub binary.
config
Package config provides layered YAML configuration loading for ub.
 Package config provides layered YAML configuration loading for ub.
context
Package context estimates and prepares model context windows.
 Package context estimates and prepares model context windows.
execution
Package execution defines session execution modes and mode-level gates.
 Package execution defines session execution modes and mode-level gates.
filehistory
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.
log
Package logx configures process-wide structured logging.
 Package logx configures process-wide structured logging.
lsp
Package lsp implements ub's minimal Language Server Protocol client.
 Package lsp implements ub's minimal Language Server Protocol client.
maintenance
Package maintenance runs low-frequency startup cleanup tasks.
 Package maintenance runs low-frequency startup cleanup tasks.
mcp
Package mcp implements ub's Model Context Protocol client.
 Package mcp implements ub's Model Context Protocol client.
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").
message
Package message defines ub's provider-neutral message model.
 Package message defines ub's provider-neutral message model.
modelinfo
Package modelinfo resolves model capability metadata.
 Package modelinfo resolves model capability metadata.
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.
permission
Package permission implements execution-mode-aware tool approval.
 Package permission implements execution-mode-aware tool approval.
provider
Package provider defines ub's SDK-neutral LLM provider runtime.
 Package provider defines ub's SDK-neutral LLM provider runtime.
provider/anthropic
Package anthropic implements ub's Anthropic provider adapter.
 Package anthropic implements ub's Anthropic provider adapter.
provider/compat
Package compat registers OpenAI-compatible chat providers.
 Package compat registers OpenAI-compatible chat providers.
provider/fake
Package fake implements a deterministic script-driven provider.
 Package fake implements a deterministic script-driven provider.
provider/openai
Package openai implements ub's OpenAI provider adapter.
 Package openai implements ub's OpenAI provider adapter.
reasoning
Package reasoning defines provider-neutral reasoning controls.
 Package reasoning defines provider-neutral reasoning controls.
rollout
Package rollout persists the event log for ub sessions.
 Package rollout persists the event log for ub sessions.
store
Package store provides SQLite-backed persistence for ub sessions.
 Package store provides SQLite-backed persistence for ub sessions.
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.
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).
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.
tool/lsp
Package lsp exposes language-server queries as ub tools.
 Package lsp exposes language-server queries as ub tools.
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.
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.
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.
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).
tool/search
Package search implements the grep code-search tool.
 Package search implements the grep code-search tool.
tool/shell
Package shell implements the bash shell-command tool.
 Package shell implements the bash shell-command tool.
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.
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.
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.
tui
Package tui contains the Bubble Tea terminal interface for ub.
 Package tui contains the Bubble Tea terminal interface for ub.
tui/dialog/permission
Package permissiondialog renders the TUI permission approval modal.
 Package permissiondialog renders the TUI permission approval modal.
tui/diffview
Package diffview renders unified diffs for terminal UI surfaces.
 Package diffview renders unified diffs for terminal UI surfaces.
tui/slash
Package slash parses TUI slash commands.
 Package slash parses TUI slash commands.
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.
vcr
Package vcr records and replays HTTP interactions using JSONL cassettes.
 Package vcr records and replays HTTP interactions using JSONL cassettes.

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.