claude-harness

Claude Code Long-Running Agent Harness

A Claude Code plugin for automated, context-preserving coding sessions with 5-layer memory architecture, failure prevention, test-driven features, and GitHub integration.

Based on Anthropic's engineering article and enhanced with patterns from:

• Context-Engine - Memory architecture
• Agent-Foreman - Task management patterns
• Autonomous-Coding - Test-driven approach

TL;DR - End-to-End Workflow

Quick Start

# Step 1: Add the marketplace (registers the catalog)
/plugin marketplace add panayiotism/claude-harness-marketplace

# Step 2: Install the plugin
/plugin install claude-harness@claude-harness

Or from the terminal:

claude plugin marketplace add panayiotism/claude-harness-marketplace
claude plugin install claude-harness@claude-harness

# Initialize in your project (one-time)
cd your-project && claude
/claude-harness:setup

# Single command for entire workflow (start → do → checkpoint → merge)
/claude-harness:flow "Add user authentication with JWT tokens"
# Auto-compiles context, creates issue/branch, implements, checkpoints, merges

# Or batch-process all active features autonomously with TDD
/claude-harness:flow --autonomous

# Or step-by-step without auto-merge
/claude-harness:flow --no-merge "Add user authentication with JWT tokens"

The /flow command handles the entire lifecycle automatically - from context compilation to PR merge. It enforces test-driven development practices with a RED-GREEN-REFACTOR cycle and acceptance testing. Use --team for ATDD with Agent Teams (tester + implementer + reviewer). Use --autonomous to batch-process all active features. Use --no-merge for step-by-step control, --quick to skip planning for simple tasks.

Complete Workflow (5 Commands Total)

# 1. SETUP (one-time)
/claude-harness:setup                              # Initialize harness in project

# 2. START SESSION (or skip with /flow)
/claude-harness:start                              # Compile context, show status

# 3. DEVELOPMENT (unified /flow command)
/claude-harness:flow "Add dark mode"               # Complete lifecycle in one command
/claude-harness:flow --no-merge "Add feature"      # Stop at checkpoint (don't auto-merge)
/claude-harness:flow --autonomous                   # Batch-process all features
/claude-harness:flow --fix feature-001 "Token bug" # Bug fix linked to feature
/claude-harness:flow feature-001                   # Resume existing feature/fix

# 4. MANUAL CHECKPOINT (optional - /flow includes checkpoint)
/claude-harness:checkpoint               # Commit, push, create PR

# 5. RELEASE
/claude-harness:merge                    # Merge all PRs, close issues

What Happens Behind the Scenes

/setup           → One-time: Creates .claude-harness/ with memory architecture

/start           → Compiles working context from 4 memory layers
                   Shows status, syncs GitHub, displays learned rules

/flow            → UNIFIED END-TO-END WORKFLOW:
                   1. Auto-compiles context (replaces /start)
                   2. Creates feature (GitHub issue + branch)
                   3. Plans implementation (checks past failures)
                   4. Implements feature with TDD enforcement
                   5. Verifies: RED → GREEN → REFACTOR
                   6. Auto-checkpoints when all tests pass
                   7. Auto-merges when PR approved
                   Options: --no-merge, --quick, --autonomous,
                            --plan-only, --fix, --team
                   --autonomous: Batch loop through ALL features
                                 (context-isolated: each feature runs
                                  in a fresh subagent context window)
                   OPTIMIZATIONS: Parallel memory reads, cached GitHub parsing

/checkpoint      → Manual commit + push + PR (when not using /flow)
                   Auto-reflects on user corrections

/merge           → Merges PRs in dependency order
                   Closes linked issues
                   Cleans up branches

v3.0 Memory Architecture

.claude-harness/
├── memory/
│   ├── episodic/    → Rolling window of 50 recent decisions
│   ├── semantic/    → Persistent project architecture & patterns
│   ├── procedural/  → Append-only success/failure logs (never repeat mistakes)
│   └── learned/     → Rules from user corrections (self-improving)
├── features/        → Shared feature registry (active.json, archive.json)
└── sessions/        → Per-session state (gitignored, enables parallel work)
    └── {uuid}/      → Each Claude instance gets isolated loop/context state

Session Cleanup (Automatic)