libra code

Launch an interactive AI coding session with TUI, web, or MCP modes.

Synopsis

libra code
libra code --web-only [-p <PORT>] [--host <HOST>]
libra code --stdio
libra code --provider <PROVIDER> [--model <MODEL>]
libra code --resume <THREAD_ID>
libra graph <THREAD_ID> [--repo <PATH>]

Description

libra code starts an interactive coding session that pairs a human developer with an AI agent. The default mode launches a terminal UI (TUI) built on ratatui/crossterm with a background web server. Plain developer requests in the generic provider TUI are routed through the built-in planning workflow first: Libra generates a reviewable IntentSpec and execution plan, then waits for Execute Plan / Network / Modify Plan / Cancel before running mutating tools. Two alternative modes are available: --web-only runs the web server without the TUI (useful for browser access or remote hosting), and --stdio runs an MCP server over standard input/output for integration with AI clients like Claude Desktop.

The command supports eight AI provider backends (Gemini, OpenAI, Anthropic, DeepSeek, Kimi, Zhipu, Ollama, Codex) and three operating contexts (dev, review, research) that tune the agent's behavior for different workflows. Sessions can be persisted and resumed with Libra's canonical --resume <thread_id> flow. Passing --goal "<objective>" boots the session directly in goal mode, where a supervisor drives the tool loop toward the stated objective until a verifier accepts completion.

A sandboxed tool-execution layer enforces approval policies that control when the agent can run shell commands, apply patches, web search, or perform other potentially destructive operations. TUI dev sessions default to workspace-write execution with network access denied. After the execution plan is ready, the Plan review dialog includes a Network: Deny / Network: Allow toggle; the selected value becomes the execution IntentSpec network policy for shell, gate, and web_search use. Review and research contexts remain read-only and do not grant network access.

When the TUI exits and Libra can derive the canonical thread ID, libra code prints a follow-up libra graph <thread_id> command so the thread's Intent/Plan/Task/Run/PatchSet version graph can be inspected in a separate TUI. Use libra graph <thread_id> --repo <path> when inspecting a repository other than the current directory.

Options

Provider Backends

For Codex app-server linkage, model forwarding, credentials ownership, and persisted object storage details, see Codex data storage integration.

DeepSeek requests can opt into provider-specific fields with --deepseek-thinking enabled --deepseek-reasoning-effort high --deepseek-stream true; these flags are rejected for non-DeepSeek providers. Kimi requests default to the selected model's thinking behavior; use --kimi-thinking disabled for K2.6/K2.5 runs where lower latency or official web-search compatibility matters. Libra preserves Kimi reasoning_content across tool-call turns when the provider returns it. For normal runs, store provider keys in vault.env.<NAME>; Libra checks repo-local Vault, then global Vault, then the process environment. Use --env-file .env.test for live tests that need an explicit dotenv override.

Ollama requests stream /api/chat responses by default and add a per-request request_id to debug logs. They also default to think:false so reasoning-capable local models do not spend several minutes generating hidden reasoning before tool calls. Use --ollama-thinking high for a single run, or set OLLAMA_THINK=true, low, medium, high, or auto as the environment default. auto omits the think field and lets Ollama decide. Use --ollama-compact-tools or OLLAMA_COMPACT_TOOLS=true when a remote/cloud Ollama endpoint accepts simple tools but returns 503 for Libra's full tool schema payload.

Local Automation Control

libra code --control observe is the default and does not create local control files unless --control-info-file is explicitly supplied. Loopback clients can continue reading /api/code/session and /api/code/events without a token.

libra code --control write enables the local automation security envelope. Libra creates a fresh 32-byte token in .libra/code/control-token, writes non-secret endpoint metadata to .libra/code/control.json after the web server binds, and holds .libra/code/control.lock for the process lifetime. control.json includes version, mode, pid, baseUrl, optional mcpUrl, workingDir, optional threadId, and startedAt; it never includes the token, token hash, token path, provider credentials, headers, or provider request/response bodies.

Write control is local-only. --control write is rejected with --stdio, and it requires --host to be loopback (127.0.0.1, ::1, or localhost). A second write-control instance using the same default paths fails fast with CONTROL_INSTANCE_CONFLICT; use distinct --control-token-file and --control-info-file paths only when the caller intentionally manages multiple local instances.

Automation clients attach with POST /api/code/controller/attach, body { "clientId": "...", "kind": "automation" }, header X-Libra-Control-Token, and then use the returned X-Code-Controller-Token for writes. Automation-held leases require both tokens for /api/code/messages, /api/code/interactions/{id}, /api/code/controller/detach, and /api/code/control/cancel. The local TUI can reclaim control with /control reclaim, which invalidates the automation lease. Code UI write request bodies are capped at 256KiB.

GET /api/code/diagnostics returns a redacted observe-only status summary for local tools. Control attach, detach, submit, respond, and cancel operations emit local-tui-control/v1 audit events through the runtime audit sink. For stdio automation clients, use libra code-control --stdio; libra code --stdio remains the MCP stdio server and does not control a live TUI.

Web Browser Control

--browser-control <off|loopback> controls whether the embedded UI's lease-based write surface is available. The default is mode-aware:

Selecting loopback is rejected when --host is not a loopback address, and the flag conflicts with --stdio. The browser server-side endpoints are tagged in the code_router() audit matrix (src/internal/ai/web/mod.rs):

• GET /api/code/session, GET /api/code/events, GET /api/code/diagnostics, GET /api/code/threads, GET /api/code/goal/status — loopback-only observe.
• POST /api/code/controller/attach — loopback. kind: "automation" requests additionally require X-Libra-Control-Token. The handler issues the lease's controllerToken (it does not expect the caller to send one).
• POST /api/code/controller/detach, POST /api/code/messages, POST /api/code/interactions/{id} — loopback + X-Code-Controller-Token; Automation leases additionally require X-Libra-Control-Token.
• POST /api/code/control/cancel — loopback + X-Code-Controller-Token. Automation leases also require X-Libra-Control-Token; this is the only difference from the TUI Esc cancel path.
• POST /api/code/task/dispatch — loopback + X-Code-Controller-Token; user-initiated sub-agent dispatch requires an automation lease.
• POST /api/code/goal/start, POST /api/code/goal/cancel — loopback + X-Code-Controller-Token; goal mutation requires the active controller lease.

Browser write requests share the same 256 KiB body limit and audit-sink wiring as automation control. The browser persists the lease only in memory; reloading the page drops the lease and the next write reattaches.

When the server is bound to a non-loopback host, non-loopback browsers receive a static remote access notice for HTML navigation instead of the SPA. The notice is zero JavaScript, includes only bind/remote/version/commit placeholders, and asset/API fallbacks return 404 so remote clients cannot probe session state.

When --browser-control loopback is requested and the browser holds the active lease, the TUI initial controller is LocalTui (visible owner, can be reclaimed) instead of Fixed { Tui } (permanently blocking). If the TUI also wants to drive writes, --control write must be supplied alongside --browser-control loopback; the two writers serialize through the same TuiControlCommand channel.

For --web-only non-Codex providers (--provider ollama is the canonical Phase 3 verification path), Libra builds a HeadlessCodeRuntime that runs the agent's tool loop directly so the browser can drive a real session -- no terminal required. Headless mode advertises messageInput, streamingText, toolCalls, planUpdates, patchsets, interactiveApprovals, structuredQuestions, and providerSessionResume. --resume <thread_id> is TUI-only by design: the headless runtime carries a session-layer resume implementation, but the --resume CLI flag is accepted only on the interactive TUI path and is rejected in --web-only (and --stdio) mode. Persisted headless resume is reachable only through the TUI — this is a deliberate contract, not deferred work. update_plan projects into plans[], and apply_patch metadata projects into patchsets[].

Code UI Wire Contract

The Code UI JSON contract uses camelCase field names and snake_case enum values. The Rust source of truth is src/internal/ai/web/code_ui.rs; the browser mirror is web/src/lib/code-ui/types.ts; tests/ai_code_ui_wire_test.rs pins the wire shape.

GET /api/code/session returns a CodeUiSessionSnapshot:

GET /api/code/events streams CodeUiEventEnvelope records with seq, type, at, and data. Event type is session_updated, status_changed, or controller_changed; session_updated carries a full CodeUiSessionSnapshot.

GET /api/code/threads returns { items, nextOffset? }. Each item has id, optional title, archived, optional currentIntentId, createdAt, and updatedAt. limit defaults to 50 and clamps to 200; malformed limit or offset returns INVALID_QUERY_PARAM.

Code UI API errors use { error: { code, message } }:

Web Search

The web_search tool requires the session network policy to allow outbound access. If BRAVE_SEARCH_API_KEY is available from vault.env.BRAVE_SEARCH_API_KEY or the process environment, Libra tries the Brave Search API first and returns result titles, URLs, and snippets. If Brave is not configured or the request fails, Libra falls back to the zero-configuration DuckDuckGo HTML endpoint.

Approval Policies

Context Modes

Common Commands

# Start a TUI session with default Gemini provider
libra code

# Start with Anthropic Claude
libra code --provider anthropic --model claude-sonnet-4-20250514

# Bind web-only on all interfaces; remote browsers see a loopback-only notice
libra code --web-only --port 8080 --host 0.0.0.0

# Browser-driven session against a local Ollama
libra code --web-only --provider ollama --port 4400

# Allow browser write control over loopback (Codex web-only is loopback by default)
libra code --web-only --provider codex --browser-control loopback

# Enable local automation write control (writes token + lease discovery files)
libra code --control write

# Load provider keys from a dotenv-style file (overrides stale shell env vars)
libra code --env-file .env.test

# Run MCP over stdio for Claude Desktop integration
libra code --stdio

# Use DeepSeek with reasoning enabled
libra code --provider deepseek --model deepseek-v4-pro --deepseek-thinking enabled --deepseek-reasoning-effort high --deepseek-stream true
libra code --env-file .env.test --provider deepseek --model deepseek-v4-pro --deepseek-thinking enabled --deepseek-reasoning-effort high --deepseek-stream true

# Use Kimi (Moonshot AI) with the K2.6 default; opt out of thinking for lower latency
libra code --provider kimi
libra code --provider kimi --model kimi-k2-thinking --kimi-thinking enabled
libra code --provider kimi --model kimi-k2.6 --kimi-thinking disabled

# Use a local Ollama model; plain requests generate a reviewable plan first
libra code --provider ollama --model llama3 --api-base http://127.0.0.1:11434/v1

# Use compact tool schemas for a remote/cloud Ollama endpoint
libra code --provider ollama --model minimax-m2.7:cloud --api-base http://192.168.0.5:11434/v1 --ollama-compact-tools

# Enable high thinking for one Ollama run
libra code --provider ollama --model qwen3.6 --ollama-thinking high

# Capture provider/TUI diagnostics while using a local Ollama model
LIBRA_LOG='libra::internal::ai=debug,libra::internal::tui=debug' \
LIBRA_LOG_FILE=/tmp/libra-code.log \
libra code --repo=/Volumes/Data/linked --provider ollama --model gemma4:31b

# Resume a canonical Libra thread (TUI-only: --resume is not accepted with
# --web-only or --stdio, by design)
libra code --resume 11111111-1111-4111-8111-111111111111

# Inspect the same thread's version graph
libra graph 11111111-1111-4111-8111-111111111111

# Inspect a thread graph from outside that repository
libra graph 11111111-1111-4111-8111-111111111111 --repo /Volumes/Data/linked

# Start in code review context with strict approval
libra code --context review --approval-policy untrusted

# Use Codex with plan-before-execute mode
libra code --provider codex --plan-mode

Human Output

Output is delivered through the TUI, web interface, or MCP protocol depending on the mode. There is no line-oriented stdout in the default TUI mode. In the generic provider TUI, a normal plain-text request starts the plan workflow automatically; explicit slash commands keep their command-specific behavior. Generic provider planning uses a two-step review: the LLM first drafts an IntentSpec for confirmation, then the confirmed IntentSpec is sent back to the LLM to generate a reviewable execution plan before any execution starts. If a confirmed plan executes and fails, or the orchestrator aborts before reaching a final decision, Libra feeds the failure evidence back into the planner, asks it to add or adjust repair steps, and automatically runs the revised plan up to the automatic repair threshold. After the threshold is reached, the TUI waits for the developer to either continue automatic repair with /plan continue or provide explicit plan repair guidance. The web server serves an embedded Next.js application. The stdio mode communicates via JSON-RPC messages following the Model Context Protocol.

Diagnostics

libra code supports tracing through RUST_LOG or LIBRA_LOG; when both are set, LIBRA_LOG takes precedence. For TUI sessions, prefer LIBRA_LOG_FILE=<path> so diagnostics are written to a plain log file instead of the alternate-screen terminal. When LIBRA_LOG_FILE is set without an explicit log filter, Libra defaults to libra=debug.

For Ollama provider failures, useful diagnostics are:

mkdir -p /tmp/libra-logs
LIBRA_LOG='libra::internal::ai=debug,libra::internal::tui=debug' \
LIBRA_LOG_FILE=/tmp/libra-logs/libra-code-ollama.log \
libra code --repo=/Volumes/Data/linked --provider ollama --model gemma4:31b

If the TUI reports an Ollama 503, also capture the local server state:

ollama ps >> /tmp/libra-logs/libra-code-ollama.log
ollama list >> /tmp/libra-logs/libra-code-ollama.log

Design Rationale

Why a TUI + web server hybrid?

The TUI provides a low-latency, keyboard-driven interface for developers already working in a terminal. The background web server runs simultaneously so that the same session can be accessed from a browser -- useful for sharing context with teammates, viewing rich diffs, or accessing the session from a mobile device. The --web-only flag drops the TUI entirely for headless or remote server deployments where no terminal is available.

Why multiple AI provider support?

Different providers excel at different tasks and have different cost/latency profiles. Gemini is the default for its generous free tier and fast response times. Anthropic Claude excels at careful reasoning and code review. Local Ollama support enables fully offline development. By abstracting behind a CompletionClient trait, adding a new provider requires only implementing the trait without touching the session, tool, or TUI layers.

Why MCP integration?

The Model Context Protocol (MCP) is an open standard for connecting AI clients to tool servers. By supporting --stdio mode, Libra can act as a tool server for any MCP-compatible client (e.g., Claude Desktop). Libra exposes an allowlisted run_libra_vcs tool for version-control operations -- status, diff, branch, log, show, show-ref, ls-files, add, commit, and switch -- so external AI agents use Libra directly instead of invoking Git. run_libra_vcs only accepts those Libra subcommands; it is not a Git-compatible shell. For repository state inspection, prefer status --json or status --porcelain v2 --untracked-files=all, and use ls-files for tracked and untracked repository path inspection (for example ls-files --others --exclude-standard for ignore-aware untracked files). Libra-managed execution also rejects direct git shell commands.

Why approval policies?

AI agents executing shell commands on a developer's machine present real safety risks. The five-tier approval system balances productivity with control:

• never is for fully locked-down environments where the agent can only read.
• allow-all is the opposite extreme: no prompts and every command runs, for trusted throwaway or sandboxed environments where friction outweighs risk.
• on-failure lets the agent try sandboxed execution and only asks when it fails.
• on-request (default) sandboxes everything and escalates when the agent or sandbox policy requires it.
• untrusted is the most conservative interactive mode, prompting for anything beyond known-safe reads.

Why session persistence and resume?

Long coding sessions accumulate significant context: file edits, conversation history, tool outputs. Losing this context on an accidental terminal close is painful. Session persistence stores the full conversation and tool state, and --resume <thread_id> restores a canonical Libra thread.

The embedded Code UI exposes the same canonical identifier as threadId in its session snapshot. Older session_id fields remain present for compatibility, but new integrations should key resume, Web, MCP, and diagnostics flows by threadId.

Parameter Comparison: Libra vs Git vs jj

Note: Neither Git nor jj have an equivalent to libra code. This command represents Libra's core differentiation as an AI-agent-native version control system. The closest analogs in the Git ecosystem are third-party tools like GitHub Copilot CLI or aider, which are separate applications rather than integrated VCS commands.

Error Handling