<div align="center">

                          _                     _
   _ __    ___    __ _   | |_    ___   ___   __| |   ___
  | '_ \  / _ \  / _` |  | __|  / __| / _ \ / _` |  / _ \
  | | | ||  __/ | (_| |  | |_  | (__ | (_) | (_| | |  __/
  |_| |_| \___|  \__,_|   \__|  \___| \___/ \__,_|  \___|

🧠 neatcode

Local-first repo intelligence for AI coding agents. The graph your agent wishes it had.

</div>

---

Stop letting your agent re-grep your repo on every turn. neatcode indexes your TypeScript codebase into a real AST graph, learns the conventions your code already follows, and answers your agent's structural questions over MCP — deterministic, no LLM in the hot path.

   ┌──────────────────┐        MCP         ┌─────────────────────────────────┐
   │  💻 your editor  │  ◀────stdio─────▶  │  ⚙️  neatcode-mcp  (11 tools)    │
   │                  │                    │                                 |
   │  Claude Code     │                    │  🔍 query_graph     📍 find_node │
   │  Cursor          │                    │  🛤️  trace_flow      ✅ validate │
   │  Codex           │                    │  💡 propose_rule    📚 get_rules │
   └──────────────────┘                    │  📝 add_note    📋 repo_overview │
                                           │  ⮕ accept_proposed_rule         │
                                           │  ⮕ derive_candidates            │
                                           │  ⮕ accept_derived_candidates    │
                                           └────────────────┬────────────────┘
                                                            │
                                                ┌───────────▼───────────┐
                                                │   📂 .neatcode/       │
                                                │    ├── graph.db       │
                                                │    ├── skills.yaml    │
                                                │    ├── decisions.yaml │
                                                │    └── REPO_OVERVIEW  │
                                                └───────────────────────┘

💡 Why

Without neatcode	With neatcode
Agent re-greps the repo every turn	Agent calls query_graph against an indexed AST
"What conventions does this repo follow?" → vibes	Heuristic miner derives conventions from real code
Agent writes BookingHandler despite a Controller convention	validate_diff flags it before the file is written
Rules live in tribal memory or stale CONTRIBUTING.md	Rules live in .neatcode/skills.yaml, validated bidirectionally
Each chat starts cold	get_repo_overview ships the one-page brief at session start

---

🚀 Quickstart — 3 commands

# 1. Install (one tarball, both binaries)
npm i -g @neatcodeai/cli

# 2. Index your repo
cd ~/your/typescript/repo
neatcode init

# 3. Wire it into Claude Code
neatcode claude install

Restart Claude Code. Your agent now has 11 structural tools — and a fresh .neatcode/REPO_OVERVIEW.md for instant context.

🎯 Founder's target: installed in 10 minutes, useful in 1 hour.

🎬 What it looks like in practice

👤 You: "Where do we handle booking cancellation?"

🤖 Agent: [calls query_graph with "booking cancellation"]
       ↓
       📍 BookingsController.cancel       (apps/api/src/bookings/…)
       📍 BookingsService.cancel          (called by Controller)
       📍 RefundService.issueRefund       (called by Service)
       📍 BookingCancelledEvent           (emitted at end)

       Here's the flow: Controller → Service → RefundService,
       with a domain event published on completion.

vs. without neatcode: agent runs 4 grep calls, reads 18 files, and still misses the event publisher.

---

🔷 TypeScript compatibility

neatcode ships TypeScript types and is built around ts-morph. It indexes any TypeScript codebase that compiles.

What	Compatibility
TypeScript versions	5.0 → 5.7+ (uses ts-morph 24.x; tracks the bundled compiler)
File extensions	.ts, .tsx (skips .d.ts and .generated.ts(x)); .js / .cjs not yet indexed
Module systems	ESM, CommonJS, mixed — output target doesn't matter
tsconfig.json	Auto-detected at repo root; respects paths, baseUrl, composite
JSX / TSX	Yes — .tsx parsed, JSX edges emitted
Decorators	Stage-3 standard + experimental (NestJS, TypeORM, class-validator)
Type-aware queries	Uses TS TypeChecker for cross-file call-graph resolution
Strict mode	Recommended but not required
Monorepos	pnpm / yarn / npm workspaces — each package gets its own qualified_name namespace
Frameworks	NestJS, React, Next.js, Express, Fastify (auto-detected; no rule packs)

Not on TypeScript? neatcode v0.1 is TS-only by design — Python, Go, and JS support are roadmapped (see Roadmap).

---

⚡ CLI reference

neatcode <command> [options]

📥 Indexing

Command	What it does
neatcode init	First-time setup. Creates .neatcode/, indexes every .ts/.tsx file, runs the heuristic miner, drops REPO_OVERVIEW.md.
neatcode sync [--force]	Re-index changed files. Content-hash cached — editing 3 files re-parses 3 files.
neatcode ask "<question>"	Ad-hoc graph query from the terminal. Same engine as query_graph over MCP.

🎓 Skills (conventions)

Command	What it does
neatcode skills derive [--threshold 0.85] [--min-population 3]	Mine the graph for high-coverage patterns. Writes skills.candidates.yaml.
neatcode skills accept <id> [--all] [--confidence high|medium] [--local]	Promote candidates into skills.yaml (committed) or skills.local.yaml (gitignored).
neatcode skills reject <id> [--reason "…"]	Mark a candidate as rejected so the next derive skips it.

✅ Validation

Command	What it does
neatcode validate [<files…>] [--json]	No args → check whole graph. With files → treat as planned diff. Pre-existing offenders are grandfathered under scope: "new".
neatcode exception add <rule_id> <location> [--days N] [--reason "…"]	Silence a specific violation. Auto-expires with --days.
neatcode exception list	Show active exceptions.
neatcode exception revoke <rule_id> <location>	Append-only revoke (original entry preserved).

🔌 Editor integration

Command	What it does
neatcode claude install	Merges .mcp.json, appends MCP guidance to CLAUDE.md. Idempotent.
neatcode claude uninstall	Reverses both. Pre-existing CLAUDE.md content is preserved.
neatcode cursor install (coming v0.2)	Wires neatcode-mcp into Cursor's MCP config.
neatcode codex install (coming v0.2)	Wires neatcode-mcp into Codex.

---

🔗 MCP integration

The agent gets 11 tools the moment Claude Code restarts after neatcode claude install:

Discovery + queries

Tool	When the agent calls it
get_repo_overview	Once per session. Returns frameworks, top symbols, layout, active rules, dirty-file status.
query_graph	"What handles X?", "what calls Y?" — keyword-scored search with optional 1-hop expansion.
find_node	Exact lookup by name or qualified_name. Returns merged class+method decorators.
trace_flow	Multi-hop path traversal. "From BookingsController.create to the DB" returns the call chain.

Rules + validation

Tool	When the agent calls it
get_rules	Returns active rules, candidates, rejected list, and repo context for curation flows.
validate_diff	Pre-flight on a planned change. Returns violations + four-option suggestions block.
propose_rule_from_prompt	Inspects a user utterance for rule-language ("never", "must", "always"). Surfaces a structured proposal.
accept_proposed_rule	Promote a single proposed rule into skills.yaml.
derive_candidates	Run the heuristic miner on demand and return candidate rules.
accept_derived_candidates	Bulk-accept miner candidates by id, confidence, or --all.

Memory

Tool	When the agent calls it
add_note	Persist a fact the user shared. Appends to .neatcode/memory/notes-YYYY-MM-DD.md.

All deterministic. No LLM call inside the server. The agent is the brain; neatcode is the spine.

---

📂 What lives in .neatcode/

neatcode init creates the directory and seeds it with the indexer output and miner proposals. The remaining files appear on demand as you accept rules, record exceptions, and let the agent take notes.

Created by neatcode init:

<repo-root>/
├── .neatcodeignore                team-shared excludes (commit it)
└── .neatcode/
    ├── graph.db                   SQLite graph         (regenerate; should gitignore)
    ├── skills.candidates.yaml     miner proposals      (regenerated each sync)
    ├── REPO_OVERVIEW.md           session-start brief  (commit it)
    ├── plans/                     /writing-plans skill scaffold (commit it)
    └── specs/                     /brainstorming skill scaffold (commit it)

Appears on demand:

.neatcode/
├── skills.yaml                   on first `skills accept`              (commit it)
├── skills.local.yaml             on `skills accept --local`            (should gitignore)
├── skills.rejected.yaml          on first `skills reject`              (commit it)
├── decisions.yaml                on first exception/supersede          (commit it)
├── memory/                       on first `add_note` MCP call          (commit it)
└── mcp.log                       on first MCP server start             (should gitignore)

ℹ️ neatcode init doesn't touch your .gitignore. Add the regeneratable bits yourself:

.neatcode/graph.db*
.neatcode/skills.candidates.yaml
.neatcode/skills.local.yaml
.neatcode/mcp.log

graph.db is regeneratable from a single neatcode sync. The committed files above form the team-shared memory of the repo — that's the part you code-review.

---

📐 How rules emerge

Three sources, one lifecycle:

1. Heuristic mining — neatcode skills derive proposes candidates above the coverage threshold. Four primitives mined today: decorator-required, annotation-forbidden, naming-pattern, folder-naming-convention.
2. Prompts — when the user says "all classes with @Controller must use @UseGuards", the agent calls propose_rule_from_prompt. A local keyword classifier — no LLM in the loop — extracts a structured candidate. User confirms, agent runs skills accept.
3. Manual — hand-edit .neatcode/skills.yaml (create it on first rule). The schema is documented and stable.

Rules are validated bidirectionally:

• A diff that violates a rule → four-option UX (record exception · time-bounded · supersede the rule · abort).
• A rule that no longer matches the codebase → can be superseded with an entry in decisions.yaml.

🧩 The six primitives

Primitive	Mined?	Example
decorator-required	yes	classes with @ApiTags must also have @Controller
annotation-forbidden	yes	classes with @Controller must not carry @Deprecated
naming-pattern	yes	classes with @Module end with "Module"
folder-naming-convention	yes	files in apps/api/services/ end with .service.ts
import-forbidden	via prompt	never import from packages/internal/
edge-forbidden	via prompt	controllers must not call repositories directly

Layer constraints ("controllers can't reach repositories") are expressed via edge-forbidden — no special "layer" type.

🌱 Default rule scope: new

Rules default to scope: "new" — pre-existing violations are grandfathered. Only code introduced after the rule was promoted gets checked. Set scope: "all" in YAML to enforce against existing code.

This avoids the classic "we accepted 30 conventions and now CI is on fire" problem.

---

🏗️ Architecture

       ┌──────────────────────────────────────────────────┐
       │  📜 ts-morph parser  ──▶  🗂️  polymorphic graph  │
       │                              (SQLite)            │
       └─────────────────────┬────────────────────────────┘
                             │
       ┌─────────────────────┼─────────────────────┐
       ▼                     ▼                     ▼
  🔍 query_graph        🎓 skills derive      ✅ validate_diff
  📍 find_node          (heuristic miner)        (engine.ts)
  🛤️ trace_flow                │                       │
       │                       ▼                       ▼
       │                skills.candidates      active rules ∩
       │                    → accept           decisions.yaml
       ▼                                              │
  🤖 agent answers ◀─────────────────────────  ⚠️ violations
                                              + 4-option UX

Every relationship gets a confidence label (EXTRACTED | INFERRED | AMBIGUOUS); the validator never fires on rules built solely from AMBIGUOUS edges. The repo-root-relative qualified_name is the FK that ties nodes, edges, rules, and decisions together. There's no LLM in the hot path of any MCP tool — the LLM lives in the agent harness (Claude Code, Cursor, Codex), and neatcode is the spine.

---

📦 Packages

The CLI bundles everything you need; the others are split for advanced use.

Package	Install for	What it gives you
@neatcodeai/cli	Most users	neatcode + neatcode-mcp binaries (depends on the others).
@neatcodeai/mcp	Bare MCP server	The stdio MCP binary alone.
@neatcodeai/core	Library users	parseFile, Database, ask, miner — all typed.

Single install gets you everything:

npm i -g @neatcodeai/cli
which neatcode neatcode-mcp

---

🛠️ Develop

pnpm install           # builds better-sqlite3 native module
pnpm build             # builds all three packages
pnpm typecheck         # tsc --noEmit across packages
pnpm test              # vitest run
pnpm test:watch
pnpm clean

# Smoke-test
node packages/cli/dist/index.js --help

Node 20+, TypeScript strict + verbatimModuleSyntax, ESM only.

---

🗺️ Roadmap

• v0.1 (shipped) — TypeScript-only, 11 MCP tools, validation engine, four-option UX, heuristic miner with four primitives, Claude Code installer.
• v0.2 — Cursor + Codex installers, import-forbidden / edge-forbidden mining, agent-proposed rules (skills derive --with-agent).
• v0.3 — Watcher mode (neatcode dev), JavaScript / .js / .cjs indexing, TypeScript LSP integration.
• Later — Python via tree-sitter, Go via go/parser, multi-language graphs joined by import-edge inference.

Issues, feature requests, and convention horror stories: github.com/HitmanDark07/neatcodeai/issues.

---

🛡️ Hard rules (project guarantees)

• No framework rule packs — conventions emerge per-repo.
• Decorators / generics / JSX live in extra JSON, not schema columns.
• qualified_name is always repo-root-relative.
• Rules built solely on AMBIGUOUS edges never enforce.
• v0.1 doesn't solve general NestJS DI — @Module({ providers, controllers, imports }) arrays become direct edges and we stop there.

---

<div align="center">

📄 License

MIT · built with ❤️ by @HitmanDark07

⭐ If neatcode helps your agent stop guessing, star the repo.

</div>