Usage

Execute a Task

BoatmanMode supports three input modes:

cd /path/to/your/project
 
# 1. Linear ticket (default)
boatman work ENG-123
 
# 2. Inline prompt
boatman work --prompt "Add a health check endpoint at /health"
 
# 3. File-based prompt
boatman work --file ./tasks/authentication.md
 
# With custom title and branch
boatman work --prompt "Add auth" --title "Authentication" --branch-name "feature/auth"

Command Options

boatman work ENG-123 --max-iterations 5        # More refactor attempts
boatman work ENG-123 --base-branch develop     # Different base branch
boatman work ENG-123 --dry-run                 # Preview without changes
boatman work ENG-123 --review-skill my-review  # Use custom review skill

All Flags

Flag	Description	Default
`--prompt`	Inline prompt text	—
`--file`	Read prompt from file	—
`--title`	Override task title (prompt/file mode)	Auto-extracted
`--branch-name`	Override branch name (prompt/file mode)	Auto-generated
`--max-iterations`	Max review/refactor iterations	3
`--base-branch`	Base branch for worktree	`main`
`--auto-pr`	Automatically create PR on success	`true`
`--dry-run`	Run without making changes	`false`
`--timeout`	Timeout in minutes for each Claude agent	60
`--review-skill`	Claude skill for code review	`peer-review`
`--extra-review-skill`	Additional review skill, repeatable	—
`--keep-draft`	Leave the successful PR as a draft	`false`
`--plan-model`	Model for `/plan` and planning	config/default
`--implementation-model`	Model for code changes and refactor work	config/default
`--skill-model`	Model for review and skill execution	config/default
`--resume`	Resume interrupted workflow from checkpoint	`false`

Watch Claude Work (Live Streaming)

Open a second terminal and run:

boatman watch

Or attach to specific tmux sessions:

tmux attach -t boatman-executor
tmux attach -t boatman-reviewer-1
tmux attach -t boatman-planner

What You'll See

Claude is working (with file write permissions)...
Activity will stream below:

Running: ls -la src/
Reading: src/api/handlers/users.go
Editing: src/api/handlers/auth.go
Writing: src/api/handlers/auth_test.go
Searching files...

Task completed!

tmux Controls

Key	Action
`Ctrl+B` then `D`	Detach from session
`Ctrl+B` then arrow keys	Switch panes

Session Management

boatman sessions list       # List active sessions
boatman sessions kill       # Kill all boatman sessions
boatman sessions kill -f    # Also kill orphaned claude processes
boatman sessions cleanup    # Clean up idle sessions

Runtime Provider Inspection

Provider commands are local checks; they do not call model APIs.

boatman providers          # Show compiled-in provider capability metadata
boatman providers --json   # Machine-readable capability output
boatman providers check    # Validate configured runtime routes

Use these before long runs when changing runtime.default_provider, runtime.role_providers, or runtime.profile_providers.

Workflow Template Inspection

Workflow commands are local checks over Boatman's built-in central-plane templates.

boatman workflows
boatman workflows --json
boatman workflows show feature
boatman workflows show firefighter --json

Templates describe stages, gates, preview points, and validation loopbacks for feature, bugfix, triage, code-review, firefighter, and research flows.

Repeatable Routines

Routines are saved, parameterized runs with integrations, runtime recording, and durable reports. They are designed to be invoked manually, from cron, from CI, or by a future Boatman scheduler.

Boatman loads built-in routines plus project routines from the current working directory, or from --workdir when provided:

.boatman/routines.json
.boatman/routines/*.json

Project routines can extend built-ins and set project defaults:

{
  "routines": [
    {
      "id": "daily-employer-gql",
      "extends": "datadog-gql-slow-queries",
      "name": "Daily Employer GraphQL",
      "defaults": {
        "graph_area": "employer",
        "service": "employer-graphql",
        "top_n": "10"
      },
      "models": {
        "plan": "claude-opus-4-6",
        "implementation": "claude-sonnet-4-5",
        "skills": "claude-sonnet-4-5"
      }
    }
  ]
}

Routine models fields are optional. Empty plan, implementation, or skills values fall back to the model selected for the run.

boatman routines
boatman routines show datadog-gql-slow-queries
boatman routines run datadog-gql-slow-queries --graph-area employer --dry-run
boatman routines run daily-employer-gql --workdir /path/to/project

Run the Datadog GraphQL slow-query routine:

export DD_API_KEY=...
export DD_APP_KEY=...
 
boatman routines run datadog-gql-slow-queries \
  --graph-area employer \
  --top-n 20 \
  --lookback 24h \
  --environment prod \
  --service employer-graphql \
  --max-remediations 3

The routine connects to the Datadog integration, passes an MCP config to capable providers such as Claude CLI, records the run under .boatman/runs, and writes a Markdown report to .boatman/routines/datadog-gql-slow-queries/<run-id>.md. The CLI routine produces a boatman_remediation_candidates block. In Desktop, Boatman automatically routes high-confidence candidates into BoatmanMode child runs that plan, create fresh worktrees, implement fixes, run validation, run peer-review plus lydia-code-review, address feedback, and leave draft PRs. If evidence is missing or ambiguous, it stops after the investigation report. Its built-in schedule is 0 8 * * *; until Boatman has a daemon scheduler, run that command from cron or GitHub Actions for daily reports.

Useful flags:

boatman routines run datadog-gql-slow-queries --graph-area employer --report-out /tmp/report.md
boatman routines run datadog-gql-slow-queries --graph-area employer --provider claude-cli --model sonnet
boatman routines run datadog-gql-slow-queries --graph-area employer --param lookback=7d
boatman work --prompt "Fix slow resolver" --keep-draft --extra-review-skill lydia-code-review --plan-model opus --implementation-model sonnet --skill-model sonnet

Integration Inspection

Boatman has shared descriptors for built-in service integrations.

boatman integrations
boatman integrations --json
boatman integrations check
boatman integrations check linear slack
boatman integrations check --emit-events

integrations check validates local environment/configuration and reports states such as ready, needs_configuration, or disabled. With --emit-events, it prints normalized runtime events. If runtime-store environment variables are set, those events are also recorded.

Recorded Runtime Runs

Project-scoped provider runs record by default:

boatman work --prompt "Add a health check endpoint"

Inspect recorded runs:

boatman runs list
boatman runs show <run-id>
boatman runs request <run-id>
boatman runs artifacts <run-id>

Useful flags:

boatman runs list --store-dir /tmp/boatman-runs
boatman runs show <run-id> --json
boatman runs artifacts <run-id> --json
boatman runs request <run-id> --json

The run store writes metadata.json, request.json, events.ndjson, and artifacts.json for each run.

Use BOATMAN_RUNTIME_STORE_DIR=/tmp/boatman-runs for a fixed store, or BOATMAN_RUNTIME_STORE=0 to disable default recording. Memory documents under .boatman/memory are loaded into provider instructions by default and recorded as memory.loaded events.

Runtime Memory Documents

Memory docs are inspectable Markdown files that future sessions can load as context.

boatman memory list
boatman memory show domains/payments
boatman memory context project domains/payments
boatman memory context --emit-event --run-id <run-id>

Useful flags:

boatman memory list --memory-dir .boatman/memory --json
boatman memory list --include-expired=false
boatman memory show domains/payments --json
boatman memory context --max-bytes 12000

Agents should read memory at run startup; background jobs and distillers write memory files with provenance so users can inspect what Boatman knows and why.

Worktree Management

boatman worktree list                    # List all worktrees
boatman worktree commit                  # Commit changes (WIP)
boatman worktree commit wt-name "msg"    # Commit with message
boatman worktree push                    # Push branch to origin
boatman worktree clean                   # Remove all worktrees

Viewing Changes Manually

# Navigate to the worktree
cd .worktrees/philmiddleton-eng-123-feature
 
# Inspect changes
git status
git diff
 
# Commit and push
git add -A
git commit -m "feat: implement feature"
git push -u origin HEAD

Checkpoint Management

# Resume an interrupted workflow
boatman work ENG-123 --resume
 
# View checkpoint history
git log --oneline --grep "\[checkpoint\]"
 
# Create a snapshot branch
boatman checkpoint snapshot "before-refactor"
 
# Squash checkpoint commits before PR
boatman checkpoint squash "feat: implement feature ENG-123"

Rollback Scenarios

# Undo last refactor attempt
git reset --hard HEAD~1
 
# Go back to before review started
boatman checkpoint rollback --step execution
 
# Restore from snapshot branch
git checkout checkpoint/ENG-123/before-review -- .

Debug Mode

For detailed structured logging:

export BOATMAN_DEBUG=1
boatman work ENG-123

This outputs structured logs showing:

Retry attempts and delays
Dropped messages
Context cancellation
Coordinator state changes

Configuration Task Modes