Metadata-Version: 2.5
Name: exocortex-project
Version: 0.1.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
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: 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.6
Requires-Dist: markdownify>=0.13
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: 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 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.1.0):** `setup --bare` and the full loop with a stand-in Codex have been tested.
`plane up --docker` / `setup --docker` and Symphony runs with real Codex are not yet verified.

## 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`.
- **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`, `USAGE.md` and `ARCHITECTURE.md`.

Not bundled: PostgreSQL, Redis or Valkey, and MinIO or S3 (for `--bare`), or Docker (for
`--docker`); Symphony with a Plane tracker adapter, and the Codex CLI (optional); 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.

## MCP tools and prompts

17 tools:

| tool          | does                                                                                 |
| ------------- | ------------------------------------------------------------------------------------ |
| `note`        | record the user's words verbatim as one item in `待整理` (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: unstarted, no open blocker, best first                              |
| `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                                          |
| `start`       | move an item to `In Progress` and name its branch                                    |
| `set`         | change state, priority, title, dates, parent or assignee, with a dry run             |
| `link`        | add blocked-by, blocks, parent or duplicate links                                    |
| `comment`     | add a Markdown comment                                                               |
| `history`     | an item's activity, oldest first                                                     |
| `review`      | what waits in `Human Review`, longest wait first, with patch stats                   |
| `approve`     | move a reviewed item to `Merging` or `Done`                                          |
| `rework`      | comment what to change, then move the item to `Rework`                               |
| `states_init` | give a project the nine states, adding only the missing ones                         |
| `plane_api`   | one call to any other Plane `/api/v1/` endpoint                                      |

4 prompts: `note`, `capture` (also the clarify pass over `待整理`), `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-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`)                                         |
| 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>`                                                          |

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.
`USAGE.md` and `ARCHITECTURE.md` are next to it in the installed package.

## License

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