Getting Started

First Run

1. Launch Boatman

   open build/bin/boatman.app
   # or double-click the app in Finder

2. Complete Onboarding

   • Choose authentication method:
     • Anthropic API: Enter your API key
     • Google Cloud: Sign in with OAuth
   • Select default model (recommended: Claude Sonnet 4.5)
   • Choose approval mode:
     • Suggest Mode: You approve all changes (safest)
     • Auto-Edit Mode: Claude edits files, asks for bash commands
     • Full Auto: Claude has full control (use with caution)

3. Create or Open a Project

   • Click "New Project" and select your codebase directory
   • Or open a recent project from the sidebar

4. Start Chatting

   • Click "New Session" to start a conversation
   • Ask questions about your code, request changes, or get explanations

5. Inspect Runtime Context

   • Open the Runtime tab for the active project
   • Review recorded runs, normalized events, artifacts, and memory documents
   • Use this when you want to understand what Boatman did, which provider handled the work, or what context future sessions may load

6. Run Repeatable Routines

   • Open the Routines tab for the active project
   • Click Authenticate if Datadog MCP needs Claude Code auth, then finish it in the terminal window. Boatman will create a current boatman-datadog-mcp server if the Claude plugin endpoint is stale.
   • Run the Datadog GraphQL slow-query routine
   • Review the report in the tab or under .boatman/routines

Sessions

Creating a Session

1. Click "New Session" button
2. Type your message in the input area
3. Claude will respond with analysis, code suggestions, or actions

Session Features

Agent Interactions

Claude can:

• Read and analyze your codebase
• Search for files and code patterns
• Edit files with your approval
• Run bash commands (with approval in suggest/auto-edit modes)
• Create git commits and PRs
• Spawn sub-agents for complex tasks

Example Prompts

"Review this pull request and suggest improvements"
"Find why the authentication is failing"
"Refactor the payment service to use async/await"
"Explain how the database migration system works"
"Add unit tests for the user service"

Approval Modes

Suggest Mode (Safest)

• Claude proposes all changes
• You review and approve each edit/command
• Best for production codebases
• Full control over what gets changed

Auto-Edit Mode (Balanced)

• Claude can edit files directly
• Still asks permission for bash commands
• Good for trusted environments
• Saves time on file edits

Full Auto Mode (Risky)

• Claude has complete autonomy
• No approval required for any action
• Use only in sandboxed/test environments
• Maximum speed, minimum safety

Keyboard Shortcuts

Git Integration

Boatman can:

• Create commits with proper messages
• Generate PRs with descriptions
• Create worktrees for parallel work (firefighter mode)
• Run git blame for code ownership

Runtime Inspector

The Runtime tab reads files from the active project:

.boatman/
  runs/
  memory/

Runs

Each recorded runtime run includes:

• Provider, model, role, profile, status, and timestamps
• Original provider-neutral request, including prompt previews, tools, MCP refs, and approval mode
• Searchable and filterable normalized event stream
• Artifact manifest for files, diffs, PRs, or other durable outputs

Memory

Memory documents are Markdown files with frontmatter. Boatman loads non-expired documents as prompt context for future sessions, records a memory.loaded event, and users can inspect the exact context directly in the Runtime tab before trusting it.

Live Development Mode

For developing the desktop app itself:

wails dev

This starts:

• A Vite development server for fast frontend hot reload
• A dev server at http://localhost:34115 for browser-based development