Claude Codex Project OS

Project OS for Claude Code and Codex

Task planning, development and QA workflows for Claude Code and Codex, stored in Markdown files.

A PM session records tasks and acceptance criteria, requests approval, and assigns work to Developer and QA roles. QA runs checks separately. Saved task files let a new session review the previous state and continue.

The workflow covers:

Claude Code and Codex use the same files, so you can switch clients between steps.

Quick start with Claude Code

You need Node.js 22+ and Claude Code. Nothing else is installed.

Then type /project-os-start and describe what you want to build. A typical first session:

Close the session whenever you like. Next time run claude and type /project-os-resume: the PM reads the board and Hand-off notes and tells you what is done and what comes next.

Want to look around first? Add --example to the install command to get Trailboard, a small reading-list project with one proposed task.

What gets installed

A new folder (the installer never touches existing ones) containing:

Nothing is written to your global Claude or Codex settings, and permissions stay as you have them. Subagents are limited by their tool lists, but your normal permission prompts still apply.

Codex and both clients

Codex gets AGENTS.md, four role definitions in .codex/agents and the same four skills ($project-os-start and others). With both, the two clients share one planning folder. Only one writer works in a repository at a time, whichever client it uses. See the Codex guide.

How a task moves

QA can send work back to the Developer twice. A third attempt needs a new plan and your approval. Risky changes also get a security review and the read-only Reviewer. "Done" means verified, not committed or deployed.

Use it with existing…