Memento

🌐 Visit Landing Page | 📦 Install | 📖 Docs | 🏗️ Architecture

Orchestrate AI. Manage Complexity. Ship Faster.

A terminal-based orchestrator for managing multiple Claude Code instances in parallel for complex software projects.

Memento (formerly Claude Code Orchestrator) - CLI command: claude-qb

What This Does

Memento automates the coordination of multiple AI coding instances working together on a structured project:

• Break down complex projects into tasks, subtasks, and batches
• Launch multiple Claude Code instances with pre-assigned work packages
• Validate dependencies before execution to prevent conflicts
• Monitor progress in real-time via terminal dashboard
• Track decisions (QB observations) for continuous improvement
• Generate retrospectives to capture learnings after each task

Key Features

• ✅ Parallel Execution - Run multiple subtasks concurrently within batches
• ✅ Dependency Management - Automatic validation of task prerequisites
• ✅ Real-time Monitoring - Live dashboard showing all instance progress
• ✅ Flexible Modes - Manual (display commands) or Auto (spawn instances)
• ✅ Smart Batching - Groups independent subtasks for efficient parallel execution
• ✅ QB Observation - Track human decisions to identify automation opportunities
• ✅ Retrospectives - Post-task reviews to capture learnings and patterns

Quick Start

Installation

Option 1: Install from npm (recommended)

npm install -g memento-orchestration

Option 2: Install from GitHub

npm install -g git+https://github.com/jbonomo38/claude-orchestrator.git

Option 3: Install from source

# Clone repository
git clone https://github.com/jbonomo38/claude-orchestrator.git
cd claude-orchestrator

# Install dependencies
npm install

# Build the project
npm run build

# Link for global CLI access
npm link

Your First Project

Option 1: AI-Powered Setup (Recommended)

# 1. Navigate to your project directory
cd /path/to/your/project

# 2. Run interactive setup wizard
claude-qb setup "My Project"

# The wizard will:
# - Interview you about project requirements
# - Generate detailed task breakdown
# - Let you review and approve the structure
# - Create all orchestrator files with real, specific content

# 3. Validate generated structure
claude-qb validate

# 4. Start working!
claude-qb orchestrate          # Manual mode (displays commands)
claude-qb orchestrate --auto   # Auto mode (spawns instances)

Option 2: Quick Template-Based Setup

# 1. Navigate to your project directory
cd /path/to/your/project

# 2. Generate template structure
claude-qb scaffold "My Project" --tasks 3

# 3. Edit task files manually (templates need customization)
# Edit tasks/0/TASK.md, tasks/1/TASK.md, etc.

# 4. Validate task structure
claude-qb validate

# 5. Launch orchestration
claude-qb orchestrate

Option 3: Manual Setup (Advanced)

# 1. Initialize orchestrator structure
claude-qb init

# 2. Create task files manually in tasks/ folder
# See USAGE.md for detailed file format

# 3. Validate and orchestrate
claude-qb validate
claude-qb orchestrate

Project Structure

After initialization, your project will have:

your-project/
├── orchestrator.config.yaml    # Configuration
├── tasks/
│   ├── PROJECT.yaml            # Project-level configuration
│   ├── STATUS.md               # Master status (auto-generated)
│   ├── QB_OBSERVATIONS.md      # QB decisions log
│   ├── 0/                      # Task 0
│   │   ├── TASK.md             # Task overview
│   │   ├── STRATEGY.yaml       # Execution strategy & batches
│   │   ├── CONTEXT.md          # Context files to load
│   │   ├── STATUS.md           # Runtime state
│   │   ├── QB_OBSERVATIONS.md  # Task-specific observations
│   │   └── RETROSPECTIVE.md    # Post-task review
│   ├── 1/                      # Task 1
│   └── ...
└── logs/
    └── orchestrator.log

Core Commands

AI-Powered Setup (Recommended)

claude-qb setup "Project Name"

Interactive wizard that uses Claude to gather requirements and generate your project:

1. Requirements Interview: Claude asks detailed questions about your project
2. Work Breakdown: Generates task/subtask structure based on your answers
3. Human Review: You review and approve the bullet-point breakdown
4. File Generation: Creates all orchestrator files with specific, actionable content (not templates!)

Multi-Project Support:

• First run creates tasks/ directory
• Subsequent runs create tasks-2/, tasks-3/, etc.
• The setup/ directory is reused for all projects

Example:

# First project
claude-qb setup "REST API Backend"
# → Creates tasks/

# Second project (in same codebase)
claude-qb setup "Admin Dashboard"
# → Creates tasks-2/

# Work on specific project
claude-qb orchestrate -d tasks       # Work on REST API
claude-qb orchestrate -d tasks-2     # Work on Admin Dashboard

Key Benefits vs. Scaffold:

• ✅ Real, specific content (not generic templates)
• ✅ AI understands your requirements before generating
• ✅ Review and iterate on structure before generation
• ✅ Saves hours of manual file editing
• ✅ Better dependency analysis

Quick Scaffold

# Generate template structure
claude-qb scaffold "Project Name" --tasks 3

# With sequential execution
claude-qb scaffold "Project Name" --sequential

Quickly generates template project structure. Note: Generated files contain placeholder content that requires manual editing.

Initialize Project

claude-qb init

Creates orchestrator configuration and task directory structure for manual setup.

Validate Tasks

# Validate all tasks
claude-qb validate

# Validate specific task
claude-qb validate 3

Checks task file structure, YAML validity, and dependency correctness.

Orchestrate

# Manual mode - displays commands for you to run
claude-qb orchestrate

# Auto mode - automatically spawns Claude Code instances
claude-qb orchestrate --auto

# Configure max concurrent instances
claude-qb orchestrate --auto --max-concurrent 2

Manual Mode (Default):

• Detects ready batches
• Displays launch commands
• You copy/paste commands to spawn instances
• Safer for first-time use

Auto Mode:

• Automatically spawns instances
• Monitors STATUS.md for completion
• Launches next batch when ready
• Requires --auto flag for safety

Launch Batch

# Generate launch command for next ready batch
claude-qb launch

# Launch specific batch
claude-qb launch --batch task-3-batch-1

# Generate executable script
claude-qb launch --script ./launch.sh
chmod +x ./launch.sh
./launch.sh

Monitor Status

# Quick status summary
claude-qb status

# Interactive dashboard (coming soon)
claude-qb run

Generate Retrospective

# Create retrospective template for completed task
claude-qb retro 3

Opens editor with retrospective template pre-filled with task metadata.

Analyze Observations

# Export and analyze QB observations
claude-qb observations

Reviews all QB decisions and identifies patterns for automation.

Cleanup Orphaned Instances

# Kill all running Claude Code instances
claude-qb cleanup

# Non-interactive cleanup
claude-qb cleanup --force

# Dry run (show what would be killed)
claude-qb cleanup --dry

Use this command when:

• Orchestrator crashed and left orphaned instances
• Need to stop all work immediately
• Testing/debugging instance lifecycle

What it does:

1. Finds all running Claude Code instances (via ps or tasklist)
2. Sends SIGTERM for graceful shutdown (waits 5s by default)
3. Force kills with SIGKILL if instances don't respond
4. Clears instance references from STATUS.md (sets status back to QUEUED)

Example:

$ claude-qb cleanup
🧹 Claude Code Instance Cleanup

Found 2 running instance(s):

  • PID 12345: claude-code implement 3.2
  • PID 12346: claude-code implement 3.3

Kill all instances? (y/N): y

Sending SIGTERM to 2 instance(s)...
  ✅ Sent SIGTERM to PID 12345
  ✅ Sent SIGTERM to PID 12346

Waiting 5000ms for graceful shutdown...
✅ All instances terminated gracefully

Clearing instance references in STATUS.md...
✅ Cleared 2 instance reference(s)

✅ Cleanup complete

Configuration

Edit orchestrator.config.yaml to customize behavior:

orchestrator:
  mode: manual                    # 'manual' or 'auto'
  max_concurrent_instances: 4     # Max parallel instances
  polling_interval_ms: 5000       # Status check frequency

spawning:
  platform: auto                  # 'windows', 'linux', 'macos', 'auto'
  terminal: auto                  # 'wt', 'gnome-terminal', 'iterm2', 'tmux', 'auto'
  layout: tabs                    # 'tabs', 'windows', 'panes'

status_updates:
  require_start_update: true      # Instances must update STATUS.md on start
  require_completion_update: true # Instances must update STATUS.md on finish
  start_timeout_seconds: 30       # Max time to report start
  stall_timeout_minutes: 30       # Mark stalled if no update

context:
  enable_enhanced_context: true   # 4-level intelligent context
  include_module_readme: true     # Module-specific docs
  include_codebase_index: false   # Full project index (opt-in)
  token_limits:
    target_tokens: 50000          # Target context size
    max_tokens: 100000            # Maximum before truncation

Context Configuration

Claude Orchestrator generates intelligent context for each subtask using a 4-level system. By default, CODEBASE_INDEX.md is NOT included to reduce context overhead.

To include the full codebase index in all subtask contexts:

# orchestrator.config.yaml
context:
  include_codebase_index: true

Trade-off: Including CODEBASE_INDEX.md adds ~4,100 tokens to every subtask's context. Enable only when subtasks need comprehensive project structure visibility (integration tasks, exploration, etc.).

Context Levels:

• Level 1: Core project files (STATUS.md, PROJECT.yaml, STRATEGY.yaml)
• Level 2: Direct dependencies (output files from prerequisite subtasks)
• Level 3: Transitive dependencies (imports discovered via static analysis)
• Level 4: Module context (module READMEs, utilities, optional CODEBASE_INDEX.md)

Execution Modes

Manual Mode (Recommended for First Use)

claude-qb orchestrate

• What it does: Monitors tasks and displays launch commands
• You control: When and how to spawn instances
• Best for: Learning the system, debugging, precise control

Auto Mode (Hands-free Operation)

claude-qb orchestrate --auto

• What it does: Automatically spawns instances for ready batches
• Requires: orchestrator.config.yaml configured correctly
• Best for: Production workflows, unattended execution

Task File Format

See USAGE.md for comprehensive guide to creating task files.

Key Files:

• PROJECT.yaml - Project-wide configuration (waves, dependencies)
• TASK.md - High-level task overview
• STRATEGY.yaml - Batch configuration and execution strategy
• CONTEXT.md - List of files for instances to read
• STATUS.md - Runtime state (auto-updated by instances)

Workflow Example

# 1. Initialize project
cd my-big-project
claude-qb init

# 2. Create task structure manually or with templates
# Edit tasks/PROJECT.yaml, tasks/0/TASK.md, tasks/0/STRATEGY.yaml, etc.

# 3. Validate structure
claude-qb validate
# ✅ Validation passed!

# 4. Launch manual orchestration
claude-qb orchestrate
# 📦 Detected ready batch: task-0-batch-1 (2 subtasks)
#
# 📋 Launch commands:
# claude-code "Read /tasks/0/CONTEXT.md and implement subtask 0.1"
# claude-code "Read /tasks/0/CONTEXT.md and implement subtask 0.2"

# 5. Copy/paste commands to spawn instances
# (Open 2 terminal tabs and run commands)

# 6. Watch orchestrator detect completion
# ✅ Batch task-0-batch-1 completed!
# 📦 Detected ready batch: task-0-batch-2 (1 subtask)

# 7. After task complete, generate retrospective
claude-qb retro 0
# Opens editor with template

# 8. Review observations
claude-qb observations
# Analyzes patterns in QB decisions

How Instances Update Status

Spawned Claude Code instances must update STATUS.md at key points:

// On start
statusManager.updateSubtask('0', '0.1', {
  status: 'IN_PROGRESS',
  instance: 'instance-12345',
  started_at: new Date().toISOString()
})

// On completion
statusManager.updateSubtask('0', '0.1', {
  status: 'COMPLETE',
  completed_at: new Date().toISOString(),
  duration_minutes: 15
})

// On blocker
statusManager.updateSubtask('0', '0.1', { status: 'BLOCKED' })
statusManager.addBlocker({
  subtask: '0.1',
  instance: 'instance-12345',
  message: 'Dependency 0.0 not complete',
  detected_at: new Date().toISOString(),
  resolved: false
})

See USAGE.md for detailed instance protocol.

Troubleshooting

STATUS.md not updating

• Check file permissions (should be writable)
• Verify instances are calling StatusManager correctly
• Look for file locking issues

Instances not spawning (auto mode)

• Verify orchestrator.config.yaml exists
• Check terminal setting matches your environment
• Try manual mode first to debug

Dependencies not validating

• Run claude-qb validate to check task structure
• Verify dependencies arrays in STRATEGY.yaml are correct
• Check STATUS.md shows prerequisite subtasks as COMPLETE

Batch not detected

• Ensure all dependencies for batch subtasks are COMPLETE
• Check for BLOCKED subtasks that need resolution
• Verify no subtasks in batch are already IN_PROGRESS

Development

# Install dependencies
npm install

# Run in development mode (with watch)
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm test -- --watch

# Build for production
npm run build

# Lint
npm run lint

# Format code
npm run format

Architecture

• Status Management - StatusManager handles STATUS.md CRUD operations
• Task Parsing - TaskParser extracts metadata from TASK.md and STRATEGY.yaml
• Dependency Validation - DependencyChecker verifies prerequisites before execution
• Batch Planning - BatchPlanner groups subtasks into executable batches
• Orchestration Loop - OrchestrationLoop watches STATUS.md and coordinates execution
• Command Building - CommandBuilder generates platform-specific launch commands
• QB Observation - QBLogger tracks human decisions for pattern analysis

See ARCHITECTURE.md for detailed design documentation.

Backlog Management

Claude QB includes a comprehensive backlog management system for planning and organizing work.

Quick Start

# Create a new backlog item
claude-qb backlog create "My Feature" --priority HIGH

# Generate project from backlog spec
claude-qb setup --from-backlog 001

# View dependencies
claude-qb backlog deps 001

Key Features

• Structured Planning - Create detailed specifications before implementation
• Freshness Checking - Detect when specs become outdated
• Dependency Tracking - Visualize relationships between backlog items
• QB Decision Points - Capture decision points for human review during setup
• Auto-Generation - Convert backlog specs into complete project structures

See Backlog Workflow for complete guide.

Philosophy

Manual QB Mode (Current): Human "quarterback" approves batches and resolves blockers. System handles monitoring, validation, and coordination.

Future Evolution:

• Semi-auto mode - Automate patterns learned from QB observations
• Full-auto mode - Fully autonomous orchestration with human oversight

QB observations during manual use inform what to automate next.

Contributing

Contributions welcome! Please:

1. Follow existing code conventions (see CLAUDE.md)
2. Add tests for new features
3. Update documentation
4. Run npm run lint and npm test before committing

License

MIT

Learn More

• USAGE.md - Comprehensive usage guide with examples
• ARCHITECTURE.md - System design and architecture
• CLAUDE.md - Developer guide and conventions