Pi-CodeMachine

Universal Multi-Agent Workflow Orchestration for Pi

Pi-CodeMachine is a comprehensive workflow orchestration extension that enables pi to coordinate multiple specialized agents for complex tasks—any kind of tasks at all. Whether you're coding, researching, writing, analyzing data, making decisions, or creating content, CodeMachine provides the infrastructure to break down complex work into orchestrated agent workflows.

Features

• 🎭 Universal Task Support: Not just coding—research, writing, analysis, creative projects, business decisions, QA, and more
• 🔄 Multi-Mode Execution: Sequential chains, parallel execution, dependency-driven workflows
• 📊 Built-in Agents: 12+ specialized agents ready to use (researcher, writer, analyst, critic, planner, creative, etc.)
• 📋 Workflow Templates: Pre-built templates for common patterns (deep research, polished content, feature implementation, etc.)
• ⏯️ Lifecycle Management: Create, run, pause, resume, abort, and delete workflows
• 📈 Real-time Monitoring: Watch progress with live updates
• 💾 Persistence: Workflows survive session restarts
• 🎯 Conditional Logic: Steps can execute conditionally based on previous results
• 🔁 Retry Logic: Automatic retry with configurable delays
• 📂 Result Aggregation: Collect, synthesize, and export workflow results

Installation

Extension Setup

# Create the extension directory
mkdir -p ~/.pi/agent/extensions/pi-codemachine

# Copy the extension file
cp pi-codemachine/index.ts ~/.pi/agent/extensions/pi-codemachine/

# Copy built-in agents
mkdir -p ~/.pi/agent/agents/codemachine
cp pi-codemachine/agents/*.md ~/.pi/agent/agents/codemachine/

Verification

# List available agents
/cm-agents

# List workflow templates
/cm-templates

Quick Start

1. Spawn a Single Agent

Use the researcher agent to find information about quantum computing applications in healthcare

Or use the tool directly:

cm_agent_spawn:0 {"agent": "researcher", "task": "Research quantum computing applications in healthcare. Focus on current implementations and near-term possibilities."}

2. Execute Parallel Tasks

Analyze this codebase from multiple angles:
- Security review
- Performance analysis  
- Maintainability assessment

Tool usage:

cm_parallel_execute:1 {"tasks": [{"agent": "critic", "task": "Security audit of the codebase", "id": "security"}, {"agent": "analyst", "task": "Performance analysis of the codebase", "id": "performance"}, {"agent": "critic", "task": "Maintainability review of the codebase", "id": "maintainability"}]}

3. Chain Sequential Tasks

Write a blog post:
1. Research the topic
2. Create an outline  
3. Write the draft
4. Edit and polish

Tool usage:

cm_chain_execute:2 {"chain": [{"agent": "researcher", "task": "Research: The impact of AI on creative industries"}, {"agent": "planner", "task": "Create a blog post outline based on: {previous}"}, {"agent": "writer", "task": "Write a blog post based on this outline: {previous}"}, {"agent": "editor", "task": "Edit and polish this draft: {previous}"}]}

4. Use a Workflow Template

Create a comprehensive research workflow on renewable energy

Tool usage:

cm_workflow_from_template:3 {"template": "deep-research", "input": "renewable energy storage technologies", "name": "renewable-energy-research"}

Then run it:

cm_workflow_run:4 {"workflowId": "wf-xxx"}

Built-in Agents

Core Agents

| Agent | Category | Best For | |-------|----------|----------| | generalist | General | Any task requiring broad capabilities | | researcher | Research | Information gathering, exploration, synthesis | | writer | Writing | Content creation, documentation, copy | | analyst | Analysis | Data analysis, insights, evaluation | | critic | Review | Quality assurance, code review, critique | | planner | Planning | Strategy, organization, project breakdown | | creative | Creative | Ideation, brainstorming, innovation | | editor | Writing | Refinement, polishing, proofreading | | summarizer | Analysis | Condensation, synthesis, distillation |

Coding-Specific Agents

| Agent | Category | Best For | |-------|----------|----------| | coder | Coding | Software development, implementation | | reviewer | Coding | Code review, security, performance | | scout | Coding/Research | Fast reconnaissance, codebase exploration |

Creating Custom Agents

Create a file in ~/.pi/agent/agents/my-agent.md:

---
name: my-agent
description: What this agent does
category: research, analysis
capabilities: research, synthesis
tools: read, grep, find, ls
model: claude-sonnet-4-5
---

System prompt for the agent goes here.

Workflow Templates

Available Templates

| Template | Category | Description | |----------|----------|-------------| | deep-research | Research | Comprehensive research with multiple angles and synthesis | | polished-content | Writing | Create content with drafting, review, and refinement | | implement-feature | Coding | Full feature implementation with planning, coding, and review | | comprehensive-analysis | Analysis | Multi-perspective analysis with synthesis | | creative-project | Creative | Creative project with ideation, development, and refinement | | informed-decision | Business | Structured decision-making process | | quality-assurance | Review | Multi-stage quality review process |

Template Usage

cm_workflow_from_template:5 {"template": "polished-content", "input": "Write an article about sustainable architecture", "name": "sustainable-arch-article"}

Tools Reference

Workflow Management

cm_workflow_create

Create a custom workflow with defined steps and dependencies.

{
  name: string;
  description: string;
  steps: Array<{
    id: string;
    name: string;
    description: string;
    agent: string;
    task: string;
    dependsOn?: string[];
    timeout?: number;
    retryCount?: number;
    retryDelay?: number;
    checkpoint?: boolean;
    condition?: string; // e.g., "previous.success", "output.includes('error')"
  }>;
  category?: string;
  tags?: string[];
  priority?: "low" | "normal" | "high" | "urgent";
}

cm_workflow_run

Execute a workflow.

{
  workflowId: string;
  watch?: boolean; // Stream progress updates
}

cm_workflow_resume

Resume a paused or partially completed workflow.

{
  workflowId: string;
  watch?: boolean;
}

cm_workflow_abort

Stop a running workflow.

cm_workflow_delete

Delete a workflow.

{
  workflowId: string;
  force?: boolean; // Force delete even if running
}

Execution Tools

cm_agent_spawn

Execute a single agent task.

{
  agent: string;
  task: string;
  timeout?: number;
  agentScope?: "user" | "project" | "both" | "builtin";
  outputFormat?: "text" | "json" | "markdown";
}

cm_parallel_execute

Execute multiple agents in parallel.

{
  tasks: Array<{
    agent: string;
    task: string;
    id?: string;
  }>;
  maxConcurrency?: number; // 1-8, default: 4
  aggregate?: boolean; // Combine results into single output
}

cm_chain_execute

Execute agents sequentially, passing outputs forward.

{
  chain: Array<{
    agent: string;
    task: string; // Use {previous}, {stepId}, or {input}
    id?: string;
    condition?: string; // "previous.success", "previous.failure"
  }>;
  initialInput?: string;
}

Monitoring & Results

cm_status_check

Check workflow status.

{
  workflowId?: string;  // Check specific workflow
  all?: boolean;        // List all workflows
  filter?: {
    status?: string;
    category?: string;
    tag?: string;
  };
}

cm_results_collect

Gather and synthesize workflow results.

{
  workflowId: string;
  stepIds?: string[];    // Specific steps (default: all)
  format?: "summary" | "full" | "json" | "markdown";
  synthesize?: boolean;  // Auto-synthesize results
}

Information

cm_list_agents

List available agents with capabilities.

{
  category?: string;
  agentScope?: "user" | "project" | "both" | "builtin";
}

cm_list_templates

List workflow templates.

{
  category?: string;
}

cm_workflow_from_template

Create workflow from template.

{
  template: string;
  input: string;
  name?: string;
  customizations?: Record<string, string>;
}

Commands

| Command | Description | |---------|-------------| | /cm-list [filters] | List workflows (e.g., /cm-list status:running) | | /cm-agents | List available agents | | /cm-templates | List workflow templates | | /cm-status <workflow-id> | Show detailed workflow status | | /cm-clean [days] | Clean up old workflows (default: 7 days) |

Workflow Patterns

Pattern 1: Sequential Pipeline

Step 1 → Step 2 → Step 3 → Step 4

Each step depends on the previous. Good for methodical work.

Pattern 2: Parallel Fan-Out

         ┌→ Agent A
Input → ├→ Agent B
         ├→ Agent C
         └→ Agent D

All agents work simultaneously on different aspects.

Pattern 3: Dependency Graph

     ┌→ B → D ─┐
A → ┤          ├→ F
     └→ C → E ─┘

Complex dependencies with parallel execution where possible.

Pattern 4: Conditional Flow

A → (if success) → B → C
   (if failure) → D → E

Steps execute conditionally based on previous results.

Pattern 5: Map-Reduce

Input → [Parallel Processing] → Aggregation → Output

Process chunks in parallel, then synthesize.

Advanced Features

Conditional Execution

Steps can be conditional based on previous results:

{
  id: "notify",
  name: "Notify on Success",
  agent: "generalist",
  task: "Send success notification",
  dependsOn: ["deploy"],
  condition: "deploy.success"  // Only run if deploy succeeded
}

Conditions supported:

• "previous.success" / "previous.failure"
• "stepId.success" / "stepId.failure"
• "output.includes('text')"
• "output.startsWith('text')"
• "always" / "never"

Variable Substitution

Tasks can reference outputs from previous steps:

{
  agent: "writer",
  task: "Write article based on research:\n{research-step}"
}

Or use {previous} for the most recent output, {input} for the initial input.

Retry Logic

{
  id: "api-call",
  name: "API Integration",
  agent: "coder",
  task: "Implement API integration",
  retryCount: 3,
  retryDelay: 5000,  // 5 seconds between retries
  timeout: 120000
}

Checkpoints

Enable checkpointing to save progress after critical steps:

{
  id: "data-processing",
  name: "Process Large Dataset",
  agent: "analyst",
  task: "Process the data",
  checkpoint: true  // Save workflow state after completion
}

Use Cases

Software Development

Implement a user authentication system:
1. Scout the codebase for existing auth code
2. Plan the implementation approach
3. Implement the auth middleware
4. Add user model and migrations
5. Create login/logout endpoints
6. Add tests
7. Review the implementation

Research & Analysis

Research the competitive landscape:
1. Scout for information sources
2. Research Company A's offerings
3. Research Company B's offerings
4. Research Company C's offerings
5. Analyze pricing strategies
6. Analyze feature comparisons
7. Synthesize competitive analysis report

Content Creation

Create a technical blog post:
1. Research the topic thoroughly
2. Create detailed outline
3. Write first draft
4. Self-review and critique
5. Edit and refine
6. Final proofread

Decision Making

Evaluate cloud providers:
1. Generate evaluation criteria
2. Research AWS offerings
3. Research Azure offerings
4. Research GCP offerings
5. Score each against criteria
6. Analyze trade-offs
7. Make recommendation with rationale

Quality Assurance

Review a pull request:
1. Initial code review
2. Security analysis
3. Performance impact check
4. Test coverage verification
5. Documentation review
6. Final approval/rejection

Configuration

Workspace Directory

Workflows are stored in .codemachine/:

.codemachine/
├── workflows/     # Workflow definitions
├── results/       # Step outputs
├── logs/          # Execution logs
├── state/         # Checkpoint data
└── artifacts/     # Generated files

Environment Variables

# Default timeout for agent tasks (ms)
CM_DEFAULT_TIMEOUT=300000

# Max parallel tasks
CM_MAX_CONCURRENCY=4

# Checkpoint interval (ms)
CM_CHECKPOINT_INTERVAL=30000

Troubleshooting

Workflow Stuck

/cm-status <workflow-id>
cm_workflow_abort:6 {"workflowId": "wf-xxx"}

Agent Not Found

cm_list_agents:7 {"agentScope": "both"}

Check Logs

ls .codemachine/logs/
cat .codemachine/logs/workflow-<id>.log

Extension Not Loading

1. Verify file is at ~/.pi/agent/extensions/pi-codemachine/index.ts
2. Check for TypeScript errors
3. Reload pi with /reload

Best Practices

1. Start Simple: Begin with simple workflows, add complexity gradually
2. Clear Tasks: Each agent task should be specific and bounded
3. Meaningful Step Names: Makes status monitoring easier to read
4. Use Templates: Leverage pre-built templates for common patterns
5. Checkpoint Critical Steps: Enable checkpoints for long-running steps
6. Handle Failures: Design workflows to handle partial failures gracefully
7. Review Results: Always review cm_results_collect output
8. Clean Up: Use /cm-clean regularly to remove old workflows

Contributing

To add new agents:

1. Create .md file in ~/.pi/agent/agents/codemachine/
2. Include YAML frontmatter with metadata
3. Write comprehensive system prompt
4. Test with various tasks

To add new templates:

1. Define template in extension code
2. Include clear description and use case
3. Test with real-world scenarios
4. Document in this README

License

MIT

Changelog

1.0.0

• Initial release
• 12+ built-in agents
• 7 workflow templates
• Full workflow lifecycle management
• Conditional execution and retry logic
• Real-time monitoring and result aggregation