[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-93269":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":14,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":15,"rankGlobal":9,"rankLanguage":9,"license":16,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":9,"pushedAt":9,"updatedAt":39,"readmeContent":40,"aiSummary":41,"trendingCount":14,"starSnapshotCount":14,"syncStatus":42,"lastSyncTime":43,"discoverSource":44},93269,"project-os-for-codex","herry2059\u002Fproject-os-for-codex","herry2059","Open-source control plane for Codex projects: Git-backed context, visible agent progress, scoped MCP access, resumable work, and safe handoffs.",null,"TypeScript",104,4,1,0,42.1,"Apache License 2.0",false,"main",true,[21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38],"agent-handoff","ai-agents","ai-coding","ai-project-management","codex","context-engineering","developer-tools","git","knowledge-base","mcp","model-context-protocol","open-source","project-management","project-tracker","react","self-hosted","typescript","workflow-automation","2026-07-22 04:02:08","\u003Ch1 align=\"center\">🚦 Project OS for Codex\u003C\u002Fh1>\n\n\u003Cp align=\"center\">\u003Cstrong>The open-source control plane for Codex projects: visible progress, resumable context, safe handoffs, and reusable knowledge.\u003C\u002Fstrong>\u003C\u002Fp>\n\n\u003Cp align=\"center\">\u003Cstrong>Independent open-source project. Not affiliated with or endorsed by OpenAI.\u003C\u002Fstrong>\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  Built for Codex. Connect through MCP, keep project truth in Git, and make every handoff resumable.\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fherry2059\u002Fproject-os-for-codex\u002Factions\u002Fworkflows\u002Fci.yml\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Fherry2059\u002Fproject-os-for-codex\u002Fci.yml?branch=main&style=for-the-badge&label=CI\" alt=\"CI Status\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fherry2059\u002Fproject-os-for-codex\u002Freleases\u002Flatest\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fherry2059\u002Fproject-os-for-codex?style=for-the-badge\" alt=\"Latest Release\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fherry2059\u002Fproject-os-for-codex\u002Fstargazers\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fherry2059\u002Fproject-os-for-codex?style=for-the-badge\" alt=\"GitHub Stars\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fherry2059\u002Fproject-os-for-codex\u002Fforks\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fforks\u002Fherry2059\u002Fproject-os-for-codex?style=for-the-badge\" alt=\"GitHub Forks\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fherry2059\u002Fproject-os-for-codex\u002Fgraphs\u002Fcontributors\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fcontributors\u002Fherry2059\u002Fproject-os-for-codex?style=for-the-badge\" alt=\"Contributors\">\u003C\u002Fa>\n  \u003Ca href=\"LICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fherry2059\u002Fproject-os-for-codex?style=for-the-badge\" alt=\"Apache-2.0 License\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fherry2059\u002Fproject-os-for-codex\u002Fcommits\u002Fmain\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flast-commit\u002Fherry2059\u002Fproject-os-for-codex?style=for-the-badge\" alt=\"Last Commit\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#quick-start\">🚀 Quick Start\u003C\u002Fa> ·\n  \u003Ca href=\"docs\u002FCODEX_SETUP.md\">🤖 Connect Codex\u003C\u002Fa> ·\n  \u003Ca href=\"#key-features\">🧭 Features\u003C\u002Fa> ·\n  \u003Ca href=\"docs\u002FDEPLOYMENT.md\">📦 Deployment\u003C\u002Fa> ·\n  \u003Ca href=\"docs\u002FINTERFACES.md\">🔌 Interfaces\u003C\u002Fa>\n\u003C\u002Fp>\n\nProject 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?**\n\nIt 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.\n\n![Project OS for Codex working project cockpit in an isolated local workspace](docs\u002Fassets\u002Fproduct-dashboard-dark.png)\n\n## 💡 Why Does This Exist?\n\nAI can generate code quickly, but real projects still fail in very ordinary ways:\n\n- The project progress is hidden inside chat history.\n- The next AI session does not know where to start.\n- Humans cannot tell which tasks are done, blocked, risky, or waiting for review.\n- Handoffs become painful because context is scattered across prompts, screenshots, commits, and private notes.\n- Teams lose trust because there is no visible project trail.\n\nProject 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.\n\n### Built from repeated real delivery work\n\nThis 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.\n\nThe 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.\n\n![Anonymized maintainer Codex activity: 14,570 tasks and 8.8B lifetime tokens](docs\u002Fassets\u002Fanonymized-codex-usage.svg)\n\n## Explain It Like I Am New\n\nThink of this system as a project cockpit for AI-assisted development.\n\nWhen an AI helps you build a project, it should not only write code. It should also leave behind:\n\n- what it changed;\n- why it changed it;\n- what still needs to be done;\n- what risks remain;\n- what the next human or AI should read first.\n\nThis 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.\n\n## Connect Codex\n\nDo **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.\n\nThe first production-oriented slice exposes two real MCP tools:\n\n- `project_os_get_context` — reads the kickoff card, acceptance criteria, AGENTS rules, handoff package, progress, Git trail, and next step;\n- `project_os_append_progress` — appends one validated, audited, idempotent progress event, an agent-reported verification note, and one matching project-record Git commit.\n\nCredentials 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.\n\nVersion 0.3.0 adds a fail-closed first-run contract:\n\n- the MCP process verifies the credential, project binding, scopes, and exact two-tool surface before Codex starts using it;\n- the project-level configuration requires the server and allowlists only the released tools;\n- 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;\n- root and generated `AGENTS.md` files tell Codex to read context first, verify one vertical slice, and only then write progress back.\n\n[Follow the Codex setup guide →](docs\u002FCODEX_SETUP.md)\n\n### Designed around Codex's real extension points\n\n- Codex reads the repository's root [`AGENTS.md`](AGENTS.md) before work starts.\n- The stdio MCP server returns concise workflow instructions during initialization.\n- Tool annotations distinguish the project-state read context tool from the scoped progress-write tool; successful reads still update credential-use and audit metadata.\n- [`.codex\u002Fconfig.toml.example`](.codex\u002Fconfig.toml.example) shows a project-scoped configuration that forwards local environment variables without committing secret values.\n- The same MCP configuration can be used by Codex CLI, the Codex IDE extension, and the ChatGPT desktop app on the same Codex host.\n- High-risk actions stay outside the MCP surface and require a human.\n\nSee OpenAI's official [MCP](https:\u002F\u002Fdevelopers.openai.com\u002Fcodex\u002Fmcp\u002F) and [`AGENTS.md`](https:\u002F\u002Fdevelopers.openai.com\u002Fcodex\u002Fguides\u002Fagents-md\u002F) documentation. This repository extends Codex with project context and progress records; it is not a fork or replacement for Codex.\n\n## Core Loop\n\n![Git-backed project loop](docs\u002Fassets\u002Fgit-loop.svg)\n\n1. Create a project with a kickoff card.\n2. Define the goal, acceptance criteria, non-goals, owner, and next step.\n3. The server creates a local Git-backed project record for the kickoff, progress, issues, and handoff files.\n4. Humans or AI agents post progress events.\n5. Important progress becomes a project record and can be linked to Git commits.\n6. The dashboard shows status, health, progress, and the recorded next action.\n7. A handoff package lets the next AI or human resume without rereading the whole history.\n8. Retrospectives and project notes become reusable knowledge for the next project.\n\n## Key Features\n\n### Project kickoff cards\n\nStart every project with a clear brief:\n\n- project goal;\n- expected result;\n- acceptance criteria;\n- non-goals;\n- current owner;\n- next step.\n\n### Visible AI progress\n\nTrack project state with progress events instead of guessing from chat logs:\n\n- active \u002F paused \u002F done project states;\n- progress percentage;\n- owner;\n- next action;\n- green \u002F yellow \u002F red project health.\n\n### Git-backed evidence\n\nThe system is designed around Git as the durable project record:\n\n- project workspace records;\n- Git file tracking;\n- commit-friendly progress notes;\n- audit trail for what changed and why.\n\n### Handoff packages\n\nGenerate context that another AI or human can use immediately:\n\n- project summary;\n- current state;\n- important files;\n- recent decisions;\n- blocked items;\n- next step;\n- acceptance checklist.\n\n### Knowledge base and retrospectives\n\nTurn finished project experience into reusable knowledge:\n\n- project lessons;\n- delivery patterns;\n- reusable prompts and checklists;\n- project review notes;\n- future improvement ideas.\n\n### Adapter-friendly open-source design\n\nThe open-source version keeps private infrastructure behind replaceable boundaries:\n\n- Git database \u002F Git service adapter;\n- AI provider adapter;\n- knowledge-base adapter;\n- deployment and reverse-proxy boundary;\n- local JSON persistence for simple evaluation.\n\nNo private API keys, production provider addresses, customer data, or internal deployment secrets are included.\n\n### AI-native access instead of password sharing\n\n- one short-lived credential per AI and project;\n- workspace and project isolation enforced on the server;\n- explicit read\u002Fappend scopes;\n- idempotent writes and Git request IDs;\n- revocation and audit history;\n- one focused MCP integration for Codex.\n\n### Current scope and honest limits\n\nThe current release is a focused project-record layer around Codex, not a replacement agent runtime.\n\n- It does not run Codex, monitor Codex sessions automatically, or control a Codex account.\n- It does not connect to or modify an existing source repository. Its Git commits belong to the local Project OS record repository.\n- 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.\n- The released MCP surface contains exactly two tools: scoped context read and scoped progress append.\n- Existing source-repository integration, richer evidence, handoff drafts, knowledge drafts, remote MCP, and OAuth remain roadmap work.\n\n## Open-Source Surface\n\nThis 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.\n\nCommercial 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.\n\nThis repository does not include a hosted commercial service, private provider credentials, production customer data, payment infrastructure, or internal deployment secrets.\n\n## Who Is This For?\n\nThis project is useful if you are:\n\n- building projects with AI coding agents;\n- managing multiple AI-assisted software projects;\n- using Codex for real, multi-session software delivery;\n- trying to make AI work visible to teammates, stakeholders, or future maintainers;\n- tired of losing project context between chat sessions;\n- building an internal AI project management platform;\n- exploring context engineering, agent handoff, and Git-based AI workflows.\n\n## Common Use Cases\n\n- AI project management dashboard\n- AI coding agent progress tracker\n- Agent handoff and context package generator\n- Git-backed project execution system\n- Internal project operating system for AI teams\n- Knowledge base for repeated AI delivery work\n- Customer-facing project progress visibility\n- Multi-project AI workflow control center\n\n## Screenshots and Diagrams\n\n### Working project cockpit\n\n![Project OS for Codex local acceptance workspace in dark mode](docs\u002Fassets\u002Fproduct-dashboard-dark.png)\n\n### Connect Codex\n\n![Create a short-lived project credential for Codex](docs\u002Fassets\u002Fproduct-connect-ai-dark.png)\n\n\u003Cdetails>\n\u003Csummary>Light mode\u003C\u002Fsummary>\n\n![Codex project connection in light mode](docs\u002Fassets\u002Fproduct-connect-ai-light.png)\n\n\u003C\u002Fdetails>\n\n> Screenshots use an isolated local workspace with non-sensitive sample content. No customer account, production endpoint, or private credential is shown.\n\n### Workflow diagram\n\n![Workflow](docs\u002Fassets\u002Fworkflow.svg)\n\n### Git loop diagram\n\n![Git-backed project loop](docs\u002Fassets\u002Fgit-loop.svg)\n\n### Architecture diagram\n\n![Architecture](docs\u002Fassets\u002Farchitecture.svg)\n\n## Tech Stack\n\n- Frontend: React, Vite, TypeScript, Tailwind CSS\n- Backend: Node.js, Express\n- Persistence: local JSON files by default\n- Project record model: Git-oriented project workspace\n- License: Apache-2.0\n\n## Quick Start\n\nRequirements:\n\n- Node.js 22+ (a currently supported LTS line)\n- pnpm 9+\n- Git\n\nThe fastest local-only start is Docker Compose:\n\n```bash\ndocker compose up --build\n```\n\nOpen \u003Chttp:\u002F\u002Flocalhost:8790>. The included Compose file binds to `127.0.0.1` and enables password-free access only for local evaluation.\n\nFor a manual development start, install frontend dependencies:\n\n```bash\npnpm install\n```\n\nStart the backend:\n\n```bash\npnpm --dir server run seed\nPROJECT_OS_DEV_NO_AUTH=true pnpm --dir server start\n```\n\nStart the frontend in another terminal:\n\n```bash\npnpm dev\n```\n\nOpen the Vite URL shown in your terminal. The API listens on:\n\n```text\nhttp:\u002F\u002Flocalhost:8790\n```\n\nProduction refuses to start without `PROJECT_OS_AUTH_USER` and `PROJECT_OS_AUTH_PASSWORD`.\n\nFor local, server, reverse-proxy, storage, backup, Git, AI provider, and knowledge-base setup, see:\n\n- [Deployment Guide](docs\u002FDEPLOYMENT.md)\n- [Interface and Adapter Contracts](docs\u002FINTERFACES.md)\n- [Codex MCP Setup](docs\u002FCODEX_SETUP.md)\n- [Publication Security Checklist](docs\u002FSECURITY_PUBLICATION_CHECKLIST.md)\n\n## Agent Event Example\n\nProject secrets must be sent in the `X-Project-Key` header. Do not put secrets in URLs.\n\n```bash\ncurl -X POST http:\u002F\u002Flocalhost:8790\u002Fapi\u002Fprojects\u002F\u003Cproject-id>\u002Fevents \\\n  -H 'Content-Type: application\u002Fjson' \\\n  -H 'X-Project-Key: \u003Cproject-secret>' \\\n  -H 'Idempotency-Key: progress-step-001' \\\n  -d '{\"message\":\"Add handoff checklist\",\"verification\":\"The checklist page loaded and each acceptance item was reviewed.\",\"progressTo\":55,\"nextStep\":\"Run acceptance smoke test\"}'\n```\n\n## Repository Keywords\n\nPeople may find this project while searching for:\n\n- AI project management\n- Codex project management\n- Codex delivery workflow\n- MCP server\n- Model Context Protocol\n- AI coding agent dashboard\n- agent handoff\n- context engineering\n- Git-based project management\n- AI workflow automation\n- project progress tracker\n- knowledge base for AI teams\n- developer tools for AI-assisted software delivery\n\n## Current Status\n\nThis repository is an early public open-source release.\n\nVersion 0.3.0 closes the audited global-role\u002Fworkspace-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\u002Fbackend connection doctor. The MCP surface remains exactly two scoped tools.\n\nBefore production use, review the release gate:\n\n- multi-tenant permission audit;\n- no production tokens, private domains, private docs, or customer data;\n- `pnpm run check` passes;\n- Agent API + MCP acceptance tests pass;\n- light and dark UI screenshots reviewed;\n- clear deployment, backup, and rollback plan.\n\n## Roadmap\n\n- Stronger project role model\n- Remote OAuth-protected MCP transport\n- More scoped tools for handoff drafts and knowledge drafts\n- Better visual progress timeline\n- Provider adapter examples without shipping private keys\n- Playwright smoke tests\n- A short end-to-end workflow GIF and more guided examples\n- More beginner-friendly setup recipes\n\n## Independent Project\n\nCodex is a trademark of OpenAI. This independent open-source project is not affiliated with or endorsed by OpenAI.\n\n## Long-term Maintenance\n\nThis 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](CHANGELOG.md) and [ROADMAP.md](ROADMAP.md).\n\nThe 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.\n\nThe 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.\n\n## Contributing\n\nIssues, ideas, and pull requests are welcome. Good contributions include:\n\n- clearer documentation;\n- adapter examples;\n- deployment recipes;\n- UI improvements;\n- security hardening;\n- real-world AI project workflow cases.\n\nIf this project helps you, starring the repository makes it easier for more AI builders and project teams to discover it.\n","Project OS for Codex 是一个开源的 AI 项目控制平面，专为基于 Codex 的 AI 编程协作设计。它通过 Git 管理项目上下文与状态，提供可视化的任务进度追踪、可恢复的工作会话、基于 MCP（Model Context Protocol）的受限能力调用，以及支持人类与 AI 无缝交接的结构化手交包。技术上采用 TypeScript 实现，强调上下文工程、知识复用与自托管部署。适用于 AI 辅助开发团队、需要长期维护多轮 AI 协作项目的工程组织，以及对可审计性、可追溯性和跨角色协同有明确要求的软件研发场景。",2,"2026-07-15 02:30:03","CREATED_QUERY"]