[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81433":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":17,"stars30d":17,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":22,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":33,"readmeContent":34,"aiSummary":35,"trendingCount":16,"starSnapshotCount":16,"syncStatus":36,"lastSyncTime":37,"discoverSource":38},81433,"codeSee","Kaka-cheaper\u002FcodeSee","Kaka-cheaper","Visualize your project's feature logic as a semantic flow graph — not call graphs, not import maps. AI writes the data, you see the story.","",null,"TypeScript",36,7,1,6,0,3,2.71,"MIT License",false,"main",true,[24,25,26,27,28,29,30,31,32],"ai-agent","code-review","developer-tools","feature-map","prompt-engineering","react-flow","semantic-graph","vibe-coding","visualization","2026-06-12 02:04:15","\u003Cdiv align=\"center\">\n\n\u003Cimg src=\".\u002Fdocs\u002Fassets\u002Fbanner.png\" alt=\"CodeSee Banner\" width=\"100%\" \u002F>\n\n# CodeSee\n\n**The feature graph your AI auto-maintains.**\n\nStop reading every line of AI-generated code. See a semantic flow graph of your project — auto-updated as AI works, never stale.\n\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](.\u002FLICENSE)\n[![Demo](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLive_Demo-▶-brightgreen.svg)](https:\u002F\u002FKaka-cheaper.github.io\u002FcodeSee\u002F?example=codesee-en)\n[![Version](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fpackage-json\u002Fv\u002FKaka-cheaper\u002FcodeSee?filename=viewer%2Fpackage.json&label=viewer)](.\u002Fviewer\u002Fpackage.json)\n[![Last commit](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flast-commit\u002FKaka-cheaper\u002FcodeSee)](https:\u002F\u002Fgithub.com\u002FKaka-cheaper\u002FcodeSee\u002Fcommits\u002Fmain)\n[![Issues](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fissues\u002FKaka-cheaper\u002FcodeSee)](https:\u002F\u002Fgithub.com\u002FKaka-cheaper\u002FcodeSee\u002Fissues)\n[![中文](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLang-中文-red.svg)](.\u002FREADME.zh-CN.md)\n[![LINUX DO](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLINUX-DO-FFB003.svg?logo=data:image\u002Fsvg%2bxml;base64,DQo8c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgd2lkdGg9IjEwMCIgaGVpZ2h0PSIxMDAiPjxwYXRoIGQ9Ik00Ni44Mi0uMDU1aDYuMjVxMjMuOTY5IDIuMDYyIDM4IDIxLjQyNmM1LjI1OCA3LjY3NiA4LjIxNSAxNi4xNTYgOC44NzUgMjUuNDV2Ni4yNXEtMi4wNjQgMjMuOTY4LTIxLjQzIDM4LTExLjUxMiA3Ljg4NS0yNS40NDUgOC44NzRoLTYuMjVxLTIzLjk3LTIuMDY0LTM4LjAwNC0yMS40M1EuOTcxIDY3LjA1Ni0uMDU0IDUzLjE4di02LjQ3M0MxLjM2MiAzMC43ODEgOC41MDMgMTguMTQ4IDIxLjM3IDguODE3IDI5LjA0NyAzLjU2MiAzNy41MjcuNjA0IDQ2LjgyMS0uMDU2IiBzdHlsZT0ic3Ryb2tlOm5vbmU7ZmlsbC1ydWxlOmV2ZW5vZGQ7ZmlsbDojZWNlY2VjO2ZpbGwtb3BhY2l0eToxIi8+PHBhdGggZD0iTTQ3LjI2NiAyLjk1N3EyMi41My0uNjUgMzcuNzc3IDE1LjczOGE0OS43IDQ5LjcgMCAwIDEgNi44NjcgMTAuMTU3cS00MS45NjQuMjIyLTgzLjkzIDAgOS43NS0xOC42MTYgMzAuMDI0LTI0LjM4N2E2MSA2MSAwIDAgMSA5LjI2Mi0xLjUwOCIgc3R5bGU9InN0cm9rZTpub25lO2ZpbGwtcnVsZTpldmVub2RkO2ZpbGw6IzE5MTkxOTtmaWxsLW9wYWNpdHk6MSIvPjxwYXRoIGQ9Ik03Ljk4IDcwLjkyNmMyNy45NzctLjAzNSA1NS45NTQgMCA4My45My4xMTNRODMuNDI2IDg3LjQ3MyA2Ni4xMyA5NC4wODZxLTE4LjgxIDYuNTQ0LTM2LjgzMi0xLjg5OC0xNC4yMDMtNy4wOS0yMS4zMTctMjEuMjYyIiBzdHlsZT0ic3Ryb2tlOm5vbmU7ZmlsbC1ydWxlOmV2ZW5vZGQ7ZmlsbDojZjlhZjAwO2ZpbGwtb3BhY2l0eToxIi8+PC9zdmc+)](https:\u002F\u002Flinux.do\u002F)\n\n[![Spec Kit](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSpec_Kit-Compatible-blue)](https:\u002F\u002Fgithub.com\u002Fgithub\u002Fspec-kit)\n[![Trellis](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FTrellis-Compatible-orange)](https:\u002F\u002Fgithub.com\u002Fmindfold-ai\u002FTrellis)\n[![BMAD](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FBMAD-Compatible-purple)](https:\u002F\u002Fgithub.com\u002Fbmad-code-org\u002FBMAD-METHOD)\n[![SKILL.md](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSKILL.md-Standard-green)](https:\u002F\u002Fagentskills.io\u002F)\n\n\u003C\u002Fdiv>\n\n> ⚠ **Active development.** Schema may change between minor versions. Track [CHANGELOG](.\u002FCHANGELOG.md) for breaking changes. Currently the most accurate way to follow progress is the [commit history](https:\u002F\u002Fgithub.com\u002FKaka-cheaper\u002FcodeSee\u002Fcommits\u002Fmain).\n\n---\n\n> Think of it like this: if a feature is \"making scrambled eggs with tomatoes\",\n> the graph shows \"prep → crack eggs → heat oil → stir-fry → season → plate\" —\n> not \"`prepare()` calls `slice()` then `whisk()`\".\n\nNot call graphs. Not import maps. A human-readable story of what your project does.\n\n\u003Cdiv align=\"center\">\n\n### ▶ [Try it in 30 seconds — no install](https:\u002F\u002FKaka-cheaper.github.io\u002FcodeSee\u002F?example=codesee-en)\n\n\u003Csub>Open the live demo · explore CodeSee modeling itself · drop your own \u003Ccode>features.json\u003C\u002Fcode>\u003C\u002Fsub>\n\n\u003C\u002Fdiv>\n\n\u003Cdiv align=\"center\">\n\u003Cimg src=\".\u002Fdocs\u002Fassets\u002Foverview_en.png\" alt=\"Overview View\" width=\"80%\" \u002F>\n\u003Cp>\u003Cem>Overview — Epics arranged by user journey order, connected by semantic flow arrows\u003C\u002Fem>\u003C\u002Fp>\n\u003C\u002Fdiv>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>▶ More views (Features \u002F Steps)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cdiv align=\"center\">\n\u003Cimg src=\".\u002Fdocs\u002Fassets\u002Ffeatures_en.png\" alt=\"Features View\" width=\"80%\" \u002F>\n\u003Cp>\u003Cem>Features — grouped in Epic containers, drag to rearrange\u003C\u002Fem>\u003C\u002Fp>\n\u003C\u002Fdiv>\n\n\u003Cdiv align=\"center\">\n\u003Cimg src=\".\u002Fdocs\u002Fassets\u002Fsteps_en.png\" alt=\"Steps View\" width=\"80%\" \u002F>\n\u003Cp>\u003Cem>Steps — directed flow within a single feature (async, conditional, error branches)\u003C\u002Fem>\u003C\u002Fp>\n\u003C\u002Fdiv>\n\n\u003C\u002Fdetails>\n\n---\n\n## Why\n\nWhen collaborating with AI on code:\n\n- 🤯 **AI writes 5000 lines in 5 minutes** — but you need hours to review them all\n- 🔍 **You need to understand logic, not syntax** — \"what does this feature do\" matters more than \"which function calls which\"\n- 🐛 **When something breaks, you trace the full chain** — but the chain might span 20 files you've never read\n- 😤 **You lose the sense of ownership** — the project grows faster than your understanding of it\n\nCodeSee solves this: AI writes the code AND writes the feature map. You see the story, not the syntax.\n\n---\n\n## Why I built this\n\nI'm an independent developer who got tired of AI writing 5000 lines in 5 minutes\nwhile I spent hours figuring out what changed.\n\nI tried call graphs, import maps, AST tools — all wrong layer. They show *how* code\ncalls itself, not *what* the project does for the user.\n\nCodeSee is the tool I wished I had when working with Cursor \u002F Claude Code on real\nprojects. After iterating on **Polisim** (40+ features simulation engine) and a\n**美团 AI Hackathon** project to validate the schema and prompts, I'm sharing it.\n\nThe three rules that emerged from real use:\n\n1. **Semantic control belongs to AI \u002F `features.json`** — naming, ordering, grouping\n2. **Visual & interaction belongs to the frontend** — drag, zoom, theme, layout\n3. **When uncertain, let AI write it down explicitly** — no frontend heuristics\n\n— [@Kaka-cheaper](https:\u002F\u002Fgithub.com\u002FKaka-cheaper) · [LinuxDo](https:\u002F\u002Flinux.do\u002F)\n\n---\n\n## Core Capabilities\n\n| Capability | Description |\n| ---------- | ----------- |\n| **Semantic flow graph** | Three-level drill-down: Epics → Features → Steps. See the \"what\" and \"why\", not the \"how\". |\n| **AI-maintained** | AI writes `features.json` after every code change. No manual diagramming. Works with any AI IDE. |\n| **Interactive canvas** | Drag, zoom, undo\u002Fredo, auto-save layout. Warm-ivory theme designed for long review sessions. |\n| **Multi-project switcher** | Top-bar dropdown to switch between projects (FSA folders \u002F uploaded files \u002F bundled examples) — no re-dragging. Authorized folders auto-restore across refreshes. |\n| **Live reload** | Toggle the Live button — viewer polls `features.json` every 3s and auto-refreshes the canvas with smooth fade-in for new nodes. Watch the graph grow as AI works. |\n| **Zero lock-in** | Plain JSON file. Human-readable, git-diffable, lockable. Switch AI providers anytime. |\n| **Incremental sync** | Each code change updates only affected features. The graph grows with your project. |\n| **Validation** | Built-in validator catches schema violations, hallucinated enums, and structural issues before you see them. |\n| **Multi-language** | UI supports Chinese\u002FEnglish toggle. Semantic text language configurable via `manifest.lang`. |\n| **SDD compatible** | Auto-detects `.specify\u002F`, `.trellis\u002F`, `.bmad-core\u002F`, `.agents\u002Fskills\u002F` and consumes spec\u002FPRD docs directly — no source-code reverse engineering. |\n| **SKILL.md standard** | Cross-platform skill following [agentskills.io](https:\u002F\u002Fagentskills.io\u002F) — works on Claude Code \u002F Cursor \u002F Codex \u002F Gemini CLI \u002F Copilot \u002F 20+ platforms out of the box. |\n| **Auto hook wiring** | One-shot `install --auto-detect` writes a Stop hook into Claude Code \u002F Kiro that reminds AI to sync `features.json` after every agent turn. Existing user hooks untouched, idempotent, `--uninstall-hooks` reverses cleanly. |\n\n---\n\n## When NOT to use\n\n- ❌ **Single-file scripts or tiny prototypes** — overkill, just read the code\n- ❌ **Pure documentation projects with no code** — you can use planning mode, but a wiki\u002FNotion may serve better\n- ❌ **Codebases without AI collaboration** — manual maintenance defeats the point; the value is \"AI writes it for you\"\n- ❌ **Real-time low-latency monitoring** — `features.json` is sync-on-change, not millisecond-live\n- ❌ **Dependency \u002F call graph analysis** — that's the wrong layer; use [Madge](https:\u002F\u002Fgithub.com\u002Fpahen\u002Fmadge), [dependency-cruiser](https:\u002F\u002Fgithub.com\u002Fsverweij\u002Fdependency-cruiser), or your IDE's built-in analyzer\n\nIf you're an independent dev \u002F small team using Cursor \u002F Claude Code \u002F Kiro \u002F Copilot to ship features and you keep losing track of what your codebase actually does — that's the sweet spot.\n\n---\n\n## Quick Start\n\n### 1. Clone this repo\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FKaka-cheaper\u002FcodeSee.git\ncd codeSee\n```\n\nThe install scripts, prompts, validator, and templates live here. The viewer is hosted on GitHub Pages so you don't need to run it locally.\n\n### 2. Install CodeSee into your project\n\n```powershell\n# Windows\n.\\scripts\\install.ps1 D:\\path\\to\\your\\project\n\n# macOS \u002F Linux\n.\u002Fscripts\u002Finstall.sh \u002Fpath\u002Fto\u002Fyour\u002Fproject\n```\n\nDrops `AGENTS.md` (or appends to existing) plus `.codesee\u002F{prompts,scripts,hooks}\u002F` into your project. Zero changes to your code.\n\n**Optional — wire hooks in one shot.** Re-run with `-AutoDetect` (PowerShell) \u002F `--auto-detect` (Bash):\n\n```powershell\n.\\scripts\\install.ps1 D:\\path\\to\\your\\project -AutoDetect\n```\n\nLooks for `.claude\u002F` or `.kiro\u002F` and writes the Stop \u002F agentStop hook so the IDE reminds AI to sync `features.json` after every turn. Existing user entries are untouched, reruns are idempotent, and `-UninstallHooks` cleans up. For manual setup or per-platform docs see [`hooks\u002FREADME.md`](.\u002Fhooks\u002FREADME.md).\n\n### 3. Let AI scan\n\nOpen your project in any AI IDE (Cursor \u002F Claude Code \u002F Kiro \u002F Copilot \u002F Codex \u002F Gemini CLI \u002F ...).\nThe AI reads `AGENTS.md` (or `.agents\u002Fskills\u002Fcodesee\u002FSKILL.md` for SKILL.md-compatible IDEs) and automatically generates `.codesee\u002Ffeatures.json`.\n\nIf your project uses a Spec-Driven Development framework (`.specify\u002F`, `.trellis\u002F`, `.bmad-core\u002F`, ...), CodeSee will detect it and consume the spec\u002FPRD docs directly — no source code scan needed.\n\n### 4. View the graph (in your browser, no install)\n\nOpen **[https:\u002F\u002FKaka-cheaper.github.io\u002FcodeSee\u002F](https:\u002F\u002FKaka-cheaper.github.io\u002FcodeSee\u002F?example=codesee-en)** — the live web viewer.\n\nBy default you'll see CodeSee's own feature graph. To switch to your project:\n\n1. Click **+ Add project** in the top-right dropdown\n2. Pick the folder containing `.codesee\u002Ffeatures.json` — you'll get a one-time browser permission prompt\n3. Done. The browser reads your local files directly via the [File System Access API](https:\u002F\u002Fdeveloper.mozilla.org\u002Fen-US\u002Fdocs\u002FWeb\u002FAPI\u002FFile_System_Access_API) — never uploads anything.\n\nAll your previous projects stay in the dropdown — next time you open the viewer, just click to switch.\n\n> **Browser support**: Chrome \u002F Edge \u002F Arc \u002F Brave (Chromium-based). Firefox\u002FSafari users can drag a `features.json` file in instead — layout still saves to localStorage.\n\n> **Want to run viewer locally?** See [Development setup](.\u002FCONTRIBUTING.md#development-setup) — `cd viewer && npm run dev`.\n\n---\n\n## How It Works\n\n```\nYour Project\u002F                              CodeSee Viewer\u002F\n├── AGENTS.md                  ←────────── templates\u002FAGENTS.md\n├── .agents\u002Fskills\u002Fcodesee\u002F    ←────────── templates\u002FSKILL.md  (cross-platform skill)\n│   └── SKILL.md\n├── .codesee\u002F                              viewer\u002F\n│   ├── prompts\u002F*.md           ←────────── prompts\u002F*.md  (scan \u002F scan-sdd \u002F sync \u002F ...)\n│   ├── scripts\u002F               ←────────── scripts\u002Fvalidate-features.mjs\n│   │                                    + hooks\u002Fscripts\u002Fcheck-staleness.mjs\n│   ├── hooks\u002F                 ←────────── hooks\u002F{claude-code,kiro,README.md}\n│   ├── features.json          ──────────→ Loaded by viewer (add project \u002F drag)\n│   └── layout.json            ←────────── Saved from viewer (FSA, same folder as features.json)\n├── .claude\u002Fsettings.json      ←────────── (optional) merged Stop hook via --auto-detect\n├── .kiro\u002Fhooks\u002Fcodesee-*.json ←────────── (optional) wired via --auto-detect\n└── your code  (or .specify \u002F .trellis \u002F .bmad-core \u002F ... for SDD projects)\n```\n\n| Layer | What | Who maintains |\n| ----- | ---- | ------------- |\n| `features.json` | Semantic flow (epics, features, steps, relations) | AI + human review |\n| `layout.json` | Node positions on canvas | User drag + auto-save |\n| Viewer | Rendering, interaction, layout algorithms | This repo |\n\n---\n\n## Three Views\n\n| View | Shows | Interaction |\n| ---- | ----- | ----------- |\n| **Overview** | Epics as nodes, `epic_flow` as edges | Drag to arrange; double-click → Features |\n| **Features** | Features grouped in Epic containers | Drag nodes\u002Fcontainers; double-click → Steps |\n| **Steps** | Step-by-step flow within one feature | Directed graph with async\u002Fconditional\u002Ferror edges |\n\n---\n\n## Best Practices\n\n### Three usage scenarios\n\n| Scenario | When | How |\n| -------- | ---- | --- |\n| **A. Greenfield (recommended)** | Starting a new project from scratch with AI | Install CodeSee first, then develop. AI updates `features.json` after each feature it writes. |\n| **B. SDD project** | Project already uses spec-kit \u002F Trellis \u002F BMAD \u002F Agent Skills | CodeSee auto-detects and consumes spec\u002FPRD docs directly — most accurate, fewest tokens. |\n| **C. Brownfield** | Adding CodeSee to an existing code-only project | Run a full code scan first, then switch to incremental sync. |\n\n### Why Greenfield is the best practice\n\nWhen you develop from zero with CodeSee integrated from day one:\n\n- **AI never loses context** — it just wrote the code, so it knows exactly what each step does, which lines to reference, and how features connect\n- **Granularity stays fine** — each sync covers one small feature, not 50 features at once\n- **No hallucination risk** — AI doesn't need to guess what existing code does; it wrote it moments ago\n- **The graph grows with your project** — you can review the canvas at any point and catch design issues early\n- **refs are precise** — file paths and line numbers are accurate because the code was just written\n\n### Greenfield workflow\n\n```\n1. Install CodeSee into your empty project\n2. Tell AI: \"Build feature X\"\n3. AI writes code → AI updates features.json (trigger 2 in AGENTS.md)\n4. You review the canvas → spot issues → tell AI to fix\n5. Repeat for next feature\n```\n\nThe canvas becomes your **living architecture diagram** that's always in sync with reality.\n\n### Brownfield workflow\n\n```\n1. Install CodeSee into your existing project\n2. AI runs scan (trigger 1) → generates full features.json\n3. You review on canvas → lock correct features → tell AI to fix wrong ones\n4. From now on, every code change triggers incremental sync\n```\n\n### SDD project workflow\n\n```\n1. Install CodeSee — install script auto-detects your SDD framework\n2. AI reads .codesee\u002Fprompts\u002Fscan-sdd.md → consumes your spec\u002FPRD docs\n3. Each task done in your SDD framework → AI runs sync (no re-scanning code)\n4. The canvas reflects your spec library, not your code structure\n```\n\nThis is the highest-fidelity path: spec → features.json is forward projection (preserves intent), while code → features.json is reverse engineering (loses intent).\n\n---\n\n## Design Principles\n\n1. **Semantic control belongs to AI \u002F features.json** — node order, naming, grouping, relations\n2. **Visual & interaction belongs to the viewer** — drag, zoom, theme, layout algorithms\n3. **When in doubt, let AI write it explicitly** — no heuristic inference in the frontend\n\nFull details: [`docs\u002Fprinciples.md`](.\u002Fdocs\u002Fprinciples.md)\n\n---\n\n## Project Structure\n\n```\ncodeSee\u002F\n├── viewer\u002F                  Canvas frontend (Vite + React + React Flow + Tailwind v4 + ELK)\n│   ├── src\u002F{fcg,graph,app,lib}\n│   └── public\u002F\n│       ├── features.json    Default example: CodeSee modeling itself (live demo)\n│       ├── examples\u002F        Other bundled examples\n│       │   └── blog-system.json\n│       └── layout.json      Default canvas layout\n├── prompts\u002F                 AI prompt templates (copied to target projects)\n│   ├── scan.md              Entry point (auto-routes: sdd \u002F planning \u002F light \u002F heavy)\n│   ├── scan-sdd.md          SDD projects (spec-kit \u002F Trellis \u002F BMAD \u002F Agent Skills)\n│   ├── scan-light.md        Light projects (one-shot)\n│   ├── scan-heavy.md        Heavy projects (phased)\n│   ├── scan-planning.md     Doc-only \u002F planning stage\n│   ├── sync.md              Incremental sync\n│   ├── _schema.md           Schema + enums + example (single source of truth)\n│   └── _rules.md            Constraints (MUST\u002FSHOULD\u002FMAY)\n├── templates\u002F               Entry-rule templates\n│   ├── AGENTS-snippet.md    Single source of truth for the AGENTS.md CodeSee section (BEGIN\u002FEND marked)\n│   └── SKILL.md             Cross-platform skill entry (agentskills.io standard)\n├── hooks\u002F                   Cross-IDE hooks (copied to target as .codesee\u002Fhooks\u002F)\n│   ├── README.md            Enablement guide\n│   ├── scripts\u002F\n│   │   └── check-staleness.mjs   Shared: detects stale features.json after each turn\n│   ├── claude-code\u002F\n│   │   └── settings.json    Stop hook template (merged into .claude\u002Fsettings.json)\n│   └── kiro\u002F\n│       └── sync-on-stop.json  agentStop hook (dropped into .kiro\u002Fhooks\u002F)\n├── scripts\u002F                 Install + tooling\n│   ├── install.ps1\n│   ├── install.sh\n│   ├── validate-features.mjs       Schema + heuristic validator\n│   └── merge-claude-settings.mjs   Phase 2: idempotent JSON merge for .claude\u002Fsettings.json\n├── docs\u002F                    Design docs\n├── LICENSE                  MIT\n└── README.md\n```\n\n---\n\n## FAQ \u002F Troubleshooting\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>How can the browser read files from my disk? Is that safe?\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nCodeSee uses the [File System Access API](https:\u002F\u002Fdeveloper.mozilla.org\u002Fen-US\u002Fdocs\u002FWeb\u002FAPI\u002FFile_System_Access_API), a modern web standard. Three things make it safe:\n\n1. **You explicitly choose the folder.** The browser shows a folder picker — nothing happens unless you click \"Allow\". Same UX as opening a file in any web app.\n2. **The browser sandboxes access.** Only that one folder you picked is readable, and only by `https:\u002F\u002FKaka-cheaper.github.io\u002F`. Refresh the page → permission resets to `prompt` until you re-grant.\n3. **Nothing leaves your machine.** The viewer is a static site (HTML\u002FJS\u002FCSS only) — there's no backend, no upload, no analytics. All file reads happen in your browser. You can verify by checking the Network tab — only the viewer assets load, nothing else.\n\nEven if you don't trust me: clone the repo, read [`viewer\u002Fsrc\u002Ffcg\u002FfileSystem.ts`](.\u002Fviewer\u002Fsrc\u002Ffcg\u002FfileSystem.ts) (the only file that touches FSA), and see for yourself. Or just run viewer locally — see [Development setup](.\u002FCONTRIBUTING.md#development-setup).\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Viewer shows a blank white screen after loading features.json\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nThe AI likely used enum values outside the schema (e.g. `role: \"logic\"` instead of `role: \"compute\"`).\n\n1. Run the validator: `node .codesee\u002Fscripts\u002Fvalidate-features.mjs`\n2. Fix the reported errors (usually invalid `step.role`, `flow.kind`, or `trigger.kind`)\n3. Reload the viewer\n\nThe viewer has fallback handling for unknown enums, but severely malformed JSON can still cause issues.\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Save button doesn't work \u002F no directory picker shows up\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nCodeSee uses the File System Access API for local read\u002Fwrite. Only available in Chromium browsers (Chrome, Edge, Arc).\n\n- Use Chrome or Edge to open the viewer\n- Must access via `localhost` or HTTPS (FSA is blocked on `file:\u002F\u002F`)\n- **Before your first save, click \"+ Add project\" in the top-bar dropdown and pick a folder containing `features.json`** — that's the unified auth entry. After authorization, the save button, autosave, and live reload all work directly without re-prompting for the folder\n- Without authorization, save only writes localStorage drafts (still survives refresh, but not to disk)\n- Browser restart may reset FSA permission to `prompt` — the canvas will show a re-authorization banner; one click on **Reauthorize** is enough\n- Firefox\u002FSafari users: the viewer falls back to localStorage and your layout is still saved\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>How do I switch between multiple projects?\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nThe **Open ▼** dropdown in the top-bar has two sections:\n\n- **Your projects** — folders or uploaded files you've added before, sorted by last opened, hover to remove\n- **Examples** — CodeSee itself, blog-system example\n\nClick any row to switch instantly. FSA projects auto-restore across page refreshes and browser restarts — once authorized, you never need to re-pick the folder.\n\nThe active project is remembered in localStorage; next time you open the viewer it loads where you left off.\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Overview is just a horizontal line\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nThe AI assigned sequential `order` values (0, 1, 2, ..., N) to every Epic instead of grouping parallel modules under the same order.\n\nFix in `features.json`: Epics that represent parallel capabilities should share the same `order` value. Only use different orders for sequential stages in the user journey.\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>AI keeps inventing enum values not in the schema\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nThis is the most common issue. The prompts include strict enum tables, but some models still hallucinate.\n\n- Always run the validator after AI writes\u002Fupdates `features.json`\n- The validator reports exact JSONPath locations of invalid values\n- Common mappings: `logic` → `compute`, `init`\u002F`cleanup` → `other`, `websocket` → `http`, `internal` → `event`\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>How do I enable \u002F disable hooks?\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nEasiest way to enable: rerun install with `--auto-detect`.\n\n```powershell\n.\\scripts\\install.ps1 D:\\my-project -AutoDetect\n```\n\nThat does two things:\n\n1. Merges the Stop hook into `.claude\u002Fsettings.json` (only if `.claude\u002F` exists)\n2. Writes `.kiro\u002Fhooks\u002Fcodesee-sync-on-stop.json` (only if `.kiro\u002F` exists)\n\nEvery entry we write carries a `_codesee` marker field. Claude Code ignores unknown fields, but we use it to identify our entries on subsequent runs — reruns are idempotent, your other hooks stay untouched.\n\nOnce enabled, after every agent turn the IDE runs `node .codesee\u002Fscripts\u002Fcheck-staleness.mjs`. The script compares `manifest.updated_at` against `git log` and prints a reminder if code changed but `features.json` did not. Always exits 0 — never blocks the agent.\n\nDisable:\n\n```powershell\n.\\scripts\\install.ps1 D:\\my-project -UninstallHooks\n```\n\nRemoves only the marker-tagged entry plus `.kiro\u002Fhooks\u002Fcodesee-*.json`. The `.codesee\u002Fhooks\u002F` templates stay so you can re-enable any time.\n\nFor per-platform manual setup or Git hook fallback see [`hooks\u002FREADME.md`](https:\u002F\u002Fgithub.com\u002FKaka-cheaper\u002FcodeSee\u002Fblob\u002Fmain\u002Fhooks\u002FREADME.md).\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>How do I update CodeSee in my project after pulling new changes?\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nRe-run the install script with `-Force` (PowerShell) or `--force` (Bash):\n\n```powershell\n.\\scripts\\install.ps1 D:\\path\\to\\your\\project -Force\n```\n\nThis refreshes prompts, validator, and the AGENTS.md CodeSee section without touching your `features.json` or `layout.json`.\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>My project uses spec-kit \u002F Trellis \u002F BMAD — does it just work?\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nYes. The install script auto-detects these directories:\n\n- `.specify\u002F` — GitHub Spec Kit\n- `.trellis\u002F` — Mindfold Trellis\n- `.bmad-core\u002F` or `bmad\u002F` — BMAD-METHOD\n- `.agents\u002Fskills\u002F` — Agent Skills standard\n- `.agent-os\u002F` — Builder Methods Agent OS\n\nWhen detected, the install script reports which framework it found, and `scan.md` routes to `scan-sdd.md` which consumes spec\u002FPRD docs directly. No source code scan needed — far more accurate than reverse engineering.\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>What's the difference between AGENTS.md and SKILL.md?\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n`AGENTS.md` is the original entry-rule format used by Cursor, Claude Code, Kiro, etc. — placed at project root.\n\n`SKILL.md` is the [agentskills.io](https:\u002F\u002Fagentskills.io\u002F) cross-platform standard (Anthropic, December 2025) used by 20+ AI tools. Placed at `.agents\u002Fskills\u002Fcodesee\u002FSKILL.md`. It uses progressive disclosure (only ~30-50 tokens load at startup, full instructions load on demand).\n\nThe install script writes both — your AI IDE will pick whichever it understands.\n\u003C\u002Fdetails>\n\n---\n\n## Roadmap\n\n> **Want to contribute?** Many of the open items below have matching issues with concrete scope and acceptance criteria. Check the **[`good first issue`](https:\u002F\u002Fgithub.com\u002FKaka-cheaper\u002FcodeSee\u002Fissues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)** and **[`help wanted`](https:\u002F\u002Fgithub.com\u002FKaka-cheaper\u002FcodeSee\u002Fissues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)** labels.\n\n### Top priority\n\n- [ ] **Prompt refinement (community-driven)** — real-world usage produces the best constraints; contributions welcome for edge cases, anti-patterns, and domain-specific rules\n- [ ] **Incremental scan + self-correction** — replace one-shot 15K-token output with per-epic \u002F per-feature streaming + self-review loops to fix long-output quality decay. Research design (Self-Refine \u002F Reflexion lineage) and three implementation tiers documented in [`docs\u002Fimproving-scan-quality.md`](docs\u002Fimproving-scan-quality.md). Not started; tier 1 (per-epic) is the recommended entry point (~6h).\n- [ ] **Semantic-aware layout** — layout should respect feature logic, not just node positions. Phase 1 done: ELK Sugiyama tuning (`considerModelOrder` makes the array order in features.json influence layout, `BRANDES_KOEPF` node placement aligns upstream\u002Fdownstream, larger edge-node spacing prevents label collisions); next: Feature.order field, swimlane view, AI-driven semantic layout intent.\n- [ ] **Plan-as-Graph** — AI outputs its plan\u002Fdesign directly as `features.json` so you review it on the canvas instead of reading walls of text. Approve, edit, or discard before any code is written. Extends CodeSee from \"post-hoc documentation\" to \"pre-implementation design review\".\n- [ ] **Feature Summary (AI memory layer)** — a deterministic script auto-generates a compact markdown summary from `features.json` (~2000 tokens vs 15000+ for raw JSON). AI reads the summary at session start to restore project context instantly. Solves long-task forgetting and cross-session inconsistency.\n- [ ] **Incremental patch output protocol** — `sync` prefers RFC 6902 JSON Patch over full file rewrite. Phase 1 done: `scripts\u002Fapply-patch.mjs` implements the patch applier (zero-deps, supports add\u002Fremove\u002Freplace\u002Fmove\u002Fcopy\u002Ftest ops + atomic write + automatic rolling backup); `sync.md` gained an output-protocol section with mode A (patch first) and mode B (full rewrite fallback). Next: validate token savings on a real heavy project (Polisim, 40+ features), iterate on prompt examples and recovery strategy from real failures.\n- [x] **Platform hooks** — auto-trigger sync via Claude Code hooks \u002F Kiro hooks. Phase 1 done: hook templates + shared `check-staleness.mjs` shipped to `.codesee\u002Fhooks\u002F`. Phase 2 done: install gains `--auto-detect` \u002F `--enable-claude-code` \u002F `--enable-kiro` to wire the IDE config in one shot; existing user entries are untouched, reruns are idempotent, `--uninstall-hooks` cleans up.\n\n### Ecosystem & integrations\n\n- [x] **SDD framework integration** — auto-detect `.specify\u002F` (Spec Kit), `.trellis\u002F` (Trellis), `.bmad-core\u002F` (BMAD), `.agents\u002Fskills\u002F` and consume spec\u002FPRD docs as the source for `features.json` (forward projection from spec instead of reverse engineering from code)\n- [x] **SKILL.md standard entry** — cross-platform skill following [agentskills.io](https:\u002F\u002Fagentskills.io\u002F), works on Claude Code \u002F Cursor \u002F Codex \u002F Gemini CLI \u002F Copilot \u002F 20+ platforms\n- [x] **Real-time canvas refresh** — local watcher detects `features.json` changes and auto-refreshes the web canvas (no manual reload), so users see the graph update live as the AI works\n\n### Canvas & UX\n\n- [ ] **Share via URL (remote `features.json`)** — load any URL-accessible `features.json` via `?features=\u003Curl>` (or `?repo=\u003Cowner>\u002F\u003Crepo>` GitHub shorthand). Drop a link in a README \u002F doc \u002F chat and recipients see the live graph instantly — no clone, no install. Read-only mode (layout drafts go to localStorage). Strong fit for OSS project showcasing and code-review sharing.\n- [ ] **Canvas editing** — edit feature names, add notes, lock nodes directly on the canvas\n- [ ] **Search & filter** — find features by name, filter by epic\u002Ftag\u002Frole\n- [ ] **Diff view** — highlight what changed between two versions of `features.json`\n- [x] **Multi-project dashboard** — top-bar dropdown to switch between projects (FSA folders \u002F uploaded files \u002F bundled examples), no re-dragging\n- [ ] **Export** — PNG \u002F SVG \u002F PDF export of the current view\n- [ ] **Dark theme** — toggle between warm-ivory and dark mode\n\n### Tooling\n\n- [ ] **CI integration** — validate `features.json` in GitHub Actions \u002F GitLab CI\n- [ ] **Plugin system** — custom node renderers, custom layout algorithms\n- [ ] **Zero-clone install** — `curl ... | bash` one-liner that fetches scripts\u002Fprompts\u002Ftemplates from GitHub raw, no `git clone` needed\n\n### Long-term (optional)\n\n- [ ] **HTML artifact complement** — keep features.json as the project-level contract (unchanged), and give AI a prompt path to render \"one-shot task outputs\" (design alternatives \u002F PR walkthroughs \u002F learning reports \u002F disposable custom editors) as standalone HTML files. Background: [Thariq Shihipar's post](https:\u002F\u002Fthariqs.github.io\u002Fhtml-effectiveness\u002F). Viewer could also gain \"export current canvas as shareable HTML\". Two layers complement each other: long-term evolution lives in codesee, single-shot artifacts live in HTML.\n- [ ] **Vector index** — semantic embedding for \"find similar features\" \u002F cross-project reuse; must remain optional and never replace the JSON-as-source-of-truth principle\n\n---\n\n## Community\n\n- 💬 [LinuxDo](https:\u002F\u002Flinux.do\u002F) — Discussion & feedback\n- 🐛 [GitHub Issues](https:\u002F\u002Fgithub.com\u002FKaka-cheaper\u002FcodeSee\u002Fissues) — Bug reports & feature requests\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](.\u002FCONTRIBUTING.md) for development setup, code style, and PR process.\n\nQuick start:\n\n1. Fork & clone\n2. `cd viewer && npm install && npm run dev`\n3. Make changes, ensure `npm run build` passes\n4. Open a PR\n\n---\n\n## License\n\n[MIT](.\u002FLICENSE)\n\n---\n\n\u003Cdiv align=\"center\">\n\nBuilt with ❤️ by **[@Kaka-cheaper](https:\u002F\u002Fgithub.com\u002FKaka-cheaper)** — independent dev exploring AI-collaborative workflows.\n\nFound this useful? **[Star ⭐ on GitHub](https:\u002F\u002Fgithub.com\u002FKaka-cheaper\u002FcodeSee)** · **[Say hi on LinuxDo](https:\u002F\u002Flinux.do\u002F)**\n\nIf you ship something with CodeSee, [open an issue](https:\u002F\u002Fgithub.com\u002FKaka-cheaper\u002FcodeSee\u002Fissues\u002Fnew) — I'd love to feature it.\n\n\u003C\u002Fdiv>\n","CodeSee 是一个用于将项目功能逻辑可视化为语义流图的工具，而非传统的调用图或导入图。其核心功能是利用AI自动生成并维护数据，用户可以直观地看到项目的语义流程图，并且该图会随着AI的工作自动更新，保持最新状态。技术上基于TypeScript开发，支持React Flow等现代前端技术栈。适用于需要对复杂代码库进行快速理解和审查的场景，特别是当团队希望减少阅读每一行AI生成代码的时间时，通过可视化的方式更高效地掌握项目结构和逻辑流程。",2,"2026-06-11 04:05:01","CREATED_QUERY"]