Flow Awareness

Flow Awareness keeps the agent’s next move respectful of what you just did. Instead of restarting from the file on disk, the agent sees a timeline of recent file changes from your current BMO session, plus a summary of recent terminal output captured in that session — so its suggestions land on the edit-in-progress, not the version it last remembered.

Configuration

[options.flow_awareness]
enabled = true
max_file_events = 20
terminal_summary_max_chars = 2000
include_clipboard = true
clipboard_max_chars = 500
timeline_format = "separate"   # or "unified"

Options

Option	Default	Description
`enabled`	`false`	Enable flow awareness
`max_file_events`	`20`	Maximum file-change events to include per turn (0–100)
`terminal_summary_max_chars`	`2000`	Maximum characters of terminal output summary (0–10000)
`include_clipboard`	`false`	Include a snippet of clipboard text in the dev-timeline when available
`clipboard_max_chars`	`500`	Maximum characters of clipboard snippet (0–5000)
`timeline_format`	`"separate"`	`separate` (default) or `unified` — unified emits one labeled stream (file/terminal/clipboard)

What gets injected

At the start of each agent turn, BMO prepends to the prompt:

A list of recent file activity from the session, including reads and tool-driven writes/edits when available
A truncated summary of recent terminal output from Bash tool calls in the session
Optionally, a snippet of current clipboard text (when include_clipboard is true)

Use cases

Active development — agent stays aware of recent files you viewed or changed in BMO without you narrating them again
Debugging sessions — agent sees recent terminal errors as context
Clipboard snippet — when enabled, the agent sees what you have copied (e.g. code or error text) for context
Unified timeline — use timeline_format = "unified" for a single labeled stream (Cascade-style)

Operator surfaces

Surface	Purpose
`get_flow_awareness_status`	App-backed JSON posture: effective config plus recent metadata-only flow-awareness events
MCP `bmo_get_flow_awareness_status` and `GET /v1/flow-awareness/status`	Same protected JSON posture for remote/read-only automation
`bmo config show-flow-awareness`	Human-readable detached config-backed projection. Fresh CLI invocations usually show an empty recent ring because they start a new process.
`/flow-awareness` (TUI)	In-session human status with the live process-local recent ring
`list_recent_flow_awareness_events`	Strict JSON export of the recent ring only
`bmo logs … \| jq 'select(.msg\|startswith("flow_awareness."))'`	Log forensics — see tracing recipes

There is no CLI/TUI/HTTP/agent/MCP API to read the full dev-timeline body — injection stays prompt-only by design. The status readers expose bounded metadata; use list_recent_flow_awareness_events only when you need the raw recent ring rather than the full posture snapshot.

Maintainer scope, non-goals, and re-entry workflow: Workflow — Flow awareness in the product docs.