Project OS for Codex MCP Server

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.

Related MCP server: AgentBridge MCP

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:doctor exercises 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.md files 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.md before 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.example shows 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

1. Create a project with a kickoff card.

2. Define the goal, acceptance criteria, non-goals, owner, and next step.

3. The server creates a local Git-backed project record for the kickoff, progress, issues, and handoff files.

4. Humans or AI agents post progress events.

5. Important progress becomes a project record and can be linked to Git commits.

6. The dashboard shows status, health, progress, and the recorded next action.

7. A handoff package lets the next AI or human resume without rereading the whole history.

8. 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 repository. Its Git commits belong to the local Project OS record repository.

• A verification note is reported by Codex and stored for review; the server validates structure, identity, scope, idempotency, and progress rules, but it does not independently prove that source code or a deployment passed.

• The released MCP surface contains exactly two tools: scoped context read and scoped progress append.

• Existing source-repository integration, richer evidence, handoff drafts, knowledge drafts, remote MCP, and OAuth remain roadmap work.

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 Codex for real, multi-session software delivery;

• 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

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 record model: Git-oriented project workspace

• License: Apache-2.0

Quick Start

Requirements:

• Node.js 22+ (a currently supported LTS line)

• pnpm 9+

• Git

The fastest local-only start is Docker Compose:

docker compose up --build

Open http://localhost:8790. The included Compose file binds to 127.0.0.1 and enables password-free access only for local evaluation.

For a manual development start, install frontend dependencies:

pnpm install

Start the backend:

pnpm --dir server run seed
PROJECT_OS_DEV_NO_AUTH=true pnpm --dir server start

Start the frontend in another terminal:

pnpm dev

Open the Vite URL shown in your terminal. The API listens on:

http://localhost:8790

Production refuses to start without PROJECT_OS_AUTH_USER and PROJECT_OS_AUTH_PASSWORD.

For local, server, reverse-proxy, storage, backup, Git, AI provider, and knowledge-base setup, see:

• Deployment Guide

• Interface and Adapter Contracts

• Codex MCP Setup

• Publication Security Checklist

Agent Event Example

Project secrets must be sent in the X-Project-Key header. Do not put secrets in URLs.

curl -X POST http://localhost:8790/api/projects/<project-id>/events \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Key: <project-secret>' \
  -H 'Idempotency-Key: progress-step-001' \
  -d '{"message":"Add handoff checklist","verification":"The checklist page loaded and each acceptance item was reviewed.","progressTo":55,"nextStep":"Run acceptance smoke test"}'

Repository Keywords

People may find this project while searching for:

• AI project management

• Codex project management

• Codex delivery workflow

• MCP server

• Model Context Protocol

• AI coding agent dashboard

• agent handoff

• context engineering

• Git-based project management

• AI workflow automation

• project progress tracker

• knowledge base for AI teams

• developer tools for AI-assisted software delivery

Current Status

This repository is an early public open-source release.

Version 0.3.0 closes the audited global-role/workspace-role escalation path, prevents startup migration from guessing or restoring a revoked default-workspace owner, and adds regression coverage for those boundaries. It also adds a reproducible repository-local MCP/backend connection doctor. The MCP surface remains exactly two scoped tools.

Before production use, review the release gate:

• multi-tenant permission audit;

• no production tokens, private domains, private docs, or customer data;

• pnpm run check passes;

• Agent API + MCP acceptance tests pass;

• light and dark UI screenshots reviewed;

• clear deployment, backup, and rollback plan.

Roadmap

• Stronger project role model

• Remote OAuth-protected MCP transport

• More scoped tools for handoff drafts and knowledge drafts

• Better visual progress timeline

• Provider adapter examples without shipping private keys

• Playwright smoke tests

• A short end-to-end workflow GIF and more guided examples

• More beginner-friendly setup recipes

Independent Project

Codex is a trademark of OpenAI. This independent open-source project is not affiliated with or endorsed by OpenAI.

Long-term Maintenance

This repository is intended to be maintained in public. Every release will document verified additions, security changes, known limits, and the next milestone in CHANGELOG.md and ROADMAP.md.

The latest release is v0.3.0: Codex First-Run Contract—fail-closed MCP preflight, a project-state connection doctor, strict tool allowlisting, clearer AGENTS.md execution rules, and workspace-role security regression tests.

The next milestone is v0.4.0: guided Codex onboarding. Remote MCP, OAuth, source-repository synchronization, and maintainer automation remain planned work and are not presented as released functionality.

Contributing

Issues, ideas, and pull requests are welcome. Good contributions include:

• clearer documentation;

• adapter examples;

• deployment recipes;

• UI improvements;

• security hardening;

• real-world AI project workflow cases.

If this project helps you, starring the repository makes it easier for more AI builders and project teams to discover it.