Shipr

Fully autonomous terminal-based coding agent

Shipr takes a plain-English mission description and produces a production-ready, committed codebase — or halts cleanly without touching git.

Install

npm install -g shipr-agent

Or run directly without installing:

npx shipr-agent --help

Quick Start

# 1. Authenticate with an AI provider
shipr auth add github-copilot    # GitHub Device Flow (opens browser)
shipr auth add openai             # paste your API key
shipr auth add anthropic          # paste your API key

# 2. Verify authentication
shipr auth list

# 3. Navigate to your project
cd my-project/

# 4. Run a mission
shipr run "Add user authentication with JWT and refresh tokens"

Commands

shipr run <mission>

Run an autonomous coding mission. This is the main command.

# Basic usage — uses the first authenticated provider
shipr run "Build a REST API with CRUD endpoints for users and posts"

# Choose a specific provider
shipr run --provider github-copilot "Add WebSocket real-time notifications"
shipr run --provider openai "Refactor the database layer to use Prisma"
shipr run --provider anthropic "Write comprehensive test coverage"

# Dry run — plan without executing (no files changed)
shipr run --simulate "Migrate from Express to Fastify"

# Set a cost budget (halts if exceeded)
shipr run --budget 5.00 "Build an admin dashboard"

# Run slices in parallel (up to 4)
shipr run --parallel 4 "Add search, filtering, and pagination"

# Use the rich Ink-based TUI
shipr run --rich "Build a payment integration"

What happens during a mission:

PREFLIGHT  →  Analyzes your codebase (files, frameworks, dependencies)
CLARIFY    →  Asks clarifying questions (press Enter to accept defaults)
RESEARCH   →  Studies codebase structure + web research
PLAN       →  Creates a task DAG (directed acyclic graph) of work
EXECUTE    →  Dispatches tasks to the AI, writes code, validates each step
VERIFY     →  Runs 6-layer verification (typecheck, lint, test, build, custom, security)
COMMIT     →  Squash-merges all changes into a clean commit

shipr new <name>

Scaffold a new project from a template.

shipr new my-api --type api          # Express + TypeScript API
shipr new my-app --type web-app      # React + Vite web app
shipr new my-cli --type cli          # Commander CLI tool
shipr new my-lib --type library      # npm library with build
shipr new my-svc --type monorepo     # Turborepo monorepo
shipr new my-bot --type fullstack    # Full-stack app

shipr status

Show the current mission's state and progress.

shipr status

  Shipr  Mission: Build a REST API with auth
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ Status: EXECUTING
  Slices: 3/6 done   Tasks: 9/18 done
  Estimated cost: $2.00
  Actual cost: $0.3280 (34 API calls)
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

shipr resume

Resume a previously interrupted or failed mission.

shipr resume                        # auto-find the most recent resumable mission
shipr resume --mission m_abc123     # resume a specific mission
shipr resume --provider anthropic   # resume with a different provider

shipr steer <instruction>

Send a mid-mission steering directive. Picked up at the next slice boundary.

shipr steer "Use PostgreSQL instead of SQLite"
shipr steer "Skip the admin dashboard, focus on the API"
shipr steer "Add rate limiting to all endpoints"

shipr cost

Show cost and token usage across all missions.

shipr cost                    # all missions
shipr cost --mission m_abc123 # specific mission

  💰 Cost Summary

  m_abc123  Build a REST API with auth
     Cost: $0.3280  Input: 186.4K  Output: 34.2K  Calls: 34
  m_def456  Add WebSocket notifications
     Cost: $0.1890  Input: 98.1K   Output: 19.7K  Calls: 22
  ──────────────────────────────────────────────────
  Total  Cost: $0.5170  Input: 284.5K  Output: 53.9K  Calls: 56

shipr auth

Manage API credentials. Stored in OS keychain (macOS Keychain, Linux libsecret) — never on disk.

shipr auth add openai          # add API key for a provider
shipr auth add github-copilot  # GitHub Device Flow (browser-based)
shipr auth list                # show all providers and auth status
shipr auth revoke openai       # remove stored credentials

shipr providers

List all 16 supported AI providers with models, pricing, and context windows.

shipr providers

shipr missions

List all past and current missions.

shipr missions

Supported Providers

| Provider | Auth | Models | |---|---|---| | Anthropic | API key | Claude Sonnet 4, Opus 4, Haiku 3.5 | | OpenAI | API key | GPT-4o, GPT-4o-mini, o3 | | Google Gemini | API key | Gemini 2.5 Pro, 2.5 Flash | | GitHub Copilot | Device Flow | GPT-4o, Claude Sonnet 4 (free with subscription) | | Groq | API key | Llama 3.3 70B, Mixtral | | Mistral | API key | Mistral Large, Codestral | | xAI | API key | Grok 2 | | DeepSeek | API key | DeepSeek V3, Coder V3 | | OpenRouter | API key | 20+ models from all providers | | Cohere | API key | Command R+, Command R | | Perplexity | API key | Sonar Large, Sonar Small | | AWS Bedrock | AWS credentials | Claude, Llama, Mistral on AWS | | Azure OpenAI | OAuth | GPT-4o, GPT-4 on Azure | | Ollama | Local | Any local model | | LM Studio | Local | Any local model | | vLLM | Local | Any local model |

How It Works

┌─────────────────────────────────────────────────────────┐
│  "Add user authentication with JWT"                     │
└──────────────────────┬──────────────────────────────────┘
                       │
          ┌────────────▼────────────┐
          │      PREFLIGHT          │  Analyze codebase
          │  Files, frameworks,     │  Estimate cost
          │  dependencies, tests    │  Zero LLM tokens
          └────────────┬────────────┘
                       │
          ┌────────────▼────────────┐
          │      CLARIFY            │  Ask smart questions
          │  "JWT or sessions?"     │  LLM-generated
          │  "Which database?"      │
          └────────────┬────────────┘
                       │
          ┌────────────▼────────────┐
          │      RESEARCH           │  Codebase: static analysis
          │  Import graph, deps,    │  Web: LLM-powered search
          │  frameworks, patterns   │
          └────────────┬────────────┘
                       │
          ┌────────────▼────────────┐
          │      PLAN               │  Create task DAG
          │  S01: Schema setup      │  Ordered by risk
          │  S02: Auth middleware    │  Dependencies tracked
          │  S03: CRUD endpoints    │
          └────────────┬────────────┘
                       │
          ┌────────────▼────────────┐
          │      EXECUTE            │  For each task:
          │  Build context packet   │   → LLM generates code
          │  Dispatch to LLM        │   → Apply file changes
          │  Apply changes          │   → Hallucination guard
          │  Run guards             │   → Stub detector
          └────────────┬────────────┘
                       │
          ┌────────────▼────────────┐
          │      VERIFY             │  6-layer gate:
          │  ✓ typecheck            │   TypeScript compiler
          │  ✓ lint                 │   Biome/ESLint
          │  ✓ test                 │   bun test/jest
          │  ✓ build                │   Build command
          │  ✓ custom               │   User scripts
          │  ✓ security             │   Pattern scanning
          └────────────┬────────────┘
                       │
          ┌────────────▼────────────┐
          │      COMMIT             │  Squash-merge
          │  Clean commit message   │  Generate REPORT.md
          │  Back to main branch    │  Cleanup worktree
          └─────────────────────────┘

Safety Guarantees

• No commit unless all 6 verify layers pass — zero errors tolerated
• Git worktree isolation — mission work happens on a separate branch
• Test immutability — tests are never modified to make them pass
• Hallucination guard — rejects empty/unchanged file responses
• Stub detector — rejects TODO/FIXME/placeholder code
• Stuck detector — halts on repeated identical responses or zero progress
• Budget enforcement — halts if cost exceeds per-mission or monthly limit
• No force push — ever
• Atomic file writes — temp + rename for crash safety
• No plaintext credentials — OS keychain or AES-256-GCM encrypted fallback

Configuration

Create .shipr/config.yaml in your project (or ~/.shipr/config.yaml for global defaults):

# Default provider and model
provider: github-copilot
model: gpt-4o

# Budget limits
budget:
  perMission: 5.00    # USD per mission
  perMonth: 50.00     # USD per calendar month

# Execution
parallel: 2            # max concurrent slices (1-8)

# Verify gate
verify:
  custom: "npm run check"   # custom verification command

Project Structure

After a mission, Shipr creates a .shipr/ directory in your project:

.shipr/
  config.yaml          # project-level configuration
  missions/
    M-abc123/
      MISSION.json     # mission metadata
      STATE.json       # state machine state
      PLAN.json        # task DAG
      RESEARCH.json    # codebase + web research findings
      LEDGER.json      # cost/token tracking
      CONTEXT.md       # task summaries and context
      STEER.md         # steering directives
      REPORT.md        # narrative completion report

License

MIT