Skip to content
Shipwright

FAQ

General

What is Shipwright?

Shipwright is a CLI tool that orchestrates Claude Code agent teams in tmux. It provides a premium dark theme, team session management, autonomous development loops, delivery pipelines, AI-powered intelligence layer, and DORA metrics — everything you need to run multi-agent AI development effectively.

What does Shipwright do that Claude Code doesn’t?

Claude Code has built-in agent teams support, but Shipwright adds the infrastructure around it:

  • Team templates — 24 pre-built compositions for common SDLC tasks, plus 8 pipeline templates
  • Quality gate hooks — block agents until code passes checks
  • Delivery pipeline — full issue-to-PR automation with self-healing builds
  • Autonomous daemon — background issue processing with DORA metrics
  • Repo preparation — auto-generate configs for any project
  • Intelligence layer — AI-powered triage, dynamic pipeline composition, self-optimization, and predictive analytics
  • tmux theme — premium dark theme with agent-aware pane borders

Is Shipwright free?

Yes. Shipwright is open source under the MIT license. You need your own Anthropic API key (or Claude Code subscription) to use Claude Code itself.

Do I need tmux?

Yes. Shipwright uses tmux to give each agent its own terminal pane. This is what makes it possible to watch multiple agents working simultaneously. tmux 3.2+ is required.

Terminal window
brew install tmux    # macOS
sudo apt install tmux  # Linux

Claude Code

What Claude models work with Shipwright?

Any model supported by Claude Code. The agent teams feature works with all Claude models. Recommended setup:

  • Team lead + workers: Sonnet (good balance of speed and quality)
  • Subagent lookups: Haiku (fast and cheap for file searches)
  • Architecture decisions: Opus (best reasoning)

How many agents can I run?

The practical limit is 2-3 agents per team. More than that increases the risk of tmux race conditions and creates coordination overhead that exceeds the parallel benefit.

Does it work with Claude Code in VS Code?

Not for the split-pane experience. VS Code’s integrated terminal doesn’t support the tmux integration needed for agent pane spawning. However, you can run tmux in an external terminal (iTerm2, Alacritty, etc.) while keeping VS Code open for editing.

How much does it cost to run agent teams?

Cost depends on your Claude Code plan and usage. Each agent in a team uses its own context window. Tips to control costs:

  • Use CLAUDE_CODE_SUBAGENT_MODEL=haiku for subagent lookups
  • Set CLAUDE_CODE_AUTOCOMPACT_PCT_OVERRIDE=70 for aggressive context management
  • Keep teams small (2-3 agents)
  • Keep tasks focused (5-6 per agent)

Pipeline & Daemon

What’s the difference between shipwright loop and shipwright pipeline?

  • shipwright loop — Runs Claude Code in a loop for a single goal. Ideal for focused tasks like “build this feature” or “fix this bug.”
  • shipwright pipeline — Chains the full SDLC (intake → plan → build → test → review → PR). The build stage actually uses shipwright loop internally. Use pipeline for end-to-end automation.

Can the daemon create PRs automatically?

Yes. When the daemon spawns a pipeline for a GitHub issue, the pipeline can run through to PR creation fully autonomously (depending on the pipeline template and gate settings). The autonomous template has all gates set to auto-approve.

Does the pipeline work without GitHub?

Yes, but with reduced functionality. Without GitHub:

  • Use --goal instead of --issue
  • No auto-assignment or progress comments
  • PR creation step is skipped (or creates a local branch)

Intelligence

What is the intelligence layer?

The intelligence layer is a set of 7 modules that replace hardcoded heuristics with AI-powered analysis. Instead of word-count scoring and label regex for triage, Claude semantically analyzes each issue. Instead of picking from static templates, Claude composes a custom pipeline per issue. All intelligence features are behind feature flags and off by default — enable them in daemon-config.json.

Does intelligence cost extra?

Intelligence features use Claude API calls, so they add some token usage. However, the self-optimization and model routing modules actively reduce overall cost by routing cheaper models to simpler stages. The net effect depends on your workload, but the system aims to pay for itself through smarter resource allocation.

What happens if intelligence calls fail?

Every intelligence function degrades gracefully to the existing static behavior. If Claude is unavailable, triage falls back to word-count scoring, template selection falls back to score thresholds, and patrol falls back to grep-based checks. The system never blocks on an intelligence failure.

Cost & Memory

How does cost intelligence work?

Shipwright tracks token usage for every pipeline stage and records it to ~/.shipwright/costs.json. You can set a daily budget with shipwright cost budget set <amount>, and the daemon auto-scaler will factor remaining budget into its worker count decisions. Use shipwright cost show --by-stage to see where tokens are spent across the pipeline, or --by-issue to compare cost per issue. Model pricing is built in for Opus, Sonnet, and Haiku.

What is persistent memory?

Persistent memory captures learnings from every pipeline run — failure patterns, root causes, design decisions, and codebase conventions. When a future pipeline starts, relevant memories are injected into the agent’s context so it avoids repeating past mistakes. Memory is stored per-repo with optional cross-repo global sharing. Use shipwright memory show to view captured knowledge and shipwright memory search <keyword> to find specific entries.

Configuration

How do I customize the tmux theme?

Edit the hex color values in tmux/tmux.conf and reload with prefix + r. The main colors to change:

  • #1a1a2e — background
  • #e4e4e7 — foreground
  • #00d4ff — accent (active borders, highlights)

Can I use my own tmux config?

Yes. The installer can add Shipwright’s config as a source overlay rather than replacing your existing config. The overlay (shipwright-overlay.conf) only adds agent-aware pane styling, color hooks, and team keybindings.

How do I add custom hooks?

Create a shell script in ~/.claude/hooks/ and wire it up in ~/.claude/settings.json. See the Configuration reference for examples.