tanagram-harness

A Claude Code plugin that gives you the full feature lifecycle in one command — isolated worktrees, dev stack orchestration, real testing, and PR creation.

/harness start fix-auth-flow
/harness test
/harness pr
/harness cleanup

Inspired by OpenAI's Harness Engineering — the idea that every feature should be developed in an isolated, bootable environment with mechanical enforcement and real validation.

Install

/plugin install ./tanagram-harness --scope user

Or from the marketplace:

/plugin marketplace add tanagram/harness
/plugin install tanagram-harness

Quick Start

1. Generate a harness.json for your project:

   npx @tanagram/harness init
   

   This detects your project structure and walks you through setup interactively. (Optional — works without one for simple single-service projects.)

2. Run /harness start my-feature

3. Develop your feature in the isolated worktree

4. Run /harness test to verify against real running services

5. Run /harness pr to create a pull request

6. Run /harness cleanup to remove the worktree and free ports

harness.json Reference

{
  "baseBranch": "origin/main",
  "envFiles": ["**/.env"],
  "services": [
    {
      "name": "api",
      "directory": "backend",
      "install": "poetry install --with dev",
      "start": "poetry run uvicorn main:app --port ${PORT}",
      "port": 8000,
      "health": "/health",
      "test": "poetry run pytest -x",
      "dependsOn": []
    },
    {
      "name": "web",
      "directory": "frontend",
      "install": "pnpm install",
      "start": "PORT=${PORT} pnpm dev",
      "port": 3000,
      "health": "/",
      "test": "pnpm test && pnpm typecheck",
      "dependsOn": ["api"],
      "env": {
        "VITE_API_BASE_URL": "http://localhost:${ports.api}"
      }
    }
  ],
  "portOffset": 10,
  "browser": { "entry": "web" }
}

Top-Level Fields

Field	Type	Default	Description
baseBranch	string	"origin/main"	Branch to create worktrees from
envFiles	string[]	["**/.env", "**/.env.local"]	Glob patterns for env files to copy into worktrees
services	Service[]	auto-detected	Services to start
portOffset	number	10	Port offset multiplier per worktree slot
browser.entry	string	first service	Which service to open in browser for verification

Service Fields

Field	Type	Required	Description
name	string	yes	Service identifier
directory	string	yes	Subdirectory relative to project root
install	string	no	Dependency install command
start	string	yes	Start command (${PORT} is substituted with the allocated port)
port	number	yes	Base port number
health	string	no	Health check endpoint path (e.g. "/health")
test	string	no	Test command
dependsOn	string[]	no	Services that must start before this one
env	object	no	Env vars to set when starting. Values support ${ports.SERVICE} to reference another service's allocated port

Without harness.json

For simple single-service projects, the plugin auto-detects:

• Node.js (package.json): npm install → npm run dev on port 3000
• Python (pyproject.toml): poetry install → poetry run uvicorn on port 8000

No config needed.

Commands

/harness start [feature-name]

Creates an isolated git worktree, copies env files, installs dependencies, starts all services with auto-allocated ports, and enters plan mode to begin development.

/harness test [feature-name]

Runs service tests per harness.json, verifies in-browser via Chrome DevTools MCP, and checks stack logs for errors. All tests run against real services — no mocks.

/harness pr [feature-name]

Stages changes, commits, pushes, and creates a GitHub PR with summary and test plan.

/harness cleanup [feature-name]

Stops all services, frees ports, removes the worktree, and optionally deletes the remote branch.

/harness status

Lists active worktrees, running stacks, and port allocations across all features.

Port Allocation

Each concurrent worktree gets a slot. Ports are offset by slot * portOffset:

Service	Base	Slot 1	Slot 2	Slot 3
api	8000	8010	8020	8030
web	3000	3010	3020	3030

Port assignments are tracked in ~/.claude/stack-registry.json.

Example Configs

Next.js App

{
  "services": [
    {
      "name": "web",
      "directory": ".",
      "install": "npm install",
      "start": "PORT=${PORT} npm run dev",
      "port": 3000,
      "health": "/",
      "test": "npm test"
    }
  ]
}

Django + React

{
  "baseBranch": "origin/main",
  "services": [
    {
      "name": "api",
      "directory": "api",
      "install": "pip install -r requirements.txt",
      "start": "python manage.py runserver 0.0.0.0:${PORT}",
      "port": 8000,
      "health": "/api/health/",
      "test": "python manage.py test"
    },
    {
      "name": "web",
      "directory": "web",
      "install": "npm install",
      "start": "REACT_APP_API_URL=http://localhost:8010 PORT=${PORT} npm start",
      "port": 3000,
      "health": "/",
      "test": "npm test",
      "dependsOn": ["api"]
    }
  ],
  "browser": { "entry": "web" }
}

Rails + Sidekiq

{
  "services": [
    {
      "name": "web",
      "directory": ".",
      "install": "bundle install",
      "start": "PORT=${PORT} bin/rails server",
      "port": 3000,
      "health": "/up",
      "test": "bin/rails test"
    },
    {
      "name": "worker",
      "directory": ".",
      "start": "bundle exec sidekiq",
      "port": 7433,
      "dependsOn": ["web"]
    }
  ]
}

How It Works

1. Worktree isolation — Each feature gets its own git worktree branched from your base branch. The main repo stays clean.
2. Port allocation — A registry at ~/.claude/stack-registry.json tracks which ports are in use across all active features. Each worktree gets a unique slot so services never collide.
3. Config-driven services — harness.json declares your services, their start commands, health checks, and test commands. The plugin handles dependency ordering, parallel installs, and health check polling.
4. Real testing — The skill explicitly instructs Claude to test against real running services, never mocks. Browser verification uses Chrome DevTools MCP.
5. State tracking — Each worktree gets a .feature-meta.json and .stack/ directory for PIDs, logs, and port assignments.

License

MIT