Borg Agent

Borg Agent is a Rust-based agent harness and orchestrator. It provides a terminal and native GPUI frontends, durable sessions, native tools, provider adapters, and optional remote hosts. Releases include the borg CLI; the experimental borg-gui frontend is developed and built separately.

简体中文 · Español · Русский · Blu language · Documentation · Backend architecture

Install

Linux and macOS:

curl -fsSL https://borg.ml/install | sh

Windows PowerShell:

irm https://borg.ml/install.ps1 | iex

The installer chooses the platform and CPU, verifies the release checksum, and installs borg in a user-local binary directory. Run borg update to update an existing installation. The native GUI is experimental and is built from source separately.

Use Borg

Run borg or borg agent to start an interactive session. Useful commands include:

borg resume
borg gui
borg capabilities
borg bug
borg extensions list

For an edge-to-edge TUI in Ghostty, see the terminal setup.

Use /login (or /connect) to choose ChatGPT subscription access or OpenAI API billing on this machine. Borg keeps the saved API key when you switch back to ChatGPT. ChatGPT login and token recovery are handled natively by Borg. To keep an existing file-backed subscription, select its authority in place: borg login codex --auth-file /path/to/auth.json. Borg stores the path, not a second copy of its rotating tokens. BORG_OPENAI_AUTH_FILE overrides that path. Fresh device logins use ~/.borg/openai-subscription.json unless an existing authority was selected or discovered through CODEX_HOME or ~/.codex/auth.json. Keychain-only logins need a fresh borg login codex device approval. You can also add a key directly with borg login codex --api-key; input is hidden, or you can pipe it through stdin.

Provider credentials do not own a Borg session: switching accounts or replacing an API key preserves its ledger, forks, and collaborators. OpenAI continuation data is reused only for its originating account; other turns use Borg's ordinary conversation history. Credentials remain fixed within an in-flight turn.

For OpenCode Go, run borg login opencode --api-key and enter your Go subscription key. /model lists Go models under OpenCode Go using the opencode-go/<model> route. The footer shows the selected billing mode. Subscription limits never trigger an automatic switch to API billing.

Interactive sessions run in a detached per-session host. Closing one TUI or GUI view does not stop an active turn, its provider app server, or subagents; another view can attach to the same durable session. An unattended host exits after five minutes only when the session is ready, has no pending prompt, and has no running background processes. See docs/session-lifecycle.md.

Session history is kept in a durable journal on PostgreSQL, which Borg provisions for you; BORG_SESSIONS_URL points it at an existing server instead. Writers serialise per session row rather than per file, so throughput keeps scaling as agents are added. See docs/session-store-backends.md.

The default native-provider harness exposes one shell-first exec surface. The model can use shell pipelines or invoke the installed language best suited to the problem; session-scoped Borg, Blu, plugin, workflow, and collaboration capabilities are discovered from that shell with borg tools and invoked with borg call NAME JSON, or from code with import borg in Python (borg.send_message(target=..., message=...)) and import borg from "borg" in Bun. Every such call shows in the transcript as a step of the command that made it. borg tools --search QUERY and borg.tools("query") find capabilities by name or purpose, and a malformed call answers with the expected signature. Code whose state should last between calls runs through runtime_exec, a persistent Python or Bun namespace with borg preloaded, and the harness capability keeps evidence-backed prompt, memory and skill refinements that Borg adds to later turns, with rollback. Set capabilities.harness = "native" only when the direct one-tool-per-capability fallback is preferred.

Ask Borg to watch a log or deployment, for example: “Watch the build log and let me know when it fails.” The watch tool runs a background shell command and delivers stdout lines automatically, in bounded batches. list_watchers and stop_watcher manage the watchers. The old list_watches and stop_watch names remain compatibility aliases. Watchers last for the current session, up to 24 hours (or the host's command limit), and stop with their process trees when the session ends. A watcher can wake an idle agent; human messages take priority, and arriving events are handled at the next turn boundary.

If the provider connection drops, Borg saves the interrupted work and retries automatically with delays capped at 30 seconds. The terminal shows the retry countdown; Escape cancels recovery. Completed tool work is included in recovery context so the agent can check interrupted commands before continuing.

Usage limits wait until the provider's reported reset time, including its time zone. If no reset is supplied, Borg retries after 30 minutes. The terminal shows when work will resume; Escape cancels the wait, and /login or /model lets you switch connections and continue sooner.

On macOS, Option/Ctrl+Left/Right move by word, Cmd+Left/Right go to line boundaries, and Cmd+Up/Down go to the start/end of the composer. Shift extends the selection. Legacy terminal word and line shortcuts are supported too. Full-screen action inspection wraps long commands so their final arguments remain visible alongside the output.

Bring existing conversations with you using /import or borg import. Threads and Memory are both selected by default, with independent opt-outs. Codex CLI/Desktop, Claude Code, Claude Desktop exports, and portable JSON are supported. Imports copy originals, skip duplicates, and appear in /resume. See importing threads and memory.

What it provides

• Responsive TUI and native GPU-rendered frontends over the same durable session runtime, with resumable sessions, compaction, image input, transcript navigation, dictation, goals, plans, and subagent controls.
• Codex and Claude subscription adapters, OpenCode, Kimi, OpenRouter, and configured OpenAI-compatible providers.
• A provider-neutral borg-core crate with no provider SDK, HTTP, MCP, or subprocess dependency.
• A shell-first, polyglot execution surface backed by files, processes, LSP, MCP, skills, goals, plans, Blu workflows, and subagents.
• Provider-neutral web search with Exa, Firecrawl, Parallel, and Brave backends; see docs/web-search.md.
• Full Access, Auto, and Manual command-approval modes.
• Borg Remote hosts that use the same durable session and tool runtime. See the unattended-host runbook for preflight, fault recovery, and rollback procedures.
• Agent discovery and direct messaging across local projects and machines enrolled under the same account. Agents use list_instances, then send_message or followup_task; no shared project workspace is required. See multiplayer messaging.

Extension authority is user-controlled. Packages can request sandboxed, trusted, or native runtime access; user policy caps project and user packages independently. Native mode loads hash-pinned, versioned C ABI code inside Borg's process and is never enabled by repository configuration alone.

Configuration

Copy the example files to Borg's configuration directory:

cp configs/agent.example.toml ~/.config/borg/agent.toml
cp configs/editor.example.toml ~/.config/borg/editor.toml

Use $XDG_CONFIG_HOME/borg instead when XDG_CONFIG_HOME is set. The agent configuration covers providers, capabilities, MCP servers, aliases, and team settings. The agent interface configuration covers shared language plus TUI presentation and input behavior; the native frontend uses the same interface language with platform-native input and rendering. /ui-language changes UI labels, while /language independently controls the model's response language.

See docs/customization.md for agent interface settings, keybindings, alerts, extension authority, and native extension authoring. Use borg customize inspect, borg customize export, and borg customize import to inspect or move the complete effective setup.

borg capabilities --json shows the effective runtime capabilities. Automated checks can use borg agent --ephemeral --local-only to avoid changing resume history.

Privacy-minimal usage count

Release download totals provide the all-time installation proxy. To estimate active installations, release builds send at most one content-free heartbeat per day. It contains one random identifier that rotates every 31 days—no version, OS, model, session, prompt, path, or device data. Set usage_count.enabled = false in agent.toml or export BORG_DISABLE_USAGE_COUNT=1 to disable it. The receiver must discard network metadata and raw request logs and retain only aggregate daily/monthly counts.

Diagnostic bundles

borg bug collects a diagnostic bundle to attach to a bug report. It is local only: it opens no socket, calls no model, and uploads nothing. The bundle is a file you read and decide about.

borg bug                                            # summary only
borg bug --output bundle.json                       # write the full bundle
borg bug --output bundle.json --include-transcript  # add conversation text

What it collects is an allowlist: build identification, durable store readiness, provider runtime readiness, and session metadata. Credentials, environment variables, request headers, and configuration file contents have no code path into the bundle, and the working directory is deliberately left out. Failures are recorded as a fixed class — connection_refused, permission_denied — rather than as their original message, because an error message is the field most likely to carry a URL or a password.

Conversation text is excluded unless you pass --include-transcript, which requires --output: a transcript may only be written to a file, created readable by you alone, never to a terminal or a pipe where permissions mean nothing. Read the bundle before you share it.

Blu extensions

Blu is a Lua/Luau superset language and runtime. Its source and documentation live in the separate borg-ml/blu repository. Borg embeds Blu for bounded workflows and uses it in the live extension package system. A package can provide skills, namespaced MCP servers, workflows, or an explicitly admitted native runtime.

borg extensions install <PATH-or-GIT-URL>
borg extensions new <id> --project
borg extensions doctor

See docs/blu-extensions.md and the extension manifest example for the package contract. Blu workflow files may use .blu, .lua, or .luau entrypoints.

Documentation

• docs/customization.md — agent interface settings, keybindings, alerts, trust policy, and native extensions
• docs/session-lifecycle.md — detached hosts, attachment, resume, and shutdown behavior
• docs/usage-count.md — active-install metric and privacy contract
• docs/zh-Hans/README.md — Simplified Chinese guide
• docs/es/README.md — Spanish guide
• docs/ru/README.md — Russian guide
• TODO.md — remaining customization surface and extension API work
• docs/blu-extensions.md — extension packages and workflows
• docs/web-search.md — web-search providers
• docs/multiplayer-workspaces.md — local workspaces and collaboration
• docs/agent-runtime-protocol-v1.md — runtime protocol
• docs/public-release-checklist.md — release process

Repository layout

• borg-core — provider-neutral message, tool, usage, and channel contracts
• borg-provider — model gateways and provider adapters
• borg-remote — durable sessions, hosts, protocols, and native tools
• borg-search — bounded web-search contracts and backends
• borg-ui — frontend-neutral commands, projections, preferences, and local session bridge
• borg-tui — Ratatui terminal frontend
• borg-gui — experimental GPUI native frontend (opt-in)
• borg-cli — public command shell and frontend launchers

Development

cargo fmt --all -- --check
cargo check --workspace --exclude borg-gui
cargo test --workspace --exclude borg-gui

# Opt in to the experimental native GUI.
cargo run -p borg-gui

See CONTRIBUTING.md before submitting a change.

Releases

Release tags matching v* build checksum-paired archives for Linux, macOS, and Windows on x86-64 and ARM64. See the changelog for user-visible changes and the public release checklist before publishing a release.

MIT licensed.