Metadata-Version: 2.5
Name: exocortex-project
Version: 0.3.0
Summary: Plane-backed work tracking for coding agents: capture, ready queue, prompt packs and Human Review over a self-hosted Plane fork.
License-Expression: AGPL-3.0-only AND Apache-2.0
License-File: src/exocortex_project/bundled_symphony/LICENSE.symphony
License-File: src/exocortex_project/bundled_symphony/NOTICE.symphony
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4==4.12.3
Requires-Dist: boto3==1.34.96
Requires-Dist: celery==5.5.3
Requires-Dist: channels==4.3.2
Requires-Dist: cryptography==50.0.0
Requires-Dist: dj-database-url==3.0.1
Requires-Dist: django-celery-beat==2.9.0
Requires-Dist: django-celery-results==2.6.0
Requires-Dist: django-cors-headers==4.9.0
Requires-Dist: django-crum==0.7.9
Requires-Dist: django-filter==25.2
Requires-Dist: django-redis==7.0.0
Requires-Dist: django-storages==1.14.6
Requires-Dist: django==5.2.15
Requires-Dist: djangorestframework==3.17.2
Requires-Dist: drf-spectacular==0.29.0
Requires-Dist: faker==25.0.0
Requires-Dist: graphql-core==3.3.0
Requires-Dist: gunicorn==23.0.0
Requires-Dist: httpx>=0.27
Requires-Dist: jsonmodels==2.7.0
Requires-Dist: jsonschema>=4.20
Requires-Dist: lxml==6.1.0
Requires-Dist: markdown==3.10.3
Requires-Dist: markdownify==1.2.3
Requires-Dist: mcp<3,>=2.2
Requires-Dist: nh3==0.2.18
Requires-Dist: openai==1.63.2
Requires-Dist: openpyxl==3.1.2
Requires-Dist: opentelemetry-api==1.28.1
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc==1.28.1
Requires-Dist: opentelemetry-exporter-otlp==1.28.1
Requires-Dist: opentelemetry-instrumentation-django==0.49b1
Requires-Dist: opentelemetry-sdk==1.28.1
Requires-Dist: psycopg-binary==3.3.4
Requires-Dist: psycopg==3.3.4
Requires-Dist: pyjwt==2.13.0
Requires-Dist: python-json-logger==4.0.0
Requires-Dist: pytz==2024.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: redis==5.0.4
Requires-Dist: requests==2.33.0
Requires-Dist: scout-apm==3.5.3
Requires-Dist: slack-sdk==3.27.1
Requires-Dist: urllib3>=2.7.0
Requires-Dist: uvicorn>=0.31.1
Requires-Dist: whitenoise==6.12.0
Requires-Dist: zxcvbn==4.4.28
Description-Content-Type: text/markdown

# 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 the
`Backlog` item to work in your session, straight to Done; or an item is dropped into `Todo`: `Todo`
is the Codex queue, and Symphony picks up every item there. Codex's 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.3.0):** `Todo` is the Codex queue (every item there is picked up), Claude Code works
`Backlog` items straight to `Done`, and the project has an Agents page for Symphony's state.
Symphony is inside the package (upstream v0.0.3, unmodified) and reads
Plane through Plane's Linear-compatible interface. `setup --bare`, the upgrade from 0.1.x
(`UPGRADE-0.1-to-0.2.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:** the guides are named by the versions they go
between, `UPGRADE-0.1-to-0.2.md` and `UPGRADE-0.2-to-0.3.md`; `exocortex-project guide upgrade`
prints the newest, `guide upgrade --from 0.1` the older one.

## 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-<from>-to-<to>.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.

```sh
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:

```sh
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:

```sh
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:

```sh
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 every item in
Merging, 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:

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

It claims `exocortex-project://open?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 ("Read work
item PROJ-12 with the show tool, then ask me what to do with it."), 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: `Todo` is the Codex queue, and Symphony picks up every item dropped into `Todo`, whoever
it is assigned to, without further confirmation (an item with an open blocker waits until the blocker
is `Done` or `Cancelled`). 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

19 tools:

| tool           | does                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| `note`         | record the user's words verbatim as one item in `Unsorted` (the inbox for quick notes)                       |
| `capture`      | create or update well-specified items with parent and blocked-by links, in one call                          |
| `ready`        | the ready queue: `Backlog` items with no open blocker, best first (`Todo` is the Codex queue)                |
| `prompt`       | the context pack for one item (north star, brief, parent, blockers, progress)                                |
| `show`         | one item in full                                                                                             |
| `list`         | a project's items, filtered by state or name                                                                 |
| `blocked`      | open items still waiting on an open blocker                                                                  |
| `merge_target` | show, set or clear where an item's approved change lands (its own repository and branch, else the project's) |
| `set`          | change state (`Todo` hands an item to Codex), priority, title, dates, parent or assignee, with a dry run     |
| `link`         | add blocked-by, blocks, parent or duplicate links                                                            |
| `comment`      | add a Markdown comment                                                                                       |
| `move`         | move an item to another project (new identifier there); keeps comments, attachments, links, history          |
| `history`      | an item's activity, oldest first                                                                             |
| `review`       | what waits in `Human Review`, longest wait first, with patch stats; flags items with nothing attached        |
| `approve`      | move a reviewed item to `Merging` or `Done`; refuses an item with nothing attached unless `force`            |
| `rework`       | comment what to change, then move the item to `Rework`                                                       |
| `answer`       | answer a blocked item, then move it back to `In Progress` (same workpad, same branch)                        |
| `states_init`  | give a project the nine states, adding only the missing ones                                                 |
| `plane_api`    | one call to any other Plane `/api/v1/` endpoint                                                              |

5 prompts: `note`, `capture` (also the clarify pass over `Unsorted`), `refine` (one item, written back
in place, then into `Todo` for Codex or left in `Backlog`), `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

| what                                                        | where                                                                                                                                      |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Plane URL, workspace, assignee, review state, notify states | `.exocortex-project.toml` in the repository, else `~/.config/exocortex-project/config.toml`; `PLANE_*` environment variables override both |
| API key                                                     | `PLANE_API_KEY`, else `~/.config/exocortex-project/token` (mode 600, written by `plane bootstrap`)                                         |
| the Codex bot's key (Symphony only)                         | `PLANE_CODEX_API_KEY`, else `~/.config/exocortex-project/codex-token` (mode 600, written by `plane bootstrap`)                             |
| MCP registration                                            | `.mcp.json` in the repository and `~/.codex/config.toml` (written by `init`)                                                               |
| default project                                             | the `exocortex-project` section of the repository's `AGENTS.md` (written by `init`)                                                        |
| Plane runtime (`.env`, logs)                                | `~/.local/share/exocortex-project/plane/` (`--runtime-dir` to change)                                                                      |
| Symphony workflow                                           | `WORKFLOW.md`, written by `exocortex-project symphony workflow --project <IDENT> [--model <model>] [--effort <effort>]`                    |
| Symphony runtime                                            | `.local/symphony/` in the repository: PID record, console log and upstream logs                                                            |

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 the newest upgrade guide (`UPGRADE-0.2-to-0.3.md`);
`guide upgrade --from 0.1` prints `UPGRADE-0.1-to-0.2.md`. `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.
