CodeSee

The feature graph your AI auto-maintains.

Stop reading every line of AI-generated code. See a semantic flow graph of your project — auto-updated as AI works, never stale.

⚠ Active development. Schema may change between minor versions. Track CHANGELOG for breaking changes. Currently the most accurate way to follow progress is the commit history.

---

Think of it like this: if a feature is "making scrambled eggs with tomatoes", the graph shows "prep → crack eggs → heat oil → stir-fry → season → plate" — not "prepare() calls slice() then whisk()".

Not call graphs. Not import maps. A human-readable story of what your project does.

▶ Try it in 30 seconds — no install

_{Open the live demo · explore CodeSee modeling itself · drop your own features.json}

Overview — Epics arranged by user journey order, connected by semantic flow arrows

▶ More views (Features / Steps)

Features — grouped in Epic containers, drag to rearrange

Steps — directed flow within a single feature (async, conditional, error branches)

---

Why

When collaborating with AI on code:

• 🤯 AI writes 5000 lines in 5 minutes — but you need hours to review them all
• 🔍 You need to understand logic, not syntax — "what does this feature do" matters more than "which function calls which"
• 🐛 When something breaks, you trace the full chain — but the chain might span 20 files you've never read
• 😤 You lose the sense of ownership — the project grows faster than your understanding of it

CodeSee solves this: AI writes the code AND writes the feature map. You see the story, not the syntax.

---

Why I built this

I'm an independent developer who got tired of AI writing 5000 lines in 5 minutes while I spent hours figuring out what changed.

I tried call graphs, import maps, AST tools — all wrong layer. They show how code calls itself, not what the project does for the user.

CodeSee is the tool I wished I had when working with Cursor / Claude Code on real projects. After iterating on Polisim (40+ features simulation engine) and a 美团 AI Hackathon project to validate the schema and prompts, I'm sharing it.

The three rules that emerged from real use:

1. Semantic control belongs to AI / features.json — naming, ordering, grouping
2. Visual & interaction belongs to the frontend — drag, zoom, theme, layout
3. When uncertain, let AI write it down explicitly — no frontend heuristics

— @Kaka-cheaper · LinuxDo

---

Core Capabilities

Capability	Description
Semantic flow graph	Three-level drill-down: Epics → Features → Steps. See the "what" and "why", not the "how".
AI-maintained	AI writes features.json after every code change. No manual diagramming. Works with any AI IDE.
Interactive canvas	Drag, zoom, undo/redo, auto-save layout. Warm-ivory theme designed for long review sessions.
Multi-project switcher	Top-bar dropdown to switch between projects (FSA folders / uploaded files / bundled examples) — no re-dragging. Authorized folders auto-restore across refreshes.
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.
Zero lock-in	Plain JSON file. Human-readable, git-diffable, lockable. Switch AI providers anytime.
Incremental sync	Each code change updates only affected features. The graph grows with your project.
Validation	Built-in validator catches schema violations, hallucinated enums, and structural issues before you see them.
Multi-language	UI supports Chinese/English toggle. Semantic text language configurable via manifest.lang.
SDD compatible	Auto-detects .specify/, .trellis/, .bmad-core/, .agents/skills/ and consumes spec/PRD docs directly — no source-code reverse engineering.
SKILL.md standard	Cross-platform skill following agentskills.io — works on Claude Code / Cursor / Codex / Gemini CLI / Copilot / 20+ platforms out of the box.
Auto hook wiring	One-shot install --auto-detect writes a Stop hook into Claude Code / Kiro that reminds AI to sync features.json after every agent turn. Existing user hooks untouched, idempotent, --uninstall-hooks reverses cleanly.

---

When NOT to use

• ❌ Single-file scripts or tiny prototypes — overkill, just read the code
• ❌ Pure documentation projects with no code — you can use planning mode, but a wiki/Notion may serve better
• ❌ Codebases without AI collaboration — manual maintenance defeats the point; the value is "AI writes it for you"
• ❌ Real-time low-latency monitoring — features.json is sync-on-change, not millisecond-live
• ❌ Dependency / call graph analysis — that's the wrong layer; use Madge, dependency-cruiser, or your IDE's built-in analyzer

If you're an independent dev / small team using Cursor / Claude Code / Kiro / Copilot to ship features and you keep losing track of what your codebase actually does — that's the sweet spot.

---

Quick Start

1. Clone this repo

git clone https://github.com/Kaka-cheaper/codeSee.git
cd codeSee

The install scripts, prompts, validator, and templates live here. The viewer is hosted on GitHub Pages so you don't need to run it locally.

2. Install CodeSee into your project

# Windows
.\scripts\install.ps1 D:\path\to\your\project

# macOS / Linux
./scripts/install.sh /path/to/your/project

Drops AGENTS.md (or appends to existing) plus .codesee/{prompts,scripts,hooks}/ into your project. Zero changes to your code.

Optional — wire hooks in one shot. Re-run with -AutoDetect (PowerShell) / --auto-detect (Bash):

.\scripts\install.ps1 D:\path\to\your\project -AutoDetect

Looks for .claude/ or .kiro/ and writes the Stop / 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/README.md.

3. Let AI scan

Open your project in any AI IDE (Cursor / Claude Code / Kiro / Copilot / Codex / Gemini CLI / ...). The AI reads AGENTS.md (or .agents/skills/codesee/SKILL.md for SKILL.md-compatible IDEs) and automatically generates .codesee/features.json.

If your project uses a Spec-Driven Development framework (.specify/, .trellis/, .bmad-core/, ...), CodeSee will detect it and consume the spec/PRD docs directly — no source code scan needed.

4. View the graph (in your browser, no install)

Open https://Kaka-cheaper.github.io/codeSee/ — the live web viewer.

By default you'll see CodeSee's own feature graph. To switch to your project:

1. Click + Add project in the top-right dropdown
2. Pick the folder containing .codesee/features.json — you'll get a one-time browser permission prompt
3. Done. The browser reads your local files directly via the File System Access API — never uploads anything.

All your previous projects stay in the dropdown — next time you open the viewer, just click to switch.

Browser support: Chrome / Edge / Arc / Brave (Chromium-based). Firefox/Safari users can drag a features.json file in instead — layout still saves to localStorage.

Want to run viewer locally? See Development setup — cd viewer && npm run dev.

---

How It Works

Your Project/                              CodeSee Viewer/
├── AGENTS.md                  ←────────── templates/AGENTS.md
├── .agents/skills/codesee/    ←────────── templates/SKILL.md  (cross-platform skill)
│   └── SKILL.md
├── .codesee/                              viewer/
│   ├── prompts/*.md           ←────────── prompts/*.md  (scan / scan-sdd / sync / ...)
│   ├── scripts/               ←────────── scripts/validate-features.mjs
│   │                                    + hooks/scripts/check-staleness.mjs
│   ├── hooks/                 ←────────── hooks/{claude-code,kiro,README.md}
│   ├── features.json          ──────────→ Loaded by viewer (add project / drag)
│   └── layout.json            ←────────── Saved from viewer (FSA, same folder as features.json)
├── .claude/settings.json      ←────────── (optional) merged Stop hook via --auto-detect
├── .kiro/hooks/codesee-*.json ←────────── (optional) wired via --auto-detect
└── your code  (or .specify / .trellis / .bmad-core / ... for SDD projects)

Layer	What	Who maintains
features.json	Semantic flow (epics, features, steps, relations)	AI + human review
layout.json	Node positions on canvas	User drag + auto-save
Viewer	Rendering, interaction, layout algorithms	This repo

---

Three Views

View	Shows	Interaction
Overview	Epics as nodes, epic_flow as edges	Drag to arrange; double-click → Features
Features	Features grouped in Epic containers	Drag nodes/containers; double-click → Steps
Steps	Step-by-step flow within one feature	Directed graph with async/conditional/error edges

---

Best Practices

Three usage scenarios

Scenario	When	How
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.
B. SDD project	Project already uses spec-kit / Trellis / BMAD / Agent Skills	CodeSee auto-detects and consumes spec/PRD docs directly — most accurate, fewest tokens.
C. Brownfield	Adding CodeSee to an existing code-only project	Run a full code scan first, then switch to incremental sync.

Why Greenfield is the best practice

When you develop from zero with CodeSee integrated from day one:

• 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
• Granularity stays fine — each sync covers one small feature, not 50 features at once
• No hallucination risk — AI doesn't need to guess what existing code does; it wrote it moments ago
• The graph grows with your project — you can review the canvas at any point and catch design issues early
• refs are precise — file paths and line numbers are accurate because the code was just written

Greenfield workflow

1. Install CodeSee into your empty project
2. Tell AI: "Build feature X"
3. AI writes code → AI updates features.json (trigger 2 in AGENTS.md)
4. You review the canvas → spot issues → tell AI to fix
5. Repeat for next feature

The canvas becomes your living architecture diagram that's always in sync with reality.

Brownfield workflow

1. Install CodeSee into your existing project
2. AI runs scan (trigger 1) → generates full features.json
3. You review on canvas → lock correct features → tell AI to fix wrong ones
4. From now on, every code change triggers incremental sync

SDD project workflow

1. Install CodeSee — install script auto-detects your SDD framework
2. AI reads .codesee/prompts/scan-sdd.md → consumes your spec/PRD docs
3. Each task done in your SDD framework → AI runs sync (no re-scanning code)
4. The canvas reflects your spec library, not your code structure

This is the highest-fidelity path: spec → features.json is forward projection (preserves intent), while code → features.json is reverse engineering (loses intent).

---

Design Principles

1. Semantic control belongs to AI / features.json — node order, naming, grouping, relations
2. Visual & interaction belongs to the viewer — drag, zoom, theme, layout algorithms
3. When in doubt, let AI write it explicitly — no heuristic inference in the frontend

Full details: docs/principles.md

---

Project Structure

codeSee/
├── viewer/                  Canvas frontend (Vite + React + React Flow + Tailwind v4 + ELK)
│   ├── src/{fcg,graph,app,lib}
│   └── public/
│       ├── features.json    Default example: CodeSee modeling itself (live demo)
│       ├── examples/        Other bundled examples
│       │   └── blog-system.json
│       └── layout.json      Default canvas layout
├── prompts/                 AI prompt templates (copied to target projects)
│   ├── scan.md              Entry point (auto-routes: sdd / planning / light / heavy)
│   ├── scan-sdd.md          SDD projects (spec-kit / Trellis / BMAD / Agent Skills)
│   ├── scan-light.md        Light projects (one-shot)
│   ├── scan-heavy.md        Heavy projects (phased)
│   ├── scan-planning.md     Doc-only / planning stage
│   ├── sync.md              Incremental sync
│   ├── _schema.md           Schema + enums + example (single source of truth)
│   └── _rules.md            Constraints (MUST/SHOULD/MAY)
├── templates/               Entry-rule templates
│   ├── AGENTS-snippet.md    Single source of truth for the AGENTS.md CodeSee section (BEGIN/END marked)
│   └── SKILL.md             Cross-platform skill entry (agentskills.io standard)
├── hooks/                   Cross-IDE hooks (copied to target as .codesee/hooks/)
│   ├── README.md            Enablement guide
│   ├── scripts/
│   │   └── check-staleness.mjs   Shared: detects stale features.json after each turn
│   ├── claude-code/
│   │   └── settings.json    Stop hook template (merged into .claude/settings.json)
│   └── kiro/
│       └── sync-on-stop.json  agentStop hook (dropped into .kiro/hooks/)
├── scripts/                 Install + tooling
│   ├── install.ps1
│   ├── install.sh
│   ├── validate-features.mjs       Schema + heuristic validator
│   └── merge-claude-settings.mjs   Phase 2: idempotent JSON merge for .claude/settings.json
├── docs/                    Design docs
├── LICENSE                  MIT
└── README.md

---

FAQ / Troubleshooting

How can the browser read files from my disk? Is that safe?

CodeSee uses the File System Access API, a modern web standard. Three things make it safe:

1. 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.
2. The browser sandboxes access. Only that one folder you picked is readable, and only by https://Kaka-cheaper.github.io/. Refresh the page → permission resets to prompt until you re-grant.
3. Nothing leaves your machine. The viewer is a static site (HTML/JS/CSS 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.

Even if you don't trust me: clone the repo, read viewer/src/fcg/fileSystem.ts (the only file that touches FSA), and see for yourself. Or just run viewer locally — see Development setup.

Viewer shows a blank white screen after loading features.json

The AI likely used enum values outside the schema (e.g. role: "logic" instead of role: "compute").

1. Run the validator: node .codesee/scripts/validate-features.mjs
2. Fix the reported errors (usually invalid step.role, flow.kind, or trigger.kind)
3. Reload the viewer

The viewer has fallback handling for unknown enums, but severely malformed JSON can still cause issues.

Save button doesn't work / no directory picker shows up

CodeSee uses the File System Access API for local read/write. Only available in Chromium browsers (Chrome, Edge, Arc).

• Use Chrome or Edge to open the viewer
• Must access via localhost or HTTPS (FSA is blocked on file://)
• 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
• Without authorization, save only writes localStorage drafts (still survives refresh, but not to disk)
• Browser restart may reset FSA permission to prompt — the canvas will show a re-authorization banner; one click on Reauthorize is enough
• Firefox/Safari users: the viewer falls back to localStorage and your layout is still saved

How do I switch between multiple projects?

The Open ▼ dropdown in the top-bar has two sections:

• Your projects — folders or uploaded files you've added before, sorted by last opened, hover to remove
• Examples — CodeSee itself, blog-system example

Click 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.

The active project is remembered in localStorage; next time you open the viewer it loads where you left off.

Overview is just a horizontal line

The AI assigned sequential order values (0, 1, 2, ..., N) to every Epic instead of grouping parallel modules under the same order.

Fix 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.

AI keeps inventing enum values not in the schema

This is the most common issue. The prompts include strict enum tables, but some models still hallucinate.

• Always run the validator after AI writes/updates features.json
• The validator reports exact JSONPath locations of invalid values
• Common mappings: logic → compute, init/cleanup → other, websocket → http, internal → event

How do I enable / disable hooks?

Easiest way to enable: rerun install with --auto-detect.

.\scripts\install.ps1 D:\my-project -AutoDetect

That does two things:

1. Merges the Stop hook into .claude/settings.json (only if .claude/ exists)
2. Writes .kiro/hooks/codesee-sync-on-stop.json (only if .kiro/ exists)

Every 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.

Once enabled, after every agent turn the IDE runs node .codesee/scripts/check-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.

Disable:

.\scripts\install.ps1 D:\my-project -UninstallHooks

Removes only the marker-tagged entry plus .kiro/hooks/codesee-*.json. The .codesee/hooks/ templates stay so you can re-enable any time.

For per-platform manual setup or Git hook fallback see hooks/README.md.

How do I update CodeSee in my project after pulling new changes?

Re-run the install script with -Force (PowerShell) or --force (Bash):

.\scripts\install.ps1 D:\path\to\your\project -Force

This refreshes prompts, validator, and the AGENTS.md CodeSee section without touching your features.json or layout.json.

My project uses spec-kit / Trellis / BMAD — does it just work?

Yes. The install script auto-detects these directories:

• .specify/ — GitHub Spec Kit
• .trellis/ — Mindfold Trellis
• .bmad-core/ or bmad/ — BMAD-METHOD
• .agents/skills/ — Agent Skills standard
• .agent-os/ — Builder Methods Agent OS

When detected, the install script reports which framework it found, and scan.md routes to scan-sdd.md which consumes spec/PRD docs directly. No source code scan needed — far more accurate than reverse engineering.

What's the difference between AGENTS.md and SKILL.md?

AGENTS.md is the original entry-rule format used by Cursor, Claude Code, Kiro, etc. — placed at project root.

SKILL.md is the agentskills.io cross-platform standard (Anthropic, December 2025) used by 20+ AI tools. Placed at .agents/skills/codesee/SKILL.md. It uses progressive disclosure (only ~30-50 tokens load at startup, full instructions load on demand).

The install script writes both — your AI IDE will pick whichever it understands.

---

Roadmap

Want to contribute? Many of the open items below have matching issues with concrete scope and acceptance criteria. Check the good first issue and help wanted labels.

Top priority

• Prompt refinement (community-driven) — real-world usage produces the best constraints; contributions welcome for edge cases, anti-patterns, and domain-specific rules
• 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/downstream, larger edge-node spacing prevents label collisions); next: Feature.order field, swimlane view, AI-driven semantic layout intent.
• Plan-as-Graph — AI outputs its plan/design 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".
• 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.
• Incremental patch output protocol — sync prefers RFC 6902 JSON Patch over full file rewrite. Phase 1 done: scripts/apply-patch.mjs implements the patch applier (zero-deps, supports add/remove/replace/move/copy/test 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.
• Platform hooks — auto-trigger sync via Claude Code hooks / Kiro hooks. Phase 1 done: hook templates + shared check-staleness.mjs shipped to .codesee/hooks/. Phase 2 done: install gains --auto-detect / --enable-claude-code / --enable-kiro to wire the IDE config in one shot; existing user entries are untouched, reruns are idempotent, --uninstall-hooks cleans up.

Ecosystem & integrations

• SDD framework integration — auto-detect .specify/ (Spec Kit), .trellis/ (Trellis), .bmad-core/ (BMAD), .agents/skills/ and consume spec/PRD docs as the source for features.json (forward projection from spec instead of reverse engineering from code)
• SKILL.md standard entry — cross-platform skill following agentskills.io, works on Claude Code / Cursor / Codex / Gemini CLI / Copilot / 20+ platforms
• 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

Canvas & UX

• Share via URL (remote features.json) — load any URL-accessible features.json via ?features=<url> (or ?repo=<owner>/<repo> GitHub shorthand). Drop a link in a README / doc / 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.
• Canvas editing — edit feature names, add notes, lock nodes directly on the canvas
• Search & filter — find features by name, filter by epic/tag/role
• Diff view — highlight what changed between two versions of features.json
• Multi-project dashboard — top-bar dropdown to switch between projects (FSA folders / uploaded files / bundled examples), no re-dragging
• Export — PNG / SVG / PDF export of the current view
• Dark theme — toggle between warm-ivory and dark mode

Tooling

• CI integration — validate features.json in GitHub Actions / GitLab CI
• Plugin system — custom node renderers, custom layout algorithms
• Zero-clone install — curl ... | bash one-liner that fetches scripts/prompts/templates from GitHub raw, no git clone needed

Long-term (optional)

• Vector index — semantic embedding for "find similar features" / cross-project reuse; must remain optional and never replace the JSON-as-source-of-truth principle

---

Community

• 💬 LinuxDo — Discussion & feedback
• 🐛 GitHub Issues — Bug reports & feature requests

---

Contributing

See CONTRIBUTING.md for development setup, code style, and PR process.

Quick start:

1. Fork & clone
2. cd viewer && npm install && npm run dev
3. Make changes, ensure npm run build passes
4. Open a PR

---

License

MIT

---

Built with ❤️ by @Kaka-cheaper — independent dev exploring AI-collaborative workflows.

Found this useful? Star ⭐ on GitHub · Say hi on LinuxDo

If you ship something with CodeSee, open an issue — I'd love to feature it.