Pi Chains

Sequential agent-chain extension for Pi Coding Agent.

This package is not a standalone app. It is a Pi extension that:

• Loads chain definitions from .pi/agents/agent-chain.yaml
• Discovers agent definitions from markdown files with frontmatter
• Registers the run_chain tool
• Adds /chain and /chain-list commands
• Supports final output delivery to chat, a follow-up turn, or a file

Repo Purpose

pi-chains gives you a repeatable way to split a job across multiple focused agents. Each chain runs step by step. Agent steps execute in order, and the next step receives the original user task plus structured outputs from earlier agents as context.

This is useful when you want workflows like:

• research -> implementation
• analyze -> plan -> write
• review -> patch -> summarize
• generate content -> write result to a file

The extension entrypoint is extensions/index.ts, which re-exports the registration logic from chains.ts.

What This Extension Adds

Tool

• run_chain

Parameters:

{
  "chain": "chain-name",
  "task": "What the chain should do"
}

Commands

• /chain <name> <task...>
• /chain-list

Install

Install from Github:

pi install https://github.com/eleqtrizit/pi-chains

Install from this directory:

pi install ./

Remove it:

pi remove ./

Run it directly without installing:

pi --extension "$(pwd)/extensions/index.ts"

How Chain Setup Works

You need two things:

1. Agent definition files
2. A chain definition file

1. Define Agents

** NOTE THE TOOL RESTRICTIONS CURRENTLY DO NOT WORK - NOT SURE IF WILL IMPLEMENT **

Agents are discovered from these directories:

• .pi/agents/
• ~/.pi/agent/agents/

Each agent is a markdown file with frontmatter plus a prompt body.

Example: .pi/agents/researcher.md

---
name: researcher
description: Finds facts and constraints for a task
tools: read,grep,ls
---
You are a research specialist.

Collect the relevant facts, constraints, and unknowns.
Be concise and structured.

Example: .pi/agents/writer.md

---
name: writer
description: Turns prior chain output into a final deliverable
tools: read,write,edit,ls
---
You write clear final artifacts based on the prior chain context.

Produce the requested deliverable directly.
Do not repeat analysis unless it is needed in the final output.

Frontmatter fields used by the extension:

• name: agent name used by the chain
• description: short label for chain context
• tools: tool allowlist passed to the spawned Pi agent

The markdown body becomes the system prompt appended to that agent run.

2. Define Chains

Create .pi/agents/agent-chain.yaml.

Each top-level key is a chain name. A chain has:

• description
• steps

Each step is either:

• An agent step: agent + prompt
• An output step: output plus optional output settings

Supported output modes:

• chatHistory: insert final content into chat history
• triggerTurn: insert final content and trigger a follow-up turn
• file: write final content to a file

Output-step options:

• display: whether the sent message should be shown in chat
• file_name: required when output: file
• prepend: text added before the final content
• append: text added after the final content

Example Chain Setup

Example 1: Research Then Write

draft-readme:
  description: Research a repo and draft a README
  steps:
    - agent: researcher
      prompt: |
        Inspect the repo and extract the purpose, key workflows, and setup steps.
        Return a concise outline for a README.
    - agent: writer
      prompt: |
        Turn the prior chain context into a polished README.md draft.
        Use markdown headings and practical examples.
    - output: chatHistory
      display: true

Run it:

/chain draft-readme Create a README for this repository

Or via the tool:

{
  "chain": "draft-readme",
  "task": "Create a README for this repository"
}

Example 2: Generate a File

spec-to-file:
  description: Convert a request into a saved markdown spec
  steps:
    - agent: researcher
      prompt: |
        Analyze the request and produce the technical requirements.
    - agent: writer
      prompt: |
        Write a concise implementation spec in markdown.
    - output: file
      file_name: docs/generated-spec.md
      prepend: |
        <!-- generated by pi-chains -->

      append: |

        <!-- end generated file -->

Run it:

/chain spec-to-file Write a spec for adding SSO to the dashboard

Example 3: Trigger a Follow-Up Turn

Use triggerTurn when the chain should feed another turn automatically.

plan-then-act:
  description: Produce a plan and immediately hand it back into Pi
  steps:
    - agent: researcher
      prompt: |
        Break the task into an execution plan with risks and assumptions.
    - output: triggerTurn
      display: true
      prepend: |
        Continue from this generated plan:

What Each Agent Receives

For the first agent, the task is the user task you pass to the chain.

For later agents, the extension builds a structured context block that includes:

• The original user input
• Earlier agent names and descriptions
• Earlier agent outputs

That means later agents can work from the full prior chain context instead of only the last step's raw output.

Typical Workflow

1. Create a few focused agent files.
2. Define one or more chains in .pi/agents/agent-chain.yaml.
3. Start Pi with this extension installed, or launch it with --extension.
4. Run /chain-list to confirm the chains were loaded.
5. Run /chain <name> <task...> or call run_chain.

Development

Install dependencies:

npm install

Type-check:

npx tsc --noEmit

Run tests:

npm test