Metadata-Version: 2.4
Name: codemind-sh
Version: 0.1.6
Summary: Local-first knowledge graph for software projects. Gives AI tools structural facts about your codebase via 11 MCP tools.
License: MIT
License-File: LICENSE
Keywords: ai,developer-tools,codebase,mcp,context,architecture
Author: Mohammed
Author-email: mohammed@onixsolutions.net
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Provides-Extra: ai
Provides-Extra: all
Requires-Dist: anthropic (>=0.40) ; extra == "ai" or extra == "all"
Requires-Dist: click (>=8.1)
Requires-Dist: jinja2 (>=3.1)
Requires-Dist: mcp (>=1.0)
Requires-Dist: pyperclip (>=1.9)
Requires-Dist: pyyaml (>=6.0)
Requires-Dist: rich (>=13.7)
Requires-Dist: tree-sitter (>=0.22)
Requires-Dist: tree-sitter-java (>=0.23)
Requires-Dist: tree-sitter-python (>=0.23)
Requires-Dist: tree-sitter-typescript (>=0.23)
Requires-Dist: typer[all] (>=0.12)
Requires-Dist: watchdog (>=4.0)
Project-URL: Bug Tracker, https://github.com/onixsolutions/codemind-community/issues
Project-URL: Documentation, https://codemind.sh/docs
Project-URL: Discussions, https://github.com/onixsolutions/codemind-community/discussions
Project-URL: Homepage, https://codemind.sh
Project-URL: Repository, https://github.com/onixsolutions/codemind-community
Description-Content-Type: text/markdown

# 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

```bash
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):

```bash
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):

```json
{
  "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:

```bash
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

```bash
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:
```bash
codemind install-hook
```

## Decision Tracking

```bash
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.

```bash
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

```bash
# 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.

## Community & Support

- **Bug reports / feature requests:** [github.com/onixsolutions/codemind-community](https://github.com/onixsolutions/codemind-community/issues)
- **Discussions & Q&A:** [github.com/onixsolutions/codemind-community/discussions](https://github.com/onixsolutions/codemind-community/discussions)
- **Email:** support@onixsolutions.net
- **Dashboard:** [codemind.sh/dashboard](https://codemind.sh/dashboard)

## Links

- **Website:** [codemind.sh](https://codemind.sh)
- **Docs:** [codemind.sh/docs](https://codemind.sh/docs)

## 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](https://onixsolutions.net)

