pi-parallel-agents: Instructions file for Codex

AGENTS.md

Guidelines for AI agents working on this codebase.

Project Overview

pi-parallel-agents is a pi extension that enables dynamic parallel execution of multiple agents with different models. This tool supports both:

1. Inline configuration: Specify model, tools, thinking level, and system prompts per task
2. Agent references: Reference existing agent definitions from ~/.pi/agent/agents or .pi/agents

Architecture

src/
├── index.ts      # Main extension entry point, tool registration, mode dispatch
├── executor.ts   # Subprocess execution, spawns `pi --mode json` processes
├── parallel.ts   # Concurrency utilities (worker pool, race with abort)
├── dag.ts        # DAG engine for team mode (build, validate, execute task graphs, iterative review loops)
├── workspace.ts  # Shared workspace for team artifact exchange
├── render.ts     # TUI rendering for progress and results
├── types.ts      # TypeScript types and Typebox schemas
├── agents.ts     # Agent discovery and configuration resolution
└── context.ts    # Context building (files, git info)

Key Design Decisions

1. Subprocess-based execution: Each task spawns a separate pi process with --mode json to capture structured output. This provides isolation and allows different models/configs per task.

2. State in tool details: Results are stored in the tool result details field, which pi automatically persists. This enables session branching/restore without additional state management.

3. Streaming progress: Uses onUpdate callback to emit progress during execution. The TUI shows real-time tool calls and partial output from running tasks.

4. Hybrid agent model: Users can specify model/tools/thinking inline OR reference existing agents. When an agent is referenced, its settings are used as defaults and inline parameters override them.

5. Agent discovery: Agents are discovered from ~/.pi/agent/agents/*.md (user-level) and optionally .pi/agents/*.md (project-level) based on agentScope parameter.