Codex Control Tower

Durable coordination, context persistence, and worker-thread protocols for large Codex projects.

Codex Control Tower separates project coordination from task execution:

• The Control Tower coordinates goals, decisions, task boundaries, worker outputs, and reviews.
• Worker threads execute one narrow task at a time.
• .tower/ stores durable state so conversations can be compacted, closed, or replaced without losing requirements.
• Skills and templates make the workflow reusable across projects.

Core Idea

Do not use chat history as the project database. Use the chat window as a work surface and persist anything durable to files:

• long-lived requirements
• decisions
• task status
• worker handoffs
• checkpoints
• bootstrap prompts

Repository Layout

skills/control-tower/
  SKILL.md
  references/templates.md

templates/project/
  AGENTS.md
  .tower/

docs/
  control-tower-method.md
  context-capsule-protocol.md
  worker-thread-protocol.md
  worker-report-protocol.md

Quick Start

From the root of the project you want to coordinate:

cp /path/to/Codex-Control-Tower/templates/project/AGENTS.md ./AGENTS.md
cp -R /path/to/Codex-Control-Tower/templates/project/.tower ./.tower

Then:

1. Fill .tower/control_state.md with the current objective and next coordination step.
2. Record long-lived constraints in .tower/requirements.md.
3. Add work items to .tower/tasks.md.
4. Copy .tower/thread-task-template.md for each bounded worker task.
5. Before context migration, update .tower/checkpoints.md and .tower/bootstrap_prompt.md.

On PowerShell, use Copy-Item instead of cp -R.

Example: Coordinate a Health Endpoint Change

Suppose an existing service needs a GET /health endpoint, tests, and documentation. After copying the template files, replace .tower/control_state.md with:

# Control Tower State

## Current Objective

Add a production-ready `GET /health` endpoint without changing existing API behavior.

## Current Context

The service code is under `src/`; HTTP tests are under `tests/http/`.

## Current Constraints

- Keep the response schema to `{ "status": "ok" }`.
- Do not add a new runtime dependency.
- Existing tests must continue to pass.

## Next Coordination Step

Dispatch T001 to a worker, review its artifact, then accept or request changes.

Add the task to .tower/tasks.md:

| ID | Task | Owner | Status | Scope | Notes |
|---|---|---|---|---|---|
| T001 | Implement and test `GET /health` | worker | planned | `src/http/`, `tests/http/`, `README.md` | No dependency changes |

Create the concrete task card, then fill its task-specific fields:

cp .tower/thread-task-template.md .tower/T001-task.md

# Codex Worker Thread Task: Add GET /health

## Role

You are a specialized Codex worker thread. You are not the Control Tower.

## Goal

Implement `GET /health`, add HTTP coverage, and document the endpoint.

## Context to Read First

1. `AGENTS.md`
2. `.tower/protocol.md`
3. `.tower/control_state.md`
4. `.tower/tasks.md`
5. `src/http/`
6. `tests/http/`

## Allowed Scope

You may modify `src/http/`, `tests/http/`, and the endpoint section of `README.md`.

## Forbidden Scope

Do not change dependencies, authentication behavior, or unrelated routes.

## Done When

1. `GET /health` returns HTTP 200 and `{ "status": "ok" }`.
2. Relevant tests pass, or failures are documented.
3. The artifact is written to `.tower/artifacts/T001.md`.
4. The worker report is written to `.tower/reports/tasks/T001.worker-report.md`.
5. The completion signal is written to `.tower/inbox/T001.done.md`.

Start the worker with the contents of .tower/T001-task.md. When it finishes, review these durable outputs in order:

1. .tower/inbox/T001.done.md
2. .tower/artifacts/T001.md
3. .tower/reports/tasks/T001.worker-report.md

Finally, update .tower/tasks.md to review or done and record any accepted decision in .tower/decisions.md. A replacement Control Tower can now recover the task without the original chat transcript.

Skill Installation

Copy skills/control-tower/ to your Codex skills directory. For example, on Windows:

%USERPROFILE%\.codex\skills\control-tower

Then invoke it with:

Use $control-tower to initialize a durable Control Tower workflow for this project.

Design Principle

The goal is not to reduce AI participation. The goal is to stop AI agents from using long natural-language chats as an unreliable database.

The Control Tower remains an AI coordinator. The file layer is its external working memory.

Future Direction

Version 0.1.0 is intentionally a lightweight, file-based workflow. The longer-term direction is to evolve it into a small deterministic coordination kernel around AI execution, with:

• one canonical state source and an append-only event log
• versioned, bounded context projection
• typed action proposals and capability-based enforcement
• idempotent dispatch, leases, fencing, and crash reconciliation
• disposable worker environments and independent verification gates
• a candidate-to-validation-to-publication pipeline for reusable skills

These ideas are a roadmap and RFC, not guarantees of current behavior. See Roadmap RFC: Evolve the file-based Control Tower into a deterministic coordination kernel for the proposed architecture, phases, acceptance tests, risks, and open questions.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the development and review process.

License

Licensed under the MIT License.