![\"CoAI](\"assets/pixel-coai-cut.png\"){kind=tracking}
\n\n \n
\n Project cognition layer for AI coding.\n
\n\n\n 中文\n ·\n Quick Start\n ·\n Docs\n ·\n Effectiveness\n
\n\nCoAI is a project cognition layer for AI coding.\n\nIt lets developers describe features in natural language, express key flows with `[[double-link tokens]]`, and let AI agents connect those tokens back to real code locations. The faster a project evolves through AI coding, the more important it becomes to keep a shared, current, and navigable cognition layer for both humans and agents.\n\nCoAI does not replace specs, plans, or code. It preserves the stable understanding that survives the coding loop:\n\n```text\nfeature.md cognition alignment -> mapper skeleton -> code + anchor -> system line sync -> feature.md cognition backflow\n```\n\n## Why CoAI\n\n- AI can generate code quickly, but projects can become black boxes just as quickly. CoAI keeps the current meaning of the project inside the repository.\n- Chat history goes stale. `.coai/` grows with the project state, so humans and agents can resume from the current cognition layer.\n- Feature docs become code entry points. A flow like `[[User Input]] -> [[Frontend Submit]] -> [[Server Validation]]` can jump to real code.\n- Agents do not need to blindly scan the whole repo. `.coai/project`, `.coai/mapper`, `.coai/node`, and `@coai anchor` provide high-signal context.\n- CoAI encourages better feature and source-file boundaries because each capability must belong to a clear scenario event.\n- CoAI helps non-specialist builders describe business workflows first, then let agents turn them into coding-ready feature docs and implementation structure.\n\nIn one sentence:\n\n```text\nCoAI helps humans stay in control of projects written with AI.\n```\n\n## Best Fit\n\nUse CoAI when you:\n\n- build with Codex, Claude Code, Cursor, Trae, Cline, or similar AI agents\n- start a new project from a prompt, workflow, or business process\n- want product meaning, architecture understanding, feature flow, and code locations connected\n- want agents to understand project cognition before editing code\n- want long-running AI coding projects to stay readable, navigable, and maintainable\n\nNot recommended yet:\n\n- one-shot full migration of a large legacy project\n- using CoAI as a full spec / plan / task management system\n- storing every exploration path or chat log in `.coai/`\n\n## Quick Start\n\n### 1. Install\n\nRecommended:\n\n```bash\nnpm install -D @5dc/coai\nnpm exec coai init\n```\n\nFor non-Node host projects:\n\n```bash\nnpm install -D @5dc/coai\nnpm exec coai init --no-package-json\n```\n\nInstall the VS Code extension:\n\n```bash\ncode --install-extension coai-0.0.1.vsix --force\n```\n\nAfter Marketplace release, install it directly from VS Code Marketplace.\n\n### 2. Sync the skill\n\nCoAI is designed for agent-assisted work. Sync the local Codex skill:\n\n```bash\nnpm exec coai skill sync\n```\n\nFor the first CoAI session in a repository, tell the agent:\n\n```text\nUse the coai skill first and understand this repository's .coai structure.\nBefore discussing a feature, before writing code, and after implementation, follow the CoAI loop:\nfeature.md cognition alignment -> mapper skeleton -> code + anchor -> agent writes anchor/file back into mapper -> system updates line -> feature.md cognition backflow.\nEarly node flow is a revisable semantic hypothesis, not a hard implementation constraint.\n```\n\n### 3. Start with an agent\n\nFor a new project, do not manually create every `.coai` file. Describe the goal in chat and let the agent use CoAI:\n\n```text\nI want a simple registration feature:\nUser Input -> Frontend Submit -> Server Validation -> Local JSON Storage -> Success Response.\nUse CoAI to create the feature doc, mapper skeleton, and implementation.\n```\n\nIf you already have a product spec or project brief:\n\n1. initialize CoAI in the repository\n2. place the spec inside the local repo\n3. ask the agent to read the spec and create or update `.coai/project/