codebase-intel 0.1.0__tar.gz → 0.2.0__tar.gz

codebase_intel-0.2.0/.codebase-intel/intents/INT-001.yaml

@@ -0,0 +1,39 @@
+id: INT-001
+title: Live efficiency tracking must work end-to-end via MCP
+description: Every get_context MCP call must record analytics, and the dashboard must
+  show real data from actual MCP usage.
+status: verified
+priority: 1
+criteria:
+- description: Analytics tracker module exists
+  criterion_type: file_exists
+  check_value: src/codebase_intel/analytics/tracker.py
+  verified: true
+- description: MCP server initializes analytics tracker
+  criterion_type: file_contains
+  check_value: src/codebase_intel/mcp/server.py::AnalyticsTracker
+  verified: true
+- description: Assembler accepts analytics_tracker parameter
+  criterion_type: file_contains
+  check_value: src/codebase_intel/orchestrator/assembler.py::analytics_tracker
+  verified: true
+- description: MCP server passes analytics to assembler
+  criterion_type: file_contains
+  check_value: src/codebase_intel/mcp/server.py::analytics_tracker=state
+  verified: true
+- description: Dashboard CLI command exists
+  criterion_type: grep_match
+  check_value: def dashboard::src/codebase_intel/cli/main.py
+  verified: true
+- description: Benchmark CLI command exists
+  criterion_type: grep_match
+  check_value: def benchmark::src/codebase_intel/cli/main.py
+  verified: true
+created_at: '2026-04-08T12:51:28.427512Z'
+updated_at: '2026-04-08T12:51:28.432214Z'
+verified_at: '2026-04-08T12:51:28.432215Z'
+session_id: null
+tags:
+- core
+- analytics
+- mcp

codebase_intel-0.2.0/.codebase-intel/intents/INT-002.yaml

@@ -0,0 +1,35 @@
+id: INT-002
+title: Feedback loop must capture acceptance/rejection via MCP
+description: Agents must be able to report whether their output was accepted or rejected,
+  and the system must learn from this.
+status: verified
+priority: 1
+criteria:
+- description: Feedback tracker module exists
+  criterion_type: file_exists
+  check_value: src/codebase_intel/analytics/feedback.py
+  verified: true
+- description: MCP server has record_feedback tool
+  criterion_type: mcp_tool_exists
+  check_value: record_feedback
+  verified: true
+- description: MCP server has get_efficiency_report tool
+  criterion_type: mcp_tool_exists
+  check_value: get_efficiency_report
+  verified: true
+- description: MCP server initializes feedback tracker
+  criterion_type: file_contains
+  check_value: src/codebase_intel/mcp/server.py::FeedbackTracker
+  verified: true
+- description: Feedback handler maps rejection reasons to suggestions
+  criterion_type: file_contains
+  check_value: src/codebase_intel/analytics/feedback.py::_suggestion_for_reason
+  verified: true
+created_at: '2026-04-08T12:51:28.428541Z'
+updated_at: '2026-04-08T12:51:28.532925Z'
+verified_at: '2026-04-08T12:51:28.532935Z'
+session_id: null
+tags:
+- core
+- feedback
+- mcp

codebase_intel-0.2.0/.codebase-intel/intents/INT-003.yaml

@@ -0,0 +1,55 @@
+id: INT-003
+title: Intent tracking must prevent 'built but not wired' gaps
+description: The system must capture user goals, verify acceptance criteria against
+  actual code, and flag unmet criteria before marking done.
+status: verified
+priority: 1
+criteria:
+- description: Intent models exist
+  criterion_type: file_exists
+  check_value: src/codebase_intel/intent/models.py
+  verified: true
+- description: Intent verifier exists
+  criterion_type: file_exists
+  check_value: src/codebase_intel/intent/verifier.py
+  verified: true
+- description: Intent store exists
+  criterion_type: file_exists
+  check_value: src/codebase_intel/intent/store.py
+  verified: true
+- description: MCP server has set_intent tool
+  criterion_type: mcp_tool_exists
+  check_value: set_intent
+  verified: true
+- description: MCP server has check_intent tool
+  criterion_type: mcp_tool_exists
+  check_value: check_intent
+  verified: true
+- description: MCP server has list_intents tool
+  criterion_type: mcp_tool_exists
+  check_value: list_intents
+  verified: true
+- description: CLI intent command exists
+  criterion_type: grep_match
+  check_value: def intent::src/codebase_intel/cli/main.py
+  verified: true
+- description: Verifier can check file_exists criterion
+  criterion_type: function_exists
+  check_value: _check_file_exists
+  verified: true
+- description: Verifier can check file_contains criterion
+  criterion_type: function_exists
+  check_value: _check_file_contains
+  verified: true
+- description: Verifier can check wired criterion
+  criterion_type: function_exists
+  check_value: _check_wired
+  verified: true
+created_at: '2026-04-08T12:51:28.430099Z'
+updated_at: '2026-04-08T12:51:28.545922Z'
+verified_at: '2026-04-08T12:51:28.545924Z'
+session_id: null
+tags:
+- core
+- intent
+- verification

codebase_intel-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv venv
+      - run: uv pip install -e ".[dev]"
+      - run: uv run pytest tests/unit/ -x -q --no-header -p no:cacheprovider -o "addopts="
+        env:
+          PYTHONDONTWRITEBYTECODE: 1

codebase_intel-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+      - run: uv python install 3.12
+      - run: uv build
+      - name: Publish to PyPI
+        run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}

{codebase_intel-0.1.0 → codebase_intel-0.2.0}/CLAUDE.md

@@ -56,7 +56,11 @@ src/codebase_intel/
 ├── contracts/     # models.py, parser.py, evaluator.py, registry.py
 ├── orchestrator/  # assembler.py, budget.py, scorer.py, conflict.py
 ├── drift/         # detector.py, reporter.py
-├── mcp/           # server.py
+├── workspace/     # manager.py, registry.py — global multi-project workspace
+├── crossrepo/     # models.py, scanner.py, registry.py — cross-service deps
+├── analytics/     # tracker.py, benchmark.py, feedback.py
+├── intent/        # models.py, verifier.py, store.py
+├── mcp/           # server.py (supports --auto multi-project mode)
 └── cli/           # main.py
 ```
 

{codebase_intel-0.1.0 → codebase_intel-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebase-intel
-Version: 0.1.0
+Version: 0.2.0
 Summary: Your AI agent writes code — but does it know WHY your code exists? Decision provenance, quality contracts, and AI anti-pattern detection for coding agents.
 Project-URL: Homepage, https://github.com/mutharasu/codebase-intel
 Project-URL: Repository, https://github.com/mutharasu/codebase-intel
@@ -91,10 +91,10 @@ Result: faster but fragile                Result: faster AND correct
 
 | Project | Files | Naive Tokens | codebase-intel | Reduction | Decisions | Contracts |
 |---|---:|---:|---:|---:|---:|---:|
-| **IDP Backend** (FastAPI monolith) | 359 | 16,063 | 5,955 | **63%** | 13 | 4 |
-| **Job Marketing AI** (microservice) | 358 | 14,611 | 5,955 | **59%** | 0 | 7 |
-| **Resume Builder** (microservice) | 87 | 2,461 | 1,275 | **48%** | 0 | 6 |
-| **User Module** (microservice) | 153 | 5,904 | 1,476 | **75%** | 0 | 4 |
+| **FastAPI monolith** (auth + frontend) | 359 | 16,063 | 5,955 | **63%** | 13 | 4 |
+| **Microservice A** (AI processing) | 358 | 14,611 | 5,955 | **59%** | 0 | 7 |
+| **Microservice B** (document generation) | 87 | 2,461 | 1,275 | **48%** | 0 | 6 |
+| **Microservice C** (user management) | 153 | 5,904 | 1,476 | **75%** | 0 | 4 |
 
 > Numbers from `codebase-intel benchmark` on real production repos. The token reduction comes from targeted graph traversal. The decisions and contracts are what no other tool provides.
 

{codebase_intel-0.1.0 → codebase_intel-0.2.0}/README.md

@@ -45,10 +45,10 @@ Result: faster but fragile                Result: faster AND correct
 
 | Project | Files | Naive Tokens | codebase-intel | Reduction | Decisions | Contracts |
 |---|---:|---:|---:|---:|---:|---:|
-| **IDP Backend** (FastAPI monolith) | 359 | 16,063 | 5,955 | **63%** | 13 | 4 |
-| **Job Marketing AI** (microservice) | 358 | 14,611 | 5,955 | **59%** | 0 | 7 |
-| **Resume Builder** (microservice) | 87 | 2,461 | 1,275 | **48%** | 0 | 6 |
-| **User Module** (microservice) | 153 | 5,904 | 1,476 | **75%** | 0 | 4 |
+| **FastAPI monolith** (auth + frontend) | 359 | 16,063 | 5,955 | **63%** | 13 | 4 |
+| **Microservice A** (AI processing) | 358 | 14,611 | 5,955 | **59%** | 0 | 7 |
+| **Microservice B** (document generation) | 87 | 2,461 | 1,275 | **48%** | 0 | 6 |
+| **Microservice C** (user management) | 153 | 5,904 | 1,476 | **75%** | 0 | 4 |
 
 > Numbers from `codebase-intel benchmark` on real production repos. The token reduction comes from targeted graph traversal. The decisions and contracts are what no other tool provides.
 

codebase_intel-0.2.0/launch/awesome_list_submissions.md

@@ -0,0 +1,45 @@
+# Awesome List Submissions
+
+Submit PRs to these repos. Each one is a backlink + discovery channel.
+
+## 1. awesome-mcp-servers
+**Repo:** https://github.com/punkpeye/awesome-mcp-servers
+**Section:** Developer Tools / Code Analysis
+**Entry to add:**
+```
+- [codebase-intel](https://github.com/MutharasuArchunan13/codebase-intel) - Codebase intelligence with decision provenance, quality contracts, and AI anti-pattern detection. 19 languages, auto-contract generation.
+```
+
+## 2. awesome-ai-devtools
+**Repo:** https://github.com/jamesmurdza/awesome-ai-devtools
+**Section:** Code Analysis
+**Entry:**
+```
+- [codebase-intel](https://github.com/MutharasuArchunan13/codebase-intel) - Open-source context layer for AI coding agents. Provides decision provenance (why code exists), quality contracts, and drift detection via MCP.
+```
+
+## 3. awesome-python
+**Repo:** https://github.com/vinta/awesome-python
+**Section:** Code Analysis
+**Entry:**
+```
+- [codebase-intel](https://github.com/MutharasuArchunan13/codebase-intel) - Codebase intelligence platform providing structured context, decision provenance, and quality contracts for AI coding agents.
+```
+
+## 4. awesome-claude
+**Repo:** Search for any awesome-claude or awesome-claude-code list
+**Entry:**
+```
+- [codebase-intel](https://github.com/MutharasuArchunan13/codebase-intel) - MCP server giving Claude Code decision provenance, quality contracts, and AI anti-pattern detection. 19 languages.
+```
+
+## 5. MCP Server Directory
+**URL:** https://modelcontextprotocol.io
+**Submit:** Check if they have a directory/registry and submit codebase-intel as an MCP server.
+
+## How to submit
+For each awesome list:
+1. Fork the repo
+2. Add your entry in the appropriate section (alphabetical order)
+3. Open a PR with title: "Add codebase-intel"
+4. Body: "codebase-intel provides AI coding agents with decision provenance, quality contracts, and drift detection via MCP. 19 languages, 595 tests, published on PyPI."

codebase_intel-0.2.0/launch/devto_article.md

@@ -0,0 +1,180 @@
+---
+title: The 3 Things AI Coding Agents Still Can't Do (And How I Fixed Them)
+published: true
+tags: ai, python, opensource, programming
+canonical_url: https://github.com/MutharasuArchunan13/codebase-intel
+---
+
+I've been using AI coding agents — Claude Code, GitHub Copilot, Cursor — daily across 11 production services for the past year. They've transformed how I work. But they keep failing at the same three things.
+
+This isn't a rant. This is a problem statement with a solution I built and open-sourced.
+
+## Problem 1: Context Rot
+
+AI agents lose track of what matters during longer sessions. Even with 1M token context windows, having a massive database without proper indexing doesn't help — the data exists, but retrieval is inefficient.
+
+**Real example:** I asked Claude to add rate limiting to a payment endpoint. It read the file, saw no existing rate limiter, and built one from scratch. There was already a rate limiting module in `src/middleware/rate_limiter.py` with 200 lines of battle-tested code. Claude just didn't see it because it was two directories away.
+
+## Problem 2: No Decision Awareness
+
+AI doesn't know WHY your code is the way it is.
+
+**Real example:** Claude suggested switching our auth tokens from EdDSA to RS256 "for broader compatibility." Our team specifically chose EdDSA six months ago because our compliance team required it for a security audit. That decision existed in a PR description that Claude never saw.
+
+The agent was technically correct. It was contextually wrong.
+
+## Problem 3: Quality Drift
+
+AI-generated code prioritizes speed over project conventions.
+
+**Real example:** Our project uses async handlers everywhere — 100% consistency across 46 handler files. Claude generated a sync handler. It worked. Tests passed. But it broke the convention, and the next developer who saw it started writing sync handlers too. One exception became a pattern.
+
+## The Root Cause
+
+Every AI context tool solves **what code exists** — code graphs, RAG, embeddings. Nobody solves **why code exists**, **what rules apply**, and **whether the context is still valid**.
+
+## What I Built
+
+**[codebase-intel](https://github.com/MutharasuArchunan13/codebase-intel)** — an open-source platform that provides AI agents with three things no other tool offers:
+
+### 1. Decision Journal
+
+Structured records of WHY decisions were made, linked to specific code locations:
+
+```yaml
+id: DEC-042
+title: "Use token bucket for rate limiting"
+context: "Payment endpoint hammered during flash sales"
+decision: "Token bucket, per-user buckets, 100 req/min"
+alternatives:
+  - name: sliding_window
+    rejection_reason: "Memory overhead too high at scale"
+constraints:
+  - description: "Must not add >2ms p99 latency"
+    source: sla
+    is_hard: true
+code_anchors:
+  - "src/middleware/rate_limiter.py:15-82"
+```
+
+These are **auto-mined from git history**. Run `codebase-intel mine --save` and it extracts decision candidates from commit messages and PR descriptions using keyword analysis. On a 359-file FastAPI project, it found 16 decision candidates automatically.
+
+### 2. Quality Contracts
+
+Not linting. Project-specific architectural rules that AI reads BEFORE generating code:
+
+```yaml
+rules:
+  - id: async-handlers
+    name: All handlers must be async
+    severity: error
+    pattern: "(?<!async\\s)def\\s+(get_|post_|create_)"
+    fix_suggestion: "Use async def for handlers"
+```
+
+**The killer feature: auto-detection.** Run `codebase-intel detect-patterns --save` and it scans your codebase to find patterns you already follow:
+
+```
+┏━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
+┃ # ┃ Pattern                ┃ Confidence ┃ Follows ┃ Violates ┃
+┡━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
+│ 1 │ Async handlers         │       100% │      46 │        0 │
+│ 2 │ Layer separation       │        96% │     132 │        5 │
+│ 3 │ Service class naming   │        90% │      35 │        0 │
+│ 4 │ Custom exceptions      │       100% │      47 │        0 │
+│ 5 │ Docstring convention   │        88% │     793 │      108 │
+└───┴────────────────────────┴────────────┴─────────┴──────────┘
+```
+
+Zero manual contract writing. The tool discovers what your team already does and generates rules from it.
+
+### 3. Drift Detection
+
+Context rots. Decisions go stale. Code anchors point to deleted files. codebase-intel detects this:
+
+```bash
+$ codebase-intel drift
+
+Overall: MEDIUM
+- Decision DEC-012 anchored to deleted file
+- Decision DEC-008 is past its review date
+- 2 files changed since last graph index
+```
+
+## The Benchmarks
+
+Tested on 4 production codebases:
+
+| Project | Without Tool | With codebase-intel | Reduction | Decisions Surfaced |
+|---|---:|---:|---:|---:|
+| FastAPI monolith (359 files) | 16,063 tokens | 5,955 tokens | **63%** | 13 |
+| Microservice A (358 files) | 14,611 | 5,955 | **59%** | 0 |
+| Microservice B (153 files) | 5,904 | 1,476 | **75%** | 0 |
+
+The token reduction is nice. But the real value is the **13 decisions surfaced** — those are constraints, trade-offs, and rejected alternatives that would have been invisible to the agent.
+
+## How It Works
+
+```
+AI Agent → MCP Server → Context Orchestrator
+                              ↓
+                    ┌─────────┼─────────┐
+                    ↓         ↓         ↓
+              Code Graph  Decisions  Contracts
+              (19 langs)  (git-mined) (auto-detected)
+                    ↓         ↓         ↓
+                    └─────────┼─────────┘
+                              ↓
+                        Drift Detector
+```
+
+The agent asks "what do I need to know to work on this file?" and gets:
+- Relevant files (from the code graph)
+- Applicable decisions (linked to this code area)
+- Quality rules to follow
+- Warnings about stale context
+
+All fitted within a token budget, prioritized by relevance.
+
+## Getting Started
+
+```bash
+pip install codebase-intel
+cd your-project
+codebase-intel init              # build graph, mine decisions
+codebase-intel detect-patterns --save  # auto-generate contracts
+codebase-intel benchmark         # see before/after numbers
+```
+
+For Claude Code, add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "codebase-intel": {
+      "command": "codebase-intel",
+      "args": ["serve", "/path/to/project"]
+    }
+  }
+}
+```
+
+## It's Not a Competition
+
+Tools like code-review-graph (6.3K stars) are excellent for code graphs. Cursor and Copilot are great for autocomplete. We don't replace any of them.
+
+We fill the gap none of them address: **why does this code exist, what rules must AI follow, and is the context still valid?**
+
+## What I'd Love Feedback On
+
+1. What patterns should the auto-detector look for in your stack?
+2. What quality rules would you want enforced in your project?
+3. Are there decision types we're missing?
+
+**GitHub:** [MutharasuArchunan13/codebase-intel](https://github.com/MutharasuArchunan13/codebase-intel)
+**PyPI:** `pip install codebase-intel`
+**License:** MIT
+
+---
+
+*Built with Python, tree-sitter, SQLite, and MCP. 10K+ lines of source, 595 tests, 19 languages supported.*

codebase_intel-0.2.0/launch/hackernews.md

@@ -0,0 +1,40 @@
+# Hacker News — Show HN
+
+**Post URL:** https://news.ycombinator.com/submitlink
+
+**Title (max 80 chars):**
+Show HN: codebase-intel – Your AI agent doesn't know why your code exists
+
+**URL:**
+https://github.com/MutharasuArchunan13/codebase-intel
+
+**Text (paste this in the comment immediately after posting):**
+
+Hi HN,
+
+I've been using AI coding agents (Claude Code, Copilot, Cursor) daily across 11 production services. They're fast — but they keep making the same mistakes:
+
+- Proposing solutions my team already evaluated and rejected 6 months ago
+- Ignoring compliance constraints that shaped our auth system
+- Writing patterns that don't match our project's conventions
+- Not knowing that changing a config file will break billing AND analytics
+
+The root cause: agents know WHAT code exists, but not WHY it exists.
+
+I built codebase-intel to fix this. It's an open-source context layer that sits between your codebase and any AI agent (via MCP), providing:
+
+1. **Decision Journal** — Records of why decisions were made, auto-mined from git history, linked to specific code locations. When an agent touches rate limiting, it sees: "We chose token bucket over sliding window because memory overhead at scale. SLA: <2ms p99."
+
+2. **Quality Contracts** — Executable rules AI must follow. Not just linting — project-specific architectural patterns. Includes AI anti-pattern detection (hallucinated imports, over-abstraction, YAGNI).
+
+3. **Auto-Contract Generation** — Scans your codebase and detects patterns automatically. On a FastAPI backend it found: 100% async handlers, 96% layer separation, service naming conventions — and generated rules from them.
+
+4. **Feedback Loop** — Tracks whether AI output was accepted or rejected, maps rejection reasons to improvements. No other tool closes this loop.
+
+Benchmarked on 4 production projects: 48-75% token reduction + decisions surfaced + contracts enforced.
+
+Technical: Python, tree-sitter (19 languages), SQLite, MCP server, 595 tests.
+
+Install: `pip install codebase-intel`
+
+Would love feedback on the approach. The comparison with existing tools is at docs/COMPARISON.md — tried to be honest about what others do well and where we fit.

codebase_intel-0.2.0/launch/reddit_claudeai.md

@@ -0,0 +1,68 @@
+# r/ClaudeAI Post
+
+**Subreddit:** r/ClaudeAI
+
+**Title:**
+I built an MCP server that gives Claude Code something no other tool does — it tells Claude WHY your code exists
+
+**Body:**
+
+Been using Claude Code daily across 11 production services. Claude is incredible at writing code, but it keeps:
+
+- Proposing approaches my team already rejected
+- Missing compliance constraints
+- Not knowing what else breaks when it changes a file
+- Over-engineering things (base classes with one subclass, error handling for impossible conditions)
+
+So I built **codebase-intel** — an MCP server that gives Claude structured context before it writes code.
+
+## What Claude gets from codebase-intel
+
+When you ask Claude to work on a file, the MCP server provides:
+
+1. **Relevant files** — not the whole project, just what's connected (graph-based, 48-75% fewer tokens)
+2. **Decisions** — "Your team chose token bucket over sliding window. Here's why. SLA: <2ms p99."
+3. **Quality rules** — "This project uses async for all handlers. Don't use sync. All DB access goes through repositories."
+4. **Drift warnings** — "Decision DEC-012 references a deleted file. Verify before following."
+
+## MCP setup (30 seconds)
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "codebase-intel": {
+      "command": "codebase-intel",
+      "args": ["serve", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+## Unique feature: auto-detects your patterns
+
+```bash
+codebase-intel detect-patterns --save
+```
+
+Scanned a FastAPI backend and found:
+- 100% async handlers
+- 96% layer separation (routes don't touch DB directly)
+- Service class naming convention (XxxService)
+- Custom exception handling everywhere
+
+Generated contract rules from these automatically. Now Claude follows them.
+
+## Install
+
+```bash
+pip install codebase-intel
+codebase-intel init
+```
+
+**GitHub:** https://github.com/MutharasuArchunan13/codebase-intel
+
+7 MCP tools: `get_context`, `query_graph`, `get_decisions`, `get_contracts`, `check_drift`, `impact_analysis`, `get_status`
+
+What other MCP tools would be useful for your Claude Code workflow?

codebase_intel-0.2.0/launch/reddit_python.md

@@ -0,0 +1,48 @@
+# r/Python Post
+
+**Subreddit:** r/Python
+**Flair:** Showcase
+**Post type:** Text post
+
+**Title:**
+codebase-intel — gives AI coding agents decision provenance, quality contracts, and drift detection
+
+**Body:**
+
+## What My Project Does
+
+codebase-intel is an open-source Python tool that provides AI coding agents with structured context via MCP (Model Context Protocol). Instead of just telling an agent what code exists, it tells the agent:
+
+- **Why code exists** — Decision records auto-mined from git history, linked to specific file locations. Example: "We chose token bucket over sliding window because of memory overhead at scale. SLA constraint: <2ms p99 latency."
+- **What rules to follow** — Quality contracts that enforce project-specific patterns before code is generated. Includes AI-specific anti-pattern detection (hallucinated imports, over-abstraction, YAGNI violations).
+- **What's stale** — Drift detection that catches when decisions reference deleted files, expired constraints, or outdated code anchors.
+
+It also auto-detects patterns in your codebase (`codebase-intel detect-patterns`) and generates quality rules from them — zero manual setup. On a 359-file FastAPI project, it detected 100% async handler usage, 96% layer separation, and service naming conventions automatically.
+
+Built with: Python 3.11+, Pydantic v2, tree-sitter-language-pack (19 languages), SQLite, MCP server, tiktoken. 595 tests.
+
+Install: `pip install codebase-intel`
+
+GitHub: https://github.com/MutharasuArchunan13/codebase-intel
+
+## Target Audience
+
+Production use. Built for developers who use AI coding agents (Claude Code, Cursor, Copilot) on real projects with established patterns, architectural decisions, and compliance requirements. Most useful for teams working on microservices, FastAPI backends, or any codebase where "why" matters as much as "what."
+
+Not a toy project — benchmarked on 4 production codebases with 48-75% token reduction and architectural decisions surfaced that agents would have missed.
+
+## Comparison
+
+**vs code-review-graph (6.3K stars):** code-review-graph builds an excellent code graph for blast-radius analysis during reviews. codebase-intel also has a code graph (19 languages) but adds three layers code-review-graph doesn't have: decision journal (why code exists), quality contracts (rules AI must follow), and drift detection (is context still valid). They're complementary — you can use both.
+
+**vs Aider:** Aider uses a repo-map for context. No persistent decisions, no quality enforcement, no drift detection. Different focus — Aider is a coding assistant, codebase-intel is a context layer for any assistant.
+
+**vs Cursor/Copilot:** These use RAG-based indexing (text chunk retrieval). No decision provenance, no architectural contracts, no auto-pattern detection. Closed ecosystems. codebase-intel is open-source and agent-agnostic via MCP.
+
+**vs adr-tools/Log4brains:** These manage Architecture Decision Records manually. codebase-intel auto-mines decisions from git, links them to code locations, makes them queryable by AI agents via MCP, and detects when they go stale. Different generation of tooling.
+
+**Unique features no alternative has:**
+- Auto-contract generation from detected codebase patterns
+- Feedback loop tracking AI output acceptance/rejection
+- AI-specific anti-pattern detection (hallucinated imports, over-abstraction)
+- Live efficiency dashboard with reproducible benchmarks