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.
If that problem feels familiar, a ⭐ Star helps more AI builders discover the project.
💡 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 or Claude Code in 3 Minutes
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 and one matching 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.
Follow the Codex and Claude Code setup guide →
Core Loop
- Create a project with a kickoff card.
- Define the goal, acceptance criteria, non-goals, owner, and next step.
- The server creates or connects a real Git-backed project workspace.
- 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 shared MCP integration for Codex and Claude Code.
Open-Source Surface
This repository is the focused OSS Project OS surface. It exposes the project cockpit, kickoff cards, Git-backed progress, handoff packages, team spaces, knowledge base, and retrospectives.
Commercial SaaS modules such as sales back-office pages, paid-plan operations, platform administration, announcement systems, and payment infrastructure have been removed from the public runtime and source tree. A fresh local run starts as a normal project workspace, not as a hosted commercial admin console.
This repository does not include a hosted commercial service, private provider credentials, production customer data, payment infrastructure, or internal deployment secrets.
Who Is This For?
This project is useful if you are:
- building projects with AI coding agents;
- managing multiple AI-assisted software projects;
- using tools such as Codex, Claude Code, Cursor, Cline, OpenHands, or other coding agents;
- trying to make AI work visible to teammates, stakeholders, or future maintainers;
- tired of losing project context between chat sessions;
- building an internal AI project management platform;
- exploring context engineering, agent handoff, and Git-based AI workflows.
Common Use Cases
- AI project management dashboard
- AI coding agent progress tracker
- Agent handoff and context package generator
- Git-backed project execution system
- Internal project operating system for AI teams
- Knowledge base for repeated AI delivery work
- Customer-facing project progress visibility
- Multi-project AI workflow control center
Screenshots and Diagrams
Working project cockpit
Connect Codex / Claude Code
Screenshots use an isolated local workspace with non-sensitive sample content. No customer account, production endpoint, or private credential is shown.
Workflow diagram
Git loop diagram
Architecture diagram
Tech Stack
- Frontend: React, Vite, TypeScript, Tailwind CSS
- Backend: Node.js, Express
- Persistence: local JSON files by default
- Project