Boatman

A desktop application that brings AI agents to your codebase with specialized Firefighter Mode for production incident investigation, repeatable Routines, and a Runtime inspector for recorded agent runs.

About

Boatman is a native desktop application built with Wails (Go + React) that provides a powerful interface for AI-assisted development. It includes a provider-neutral runtime layer, repeatable Routines, a specialized Firefighter Mode that integrates Linear, Bugsnag, and Datadog, and an inspectable Runtime tab for recorded runs, artifacts, events, and memory.

Features

🤖 Claude AI Agent

Interactive Chat: Ask questions, request changes, get explanations about your codebase
Code Analysis: Deep understanding of your project structure and patterns
Autonomous Actions: Edit files, run commands, create commits with your approval
Sub-Agent Tracking: Spawns specialized agents for complex multi-step tasks, with automatic context switching and per-agent message attribution
Agent Logs Panel: View messages grouped by agent in separate tabs with status indicators (active/completed)
Agent Badges: Messages show which agent produced them via inline badges
Project Management: Open and manage multiple coding projects
Task Tracking: View and monitor tasks created by the agent during sessions
Agent Logs: Real-time streaming logs panel to see agent activity and tool usage
Task Detail Modal: Clickable task cards showing diffs, feedback, plans, and issues
Provider Runtime: Sessions are shaped as provider-neutral runtime requests before adapter-specific execution

📊 Triage Mode

Backlog Analysis: Score and classify tickets from Linear using a 7-dimension AI rubric
Deterministic Classification: Hard stops for payments/auth/migrations, threshold gates for everything else
4 Categories: AI_DEFINITE, AI_LIKELY, HUMAN_REVIEW_REQUIRED, HUMAN_ONLY
Ticket Clustering: Groups related tickets by shared domains, files, and dependencies
Plan Generation: Claude explores the repo and generates validated execution plans
Execute from Triage: One click to create a BoatmanMode session with the plan pre-loaded
Real-time Progress: Live scoring progress bar and event feed during pipeline execution

See TRIAGE.md for full documentation.

🚣 BoatmanMode

Autonomous Execution: 9-step pipeline from planning through PR creation
Draft PR Checkpoint: Work preserved as draft PR before review/refactor starts
Resume Failed Runs: Pick up from review/refactor without re-executing the task
Generated File Filtering: Protobuf, GraphQL codegen, and Wails bindings excluded from review
Real-time Streaming: See planning, execution, review, and refactor phases live

🔥 Firefighter Mode

Linear Integration: Automatically monitors triage queue for production incidents
Error Investigation: Connects Bugsnag errors with Datadog logs and git history
Root Cause Analysis: Correlates deployments, code changes, and error patterns
Auto-Fix: Creates isolated worktrees, attempts fixes, runs tests, and opens PRs
Dual Workflow: Handles both ticket-based investigations and proactive monitoring
Slack Integration: Responds to @mentions for urgent production issues

🔌 MCP Integration

Extensible: Connect to any MCP-compatible tool or service
Built-in Servers: GitHub, Datadog, Bugsnag, Linear, Slack, and more
OAuth Support: Authenticate Datadog through Claude Code MCP auth and Okta SSO for enterprise integrations
Custom Servers: Build your own MCP servers for specialized workflows
MCP Server Dialog: Easy configuration and management of MCP servers via UI
Integration Health: Shows whether built-in services are ready, disabled, degraded, or missing configuration

🧭 Runtime Inspector

Run Browser: Inspect project-local .boatman/runs metadata
Event Timeline: Review normalized runtime events for phases, messages, tools, usage, schema checks, memory loads, integrations, and artifacts
Artifact Manifest: See files, diffs, PRs, or other durable outputs recorded by each run
Inspectable Memory: Read .boatman/memory Markdown context files with provenance and source run IDs

✨ Routines

Project Routine Library: Load built-ins plus .boatman/routines.json and .boatman/routines/*.json from the active project
Datadog GraphQL Slow Queries: Run the saved slow-query investigation from the desktop app
Datadog MCP Auth: Open Claude Code's Datadog MCP auth flow in an interactive terminal from the Routines tab, creating boatman-datadog-mcp on Datadog's current /v1/mcp endpoint when needed
Dry-Run Checks: Verify Datadog readiness and prompt shape before model execution
Markdown Reports: Save daily investigation output under project-local .boatman/routines

🔍 Advanced UI Features

Smart Search: Full-text search across sessions with filters (tags, dates, favorites, projects)
Favorites & Tags: Organize sessions with favorites and custom tags for easy retrieval
Batch Diff Approval: Select and approve/reject multiple file changes at once
Inline Diff Comments: Add threaded comments directly on diff lines for review discussions
Diff Summary Cards: Quick overview of file changes with stats (additions, deletions, modifications)
Onboarding Wizard: Guided first-run experience for setting up authentication and preferences
Model Selection: Choose between Claude Opus 4.6, Sonnet 4.5, Haiku 4, and Claude 3.5 Sonnet
Session Modes: Visual badges to distinguish standard, firefighter, and boatmanmode sessions
Runtime Tab: Browse recorded runs and memory without leaving the app
Routines Tab: Run repeatable Datadog investigations without dropping to the CLI

Quick Start

# Clone and build
git clone <repository-url>
cd boatmanapp
wails build

# Run
open build/bin/boatman.app

📚 First time? See the complete Getting Started Guide

Prerequisites

Required

Go 1.24.1+: Build the application
Node.js 24+: Frontend development and quality gates
Wails CLI: go install github.com/wailsapp/wails/v2/cmd/wails@latest
Claude API: Get key from https://console.anthropic.com

For Firefighter Mode

Okta Account: For SSO authentication
Linear API Token: From https://linear.app/settings/api
Datadog/Bugsnag: Access via Okta SSO
Slack Bot (optional): For alert integration

Installation

Clone the repository:

git clone <repository-url>
cd boatmanapp

Install dependencies:

wails doctor  # Check if all dependencies are installed
cd frontend && npm install && cd ..

Build the application:
```
wails build
```

The built application will be in the build/bin directory.

Firefighter Mode

Firefighter Mode is designed for on-call engineers handling production incidents. It combines Linear ticket management with Bugsnag error tracking and Datadog monitoring for automated investigation.

How It Works

Linear Ticket → Extract Context → Query Bugsnag/Datadog → Analyze Git History → Generate Report → Auto-Fix → Update Ticket

Workflow:

Monitor Linear Queue: Checks triage queue for tickets labeled "firefighter"
Investigate on Demand: Click "Investigate" button on any ticket
Gather Context: Fetches error details from Bugsnag, logs from Datadog
Code Analysis: Uses git blame to find recent changes and code owners
Root Cause: Correlates deployments, errors, and code changes
Generate Report: Creates comprehensive investigation summary
Attempt Fix: For High/Urgent tickets, creates worktree and implements fix
Test & PR: Runs tests, opens draft PR if tests pass
Update Ticket: Adds findings and PR link to Linear ticket

Key Capabilities

✅ Automated Triage: Monitors Linear queue every 5 minutes
✅ Context Correlation: Links Bugsnag errors with Datadog logs and git commits
✅ Code Ownership: Identifies responsible teams via git blame
✅ Isolated Fixes: Uses git worktrees for safe, parallel investigations
✅ Test Validation: Runs test suite before creating PRs
✅ Documentation: Generates structured reports for postmortems

See the Firefighter Mode Guide for setup instructions.

Getting Started

First Launch

Launch Boatman
Complete onboarding: Choose auth method (API key or Google Cloud OAuth)
Select default model and approval mode
Create or open a project
Start chatting!

For detailed walkthrough, see Getting Started → First Run

Usage

Standard Mode

Ask Claude anything about your codebase:

"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"

Claude can:

Read and analyze code
Edit files with your approval
Run bash commands (git, npm, tests, etc.)
Create commits and pull requests
Spawn sub-agents for complex tasks (tracked in the Agent Logs panel)

BoatmanMode Integration

Full Claude event streaming:

Each workflow phase (Planning, Execution, Review, Refactor) creates a separate agent tab
Claude's raw streaming output is forwarded via claude_stream events for full visibility
Progress messages and agent lifecycle events appear as system messages in the chat
See BOATMANMODE_INTEGRATION.md for details

Firefighter Mode

Investigate production incidents:

Click "Firefighter" button (flame icon)
View Linear triage queue in left sidebar
Click "Investigate" on any ticket
Agent automatically:
- Fetches Bugsnag error details
- Queries Datadog logs
- Analyzes git history
- Generates investigation report
- Attempts fix (if High/Urgent)
- Updates Linear ticket

BoatmanMode Integration

Autonomous ticket execution with full workflow:

Click "Boatman Mode" button (purple button in header)
Enter Linear ticket ID
Watch real-time execution with structured events:
- Planning phase with codebase analysis
- Implementation with code generation
- Test execution and validation
- Peer review with feedback
- Automated refactoring
- PR creation and ticket updates
Track progress in Tasks tab with clickable task details
Review diffs, feedback, and issues in task modals

Key Benefits:

✅ Full autonomous workflow (plan → execute → review → refactor → PR)
✅ Git worktree isolation for safe parallel work
✅ Real-time event streaming with structured task tracking

Runtime Tab

Open the Runtime tab after selecting a project. It reads:

<project>/.boatman/runs/
<project>/.boatman/memory/

Use it to answer:

Which provider, model, role, and profile handled a run?
What prompt/request shape, tools, MCP refs, schema, and approval mode were used?
What tool calls, schema checks, usage events, integration states, memory loads, and artifacts were recorded?
What memory documents might future sessions load?
Which run generated a memory document?
✅ Task metadata includes diffs, plans, feedback, and issues
✅ Integrated with CLI for subprocess execution

See documentation:

For detailed usage, see:

Development

Live Development Mode

Run the app in development mode with hot reload:

wails dev

This starts:

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

Project Structure

boatmanapp/
├── frontend/          # React TypeScript frontend
│   ├── src/
│   │   ├── components/  # UI components (MessageBubble, AgentLogsPanel, etc.)
│   │   ├── hooks/       # React hooks (useAgent for event handling)
│   │   ├── types/       # TypeScript types (AgentInfo, Message, etc.)
│   │   └── store/       # State management
├── agent/             # Agent session management (subagent tracking, stream parsing)
├── boatmanmode/       # BoatmanMode CLI integration (subprocess, event routing)
├── project/           # Project and workspace management
├── config/            # Configuration and preferences
├── git/               # Git integration
├── diff/              # Diff parsing and rendering
├── mcp/               # MCP server management
├── app.go             # Main application logic (event routing, session management)
└── main.go            # Application entry point

Configuration

User Configuration:

Settings: ~/.boatman/config.json
MCP Servers: ~/.claude/claude_mcp_config.json
Sessions: ~/.boatman/sessions/

For detailed configuration, see Configuration Guide

Build Configuration: Edit wails.json for build settings. See https://wails.io/docs/reference/project-config

Building

Development Build

wails build

Production Build

wails build -clean -production

Platform-Specific Builds

# macOS
wails build -platform darwin/universal

# Windows
wails build -platform windows/amd64

# Linux
wails build -platform linux/amd64

Built applications will be in build/bin/.

Troubleshooting

Common Issues:

# App won't launch
xattr -d com.apple.quarantine build/bin/boatman.app

# Check dependencies
wails doctor

# Test MCP server
npx -y @package/mcp-server

Full troubleshooting guide: GETTING_STARTED.md → Troubleshooting

Documentation

Getting Started Guide - Complete setup and usage
Features Guide - Comprehensive feature documentation (NEW)
Firefighter Mode - Production incident investigation
BoatmanMode Integration - Autonomous ticket execution
BoatmanMode Events - Event specification and integration
MCP Servers - Extending capabilities
Configuration - Settings and customization
BoatmanMode Integration - CLI integration and event routing
BoatmanMode Events - Event system and subagent tracking
Changelog - Version history and release notes

FAQ

Q: What models are supported? A: Claude Opus 4.6, Sonnet 4.5, Haiku 4, and Claude 3.5 Sonnet.

Q: How much does it cost? A: Boatman is free. You pay for Claude API usage (via Anthropic or Google Cloud).

Q: Is my code secure? A: Code is sent to Claude API following Anthropic's privacy policy. Use Google Cloud for private VPC.

Q: Can I use it offline? A: No, requires internet for Claude API and MCP servers.

Q: What OS is supported? A: Currently macOS (M1/M2/M3). Windows/Linux support planned.

More FAQs: Getting Started → FAQ

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

License

[Add your license here - e.g., MIT, Apache 2.0, etc.]

Support

Documentation: Getting Started Guide
Issues: GitHub Issues
Discussions: GitHub Discussions

Acknowledgments

Anthropic - Claude AI and Model Context Protocol
Wails - Native app framework
Linear, Datadog, Bugsnag - Monitoring and issue tracking integrations

Built with ❤️ for on-call engineers

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Boatman

About

Features

🤖 Claude AI Agent

📊 Triage Mode

🚣 BoatmanMode

🔥 Firefighter Mode

🔌 MCP Integration

🧭 Runtime Inspector

✨ Routines

🔍 Advanced UI Features

Quick Start

Prerequisites

Required

For Firefighter Mode

Installation

Firefighter Mode

How It Works

Key Capabilities

Getting Started

First Launch

Usage

Standard Mode

BoatmanMode Integration

Firefighter Mode

BoatmanMode Integration

Runtime Tab

Development

Live Development Mode

Project Structure

Configuration

Building

Development Build

Production Build

Platform-Specific Builds

Troubleshooting

Documentation

FAQ

Contributing

License

Support

Acknowledgments