Configuration

BoatmanMode is configured through a YAML file, environment variables, and CLI flags.

Configuration File

Create ~/.boatman.yaml (global) or .boatman.yaml in your project root (project-specific):

# Linear API key (or set LINEAR_API_KEY env var)
linear_key: lin_api_xxxxx
 
# Claude CLI tools
enable_tools: true
 
# Workflow settings
max_iterations: 5
base_branch: main
auto_pr: true
review_skill: peer-review
extra_review_skills:
  - lydia-code-review
keep_draft_pr: false
 
# Review pass criteria
review:
  max_critical_issues: 1
  max_major_issues: 3
  min_verification_confidence: 50
  strict_parsing: false
 
# Claude CLI settings
claude:
  command: claude
  use_tmux: false
  large_prompt_threshold: 100000
  timeout: 0
  enable_prompt_caching: true
 
  # Multi-model strategy per agent type
  models:
    planner: claude-sonnet-4-5
    executor: claude-sonnet-4-5
    reviewer: claude-sonnet-4-5
    refactor: claude-sonnet-4-5
    preflight: claude-haiku-4
    test_runner: claude-haiku-4
 
# Runtime provider routing
runtime:
  default_provider: claude-cli
  role_providers:
    reviewer: claude-cli
    routine: claude-cli
  profile_providers:
    triage-scorer: openai-responses
    routine.datadog-gql-slow-queries: claude-cli
 
# Coordinator settings
coordinator:
  message_buffer_size: 1000
  subscriber_buffer_size: 100
 
# Retry settings
retry:
  max_attempts: 3
  initial_delay: 500ms
  max_delay: 30s
 
# Token budgets for handoffs
token_budget:
  context: 8000
  plan: 2000
  review: 4000
 
# Feature toggles
enable_preflight: true
enable_tests: true
enable_diff_verify: true
enable_memory: true
checkpoint_dir: ~/.boatman/checkpoints
memory_dir: ~/.boatman/memory

Environment Variables

Variable	Description	Required
`LINEAR_API_KEY`	Linear API key for ticket fetching	Yes (for Linear mode)
`CLAUDE_CODE_USE_VERTEX`	Set to `1` for Vertex AI	If using Vertex
`CLOUD_ML_REGION`	Vertex AI region	If using Vertex
`ANTHROPIC_VERTEX_PROJECT_ID`	GCP project ID	If using Vertex
`ANTHROPIC_API_KEY`	Anthropic API key	If using direct API
`BOATMAN_DEBUG`	Set to `1` for debug output	No
`BOATMAN_PROVIDER`	Default runtime provider override	No
`BOATMAN_EXTRA_REVIEW_SKILLS`	Comma-separated additional review skills, such as `lydia-code-review`	No
`BOATMAN_RUNTIME_EVENTS`	Set to `1` to emit normalized runtime events alongside legacy events	No
`BOATMAN_RUNTIME_STORE`	Set to `0` to disable default project-local recording, or `1` to force recording in older paths	No
`BOATMAN_RUNTIME_STORE_DIR`	Custom runtime run store directory	No
`BOATMAN_CHECKPOINT_DIR`	Custom checkpoint directory	No
`BOATMAN_MEMORY_DIR`	Custom memory directory	No
`DD_API_KEY`	Datadog API key for Datadog MCP routines	For Datadog routines
`DD_APP_KEY`	Datadog app key for Datadog MCP routines	For Datadog routines
`DD_SITE`	Datadog site, defaults to `datadoghq.com`	No
`OPENAI_API_KEY`	OpenAI API key for the OpenAI Responses provider	If using OpenAI
`OPENAI_MODEL`	Default model for the OpenAI Responses provider when not set by the request	If using OpenAI without per-run model
`LINEAR_API_URL`	Override Linear API URL (for testing)	No

Model Configuration

Each agent in the workflow can use a different Claude model for cost optimization:

Available Models

Model	ID	Best For
Claude Opus 4.6	`claude-opus-4-6`	Highest quality: complex planning, nuanced code generation
Claude Sonnet 4.5	`claude-sonnet-4-5`	Good balance of quality and cost
Claude Haiku 4	`claude-haiku-4`	Fast and cheap: validation and parsing tasks

Configuration Profiles

Maximum quality:

claude:
  models:
    planner: claude-opus-4-6
    executor: claude-opus-4-6
    reviewer: claude-opus-4-6
    refactor: claude-opus-4-6
    preflight: claude-haiku-4
    test_runner: claude-haiku-4

Balanced (recommended):

claude:
  models:
    planner: claude-sonnet-4-5
    executor: claude-sonnet-4-5
    reviewer: claude-sonnet-4-5
    refactor: claude-sonnet-4-5
    preflight: claude-haiku-4
    test_runner: claude-haiku-4

Cost-optimized:

claude:
  models:
    planner: claude-sonnet-4-5
    executor: claude-sonnet-4-5
    reviewer: claude-haiku-4
    refactor: claude-haiku-4
    preflight: claude-haiku-4
    test_runner: claude-haiku-4

If a model field is omitted, the Claude CLI's default model is used.

For one-off work runs, you can override the common phases directly:

boatman work --prompt "Fix slow resolver" \
  --plan-model claude-opus-4-6 \
  --implementation-model claude-sonnet-4-5 \
  --skill-model claude-sonnet-4-5

Routine definitions use the provider-neutral shape:

{
  "models": {
    "plan": "claude-opus-4-6",
    "implementation": "claude-sonnet-4-5",
    "skills": "claude-sonnet-4-5"
  }
}

Runtime Provider Routing

Boatman workflows build provider-neutral runtime requests, then route those requests to a provider adapter. The default adapter is claude-cli.

runtime:
  default_provider: claude-cli
  role_providers:
    planner: claude-cli
    reviewer: claude-cli
  profile_providers:
    triage-scorer: openai-responses
    triage-planner: claude-cli

Profile routes are the narrowest match and take precedence over role routes. Role routes take precedence over runtime.default_provider.

Inspect compiled-in providers:

boatman providers
boatman providers --json
boatman providers check

OpenAI Responses

The openai-responses adapter supports text output, structured output schemas, remote MCP descriptors, hosted tool descriptors, raw response preservation, and broker-backed local function calls.

export OPENAI_API_KEY=sk-...
export OPENAI_MODEL=<model-name>
boatman providers check

Use provider routing to opt individual roles or profiles into OpenAI while the rest of the workflow stays on Claude CLI.

Runtime Store And Memory

Recorded runtime runs are plain files:

.boatman/runs/<run-id>/
  metadata.json
  request.json
  events.ndjson
  artifacts.json

Project-scoped provider runs record per project by default:

boatman work --prompt "Update documentation"

Or write to a fixed location:

export BOATMAN_RUNTIME_STORE_DIR=/tmp/boatman-runs

Memory documents are Markdown files under .boatman/memory or BOATMAN_MEMORY_DIR. They include frontmatter for scope, provenance, source run, generated time, updated time, and optional expiration.

Provider calls load non-expired memory documents automatically unless BOATMAN_MEMORY=0 is set. Loaded documents are prepended to the provider instructions and recorded as memory.loaded events.

Review Configuration

Control how strict the peer review system is:

review:
  max_critical_issues: 1           # Max critical issues to still pass
  max_major_issues: 3              # Max major issues to still pass
  min_verification_confidence: 50  # Min confidence % for diff verification
  strict_parsing: false            # Strict keyword parsing for reviews

Review Profiles

Profile	Critical	Major	Confidence	Strict Parsing
Strict	0	1	70%	true
Balanced (default)	1	3	50%	false
Lenient	2	5	40%	false

Coordinator Configuration

For parallel agent execution:

coordinator:
  message_buffer_size: 1000      # Main message channel buffer
  subscriber_buffer_size: 100    # Per-agent channel buffer

Increase these if you see "coordinator message channel full" warnings.

Retry Configuration

Control retry behavior for API calls:

retry:
  max_attempts: 3       # Number of retry attempts
  initial_delay: 500ms  # Initial delay between retries
  max_delay: 30s        # Maximum delay (exponential backoff)

Token Budget Configuration

Control context sizes for agent handoffs:

token_budget:
  context: 8000   # General context budget
  plan: 2000      # Plan handoff budget
  review: 4000    # Review handoff budget

Handoff	Content	Default Budget
Plan to Executor	Summary, approach, files	~4000 tokens
Executor to Reviewer	Requirements, diff, test results	~3000 tokens
Reviewer to Refactor	Issues (deduplicated), guidance	~2000 tokens

Installation Usage