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