pi-exoself

Warning

This stack is new, experimental, and actively changing. It is being used as a daily-driver orchestration environment while the workflow is still under heavy development, and behavior is still being corrected in real time as edge cases are discovered. Expect rough edges, evolving conventions, and occasional workflow breakage while the control plane, worker model, and rollout loop continue to mature.

Why “pi-exoself”?

The name is a deliberate homage to science-fiction giants Hannu Rajaniemi and Greg Egan, among the many writers whose work imagines minds, identities, and intelligences extending beyond a single biological self. Rajaniemi's Jean le Flambeur novels and Egan's Permutation City and Diaspora were especially important inspirations.

Here, an exoself is the practical version of that idea: something outside the operator that can coordinate a horde of specialized AI subagents, preserve what each one is doing, route their work through review and integration, and turn the combined results back into something one person can understand and act on. The human remains the source of intent and judgment; pi-exoself supplies the external memory, parallel hands, and digestible control surface.

This project is not affiliated with either author. It is simply built with gratitude for the imaginative territory their work helped open.

What is customized to make Pi behave like this

This repository does not represent stock Pi behavior by itself. The current workflow depends on a layered customization stack:

1. Pi harness itself — a locally installed/customized Pi coding-agent runtime is assumed as the base control surface.
2. Project operating rules — AGENTS.md defines the orchestration policy, bead hierarchy, human-review rules, and lifecycle expectations for this control repo.
3. Local workflow CLI — bin/pi-exoself adds the repo-specific lifecycle commands that keep canonical state, worktrees, review state, and generated notes synchronized.
4. Project Pi package customizations — package.json registers this repo's project-local Pi package content:
   • agents in .pi/agents/
   • skills in .pi/skills/
   • prompts in .pi/prompts/
   • extension code in .pi/extensions/pi-exoself/
5. Project extension automation — .pi/extensions/pi-exoself/index.ts wires subagent launches/results back into canonical exoself state and derived operator views.
6. Installed Pi extensions/capabilities outside this repo — this workflow assumes non-stock Pi capabilities such as subagent orchestration and MCP/tooling support are installed in the user Pi environment.
7. Beads (bd) — durable issue/state tracking is part of the control plane; this repo assumes Beads is installed and used as the canonical work ledger.

If any of those layers are missing or diverge, Pi may still run, but it will not behave like the orchestration environment described here.

External Pi packages used by this harness

This repository contains the pi-exoself project extension, agents, skills, and prompts, but the current operator environment also loads these user-scoped Pi packages. They are not installed by this project's package.json, so a new adopter must install the capabilities they want separately.

Package	Current version	Purpose here
pi-subagents	0.40.0	Async implementer, reviewer, integrator, scout, and other delegated-agent workflows
max-context	1.0.2	Keeps model context near a configurable soft limit
pi-rewind	0.5.0	Local checkpoints and safe session/worktree rewind support
@vanillagreen/pi-session-manager	1.5.3	Browse, search, resume, rename, and remove Pi sessions
@narumitw/pi-usage	0.49.2	Displays provider/account usage information
@llblab/pi-telegram	0.27.0	Optional Telegram runtime bridge for remote operator interaction
pi-mcp-adapter	2.21.2	MCP server discovery and tool access
@99percentpeople/pi-background-tasks	2.1.1	Parent-owned long-running background commands, logs, attachable PTY/TUI sessions, and cleanup control

Install the current releases with:

pi install npm:pi-subagents
pi install npm:max-context
pi install npm:pi-rewind
pi install npm:@vanillagreen/pi-session-manager
pi install npm:@narumitw/pi-usage
pi install npm:@llblab/pi-telegram
pi install npm:pi-mcp-adapter
pi install npm:@99percentpeople/pi-background-tasks

pi-subagents is required for the delegated workflow described below. @99percentpeople/pi-background-tasks is required for parent-owned long-running command execution and log inspection by the primary session. pi-mcp-adapter is required only for MCP-backed tools. Telegram, usage display, rewind, session management, and context limiting improve the current operator experience but are not required to understand the core lifecycle. Pi packages execute with the user's permissions; review them before installation.

pi-exoself is a Pi-native orchestration control plane for coordinating AI work across repositories.

It takes the core ideas from Exoself—durable task state, owned worktrees, independent review, and human-review staging—but shifts the human interface toward automation:

• machine-readable state is canonical
• markdown notes are derived outputs
• hooks and lifecycle commands keep status fresh
• logical worker ids survive pause/resume even when subagent run ids change
• worker leases can expire into stale state and be recovered explicitly
• agents do work; automation maintains the operator surface

Design principles

1. Markdown is not source of truth. Notes under obsidian/pi-exoself/ are generated views.
2. Lifecycle transitions own synchronization. Commands and hooks update state, then regenerate notes.
3. Pi is the control surface. Project agents, skills, prompts, and extensions drive the workflow.
4. Subagents are explicit workers. The primary session orchestrates; workers own implementation/review/integration tasks.
5. Human review is a real gate. Approval, verification, and staging state are tracked explicitly.

Repository layout

• AGENTS.md — repo-wide operating rules
• docs/ — architecture and workflow docs
  • includes docs/beads-conventions.md for planned durable metadata conventions
• config/ — repository profiles used by Beads-backed lifecycle commands
• clones/ — ignored managed bare clones
• worktrees/ — ignored mutable worktrees derived from managed clones
• .pi/agents/ — Pi project agents
• .pi/skills/ — Pi skills for workflow operations
• .pi/prompts/ — Pi prompt templates / commands
  • includes helpers for syncing status and registering review artifacts
• .pi/extensions/pi-exoself/ — hook and UI automation
• bin/pi-exoself — local CLI for state transitions and note generation
• obsidian/pi-exoself/ — generated operator-facing markdown notes
• .pi-exoself/state/ — canonical machine-readable runtime state for this control repo

Current focus

This initial scaffold establishes:

• the Pi-native operating model
• generated human-facing notes
• a local state/notes sync command
• project agents that forbid manual edits to generated notes

Setup quick start

Prerequisites: the customized Pi harness, Beads (bd), Git, and pi-subagents. Install any other user-scoped packages you want from the inventory above, then verify the required commands are available:

pi --version
bd version

git clone <pi-exoself-url>
cd pi-exoself
bd init            # once, if .beads does not exist yet
bin/pi-exoself adopt-repo <repo> <source> [default-branch]
bin/pi-exoself sync-status
pi

Inside Pi, trust the project so project-local agents, prompts, skills, and extensions load. Existing installations created before the current review-state model can run bin/pi-exoself migrate-review-statuses once; fresh installations do not need it.

Daily development quick start

1. Open one terminal in this repository and run pi.
2. Tell Pi what outcome you want and whether integration should be automatic or wait for you.
3. Pi turns the work into Beads tasks, delegates implementation and review in managed worktrees, and coordinates one integrator for the repository.
4. Review accepted work in worktrees/<repo>/human-review/.
5. Use an explicit “skip the process” request for a true hot fix.

Example prompts:

For this epic slice, work every ready bead through implementation and review,
then land every approved bead in human-review.

Work through this slice, but let me know when each branch is ready to integrate
into human-review. Do not merge it until I decide.

I want you to directly do the following, skip the process: <hot-fix description>

What development looks like

One terminal is the control plane

The normal operator experience is one Pi session running in one terminal. You describe outcomes and make approval decisions there; Pi coordinates repositories, workers, reviews, integration, and status behind the scenes. You do not need a terminal for every agent or worktree.

Repositories are adopted, not mixed together

bin/pi-exoself adopt-repo records a local repository profile and creates a managed bare clone under clones/. Actual work happens in isolated directories under worktrees/<repo>/, so multiple branches can be inspected without repeatedly switching the operator's checkout.

Both directories and real repository profiles are local-only and ignored by Git:

config/<repo>.json             local repository profile
clones/<repo>.git/             managed bare clone
worktrees/<repo>/<worker>/     implementation or review worktree
worktrees/<repo>/human-review/ stable operator-review worktree

The default delivery loop

The normal path from an idea to human review is:

Bead → implementer → reviewer → approved branch → integrator → human-review

• A Bead is the durable unit of work and records ownership and workflow state.
• An implementer owns a bounded branch/worktree and produces a reviewable commit.
• A reviewer independently checks that exact commit. Changes can cycle back to the implementer until approved.
• A single integrator per repository collects approved branches and lands them into the repository's human-review branch. Keeping integration single-threaded avoids competing merges at the same seam.
• The human operator reviews the combined result in worktrees/<repo>/human-review/ before deciding what should move onward.

The primary Pi session remains the orchestrator throughout this loop; delegated agents do bounded work rather than becoming separate control planes.

Choose automatic or gated integration

You can set the integration policy in ordinary language for an epic, slice, or individual bead.

Automatic: ask Pi to land every approved bead for a slice in human-review. Pi can continue the implementer/reviewer cycle and queue approved branches with the single integrator without stopping for a merge decision after each bead.

Please land in human-review every approved bead for this epic slice.

Gated: ask Pi to notify you when a branch is ready and wait. Implementation and independent review can still proceed automatically, but the integrator does not merge that branch until you approve it.

Please let me know when a branch is ready to integrate into human-review,
and allow me to decide when to merge the completed work.

Hot fixes can bypass the full loop

The full workflow is a safety-oriented default, not a requirement for every tiny or urgent edit. To request direct work, explicitly say that you want to skip the process and describe the exact change:

I want you to directly do the following, skip the process: <exact change>

That tells the primary session to make the bounded change directly instead of creating the normal implementer/reviewer/integrator pipeline. Normal validation, clear reporting, and safe Git handling still apply.

Status files

Generated notes live under obsidian/pi-exoself/:

• Exoself.md
• active-agents/
• past-agents/
• active-reviews/
• archived-reviews/
• links/
• docs/ for manual operator-authored docs

Do not edit generated status notes manually. Update canonical state and regenerate them instead.

When bin/pi-exoself is invoked from a managed pi-exoself worktree, it resolves the authoritative control-repo root and updates the shared .pi-exoself/state/, .beads/, and obsidian/pi-exoself/ paths there so lifecycle commands and hooks keep one canonical status surface.

Near-term direction

• integrate and enforce Beads metadata conventions
• use adopt-repo, start-work, bind-work, record-verification, record-review, prepare-human-review, stage-human-review, publish-human-review, remove-worktree, recover-agent, and reassign-work as the first Beads-backed lifecycle commands
• hook pi-subagents lifecycle into agent/review state updates, including pause/resume tracking
• add worker lease / recovery semantics
• add human-review staging automation
• make Obsidian-facing docs fully derived from runtime + Beads state