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.

import { Steps } from ‘@astrojs/starlight/components’;

1. Install BMO

   go install github.com/instagrim-dev/bmo@<release-tag>

   Replace <release-tag> with the reviewed version from the GitHub release page (for example vX.Y.Z).

   What you should see: Go downloads and compiles BMO with no errors. The binary is placed in $GOPATH/bin (usually ~/go/bin).

   Verify it worked: Run bmo --version — it should print the installed version string.

   Recovery: If the install fails, check that Go 1.26.4 or later is installed (go version), that $GOPATH/bin is on your $PATH, and that you used a published release tag instead of a placeholder.

   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. No files are modified until you explicitly approve a change.

4. Initialize the project context

   Type /init to have BMO analyze your codebase and write 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 scans your project files and writes an AGENTS.md (or your configured context file) in the project root.

   Verify it worked: Check that AGENTS.md exists in your project root and contains a project summary.

   Undo: Delete the generated AGENTS.md file. BMO does not modify any other project files during /init.

5. Ask your first question

   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. No files are modified during read-only questions.

6. Make a safe first change

   Before asking BMO to edit production code, start with a small reversible workspace change:

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

   BMO will show you the proposed change and ask for confirmation before writing.

   What you should see: BMO displays a diff of the proposed edit and waits for your approval. No file is written until you confirm.

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

   Before broad edits — checkpoint first: 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. Checkpoints preserve conversation history, todos, and workspace context — not just files — so you can explore changes freely and roll back entirely if they don’t work out.

   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|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 "Add a docstring to every exported function in ./internal/api"

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.

There is no root --session flag for resuming prior work. Use /session in the TUI to switch between saved sessions.

Understand the model

BMO is not a chat wrapper. A few things that 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 (code, review, plan, debug, sre) change how BMO prioritizes tools and structures responses.

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
• Configuration — customize BMO for your workflow
• Tools Reference — the full list of agent capabilities

Contributing to BMO itself? Start with CONTRIBUTING.md for the first local build, starter lanes, and validation commands.