# Prodigy Session Documentation for Claude
This document explains how Prodigy manages sessions and provides information to Claude during development iterations.
## Overview
Prodigy is a workflow orchestration tool that executes Claude commands through structured YAML workflows. It manages session state, tracks execution progress, and supports parallel execution through MapReduce patterns.
## Error Handling Guidelines (Spec 101)
### Production Code Requirements
**CRITICAL**: Production code must NEVER use `unwrap()` or `panic!()` directly. All error conditions must be handled gracefully using Result types and the `?` operator.
#### Prohibited Patterns in Production Code
```rust
// NEVER DO THIS in production code:
let value = some_option.unwrap(); // Will panic on None
let result = some_result.unwrap(); // Will panic on Err
panic!("Something went wrong"); // Explicit panic
```
#### Required Patterns for Error Handling
```rust
// DO THIS instead:
let value = some_option.context("Failed to get value")?;
let result = some_result.context("Operation failed")?;
return Err(anyhow!("Something went wrong"));
```
#### Safe Fallback Patterns
```rust
// For Options:
let value = some_option.unwrap_or(default_value);
let value = some_option.unwrap_or_else(|| compute_default());
// For Results:
let value = some_result.unwrap_or(default_value);
let value = some_result.unwrap_or_else(|e| {
log::warn!("Failed with error: {}, using default", e);
default_value
});
```
### Test Code Exceptions
Test code MAY use `unwrap()` and `panic!()` as they serve as appropriate test failure mechanisms:
```rust
#[test]
fn test_something() {
let result = function_under_test();
assert!(result.is_ok());
let value = result.unwrap(); // OK in tests - will fail test on error
}
```
### Static Compilation Patterns
For compile-time constants like regex patterns that are known to be valid:
```rust
// OK - Regex is statically known to be valid
});
```
### Error Context Best Practices
1. **Always add context** when propagating errors:
```rust
file_operation()
.context("Failed to perform file operation")?;
```
2. **Include relevant details** in error messages:
```rust
read_file(&path)
.with_context(|| format!("Failed to read file: {}", path.display()))?;
```
3. **Use appropriate error types** for each module:
- Storage operations: `StorageError`
- Worktree operations: `WorktreeError`
- Command execution: `CommandError`
- General operations: `anyhow::Error`
### Troubleshooting Common Issues
#### Issue: "thread 'main' panicked at..."
**Cause**: An `unwrap()` or `panic!()` in production code
**Solution**: Find the location in the stack trace and replace with proper error handling
#### Issue: "called `Option::unwrap()` on a `None` value"
**Cause**: Attempting to unwrap a None Option
**Solution**: Use `unwrap_or()`, `unwrap_or_else()`, or `?` operator with context
#### Issue: "called `Result::unwrap()` on an `Err` value"
**Cause**: Attempting to unwrap an Err Result
**Solution**: Use `?` operator to propagate the error or handle it explicitly
### Validation and Testing
All error handling changes must:
1. Pass existing tests without modification
2. Include new tests for error paths
3. Maintain backward compatibility
4. Provide clear error messages for debugging
## Claude Command Observability (Spec 121)
### JSON Log Location Tracking
Prodigy captures the location of Claude JSON log files for debugging Claude command execution, especially useful for troubleshooting MapReduce agent failures.
#### What are Claude JSON Logs?
Claude Code creates detailed JSON log files for each command execution containing:
- Complete message history (user messages and Claude responses)
- All tool invocations with parameters and results
- Token usage statistics (input, output, cache tokens)
- Session metadata (model, tools available, timestamps)
- Error details and stack traces
These logs are stored in:
```
~/.local/state/claude/logs/session-{session_id}.json
```
#### Accessing JSON Log Location
**Via Verbose Output (-v flag):**
```bash
prodigy run workflow.yml -v
```
With verbose mode, Prodigy displays the JSON log location after each Claude command:
```
Executing: claude /my-command
Claude JSON log: /Users/username/.local/state/claude/logs/session-abc123.json
✓ Command completed
```
**Programmatically via ExecutionResult:**
```rust
let result = execute_claude_command(&cmd).await?;
if let Some(log_path) = result.json_log_location() {
println!("Debug logs available at: {}", log_path);
}
```
**In MapReduce Events:**
```rust
// AgentCompleted events include json_log_location
MapReduceEvent::AgentCompleted {
job_id: "job-123".to_string(),
agent_id: "agent-1".to_string(),
duration: Duration::seconds(30),
commits: vec!["abc123".to_string()],
json_log_location: Some("/path/to/logs/session-xyz.json".to_string()),
}
```
**In Dead Letter Queue (DLQ) Items:**
```rust
// Failed items capture json_log_location in FailureDetail
let dlq_item = DeadLetteredItem {
// ... other fields ...
failure_history: vec![
FailureDetail {
// ... error details ...
json_log_location: Some("/path/to/logs/session-xyz.json".to_string()),
}
],
};
```
#### Debugging with JSON Logs
**View complete Claude interaction:**
```bash
```bash
cat ~/.local/state/claude/logs/session-abc123.json | jq '.usage'
```
**Extract error details:**
```bash
```bash
cat /path/from/step1/session-xyz.json | jq
```
3. **Identify the failing tool or message:**
```bash
cat /path/from/step1/session-xyz.json | jq '.messages[-3:]'
```
4. **Understand the context:**
- Review the full conversation history
- Check what tools were invoked and their results
- Examine token usage to identify context issues
- Look for error messages or unexpected responses
#### API Integration
The json_log_location field is available in:
- `AgentResult` - Captures log path for successful and failed agent executions
- `MapReduceEvent::AgentCompleted` - Includes log path in event stream
- `MapReduceEvent::ClaudeMessage` - Associates messages with their log files
- `FailureDetail` - Preserves log location for DLQ debugging
## Custom Merge Workflows
Prodigy now supports configurable merge workflows that execute when merging worktree changes back to the main branch. This allows you to customize the merge process with your own validation, conflict resolution, and post-merge steps.
### Merge Workflow Configuration
You can define a custom merge workflow in your YAML file using the `merge` block:
```yaml
# Custom merge workflow
merge:
commands:
- shell: "git fetch origin"
- shell: "git merge origin/main" # Merge main into worktree first
- shell: "cargo test" # Run tests
- shell: "cargo clippy" # Run linting
- claude: "/prodigy-merge-worktree ${merge.source_branch}"
- shell: "echo 'Successfully merged ${merge.worktree}'"
timeout: 600 # 10 minutes timeout for merge operations
```
### Merge-Specific Variables
The following variables are available in merge workflows:
- `${merge.worktree}` - Name of the worktree being merged
- `${merge.source_branch}` - Source branch (worktree branch)
- `${merge.target_branch}` - Target branch (usually main or master)
- `${merge.session_id}` - Session ID for correlation
### Claude Merge Streaming
The Claude merge command now respects the same verbosity settings as other workflow commands:
- With `-v` (verbose) or higher, you'll see real-time JSON streaming output from Claude
- Set `PRODIGY_CLAUDE_CONSOLE_OUTPUT=true` to force streaming output regardless of verbosity
- This provides full visibility into Claude's merge operations and any tool invocations
### Example Workflows
#### Pre-merge Validation
```yaml
merge:
commands:
- shell: "cargo build --release"
- shell: "cargo test --all"
- shell: "cargo fmt --check"
- claude: "/prodigy-merge-worktree ${merge.source_branch}"
```
#### Conflict Resolution Strategy
```yaml
merge:
commands:
- shell: "git merge origin/main --no-commit"
- claude: "/resolve-conflicts"
- shell: "git add -A"
- shell: "git commit -m 'Merge main and resolve conflicts'"
- claude: "/prodigy-merge-worktree ${merge.source_branch}"
```
## MapReduce Workflow Syntax
Prodigy supports MapReduce workflows for massive parallel processing. The syntax follows the specification in the whitepaper:
### Basic MapReduce Structure
```yaml
name: workflow-name
mode: mapreduce
# Optional setup phase
setup:
- shell: "generate-work-items.sh"
- shell: "analyze-codebase --output items.json"
# Map phase: Process items in parallel
map:
input: "items.json" # JSON file with array of items
json_path: "$.items[*]" # JSONPath to extract items
agent_template:
- claude: "/process '${item}'"
- shell: "test ${item.path}"
on_failure:
claude: "/fix-issue '${item}'"
max_parallel: 10 # Number of concurrent agents
filter: "item.score >= 5" # Optional: filter items
sort_by: "item.priority DESC" # Optional: process order
max_items: 100 # Optional: limit items per run
# Reduce phase: Aggregate results
reduce:
- claude: "/summarize ${map.results}"
- shell: "echo 'Processed ${map.successful}/${map.total} items'"
```
### Key Syntax Changes from Previous Versions
- **Agent Template**: No longer uses nested `commands` array - commands are directly under `agent_template`
- **Reduce Phase**: Commands are directly under `reduce`, not nested under `commands`
- **Error Handling**: Simplified `on_failure` syntax without `max_attempts` and `fail_workflow`
- **Removed Parameters**: No longer supports `timeout_per_agent`, `retry_on_failure`, or other deprecated parameters
## Directory Structure
### Local Storage (Legacy)
```
.prodigy/
├── session_state.json # Current session state and timing
├── validation-result.json # Workflow validation results
├── events/ # MapReduce event logs (legacy)
│ └── {job_id}/ # Job-specific events
│ ├── {timestamp}.json # Individual event records
│ └── checkpoint.json # Job checkpoint for resumption
└── dlq/ # Dead Letter Queue for failed items (legacy)
└── {job_id}.json # Failed work items for retry
```
### Global Storage (Default)
```
~/.prodigy/
├── events/
│ └── {repo_name}/ # Events grouped by repository
│ └── {job_id}/ # Job-specific events
│ └── events-{timestamp}.jsonl # Event log files
├── dlq/
│ └── {repo_name}/ # DLQ grouped by repository
│ └── {job_id}/ # Job-specific failed items
├── state/
│ └── {repo_name}/ # State grouped by repository
│ └── mapreduce/ # MapReduce job states
│ └── jobs/
│ └── {job_id}/ # Job-specific checkpoints
└── worktrees/
└── {repo_name}/ # Git worktrees for sessions
```
## Session Management
### Session State (`session_state.json`)
Tracks the current cooking session:
```json
{
"session_id": "cook-1234567890",
"status": "InProgress|Completed|Failed",
"started_at": "2024-01-01T12:00:00Z",
"iterations_completed": 2,
"files_changed": 5,
"worktree_name": "prodigy-session-123",
"iteration_timings": [[1, {"secs": 120, "nanos": 0}]],
"command_timings": [["claude: /prodigy-lint", {"secs": 60, "nanos": 0}]]
}
```
### Environment Variables
When executing Claude commands, Prodigy sets these environment variables:
- `PRODIGY_AUTOMATION="true"` - Signals automated execution mode
Claude JSON streaming is enabled by default for all Claude commands to ensure workflow auditability. To disable streaming (e.g., in CI/CD environments with storage constraints), set:
- `PRODIGY_CLAUDE_STREAMING="false"` - Explicitly disables JSON streaming and uses legacy print mode
## Global Storage Architecture
### Overview
Prodigy uses a global storage architecture by default, storing all events, state, and DLQ data in `~/.prodigy/`. This enables:
- **Cross-worktree event aggregation**: Multiple worktrees working on the same job share event logs
- **Persistent state management**: Job checkpoints survive worktree cleanup
- **Centralized monitoring**: All job data accessible from a single location
- **Efficient storage**: Deduplication across worktrees
## MapReduce Features
### Parallel Execution
Prodigy supports parallel execution of work items across multiple Claude agents:
- Each agent runs in an isolated git worktree
- Work items are distributed automatically
- Results are aggregated in the reduce phase
- Failed items can be retried via the DLQ
### Worktree Isolation (Spec 127)
**All MapReduce workflow phases (setup, map, reduce) execute in an isolated git worktree**, ensuring the main repository remains untouched during workflow execution.
#### Execution Flow
```
Main Repository (untouched during execution)
↓
Worktree Created: ~/.prodigy/worktrees/{project}/session-mapreduce-{id}
↓
Setup Phase → Executes in parent worktree
↓
Map Phase → Each agent executes in child worktree (branched from parent)
↓
Reduce Phase → Executes in parent worktree
↓
Merge Phase → Merges parent worktree changes to main repo (user confirmed)
```
#### Isolation Guarantees
1. **Setup Phase Isolation**
- Creates dedicated worktree before setup phase execution
- All setup commands execute in the worktree directory
- File modifications occur in worktree, not main repo
- Git commits are created in worktree context
- Main repository remains clean until final merge
2. **Map Phase Isolation**
- Each map agent runs in its own child worktree
- Child worktrees branch from the parent worktree (setup results)
- No cross-contamination between agents
- Independent failure isolation
3. **Reduce Phase Isolation**
- Executes in parent worktree (same as setup)
- Aggregates results from all map agents
- Continues worktree isolation guarantee
#### Benefits
- **Safety**: Main repository never modified during execution
- **Parallelism**: Multiple agents can work concurrently
- **Reproducibility**: Clean state for each workflow run
- **Debugging**: Worktrees preserve full execution history
- **Recovery**: Failed workflows don't pollute main repo
#### Example Verification
After running a MapReduce workflow, verify main repo is clean:
```bash
# Check main repo status (should be clean)
git status
# Expected: nothing to commit, working tree clean
# Verify worktree has changes
cd ~/.prodigy/worktrees/prodigy/session-mapreduce-*/
git status
git log
# Expected: See setup phase changes and commits
```
### Event Tracking
Events are logged to `~/.prodigy/events/{repo_name}/{job_id}/` for debugging:
- Agent lifecycle events (started, completed, failed)
- Work item processing status
- Checkpoint saves for resumption
- Error details with correlation IDs
- Cross-worktree event aggregation for parallel jobs
### Dead Letter Queue (DLQ)
Failed work items are stored in `~/.prodigy/dlq/{repo_name}/{job_id}/` for review and retry:
- Contains the original work item data
- Includes failure reason and timestamp
- Supports automatic reprocessing via `prodigy dlq retry`
- Configurable parallel execution and resource limits
- Shared across worktrees for centralized failure tracking
#### DLQ Retry
The `prodigy dlq retry` command allows you to retry failed items:
```bash
# Retry all failed items for a job
prodigy dlq retry <job_id>
# Retry with custom parallelism (default: 5)
prodigy dlq retry <job_id> --max-parallel 10
# Dry run to see what would be retried
prodigy dlq retry <job_id> --dry-run
```
Features:
- Streams items to avoid memory issues with large queues
- Respects original workflow's max_parallel setting
- Preserves correlation IDs for tracking
- Updates DLQ state (removes successful, keeps failed)
- Supports interruption and resumption
## Workflow Execution
### Command Types
Prodigy supports several command types in workflows:
- `claude:` - Execute Claude commands via Claude Code CLI
- `shell:` - Run shell commands
- `goal_seek:` - Run goal-seeking operations with validation
- `foreach:` - Iterate over lists with nested commands
### Variable Interpolation
Workflows support variable interpolation:
- `${item.field}` - Access work item fields in MapReduce
- `${shell.output}` - Capture command output
- `${map.results}` - Access map phase results in reduce
- `$ARG` - Pass arguments from command line
### Environment Variables (Spec 120)
MapReduce workflows support environment variables for parameterization and secrets management. Environment variables can be defined at the workflow level and used throughout all phases.
#### Defining Environment Variables
Environment variables are defined in the `env` block at the workflow root:
```yaml
name: workflow-name
mode: mapreduce
env:
# Plain variables
PROJECT_NAME: "prodigy"
VERSION: "1.0.0"
# Secret variables (masked in logs)
API_KEY:
secret: true
value: "sk-abc123"
# Profile-specific variables
DATABASE_URL:
default: "postgres://localhost/dev"
prod: "postgres://prod-server/db"
```
#### Variable Interpolation Syntax
Environment variables can be referenced using two syntaxes:
- `$VAR` - Simple variable reference (shell-style)
- `${VAR}` - Bracketed reference for clarity and complex expressions
```yaml
setup:
- shell: "echo Processing $PROJECT_NAME version $VERSION"
- shell: "curl -H 'Authorization: Bearer ${API_KEY}' https://api.example.com"
map:
agent_template:
- claude: "/process-item '${item.name}' --project $PROJECT_NAME"
- shell: "test -f ${item.path}"
reduce:
- shell: "echo Completed $PROJECT_NAME workflow"
```
#### Secret Masking
Variables marked with `secret: true` are automatically masked in:
- Command output logs
- Error messages
- Event logs
- Checkpoint files
Example output:
```
$ curl -H 'Authorization: Bearer ***' https://api.example.com
```
#### Profile Support
Profiles allow different values for different environments:
```yaml
env:
API_URL:
default: "http://localhost:3000"
staging: "https://staging.api.com"
prod: "https://api.com"
```
Activate a profile:
```bash
prodigy run workflow.yml --profile prod
```
#### Usage in All Workflow Phases
Environment variables are available in:
**Setup Phase:**
```yaml
setup:
- shell: "npm install --prefix $PROJECT_DIR"
- shell: "cargo build --manifest-path ${PROJECT_DIR}/Cargo.toml"
```
**Map Phase:**
```yaml
map:
agent_template:
- claude: "/analyze ${item.file} --config $CONFIG_PATH"
- shell: "test -f $PROJECT_DIR/${item.file}"
```
**Reduce Phase:**
```yaml
reduce:
- claude: "/summarize ${map.results} --project $PROJECT_NAME"
- shell: "cp results.json $OUTPUT_DIR/"
```
**Merge Phase:**
```yaml
merge:
commands:
- shell: "echo Merging $PROJECT_NAME changes"
- claude: "/validate-merge --branch ${merge.source_branch}"
```
#### Best Practices
1. **Use secrets for sensitive data**: Mark API keys, tokens, and credentials as secrets
2. **Parameterize project-specific values**: Use env vars instead of hardcoding paths
3. **Document required variables**: Include comments in workflow files
4. **Use profiles for environments**: Separate dev, staging, and prod configurations
5. **Prefer ${VAR} syntax**: More explicit and works in all contexts
### Error Handling
Commands can specify error handling behavior:
- `on_failure:` - Commands to run on failure
- `commit_required:` - Whether a git commit is expected
### Claude Streaming Output Control
Prodigy provides fine-grained control over Claude interaction visibility through verbosity levels:
**Default mode (verbosity = 0):**
- Clean, minimal output showing only progress and results
- No Claude JSON streaming output displayed
- Optimal for production workflows and CI/CD
**Verbose mode (verbosity >= 1, `-v` flag):**
- Shows Claude streaming JSON output in real-time
- Enables debugging of Claude interactions
- Useful for development and troubleshooting
**Environment Override:**
- Set `PRODIGY_CLAUDE_CONSOLE_OUTPUT=true` to force streaming output regardless of verbosity
- Useful for debugging specific runs without changing command flags
This design ensures clean output by default while preserving debugging capabilities when needed.
## Git Integration
### Worktree Management
Prodigy uses git worktrees for isolation:
- Each session gets its own worktree
- Located in `~/.prodigy/worktrees/{project-name}/`
- Automatic branch creation and management
- Clean merge back to parent branch
### Commit Tracking
All changes are tracked via git commits:
- Each successful command creates a commit
- Commit messages include command details
- Full audit trail of all modifications
### Branch Tracking (Spec 110)
Prodigy tracks the original branch when creating worktrees to enable intelligent merge behavior:
**Original Branch Detection**:
- When creating a worktree, Prodigy captures the current branch as `original_branch`
- For feature branches: Tracks the exact branch name (e.g., `feature/my-feature`)
- For detached HEAD: Falls back to repository's default branch (main or master)
- Stored in worktree state for lifetime of the session
**Merge Target Logic**:
- Default behavior: Merge back to the tracked `original_branch`
- If original branch was deleted: Fall back to default branch (main/master)
- Merge target is displayed in the merge confirmation prompt
- Example: "Merge session-abc123 to feature/my-feature? [y/N]"
**Special Cases**:
- **Feature Branch Workflow**: Worktree created from `feature/ui-updates` merges back to `feature/ui-updates`
- **Detached HEAD**: Worktree tracks default branch (main/master) as fallback
- **Deleted Branch**: If original branch is deleted, falls back to main/master
- **Branch Rename**: Uses branch name at worktree creation time
**Implementation Details**:
- `WorktreeManager::create_session()` captures original branch using `git rev-parse --abbrev-ref HEAD`
- `WorktreeManager::get_merge_target()` determines merge target with fallback logic
- Merge target is shown in orchestrator's completion prompt for user confirmation
## Available Commands
Prodigy CLI commands:
- `prodigy run` - Execute a workflow (with `--resume` flag for checkpoint-based resume)
- `prodigy resume` - Resume an interrupted workflow from checkpoint
- `prodigy worktree` - Manage git worktrees
- `prodigy init` - Initialize Claude commands
- `prodigy resume-job` - Resume MapReduce jobs with enhanced options
- `prodigy events` - View execution events
- `prodigy dlq` - Manage and retry failed work items
- `prodigy checkpoints` - Manage workflow checkpoints
- `prodigy sessions` - View and manage session state
- `prodigy logs` - View and manage Claude JSON logs
## Best Practices
1. **Session Hygiene**: Clean up completed worktrees with `prodigy worktree clean`
2. **Error Recovery**: Check DLQ for failed items after MapReduce jobs
3. **Workflow Design**: Keep workflows simple and focused
4. **Testing**: Always include test steps in workflows
5. **Monitoring**: Use verbosity flags for appropriate detail level:
- Default: Clean output for production use
- `-v`: Claude streaming output for debugging interactions
- `-vv`/`-vvv`: Additional internal logs and tracing
6. **Documentation**: The book documentation workflow now includes automatic drift detection and gap detection to keep documentation synchronized with code changes. Features are analyzed automatically and documentation is updated to match implementation.
## Limitations
- No automatic context analysis or generation
- Each iteration runs independently (memory preserved via checkpoints and state)
- Context directory feature is planned but not implemented
- Limited to Claude commands available in `.claude/commands/`
- Resume functionality requires workflow files to be present
## Troubleshooting
### Session Issues
- Check `.prodigy/session_state.json` for session status
- View events in `.prodigy/events/` for detailed logs
- Use verbosity flags for debugging:
- `-v`: Shows Claude streaming output
- `-vv`: Adds debug logs
- `-vvv`: Adds trace-level logs
### MapReduce Failures
- Check `.prodigy/dlq/` for failed items
- Retry failed items with `prodigy dlq retry <job_id>`
- Resume MapReduce jobs with `prodigy resume-job <job_id>`
- Review checkpoint in `~/.prodigy/state/{repo_name}/mapreduce/jobs/{job_id}/`
### Worktree Problems
- List worktrees with `prodigy worktree ls`
- Clean stuck worktrees with `prodigy worktree clean -f`
- Check `~/.prodigy/worktrees/` for orphaned directories
### Viewing Claude Execution Logs (Spec 126)
**Every Claude command creates a streaming JSONL log file** at `~/.claude/projects/{worktree-path}/{uuid}.jsonl`. These logs are automatically displayed after each command execution:
```
#### Watching Logs Live
For long-running Claude commands, watch the log in real-time:
```bash
# Watch live as Claude executes
tail -f ~/.claude/projects/.../6ded63ac.jsonl
# Pretty-print each line as it's added
```bash
# View most recent Claude log
prodigy logs --latest
# View most recent log with summary
prodigy logs --latest --summary
# Tail the latest log (follow mode)
prodigy logs --latest --tail
# List recent logs
prodigy logs
```
#### When Workflows Fail
When a Claude command fails, the log path is displayed prominently in the error output, making it easy to debug the issue without requiring verbose mode.
#### Debugging Failed MapReduce Agents
Failed MapReduce agents include log paths in their DLQ entries for easy debugging.