How BMO thinks and acts
BMO is not just chat attached to a model. It is a terminal-native system where the agent operates against the same BMO-managed workspace state you do: shared tools, filesystem access, and—when BMO is running with the full app—the same session/message store and data directory.
The short version
Section titled “The short version”- One workspace, multiple entry points. The TUI, CLI, HTTP server, and MCP surfaces are different ways to work with the same underlying system.
- Tools are the action layer. File edits, shell commands, LSP actions, schedules, parity reads, and remote delegation all happen through explicit capabilities instead of hidden side effects.
- Workflows build on primitives. Staged workflow, recipes, teams, mesh,
and the automation engine’s declarative layers (
options.automation.jobsandoptions.automation.rules) are higher-order behaviors that still rely on observable tool and state transitions. - Background work stays inspectable. Nanites, workstreams, explicit markers, and workspace trail make side work and bounded cross-session hints visible instead of hiding them in model memory.
- Coherence is evidence-backed. BMO records operational activity in inspectable surfaces, retrieves named context, and summarizes state from provenance instead of asking users to trust hidden memory.
- Factory-shaped work stays inspectable. When a task spans planning, delegation, review, and verification, workstreams and recorded results make the outcome inspectable after interruption.
- Adaptation is bounded. BMO can change coordination behavior, tool packing, or background scheduling, but those layers are scoped, inspectable, and not marketed as unconstrained autonomy.
- The constitution is inspectable.
bmo config show-constitution,/constitution,get_constitution_posture, andbmo://constitution/statusreport authority seams, drift warnings, and non-goals without granting permissions or changing runtime state.
What “agent-native” means
Section titled “What “agent-native” means”BMO treats the agent as part of the product architecture, not as an external assistant. Context, tools, permissions, plans, memory, review, orchestration, and recovery are explicit system surfaces that the user can inspect and control.
In practice, this means:
- Context is visible. BMO shows which session, workspace, files, protocol surfaces, and runtime signals are shaping a run.
- Actions are routed through named tools. Reads, edits, shell commands, workflow operations, and delegation are not hidden behind a generic answer.
- Control points stay explicit. Staged workflow, permissions, auto-checkpoint, interrupt handling, and review surfaces define where the agent may act and where the operator can stop or redirect it.
- Work can move between surfaces. The same architecture supports interactive TUI work, CLI runs, server/API use, MCP/A2A integrations, and multi-agent workflows without pretending they are unrelated products.
Agent-native does not mean BMO should do everything automatically. BMO’s design bias is bounded agency: the system can act, but important state, risk, and recovery paths remain visible.
Shared workspace
Section titled “Shared workspace”When BMO is running with the full app, you and the agent share the same session/message store, the same data directory, and the same process-owned runtime signals. That is why features like slash commands, session observability, agent debugger traces, and parity tools line up instead of describing different worlds.
Shell commands share the configured working directory and exported process environment, but they do not run inside your already-open interactive shell. BMO starts a tracked POSIX-compatible command runner for each shell tool call so permission prompts, cancellation, background jobs, and captured output stay attached to the requested action.
Shared workspace does not mean unmanaged writes. Full-app runs keep a
process-local workspace_claim registry for path ownership. Soft claims
publish intent, hard claims block BMO mutation paths that consult the claim
guard, and /workspace-claims shows the active claim state. Claims coordinate
BMO-owned tools; they are not OS-level locks and they do not protect against
external editors or separate BMO processes.
Minimal bmo serve-mcp integrations can expose scoped filesystem tools
without loading the full session/message database; that path is intentional and
differs from full-app shared state above.
For contributors: The full shared-workspace contract (full app vs minimal MCP) is documented in the repository topic
shared-workspace.md.
How a request becomes work
Section titled “How a request becomes work”- You ask for something in the TUI, CLI, HTTP, or MCP surface.
- BMO assembles prompt context from session state, enhancer inputs, config, mode, tools, and runtime overlays.
- The model decides whether to answer directly, call primitive tools, or use a workflow tool such as staged workflow, mesh delegation, or a recipe.
- Tool calls update shared workspace state.
- Observability surfaces tell you what happened and inform the next turn.
For the end-to-end flow, see Workflow map.
Beginner-safe vs advanced layers
Section titled “Beginner-safe vs advanced layers”| Layer | Maturity | Best for | Start here |
|---|---|---|---|
| Core chat + file/code tools | Daily-use | Everyday code understanding and edits | Quickstart |
| Session modes + staged workflow | Daily-use | More predictable review, planning, and delivery loops | Staged Workflow |
| Multi-agent work | Advanced | Parallel subtasks inside one session | Multi-Agent Workflows |
| Background micro-runs | Advanced | Bounded side checks that report back to the parent session/workstream | Nanites |
| Durable work cells | Advanced | Repeatable workstreams with plans, recipes, evidence, markers, and handoffs | Workstreams and Factory Patterns |
| Remote agent discovery | Advanced | Choosing peers by capability instead of URL | Agent Mesh |
| Runtime replay and support evidence | Maintainer-facing | Diagnosing what happened after a run or support incident | Agent Debugger and Session observability parity |
| Evaluation apparatus | Eval-only | Measuring classifier, routing, prompt, and background-signal behavior | Shadow Evals and Session Mode Autoselect Eval |
| Adaptive coordination | Advanced | Letting BMO reshape coordination intent per session | Adaptive Orchestration |
| Background stewardship | Advanced | Idle-gated compaction, automation jobs, and daemon-backed work | Compaction and Automation & Headless |
Inspectable coherence and layered regulation
Section titled “Inspectable coherence and layered regulation”BMO stays coherent over time by recording operational activity, retrieving named context, synthesizing from provenance, and routing work through explicit tools and regulators. Adaptive subsystems — orchestration, mesh biasing, health follow-ons, workspace observation — each operate inside clear boundaries with well-defined precedence rules and bounded feedback loops.
Internally, BMO calls this design the “organism” metaphor because layered biological regulation is a useful analogy for how these boundaries work. The user-facing point is simpler: every adaptive behavior is scoped, inspectable, and limited to its own domain. BMO is not presented as a human-like agent or unconstrained autonomous system.
For contributors: Precedence rules and non-goals are detailed in the repository topic
ai-organism-constitution.md.