exocortex-project

A personal project-management layer on a self-hosted fork of Plane Community Edition, for a solo developer who works with Claude Code and with OpenAI Codex run by Symphony. The loop:

capture ──► clarify ──► dispatch ──► Human Review
 note        capture     next         review

You say "note: ..." and the agent records your words verbatim. A clarify pass turns notes and ideas into well-specified work items with parent and blocked-by links. The ready queue picks what can start now, and the item is worked in your session or handed to Codex through Symphony. Finished work waits in Human Review with its patch until you approve it or send it back with a comment. The agent does all of this through MCP tools. You use the Plane web app and talk to the agent.

Status (0.2.0): Symphony is now inside the package (upstream v0.0.3, unmodified) and reads Plane through Plane's Linear-compatible interface. setup --bare, the upgrade from 0.1.1 (UPGRADE.md) and Codex runs through the bundled Symphony have been tested on macOS arm64. The Linux executables are checked only by their SHA256; plane up --docker / setup --docker are not yet verified. Upgrading from 0.1.x: follow UPGRADE.md (exocortex-project guide upgrade).

What the wheel contains

• Client core (exocortex_project.core): a client for Plane's /api/v1/, the ready rule over blocked_by, context packs for one item, capture with parent and blocker links, and the Human Review queue with per-file patch stats.
• MCP server exocortex-project-mcp (stdio): every everyday operation as a tool, the procedures as prompts, the state vocabulary and the working rules as server instructions.
• One-time commands exocortex-project: guide, version, setup, init, doctor, plane up|down|status|bootstrap|backup|restore, symphony workflow|check|start|status|stop, agent-link.
• Upstream Symphony v0.0.3: unchanged executables for macOS arm64 and Linux x86_64/arm64, selected and verified locally. No separate Symphony installation is needed.
• The Plane fork server: the Django API with Celery worker and beat, its migrations, a bootstrap_exocortex management command, and the prebuilt web app, served by the API on the same port (no Node, no proxy). The public boards, God Mode admin and realtime servers are not included.
• Offline docs: SETUP.md, UPGRADE.md, USAGE.md and ARCHITECTURE.md.

Not bundled: PostgreSQL, Redis or Valkey, and MinIO or S3 (for --bare), or Docker (for --docker); the Codex CLI (for Symphony); Claude Code or another MCP client.

Install and first run

Python 3.11 or newer.

pip install exocortex-project        # or: pipx install exocortex-project

Then, in the repository the work is about, tell your agent:

exocortex-project is installed, set it up

The agent reads the setup checklist with exocortex-project guide and runs it. To do it yourself:

exocortex-project guide                                    # the full SETUP.md
exocortex-project setup --bare --workspace <slug> --project <IDENT>
# or: exocortex-project setup --docker --workspace <slug> --project <IDENT>

setup runs guide, plane up, plane bootstrap, init and doctor in order and stops at the first failure, saying how to fix it. Every step is safe to repeat. Afterwards, log in to the web app with the admin account that plane bootstrap printed, change its password, and approve the exocortex-project MCP server when your client asks.

Run Symphony for this repository

Generate the repository's WORKFLOW.md once, pointing upstream Symphony at Plane's Linear-compatible GraphQL endpoint, then manage it from anywhere inside the checkout:

exocortex-project symphony workflow --project <IDENT> --pr-host none
exocortex-project symphony start
exocortex-project symphony status
exocortex-project symphony stop

To land approved work in a local repository, name it and its branch when you generate the WORKFLOW:

exocortex-project symphony workflow --project <IDENT> --pr-host none \
  --merge-into /absolute/path/to/repo --merge-branch main

This also writes WORKFLOW.merge.md and sets Plane's project merge target to the same repository and branch. start, status and stop then run a second Symphony on port 4101 that takes only items in Merging assigned to the Codex bot, and whose agent may write only that repository (and its .git). The development agents never get write access to it. doctor checks that Plane and WORKFLOW.merge.md name the same target.

To let a web page open Codex or Claude Code on one work item, register the link handler once:

exocortex-project init --agent-link        # --remove-agent-link undoes it

It claims exocortex-project://refine?tool=codex|claude&item=PROJ-12 links (an applet in ~/Applications on macOS, an x-scheme-handler desktop file on Linux). A link only names the tool and the item: the repository comes from the item's merge target in Plane, the prompt is fixed ("Use the pm-refine procedure on PROJ-12."), and a new terminal window starts the agent there.

Workflows always use tracker kind linear and Plane's Linear-compatible endpoint. Optional --model <model> and --effort <effort> values are passed through as supplied; omitting them uses your own Codex defaults.

start checks WORKFLOW, the bot credential, Plane connectivity and dashboard port 4100 before launching the bundled binary in the background. It prints the project identifier and name, model/effort, WORKFLOW, repository and agent workspace directories, and logs. It automatically acknowledges unattended operation: Symphony will pick up Todo items assigned to its Codex bot without further confirmation. Use handoff only after explicit approval for Codex; moving a user-assigned item to Todo alone does not dispatch it. Repeated starts report the existing PID. Another repository using port 4100 causes an error.

The child environment excludes PLANE_API_KEY and LINEAR_API_KEY; it receives the bot key from PLANE_CODEX_API_KEY or the codex-token file written by plane bootstrap. Keys are never put in launch arguments, PID records, or command output. Logs and PID records live in .local/symphony/ inside this repository; add that directory to the repository's .gitignore. status returns 0 while running and 1 while stopped. stop signals the entire process group, including active Codex children, and escalates to SIGKILL after a grace period. Logs remain available after stopping. Console output in .local/symphony/logs/symphony.log rotates at 10 MiB with two backups (symphony.log.1 and symphony.log.2, newest first). Rotation continues while Symphony runs; starting again bounds older console logs as well. status prints the log path and retention policy. This is a detached process for the current machine session; it does not install a system service.

MCP tools and prompts

21 tools:

5 prompts: note, capture (also the clarify pass over Unsorted), refine (one item, written back in place, then Codex or Claude Code), next and review. In Claude Code they appear as /mcp__exocortex-project__<name>. For clients without MCP prompts, init writes the same procedures as the skills pm-note, pm-capture, pm-refine, pm-next and pm-review.

Configuration

The package stores no data of its own. Work items live in Plane's Postgres and storage bucket, and plane backup / plane restore cover both.

More

exocortex-project guide prints the full SETUP.md: prerequisites, every step with its expected output, all doctor checks, the optional Symphony setup, and upgrades, backups and rollback. exocortex-project guide upgrade prints UPGRADE.md, the steps from 0.1.x. USAGE.md and ARCHITECTURE.md are next to them in the installed package (guide usage, guide architecture).

License

AGPL-3.0-only, like the Plane code it includes. This project is not affiliated with or endorsed by Plane Software, Inc.