Metadata-Version: 2.4
Name: codex-planner
Version: 0.1.0
Summary: Local orchestration tooling for planner and worker Codex sessions.
Author: Codex Orchestrator maintainers
License-Expression: MIT
Project-URL: Homepage, https://github.com/peremarc/codex-orchestrator
Project-URL: Repository, https://github.com/peremarc/codex-orchestrator
Project-URL: Issues, https://github.com/peremarc/codex-orchestrator/issues
Keywords: codex,cli,orchestration,tmux,git-worktree
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Terminals
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.27.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=6.1.0; extra == "dev"
Dynamic: license-file

# Codex Orchestrator

Codex Orchestrator is an installable CLI tool for coordinating one `planner` Codex session plus multiple `worker` sessions against the same repository.

The design goal is explicit orchestration:

- one global command: `codex-planner`
- one machine-level installation
- one repo-local state directory: `.codex/`
- visible session prompts and traceable runtime actions
- isolated worker worktrees via `git worktree`

## Current Sprint 1 Scope

This repository currently ships the first technical MVP:

- installable Python package with console entrypoint
- one-command launch flow: `codex-planner`
- guided usage command: `codex-planner quickstart`
- repo dashboard command: `codex-planner dashboard`
- repo bootstrap command: `codex-planner init`
- readiness diagnostics: `codex-planner doctor`
- session attach command: `codex-planner attach`
- board inspection commands: `codex-planner list-tasks`, `list-sessions`, `show-handoff`, `show-prompt`
- task creation command: `codex-planner create-task`
- task update commands: `codex-planner update-task`, `request-review`
- planner startup flow: `codex-planner start-planner`
- worker launch flow: `codex-planner spawn-worker`
- generic session closure: `codex-planner close-session`
- worker closure flow: `codex-planner close-worker`
- repo-local MCP/plugin layer backed by `codex-planner serve-mcp`
- YAML-backed board under `.codex/board/`
- real `git worktree` manager for future workers
- terminal backend abstraction with `auto`, `desktop`, and `tmux` modes

Worker orchestration now exists as explicit CLI-driven flows plus a structured MCP/plugin layer. The default `codex-planner` launch path now prepares that direct MCP wiring automatically when possible.

## Installation

### `pipx`

From a local checkout:

```bash
pipx install .
```

Once published to a package index, the same entrypoint can be installed by package name instead of path.

### `uv tool`

From a local checkout:

```bash
uv tool install .
```

Either installation path exposes a global command:

```bash
codex-planner --help
```

## Publishing to PyPI

The repository now includes a release workflow at `.github/workflows/publish.yml` for Trusted Publishing via GitHub Actions.

The distribution package name is `codex-planner`. This keeps the PyPI install name aligned with the CLI command and avoids a collision with an existing `codex-orchestrator` project on PyPI.

Before the first public release:

1. Ensure the package name in `pyproject.toml` is available on PyPI.
2. Create the `codex-planner` project on PyPI if needed.
3. In the PyPI project settings, add a Trusted Publisher for:
   `owner = peremarc`
   `repository = codex-orchestrator`
   `workflow = .github/workflows/publish.yml`
   `environment = pypi`
4. Create the matching `pypi` environment in GitHub if you want environment protection rules.

To validate distributions locally before publishing:

```bash
python3 -m pip install --upgrade build twine
python3 -m build
python3 -m twine check dist/*
```

To publish automatically:

- push the workflow file to GitHub
- create a GitHub Release
- the workflow will build `sdist` and `wheel`, then publish them to PyPI through Trusted Publishing

If you need a manual fallback instead of GitHub Actions:

```bash
python3 -m pip install --upgrade build twine
python3 -m build
python3 -m twine upload dist/*
```

After publication, the tool is installable globally with:

```bash
pipx install codex-planner
```

or:

```bash
pip install codex-planner
```

## Fastest Path

Inside a Git repository, the simplest operator path is now:

```bash
codex-planner
```

In one step, that command:

1. checks that the machine is ready enough to launch the planner
2. initializes `.codex/` if needed
3. ensures the direct Codex MCP server registration for `codex-orchestrator-local`
4. reconciles stale planner or worker sessions whose terminal backends no longer exist
5. starts a planner session if one is not already running for the repo
6. if no planner terminal is currently running, resumes the latest Codex planner session recorded for this repo when available
7. otherwise reuses the running planner session
8. ensures a repo dashboard session exists when the active backend supports dashboards
9. attaches you to that dashboard or planner session immediately when the command is run interactively

If you run it from a non-interactive context, it still performs the setup and prints the relevant attach or visibility command instead of blocking.

If you want a clean planner context instead of resuming the last one:

```bash
codex-planner --new-session
```

If you want the tool to explain the operator flow with concrete commands for the current repository:

```bash
codex-planner quickstart
```

That command prints:

- the active terminal backend
- whether the repo is already initialized
- the recommended planner-first workflow
- the structured handoff flow that workers receive
- example manual commands for creating a task and launching a worker
- the live planner and worker session names, when they already exist

## Global vs Repo-Local State

The tool is intentionally split into two layers:

### Global installation and config

- installed once per machine
- configuration lives outside repos
- default config path:
  `~/.config/codex-orchestrator/config.toml`

### Repo-local runtime state

- created per repository with `codex-planner init`
- stored only under `.codex/`
- contains board files, prompts, logs, and rendered prompt artifacts

`Codex Orchestrator` does not store repo runtime state in a global cache.

## Global Configuration

Default config file:

```toml
[defaults]
terminal_backend = "auto"
codex_executable = "codex"
git_executable = "git"

# Optional
# worktrees_base_dir = "~/codex-worktrees"
# planner_model = "gpt-5.4"
# worker_model = "gpt-5.4-mini"
```

Supported terminal backend values:

- `auto`: prefer a desktop terminal window when a graphical session is available and a supported emulator exists; otherwise fall back to `tmux`
- `desktop`: force a native terminal window per planner or worker session; currently supports `gnome-terminal` and `xterm`
- `tmux`: force the tmux-backed dashboard and attach flow

Supported environment overrides:

- `CODEX_ORCHESTRATOR_CONFIG`
- `CODEX_ORCHESTRATOR_TERMINAL_BACKEND`
- `CODEX_ORCHESTRATOR_CODEX_EXECUTABLE`
- `CODEX_ORCHESTRATOR_GIT_EXECUTABLE`
- `CODEX_ORCHESTRATOR_WORKTREES_BASE_DIR`
- `CODEX_ORCHESTRATOR_PLANNER_MODEL`
- `CODEX_ORCHESTRATOR_WORKER_MODEL`

Environment variables override file-based settings.

## Doctor

Run this before using the tool on a machine:

```bash
codex-planner doctor
```

`doctor` currently checks:

- global config loading
- `codex` availability
- `git` availability
- `git worktree` usability
- configured terminal backend readiness

Backend-specific readiness:

- `auto` resolves to `desktop` when `DISPLAY` or `WAYLAND_DISPLAY` is set and a supported terminal emulator is available; otherwise it resolves to `tmux`
- `desktop` requires a graphical session plus either `gnome-terminal` or `xterm`
- `tmux` requires `tmux` on `PATH`

## Repository Bootstrap

Inside a Git repository:

```bash
codex-planner init
```

This creates the repo-local control plane:

```text
.codex/
  board/
    tasks.yaml
    sessions.yaml
    decisions.md
    risks.md
    backlog.md
  handoffs/
  prompts/
    planner.md
    worker.md
    reviewer.md
  logs/
    orchestrator.jsonl
  state/
    rendered_prompts/
```

The YAML files are the shared source of truth for tasks and active sessions.

## Start the Planner

After `init`:

```bash
codex-planner start-planner
```

For normal day-to-day use, prefer `codex-planner` without subcommands. `start-planner` remains available when you want an explicit low-level entrypoint.

What this does today:

1. validates the repo is initialized
2. resumes the latest Codex planner session recorded for this repo when one exists
3. otherwise renders a persisted planner prompt into `.codex/state/rendered_prompts/`
4. prepares the corresponding interactive Codex CLI command, including per-session Codex config overrides when needed
5. launches the configured terminal backend
6. registers the planner session in `.codex/board/sessions.yaml`
7. appends a trace event to `.codex/logs/orchestrator.jsonl`

To force a clean planner conversation from this lower-level entrypoint:

```bash
codex-planner start-planner --new-session
```

For tmux-backed interactive sessions, the launcher also detects Codex's initial per-repo trust prompt and confirms it automatically when it appears.

If Codex already has an orchestrator MCP server configured under `codex-orchestrator-local` or `codex-orchestrator`, `start-planner` also injects a per-session override that sets `default_tools_approval_mode="approve"` for that server. This keeps the planner's own orchestration tool calls from stopping on a repeated approval menu while avoiding invalid overrides for MCP servers that are not actually installed in the local Codex config.

The default `codex-planner` launch path goes one step further and ensures the direct `codex-orchestrator-local` MCP registration exists before planner startup, so a fresh machine does not require a separate manual `codex mcp add` just to reach a usable planner.

Sprint 1 decision:

- the `planner` runs in the main repository worktree
- extra worktrees are reserved for future worker sessions
- the default portable launcher path is `terminal_backend = "auto"`, which uses separate native terminal windows on graphical machines and falls back to a repo-scoped tmux dashboard on headless or terminal-only machines

## Planner Tool Layer

The repository now includes a repo-local plugin scaffold under `plugins/codex-orchestrator-tools/` plus a marketplace file at `.agents/plugins/marketplace.json`.

The plugin does not depend on local source paths. It launches the globally installed CLI entrypoint:

```bash
codex-planner serve-mcp
```

Activate the repo-local marketplace from the repository root:

```bash
codex marketplace add .
```

If you prefer a direct machine-level MCP registration instead of the repo-local marketplace:

```bash
codex mcp add codex-orchestrator -- codex-planner serve-mcp
```

Live validation in this repository confirmed that a planner started after direct MCP registration can call the orchestrator tools through Codex without per-tool approval prompts, as long as the configured server name matches one of the supported orchestrator registrations above.

The structured tool layer currently exposes:

- `doctor`
- `init_repo`
- `list_tasks`
- `create_task`
- `update_task`
- `request_review`
- `list_sessions`
- `spawn_worker`
- `close_session`
- `close_worker`
- `show_handoff`
- `show_prompt`

When invoking these tools from a planner session, pass `repo_path` explicitly when you need deterministic repo targeting.

## Watching Sessions

When a worker is spawned, it gets its own terminal backend session and the spawn result includes an attach command. Today, with the `tmux` backend, the operator model is:

- one repo dashboard `tmux` session
- one dashboard window for the planner
- one dashboard window per active worker
- explicit attach commands if you want to jump straight to an individual planner or worker backend session

With the `desktop` backend, the operator model is:

- one native terminal window for the planner
- one native terminal window per active worker
- no repo dashboard session
- no interactive reattach support; the command output tells you which terminal process was launched

The simplest way back into the operator view is:

```bash
codex-planner
codex-planner dashboard
codex-planner attach
```

You can still jump into any running session directly:

```bash
codex-planner attach planner
codex-planner attach worker-task-003
```

If `attach` is called without a session name, it prefers the repo dashboard and falls back to the active planner session only if no dashboard exists.

With the `desktop` backend, `attach` prints the visibility hint for the existing native terminal window instead of trying to reattach.

## Task and Worker Lifecycle

Create a task explicitly in the shared board:

```bash
codex-planner create-task "Implement worker launcher" \
  --write-scope src/codex_orchestrator/orchestrator.py \
  --read-scope src/codex_orchestrator/board.py \
  --acceptance "Worker prompt is persisted"
```

Each task now gets a structured handoff file under `.codex/handoffs/`. If you do not provide a handoff path in `write_scope`, the tool creates one automatically and records it on the task as `handoff_file`.

Inspect the structured handoff that a worker will receive:

```bash
codex-planner show-handoff TASK-001
```

Or only print the resolved handoff file path:

```bash
codex-planner show-handoff TASK-001 --path-only
```

Inspect board state:

```bash
codex-planner list-tasks
codex-planner list-sessions --active-only
```

For machine-readable output:

```bash
codex-planner list-tasks --format yaml
codex-planner list-sessions --format json
```

Update a task when planning changes:

```bash
codex-planner update-task TASK-001 \
  --status blocked \
  --clear-owner \
  --acceptance "Waiting on design decision"
```

Mark a task ready for review:

```bash
codex-planner request-review TASK-001
```

Spawn a worker for a task:

```bash
codex-planner spawn-worker TASK-001
```

This flow:

1. validates the task exists
2. creates or reuses an isolated worktree
3. ensures the task has a structured handoff file and injects its content into the worker prompt
4. launches a terminal session through the configured backend
5. marks the task `in_progress`
6. registers the worker in `.codex/board/sessions.yaml`

Close a worker in the board when it finishes or hands off:

```bash
codex-planner close-worker worker-task-001 --task-status review_ready
```

If you also want the backend terminal session terminated:

```bash
codex-planner close-worker worker-task-001 --task-status review_ready --terminate-terminal
```

`spawn-worker` and `--terminate-terminal` both depend on the configured terminal backend being available. With the default backend, that means either a supported desktop terminal environment or `tmux`.

Close any session generically, including `planner`:

```bash
codex-planner close-session planner --terminate-terminal
```

For worker sessions, `close-session` can also carry a task transition:

```bash
codex-planner close-session worker-task-001 --task-status review_ready --terminate-terminal
```

Inspect the persisted prompt sent to a session:

```bash
codex-planner show-prompt worker-task-001
```

Or only print the prompt file path:

```bash
codex-planner show-prompt worker-task-001 --path-only
```

## Worktree Strategy

Worker worktrees are managed by the package, not by ad hoc shell snippets.

Default layout:

- main repo stays where it is
- worker worktrees default to a sibling directory named `<repo>-worktrees/`

This can be overridden globally with `worktrees_base_dir`.

## Development

Install editable mode with dev dependencies:

```bash
python3 -m pip install -e '.[dev]'
```

Run tests:

```bash
python3 -m pytest
```

Current automated coverage includes:

- board bootstrap and YAML persistence
- global config loading and env overrides
- orchestration flows for task creation, worker spawn, and worker close
- orchestration flows for task listing, update, review handoff, session listing, and prompt inspection
- planner tool wrapper flows and MCP server tool registration
- real `git worktree` creation

## Constraints of the Current MVP

- `desktop` currently supports `gnome-terminal` and `xterm` only
- the `desktop` backend opens real windows but does not support dashboard mode or interactive reattach
- planner-driven automatic plugin adoption is not implemented yet
- prompt inspection only works after a session has been created and persisted in the board
- no web UI or SDK-heavy orchestration has been added
