@damper/cli

Agent orchestration CLI for working on Damper roadmap tasks with Claude Code.

What it does

1. Picks a task from your Damper roadmap (interactive or by ID)
2. Creates an isolated git worktree for the task
3. Bootstraps context - fetches task details, project docs, and critical rules from Damper
4. Launches Claude Code with full context ready to go

Claude then handles the task lifecycle via Damper MCP - logging commits, adding notes, and completing/abandoning tasks.

Installation

# Run directly with npx (recommended)
npx @damper/cli

# Alternative: use the 'damper' command name
npx damper

# Or install globally
npm install -g @damper/cli
damper

Prerequisites

• Claude Code CLI installed
• A Damper account with an API key

Quick Start

# First time? Run setup in your project directory
cd your-project
npx @damper/cli setup

# Start working on a task
npx @damper/cli

Commands

npx @damper/cli (default)

Interactive task picker. Shows:

• In Progress - Tasks with existing worktrees you can resume
• Available - Planned tasks from your roadmap

npx @damper/cli                    # Interactive picker
npx @damper/cli --task 42          # Start specific task
npx @damper/cli --type bug         # Filter by type
npx @damper/cli --status planned   # Filter by status

npx @damper/cli setup

Configure Damper for the current project. Stores your API key in .damper/config.json.

• Checks if Claude CLI is installed
• Prompts for your project's API key
• Configures Damper MCP globally (if not already set up)

npx @damper/cli setup                # Configure current project
npx @damper/cli setup --reconfigure  # Change API key

Note: Add .damper/ to your .gitignore to keep your API key private.

npx @damper/cli status

Show all tracked worktrees and their task status.

Tracked Worktrees:

myproject (current)
  /Users/me/projects/myproject

  ● #42 [in_progress]
    Path: myproject-oauth-support
    Branch: feature/oauth-support
    Created: 2/5/2025

npx @damper/cli cleanup

Remove worktrees for completed or abandoned tasks. Interactive selection with auto-detection of:

• Completed tasks
• Abandoned tasks (unlocked in Damper)
• Missing worktree directories

Configuration

Per-Project Setup (Default)

Each project has its own API key stored in .damper/config.json:

cd project-a
npx @damper/cli setup  # Enter API key for project-a

cd ../project-b
npx @damper/cli setup  # Enter API key for project-b

API Key Resolution

The CLI looks for API keys in this order:

1. DAMPER_API_KEY environment variable (highest priority)
2. .damper/config.json in the project root
3. Global MCP config in ~/.claude/settings.json (legacy)

Environment Variables

| Variable | Description | |----------|-------------| | DAMPER_API_KEY | Override API key (useful for CI/scripts) | | DAMPER_API_URL | API URL override (default: https://api.usedamper.com) |

Workflow

Starting a New Task

$ npx @damper/cli

? Select a task to work on:
  --- Available Tasks ---
❯ #42 Add OAuth support [feature] !
  #38 Fix login timeout [bug] ~

✓ Task locked in Damper
✓ Created worktree: ../myproject-oauth-support
✓ Created TASK_CONTEXT.md
✓ Updated CLAUDE.md with task section

Starting Claude Code for task #42: Add OAuth support

Resuming Work

$ npx @damper/cli

? Select a task to work on:
  --- In Progress (your worktrees) ---
❯ #42 Add OAuth support [feature] !
    Worktree: myproject-oauth-support
  --- Available Tasks ---
  #38 Fix login timeout [bug] ~

✓ Resuming: #42 Add OAuth support
✓ Updated TASK_CONTEXT.md with latest notes

Generated Files

The CLI creates these files in the worktree:

TASK_CONTEXT.md - Full task context for Claude:

• Critical rules (must-follow patterns)
• Damper workflow instructions
• Task description and implementation plan
• Previous session notes and commits
• Project architecture docs
• Available templates and modules
• Linked customer feedback

CLAUDE.md (appended) - Task-specific section pointing to TASK_CONTEXT.md

Task Lifecycle (handled by Claude via MCP)

Once Claude is running, it handles:

• add_commit - Log commits to Damper
• add_note - Record decisions and progress
• complete_task - Mark done with summary
• abandon_task - Hand off with notes for next agent

How it Works

Worktree Isolation

Each task gets its own git worktree:

myproject/                    # Main repo
../myproject-oauth-support/   # Task #42 worktree
../myproject-fix-login/       # Task #38 worktree

The CLI automatically:

• Creates the worktree with a feature branch
• Symlinks node_modules (detects monorepo structure)
• Copies .env files

Context from Damper

The CLI fetches from Damper:

• Task details (description, plan, subtasks)
• Project context (architecture, conventions)
• Critical rules (shown prominently to Claude)
• Templates (code patterns to follow)
• Modules (monorepo structure)
• Previous agent notes (for continuity)

This context survives Claude conversation compaction because it's in local files.

State Tracking

Worktree-to-task mappings are stored in ~/.damper/worktrees.json. This enables:

• Showing "resume" options for in-progress tasks
• Detecting stale worktrees for cleanup
• Tracking across multiple projects

Parallel Work

Run multiple instances in different terminals:

# Terminal 1
npx @damper/cli --task 42

# Terminal 2
npx @damper/cli --task 38

Each task gets its own worktree and Claude session.

License

MIT