codemind-sh 0.1.1

Local-first knowledge graph for software projects. Gives AI tools structural facts about your codebase via 11 MCP tools.

CodeMind

Your codebase finally knows what connects to what — and it never leaves your machine.

CodeMind is a local-first knowledge graph for software projects. It lives inside your project as .codemind/ (like .git/) and builds a precise, always-current graph of every component and every typed connection. When you use AI coding tools (Claude Code, Cursor, Copilot), CodeMind exposes 11 structural MCP tools — so the AI answers "what calls X?", "what breaks if I change Y?", and "which Angular service calls /api/offers?" with facts from the graph, not guesses.

Why?

Every AI coding tool has amnesia. Claude Code, Cursor, Copilot — they read your files, help you code, and forget everything the moment the session ends. You waste 10–30 minutes per session re-explaining your architecture.

CodeMind fixes this — and goes further: it maps every component and connection so the AI understands your project structurally, not just textually.

Quick Start

pip install codemind-sh

cd your-project/
codemind init
codemind scan

✓ graph.json built

  Graph summary
    Components (nodes): 428
    Connections (edges): 1,138
    Cross-layer (frontend→backend): 20
    Languages: java, typescript
    Types: 118 interface, 92 class, 69 service, 44 component,
           23 controller, 20 repository, 19 entity, 24 enum ...

That's it. Your project now has a living knowledge graph.

Use With Claude Code, Cursor, or Claude Desktop (MCP)

codemind init automatically registers CodeMind with every AI coding tool it detects on your machine. No manual config editing required.

If you need to re-register later (e.g. after installing a new tool):

codemind connect              # auto-detect and register all installed AI tools
codemind connect --tool claude  # Claude Code only
codemind connect --global     # write to global config instead of project-level

This creates .mcp.json at your project root (the format Claude Code requires):

{
  "mcpServers": {
    "codemind": {
      "command": "/path/to/codemind",
      "args": ["serve", "--path", "/absolute/path/to/your/project"]
    }
  }
}

codemind serve always includes the file watcher — graph.json is kept current on every save so the AI always answers with structural facts, never stale data.

The 11 MCP Tools

Once connected, Claude Code (or any MCP-compatible tool) can use:

Tool	What it answers
get_connections(component)	What it injects, calls, extends, implements — and what depends on it. Includes cross-layer edges (frontend→backend).
impact_analysis(component)	Everything that breaks if this component changes. BFS, sorted by distance.
find_components(query)	Free-text search across names, packages, method names. Auto-discovers unindexed files when nothing found.
find_for_task(description)	Relevant existing components + gaps for a stated feature.
get_pattern()	Best existing full-stack domain as a copy-me template.
trace_request(path)	Trace an HTTP path from frontend to backend. /api/offers → OfferService → OfferController.
record_decision(...)	Write a decision record after completing a task.
get_decisions(limit)	Read recent decisions at session start — the AI never starts from zero.
enrich_node(component, notes)	Attach AI-discovered notes to a graph node — persists across sessions.
index_file(path)	Read any source file (Dart, Kotlin, Swift, Go…) and return it with extraction instructions.
add_component(name, type, file, language, …)	Persist a component extracted from index_file to the graph permanently.

Example session (Claude Code with CodeMind connected)

You: "What would break if I change ThresholdEvaluator?"

Claude → impact_analysis("ThresholdEvaluator")
→ Direct dependents (distance 1): KpiCalculationService, KpiAlertService
→ Indirect dependents (distance 2): KpiController, ReportsService
→ 4 components affected — 2 controllers + 2 services

You: "Which Angular service calls /api/kpi-builder?"

Claude → trace_request("/api/kpi-builder")
→ Frontend: KpiService (service) — calls this endpoint
→ Backend: KpiBuilderController (controller) — route: /api/kpi-builder
→ Cross-layer connection: KpiService → KpiBuilderController

What .codemind/ Contains

your-project/
└── .codemind/
    ├── graph.json          ← The knowledge graph (auto-updated on every save)
    ├── ARCHITECTURE.md     ← System overview, module map (auto-generated)
    ├── modules/            ← Per-domain docs: auth.md, kpi.md, ...
    ├── decisions/          ← Why things were built this way
    │   └── 2026-02-15-add-kpi-alert.md
    ├── tasks/              ← Implementation checklists (from scaffold)
    └── config.yml          ← Project settings

Everything is human-readable. Git-friendly. Private.

Scaffold — Generate Code From Your Graph

CodeMind learns your project's package structure, naming conventions, and injection patterns from the graph, then generates new code that matches:

codemind scaffold service KpiAlert     # KpiAlertService.java + test
codemind scaffold module Attendance    # Full stack: service + controller + entity + repository + test
codemind scaffold api ReportExport     # Controller + service + test
codemind scaffold component Dashboard  # Angular/TypeScript service

# Preview without writing:
codemind scaffold module Attendance --dry-run

Generated files use your real package (com.app.kpi.business.kpialert), your real API path (/api/kpi-alert), and your real table name (kpi_alert) — all derived from the graph.

Health Checks

codemind check             # Full check: naming, layer violations, missing tests, orphans, domains
codemind check --quick     # Fast: naming + layer violations only
codemind check --pre-commit  # Git hook mode: exit 1 on errors

Five checks, all driven by the graph:

• naming — component names match their type (KpiService should end in Service)
• layer_violation — controllers injecting repositories directly (error)
• missing_test — services/controllers without a test class
• orphan — structural nodes with no connections (dead code?)
• domain_incomplete — domains missing key layers

Install as a git pre-commit hook:

codemind install-hook

Decision Tracking

codemind decide "Add KPI threshold alert"   # Interactive — prompts for components + reason
codemind decisions                          # List recent decisions
codemind decisions show kpi-threshold       # Print full decision

At session start, Claude calls get_decisions automatically and knows what was built and why. No re-explaining.

Team Reports (BYOK)

When you ask Claude about your codebase in a session, the answer disappears when the session ends. These three commands generate persistent markdown reports that live in your repo — readable by the whole team, committable, and shareable without anyone needing an active AI session.

codemind review                           # Architectural review → .codemind/REVIEW.md
codemind brief                            # Onboarding brief   → .codemind/BRIEF.md
codemind impact ThresholdEvaluator --ai   # Risk badge         → printed + committable

codemind review — compresses your entire graph (all components, health check results, connection counts) into a structured architectural review: strengths, risks, recommendations, key metrics. Commit REVIEW.md so every teammate sees the same picture.

codemind brief — generates an onboarding doc: what the system does, the 5 most important components, the 3 domains to understand first, key patterns, and a glossary of domain terms extracted from your component names. A new developer reads it before their first session — onboarded before they open Claude Code.

codemind impact <component> --ai — runs a full BFS across the entire graph first (not just what's in your current context), then asks Claude to assess risk level (🟢/🟡/🔴) with specific high-risk callers named. Useful in CI: block a PR when blast radius is 🔴 HIGH.

All three require ANTHROPIC_API_KEY (set once in your shell). Results are cached in .codemind/ai-cache/ keyed by graph content — running them twice on the same graph costs nothing. One codemind review (~$0.003) generates a report the whole team benefits from.

Any-language support needs no API key. index_file + add_component index Dart, Kotlin, Swift, Go, C#, Ruby, Rust and any other language at zero cost — they use your existing Claude Code session, not a separate key.

CLI Reference

# Core
codemind init                   # Initialize .codemind/ (1 project free)
codemind scan                   # Parse codebase → graph.json + ARCHITECTURE.md + modules/
codemind status                 # Graph stats overview

# AI tool integration
codemind connect                # Auto-register MCP with Claude Code/Cursor/Claude Desktop
codemind connect --tool claude  # Claude Code only
codemind connect --global       # Global config (all projects)

# Keep graph live
codemind watch                  # File watcher only (CLI workflow)
codemind serve                  # MCP server + file watcher (AI tool integration)

# Query
codemind query "email on KPI drop"             # find_for_task
codemind query "" --connections KpiService     # get_connections
codemind query "" --impact ThresholdEvaluator  # impact_analysis
codemind query "" --pattern                    # get_pattern

# Pro AI (requires ANTHROPIC_API_KEY)
codemind review                 # Architectural review
codemind brief                  # Onboarding brief
codemind impact <component> --ai  # Impact + AI risk assessment

# Scaffold
codemind scaffold service|module|api|component <name>
codemind scaffold module Attendance --dry-run   # Preview

# Health
codemind check
codemind check --quick
codemind install-hook            # Install as git pre-commit hook

# Decisions
codemind decide "What was built"
codemind decisions
codemind decisions show <slug>

Supported Stacks

Native parsers — fully offline, no API key ever

Language	Frameworks	Edges extracted
Java	Spring Boot, Jakarta EE, Lombok, JPA	injects, calls, extends, implements
TypeScript	Angular, React, Next.js, NestJS	injects, calls, extends, implements
Python	FastAPI, Django, Flask, Pydantic, SQLAlchemy	injects, calls, extends

Fullstack cross-layer routing: Spring Boot + Angular, Spring Boot + React. CodeMind detects frontend HTTP calls and backend routes, then creates cross-layer edges — so trace_request("/api/offers") shows the full path from Angular service to Spring controller.

Any other language — via index_file + add_component — free, no API key

When find_components finds nothing for a Dart / Kotlin / Swift / Go file, CodeMind automatically reads the file and returns it to your AI session with extraction instructions. Claude Code analyses it using your existing subscription and calls add_component to persist each class to graph.json permanently — available offline from that point forward.

Language	Cost
Dart / Flutter	$0 — uses your Claude Code session
Kotlin / Android	$0 — uses your Claude Code session
Swift / iOS	$0 — uses your Claude Code session
Go / Gin	$0 — uses your Claude Code session
C# / ASP.NET Core	$0 — uses your Claude Code session
Ruby / Rails	$0 — uses your Claude Code session
Rust, PHP, Elixir, …	$0 — uses your Claude Code session

Privacy

Everything stays on your machine. No cloud. No external database. No telemetry.

• graph.json — stays local
• decisions/*.md — stays local
• Your source code — never leaves your machine
• MCP tools run over local stdio — no network

The optional BYOK AI enricher (gap-filling injection edges) sends only small structural samples to the Claude API and is strictly opt-in via ANTHROPIC_API_KEY. All other features — including any-language indexing via index_file — run entirely offline using your existing AI tool session.

Links

• Website: codemind.sh
• Docs: codemind.sh/docs
• GitHub: github.com/onixsolutions/codemind

License

Business Source License 1.1 (BSL) — source visible, not for commercial redistribution. Converts to MIT after 4 years. Personal and evaluation use permitted.

Built by OnixSolutions