Project OS for Codex is for the moment when a team asks: What is the AI doing? Where should the next session start? How can another person or AI take over without rereading every chat?
It is not another AI chat window. It is the control plane around the work: kickoff card, acceptance criteria, current progress, Git evidence, next action, reusable knowledge, and a handoff package that both humans and agents can read.
💡 Why Does This Exist?
AI can generate code quickly, but real projects still fail in very ordinary ways:
- The project progress is hidden inside chat history.
- The next AI session does not know where to start.
- Humans cannot tell which tasks are done, blocked, risky, or waiting for review.
- Handoffs become painful because context is scattered across prompts, screenshots, commits, and private notes.
- Teams lose trust because there is no visible project trail.
Project OS for Codex turns those scattered pieces into one workspace: project goals, acceptance criteria, Git records, progress events, risks, next steps, knowledge, and handoff packages.
Built from repeated real delivery work
This is not a weekend concept built from imagined agent problems. It was distilled from recurring problems seen across many real internal and client projects, then refined through sustained Codex use: context loss, invisible progress, unclear acceptance, difficult handoffs, and knowledge that disappears after delivery.
The anonymized July 2026 maintainer snapshot below shows 14,570 Codex tasks, 8.8B lifetime tokens, a 23-day streak, and 743 skill uses. These numbers are evidence of maintainer practice—not repository users, downloads, adoption, or 14,570 separate projects.
Explain It Like I Am New
Think of this system as a project cockpit for AI-assisted development.
When an AI helps you build a project, it should not only write code. It should also leave behind:
- what it changed;
- why it changed it;
- what still needs to be done;
- what risks remain;
- what the next human or AI should read first.
This repository provides the structure for that cockpit. It helps a project become something another person or AI can continue, instead of a one-time chat transcript.
Connect Codex
Do not give an AI your website username and password. From a project page, create a short-lived AI credential that is bound to one workspace and one project, then run the generated MCP command in your own terminal.
The first production-oriented slice exposes two real MCP tools:
project_os_get_context— reads the kickoff card, acceptance criteria, AGENTS rules, handoff package, progress, Git trail, and next step;project_os_append_progress— appends one validated, audited, idempotent progress event, an agent-reported verification note, and one matching project-record Git commit.
Credentials expire after 24 hours or 7 days, can be revoked independently, are stored only as hashes, and cannot access members, keys, deletion, publication, or deployment.
Version 0.3.0 adds a fail-closed first-run contract:
- the MCP process verifies the credential, project binding, scopes, and exact two-tool surface before Codex starts using it;
- the project-level configuration requires the server and allowlists only the released tools;
- from a checked-out and installed repository,
pnpm codex:doctorexercises that checkout's MCP server and backend without calling the progress-write tool; normal credential usage and audit metadata are still recorded, and this local check does not prove that Codex loaded a saved client configuration or the pinned Git tag; - root and generated
AGENTS.mdfiles tell Codex to read context first, verify one vertical slice, and only then write progress back.
Follow the Codex setup guide →
Designed around Codex's real extension points
- Codex reads the repository's root
AGENTS.mdbefore work starts. - The stdio MCP server returns concise workflow instructions during initialization.
- Tool annotations distinguish the project-state read context tool from the scoped progress-write tool; successful reads still update credential-use and audit metadata.
.codex/config.toml.exampleshows a project-scoped configuration that forwards local environment variables without committing secret values.- The same MCP configuration can be used by Codex CLI, the Codex IDE extension, and the ChatGPT desktop app on the same Codex host.
- High-risk actions stay outside the MCP surface and require a human.
See OpenAI's official MCP and AGENTS.md documentation. This repository extends Codex with project context and progress records; it is not a fork or replacement for Codex.
Core Loop
- Create a project with a kickoff card.
- Define the goal, acceptance criteria, non-goals, owner, and next step.
- The server creates a local Git-backed project record for the kickoff, progress, issues, and handoff files.
- Humans or AI agents post progress events.
- Important progress becomes a project record and can be linked to Git commits.
- The dashboard shows status, health, progress, and the recorded next action.
- A handoff package lets the next AI or human resume without rereading the whole history.
- Retrospectives and project notes become reusable knowledge for the next project.
Key Features
Project kickoff cards
Start every project with a clear brief:
- project goal;
- expected result;
- acceptance criteria;
- non-goals;
- current owner;
- next step.
Visible AI progress
Track project state with progress events instead of guessing from chat logs:
- active / paused / done project states;
- progress percentage;
- owner;
- next action;
- green / yellow / red project health.
Git-backed evidence
The system is designed around Git as the durable project record:
- project workspace records;
- Git file tracking;
- commit-friendly progress notes;
- audit trail for what changed and why.
Handoff packages
Generate context that another AI or human can use immediately:
- project summary;
- current state;
- important files;
- recent decisions;
- blocked items;
- next step;
- acceptance checklist.
Knowledge base and retrospectives
Turn finished project experience into reusable knowledge:
- project lessons;
- delivery patterns;
- reusable prompts and checklists;
- project review notes;
- future improvement ideas.
Adapter-friendly open-source design
The open-source version keeps private infrastructure behind replaceable boundaries:
- Git database / Git service adapter;
- AI provider adapter;
- knowledge-base adapter;
- deployment and reverse-proxy boundary;
- local JSON persistence for simple evaluation.
No private API keys, production provider addresses, customer data, or internal deployment secrets are included.
AI-native access instead of password sharing
- one short-lived credential per AI and project;
- workspace and project isolation enforced on the server;
- explicit read/append scopes;
- idempotent writes and Git request IDs;
- revocation and audit history;
- one focused MCP integration for Codex.
Current scope and honest limits
The current release is a focused project-record layer around Codex, not a replacement agent runtime.
- It does not run Codex, monitor Codex sessions automatically, or control a Codex account.
- It does not connect to or modify an existing source repo