Quickstart

This page is the shortest first-run path: install, authenticate, start a session, make a safe first edit, and learn enough of the mental model to keep going. Each step links to fuller reference pages when you need more detail.

1. Install BMO

   BWO stable v2.1.0 provides BMO binary builds for authorized BWO repository readers. Select your OS/architecture, verify its complete SHA-256 digest, and follow the version-specific installation notes. The executable remains bmo; bmo --version should report bmo version v2.1.0. Preview and nightly remain empty.

   Full details: Installation

2. Set your API key

   The simplest way is to export it in the same terminal you will use to start BMO:

   export ANTHROPIC_API_KEY=sk-ant-...

   Or set it in your shell profile so it’s always available. See Authentication for all supported providers.

   Verify it worked: Run test -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY configured" — it should print the confirmation without revealing the secret. If it prints nothing, re-export or check your shell profile.

3. Start BMO in your project

   cd your-project
   bmo

   BMO opens the interactive TUI. On first run you’ll be prompted for an API key if none is set.

   What you should see: The TUI launches with a prompt input area and a sidebar. If the API key is missing, BMO shows a key-entry prompt instead.

   Recovery: Press ctrl+c or type /quit to exit BMO at any time. Tool actions follow the active policy and permission grants; some can run without a new prompt.

4. Initialize the project context

   Type /init to have BMO ask the agent to analyze your codebase and create or refresh the configured project context file (AGENTS.md by default). This improves response quality in new sessions in that project.

   /init

   What you should see: BMO starts an initialization run that analyzes the project and proposes or writes the configured context file in the project root (or configured path).

   Verify it worked: Check that the configured context file exists and contains a project summary.

   Review: Inspect the context-file diff. If the file already existed, preserve its prior content and unrelated edits when undoing changes. Delete it only if this run created it and you do not want to keep it.

5. Ask your first question

   Switch to /mode chat to use a mode without file-editing or shell tools, then try understanding your codebase:

   What does this project do?

   Where is the main entry point?

   What are the most important files I should know about?

   What you should see: BMO streams a conversational answer describing your project. Chat mode limits the available tools; asking a read-only question by itself does not change tool permissions.

6. Make a safe first change

   Switch to /mode code, then start with a small reversible workspace change:

   Create scratch/bmo-first-edit.md with a one-paragraph summary of what this project does

   What you should see: BMO requests a file-writing tool. Depending on your policy and existing grants, it may ask for approval or execute directly. Review the resulting file and diff.

   You and the agent share the same workspace — there is no separate staging area or hidden branch.

   Save session state: Open the Sessions dialog, select the session, then press ctrl+k to create a checkpoint. To restore one later, press ctrl+e to open that session’s Checkpoints list, then press Enter (or r) on the checkpoint you want. A successful restore rewinds conversation history, todos, and session file-history/read-file state when retained transcript identity still matches; it refuses when that prefix is missing or changed. It does not restore files on disk; use version control or backups for file recovery. See Sessions.

   Undo a file change: For the scratch file above, delete it. For a tracked file, use git diff <file> first. Restore only that file after confirming it contains no unrelated edits: git restore -- <file>.

Essential slash commands

Command	What it does
/new	Start a fresh session
/session	Switch between sessions
/model	Switch AI model mid-session
/mode [code|chat|coordinator|review|debug|plan|sre]	Change session mode
/summarize	Compact context when it gets long
/thinking	Toggle extended reasoning
/help	Open the Commands palette for /tools and /capabilities discovery
/slash-status	Inspect slash discovery posture and recent routing outcomes when slash behavior seems surprising
/tools	Open the Commands palette on the Tools tab
/pack	Open the operating pack picker for session overlays such as cautious, delivery, or workspace sensing
/capabilities	Show what BMO can do
/review	Run the built-in code review command
/pr-ready	Run the built-in pre-merge readiness check
/quit	Exit BMO

Open this guide from BMO

From inside BMO, press ctrl+p (or type /) to open the Commands palette, then choose Docs (or type /docs). That opens the Quickstart guide in your default browser.

Essential keyboard shortcuts

Key	What it does
ctrl+p	Open the slash command picker
ctrl+m	Open the model picker
ctrl+s	Switch sessions
shift+tab	Cycle session modes
ctrl+l	Toggle the sidebar
esc	Interrupt the active run

Run a one-off task (no TUI)

bmo run "Summarize the README and identify the project entry points"

What you should see: BMO prints its progress and final output to stdout, then exits with code 0 on success. Use echo $? to check the exit code.

For tasks requiring writes, configure permissions deliberately; a headless request that needs an interactive approval is refused when no approval listener is available. See Automation.

Resume an existing session with bmo --session-id <id> or use /session in the TUI. To continue without the TUI, use bmo run --session-id <id> "Continue the task".

Understand the model

Three things matter early:

• Shared workspace. You and the agent operate against the same files, session state, and data directory. Edits are real edits.
• Tools are explicit. File reads, shell commands, LSP actions, and everything else happen through named capabilities that you can inspect.
• Modes shape behavior. Session modes shape tool availability and how BMO approaches the task.

For the full mental model, read How BMO Thinks and Acts.

Next steps

• Common Workflows — practical patterns for daily coding
• Workflow Map — how requests turn into tool use and automation
• Keyboard Shortcuts — learn the core TUI controls
• CLI Commands — full command reference
• Change synthesis — advanced, opt-in evaluation of a specification you write; it does not replace the first-run edit above
• Mutation aftercare — how a reserved file effect is recorded, separate from git auto-checkpoint
• Configuration — customize BMO for your workflow
• Tools Reference — the full list of agent capabilities

Contributing to BMO itself requires access to the source tree. Use CONTRIBUTING.md there for the first local build and validation commands.