FAQ
General
Section titled “General”What is BMO?
Section titled “What is BMO?”BMO is a terminal-native AI coding agent built in Go. It integrates directly into your development workflow — reading, editing, and running code in your local environment.
What models does BMO support?
Section titled “What models does BMO support?”BMO supports Anthropic Claude, OpenAI, Google Gemini/Vertex, AWS Bedrock, Azure OpenAI, Groq, OpenRouter, and any OpenAI-compatible endpoint. See Authentication for setup.
Does BMO send my code to a server?
Section titled “Does BMO send my code to a server?”BMO sends prompts and selected file or tool content to your configured model provider. Web tools, MCP servers, remote execution, and optional telemetry can have other destinations. See Security and data for the boundaries to review.
Is BMO free?
Section titled “Is BMO free?”The BMO binary has no license fee. Redistribution follows the terms shipped with a published release. You pay for configured provider usage and any infrastructure or paid tool services you use. See Cost and operations.
Configuration
Section titled “Configuration”Where is the config file?
Section titled “Where is the config file?”Global config lives in ~/.config/bmo/bmo.toml by default. Project-local
overrides use bmo.toml or .bmo.toml. Existing JSON config files are still
loaded as a fallback, but TOML is the canonical format.
How do I set my API key?
Section titled “How do I set my API key?”export ANTHROPIC_API_KEY=sk-...Or set it in bmo.toml:
[providers.anthropic]api_key = "${ANTHROPIC_API_KEY}"See Authentication.
Can I use different models for different tasks?
Section titled “Can I use different models for different tasks?”Yes. Use Phase Model Routing to configure separate planning and execution models, or configure per-agent models in multi-agent setups.
Tools & Execution
Section titled “Tools & Execution”Can BMO run terminal commands?
Section titled “Can BMO run terminal commands?”Yes — the bash tool runs shell commands. Commands pass through tool policy and permission checks. Existing grants and auto-approval settings can allow execution without a new prompt. Use Lifecycle Hooks or the Execution Sandbox to restrict what can run.
Why does BMO use a bash tool instead of my shell?
Section titled “Why does BMO use a bash tool instead of my shell?”BMO runs commands through an embedded POSIX shell interpreter (mvdan.cc/sh/v3),
not your active shell — $SHELL, zsh, fish, and your aliases and shell functions
are deliberately not inherited. This gives BMO three useful properties:
- Shared shell grammar — the embedded interpreter parses commands across platforms. Available programs, paths, and operating-system behavior still vary.
- Parse-before-execute — commands are parsed into a syntax tree before anything runs, so the approval and blocklist checks read command structure rather than pattern-matching a string.
- Fewer shell-profile dependencies — aliases and functions from your personal shell are excluded. Reproduction still requires compatible tools, environment variables, permissions, and working directories.
The tool is named bash because it accepts common Bash syntax, not because it
shells out to GNU Bash. Bash-specific extensions may be unsupported; each call
gets a fresh interpreter, so no state, history, or aliases carry between calls.
Does BMO have internet access?
Section titled “Does BMO have internet access?”Yes. The built-in web tools are web_fetch, web_search, and agentic_fetch.
Hide them globally with options.disabled_tools, or remove them from a
specific agent via [agents.<id>.tools].
How do I limit what tools the agent can use?
Section titled “How do I limit what tools the agent can use?”Use the layer that matches what you want to control:
[options]disabled_tools = ["web_search", "sourcegraph"]
[agents.coder.tools]allowed = ["view", "search", "bash"]
[permissions]allowed_tools = ["view", "search"]options.disabled_tools hides built-ins globally. agents.<id>.tools shapes
one agent’s tool set. permissions.allowed_tools skips approval prompts but
does not hide the tools.
Sessions
Section titled “Sessions”See Sessions for the full concept: one SQLite-backed conversation, switching, branches, and session checkpoints vs git undo.
How do I continue a previous session?
Section titled “How do I continue a previous session?”Use /session in the TUI to browse and resume prior sessions, or
bmo session resume --session <id> for health-checked resume from the CLI.
What is the context window limit?
Section titled “What is the context window limit?”BMO uses Context Pruning to automatically trim
older context as a session approaches the model limit. Tune it with
options.pruning.*.
Evidence and recovery
Section titled “Evidence and recovery”Which BMO artifact should I use to understand what happened?
Section titled “Which BMO artifact should I use to understand what happened?”BMO does not reduce run evidence to one receipt-like file. It keeps separate surfaces for separate operator questions:
| Use case | Use this surface |
|---|---|
| Replay the ordered timeline of a run | Agent Debugger or get_agent_run_events, backed by the durable run ledger |
| Check what is happening now and who should act next | Run observability and the cue ledger |
| Preserve enough context to continue after handoff or compaction | Session continuity capsules, surfaced through session observability and session-capsule posture |
| Read a dated narrative with provenance across subsystems | Journal export and Journal posture |
| Package evidence for a runtime failure | /incident or the runtime incident tools, which write a bounded diagnostic capsule |
| Audit tool authority decisions | Permission prompts and permission audit entries |
Capsules are part of the answer, but they are not the whole evidence system:
session continuity capsules are for handoff, while edit capsules are for
multi-file rollback. For post-run replay, start with the Agent Debugger. For a
support incident, start with /incident. For current session state across HTTP,
TUI, tools, and MCP, use Session observability parity.
What is MCP?
Section titled “What is MCP?”Model Context Protocol — a standard for connecting AI models to external tools and data sources. BMO can act as both an MCP client (consuming external tools) and an MCP server (exposing its tools to editors like Cursor, VS Code, Zed). See MCP Client and MCP Server.