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.

flowchart TD
    user["You"] --> surfaces["TUI / CLI / HTTP / MCP"]
    surfaces --> coordinator["Coordinator"]
    coordinator --> prompt["Prompt assembly"]
    coordinator --> actions["Primitive tools and workflow tools"]
    prompt --> model["Model provider"]
    model --> actions
    actions --> workspace["Shared workspace state"]
    workspace --> observability["Debugger, status bar, parity tools"]
    workspace --> regulation["Adaptive orchestration, mesh, compaction, health signals"]
    regulation --> coordinator

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.jobs and options.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 /v1/constitution/posture, get_constitution_posture, bmo_get_constitution_posture, and bmo://constitution/status report authority seams, drift warnings, and non-goals without granting permissions or changing runtime state. They also report whether the answer is checkout-backed or embedded-fallback-only and route maintainers to the canonical review workflow. When BMO cannot resolve a repo root, those surfaces fall back to an embedded baseline rather than pretending the checkout itself was validated.

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.
Uncertainty is inspectable. Decision posture shows whether BMO is ready to act, should ask, should inspect a cheap surface, or should avoid an unsafe step.
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

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. When durable hard claims are explicitly enabled, hard claims also block overlapping BMO mutation tools in sibling BMO processes that share the same data directory. Claims coordinate BMO-owned tools; they are not OS-level locks and they do not protect against external editors, shell commands, or non-BMO writers.

Minimal bmo service start 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

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.

Where to look when something feels wrong

Not every debugging question needs the same surface. BMO keeps replay, bounded summary, incident capture, narrative audit, and handoff state split on purpose so each tool can stay honest about what it knows.

If you need to answer…	Start here	Why this is the right first stop
What just happened in this session, and where should I drill next?	Run Observability	It is the bounded read for counts, latest run, cue phase, and routing without opening the full timeline.
What happened step by step in one run?	Agent Debugger	It is the durable event timeline for prompt assembly, tool calls, checkpoints, and terminal status.
Who acts next, and what evidence should confirm that move?	Run Observability / cue ledger	Cue ledger is the compact next-action projection rather than a replay surface.
The TUI wedged, stalled, or feels operationally opaque.	Runtime incident capture	Incident capture writes the bounded evidence bundle for wedge-style and liveness investigation.
I need the dated cross-subsystem story, not just one run.	Journal	Journal derives a narrative over existing telemetry instead of replaying one run in isolation.
I need a durable handoff after interruption or context pressure.	Session continuity capsules	Continuity capsules preserve bounded continuation state without making the transcript the source of truth.

The order is usually: bounded summary first, full replay second, incident or narrative surfaces only when the question is bigger than one run.

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	Conversation quality, 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

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.

Agent-native architecture map

Agent-native architecture

Operator

You and the terminalPrompts, approvals, steering, interrupts, and recovery all stay visible.

Surfaces

TUI / CLI / HTTP / MCP / A2ADifferent entrypoints share the same product concepts instead of separate agent worlds.

Coordinator

Prompt assembly and tool policyContext, mode, permissions, tools, and model selection converge before inference.

Execution

Primitive tools, workflows, and providersReads, edits, shell, LSP, recipes, delegation, and model calls are explicit actions.

State

Shared workspace and run ledgerSession, messages, events, checkpoints, memory, and artifacts form the inspectable substrate.

Regulation

Observability, compaction, orchestration, and healthDebugger, status bar, pruning, adaptive layers, and follow-ons keep long work bounded.

BMO is agent-native because tools, state, authority, and observability are first-class product surfaces.