Bullx Project Manager

Orchestrate work across pipeline stages with isolated task folders. A pi extension that turns the current working directory into a live-discovered project workspace. Assign tasks, run commands (sync or async), and get automatic notifications when work completes.

# Install from local path
pi install ./packages/project-manager

# Or from npm:
pi install npm:@lalalaic/project-manager

Requires: pi 0.79+
Peer deps: @earendil-works/pi-coding-agent, typebox

---

Features

• No registry — projects = folders on disk with .pi/pipeline.md. Add/remove by creating or deleting directories.
• 2 tools only — minimal tool surface; project management is guided via the bundled SKILL.md
• Sync or async execution — run commands inline or spawn background processes
• Auto-notifications — file watcher pushes proactive user messages when async tasks complete
• Configurable workspace root — defaults to cwd, overridable via projects.root in settings
• Project context enforcement — auto-creates a temp project when cwd is outside the workspace
• Per-project .pi isolation — each project folder can have its own .pi/settings.json with packages, skills, tools, and model config

---

Quick Start

# Install
pi install ./packages/project-manager

# Restart pi — the extension loads automatically
pi

# List pipeline stages
> list_projects

# Create a project (using bash)
> mkdir -p ./my-stage/.pi
> write ./my-stage/.pi/pipeline.md:
  ---
  name: My Stage
  description: Build pipeline stage
  ---
  # My Stage

# Assign a task and spawn a pi session to do it
> assign_project_task(
    projectName: "my-stage",
    taskName: "init",
    instructions: "Initialize a TypeScript project with pnpm and vitest",
    mode: "sync"
  )

# Assign a task for interactive work (no mode)
> assign_project_task(
    projectName: "my-stage",
    taskName: "design-api",
    instructions: "Design the API routes"
  )
# Then cd into the task folder and work directly:
> bash: cd ./my-stage/.tasks/design-api
# ... work with bash/write/edit ...
# When done:
> write result.json → { "finalResponse": "API design complete" }
> write status.json → { "status": "completed" }

---

Tools

list_projects

Scan the workspace root and show all pipeline stages. Only discovers folders with .pi/pipeline.md. Reads frontmatter for display name and description.

Parameter	Type	Description
includeTasks	boolean (optional)	Include task details for each project

assign_project_task

Create an isolated task workspace and optionally spawn a pi child session.

Parameter	Type	Default	Description
projectName	string	—	Project (pipeline stage) name
taskName	string	—	Task identifier (used as folder name)
instructions	string	—	Written to instructions.md in the task folder
timeout	number	300000	Pi session timeout in ms (5 min)
mode	"async" | "sync"	—	Execution mode

Modes:

Mode	Behavior
omit mode	Creates task folder with instructions.md. cd there with bash and work interactively, then write result.json + status.json when done.
sync	Spawns a pi child session in the task folder, waits for completion. Pi reads instructions.md, does the work, writes result.json + status.json. Returns exit code + output.
async (default when set)	Spawns pi in background, returns immediately with PID. Pi writes output.log → result.json → status.json on its own. File watcher notifies the orchestrator on completion.

---

Commands

Command	Description
/projects	Interactive project browser
/project:new <name>	Create a project folder
/project:link <path> [name]	Symlink an existing folder as a project
/project:delete <name>	Delete a project folder (with confirmation)
/project:task <project> <task> <instructions...>	Assign a task
/project:run <project> <task> <instructions...>	Assign task + spawn pi session (sync)
/project:adopt [name]	Adopt a temp project into a permanent one

---

Configuration

Workspace root

The workspace root defaults to the current working directory. Set a custom root in settings (cascade: project → global → default):

// .pi/settings.json or ~/.pi/agent/settings.json
{
  "projects": {
    "root": "./my-projects"
  }
}

Default: cwd (the directory where pi was started)

Per-project .pi setup

Each project folder can have its own .pi/settings.json for isolated configuration:

A project is only recognized if it has .pi/pipeline.md. Create one to register a folder as a project:

<!-- ./my-project/.pi/pipeline.md -->
---
name: My Project
description: What this pipeline stage does
---

# My Project

## Purpose
...

Each project folder can also have .pi/settings.json for isolated configuration:

// ./my-project/.pi/settings.json
{
  "packages": ["npm:some-skill-package"],
  "skills": ["./custom-skills"],
  "extensions": ["./extensions/my-tool.ts"],
  "projects": { "root": "." },
  "hermes-memory": { "localPath": ".pi/memory" },
  "defaultModel": "anthropic/claude-sonnet-4-20250514"
}

---

Pipeline definition (pipeline.md)

.pi/pipeline.md is the project marker — only folders with it are discovered as projects. It is auto-injected into the system prompt whenever the LLM works in that project. The frontmatter (name, description) provides the project's display metadata:

---
name: My Pipeline
description: Builds and packages the release artifacts
---

# My Pipeline

## Purpose
What this pipeline stage does.

## Conventions
- Code style, tools, expected input/output

## Workflow
1. First step
2. Done when...

## Learnings
- Updated after each task to capture lessons learned

Create on project setup, update after each task. The LLM reads, follows, and refines pipeline.md — it self-improves over time as more work is done.

---

How It Works

Task folder structure

./<project>/
├── .pi/
│   ├── pipeline.md          ← REQUIRED — project marker + auto-injected into system prompt
│   │                          Frontmatter: name, description
│   └── settings.json        ← project-specific config (optional)
└── .tasks/
    └── <task-name>/
        ├── instructions.md  ← task definition (written by assign_project_task)
        ├── status.json      ← current status (write on progress)
        ├── result.json      ← final output (write when done)
        └── output.log       ← command stdout/stderr (written on run)

File watcher & push notifications

A recursive fs.watch on the workspace root detects changes to result.json and status.json:

Event	Behavior
Task completes (result.json written)	pi.sendUserMessage() triggers a new LLM turn — orchestrator sees: "Async task X completed. Check result.json."
Task fails (non-zero exit)	Same — proactive user message with ❌
Status update (in_progress)	Passive sendMessage() visible on next user prompt

Async execution flow

assign_project_task(project, task, instructions, command, mode="async")
  → Creates task folder + instructions.md
  → Spawns command in background (PID returned)
  → Returns immediately

  [background process runs]
  → Writes output.log
  → Writes result.json
  → Writes status.json (completed/failed)

  [file watcher detects change]
  → Sends proactive user message to orchestrator
  → Orchestrator decides next steps

Project context enforcement

When the extension loads, if the current working directory is outside the workspace root, a temp project is auto-created at <root>/.tmp/<dirname>-<ts>/ with a minimal .pi/settings.json. Use /project:adopt to make it permanent.

---

Skill

The package bundles a pi skill that teaches the LLM how to:

• Create, link, and delete projects
• Set up .pi/settings.json with packages, skills, and tools
• Use assign_project_task in sync, async, and interactive modes
• Work directly in task folders using bash/write/edit

---

Design

See project-manager/DESIGN.md for the full architecture document.

---

License

MIT