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

🧠 neatcode

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

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

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

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

🎓 Skills (conventions)

✅ Validation

🔌 Editor integration

🔗 MCP integration

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

Discovery + queries

Rules + validation

Memory

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

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.

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.

📄 License

MIT · built with ❤️ by @HitmanDark07

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