🧠 AI Code Context Graph

A plug-and-play persistent knowledge graph that gives AI coding tools memory, trust scores, and team awareness.

Track AI-generated code across tools (Cursor, Copilot, Antigravity, Claude), detect anti-patterns, enforce quality gates in CI/CD, and monitor everything from a real-time dashboard.

---

✨ Key Features

Feature	Description
Knowledge Graph	SQLite-backed graph of your codebase: files, functions, classes, imports, dependencies
AI Attribution	Automatically detects which AI tool generated each piece of code (via git history)
Trust Scores	0–100 trust score per file with letter grades (A–F)
Anti-Pattern Detection	7 built-in checks: hardcoded secrets, SQL injection, eval(), missing error handling, etc.
Team Patterns	Learns your team's conventions (type hints, testing frameworks, logging practices)
REST API	Local FastAPI server on localhost:7878 — any tool can query context
GitHub Actions	Drop-in CI workflow: scan PRs, post quality reports, block low-trust code
Web Dashboard	Next.js dashboard with real-time trust scores, anti-pattern charts, AI tool comparison
Git Hooks	Auto-installed post-commit + pre-push hooks for continuous tracking

---

🚀 Quick Start

# Install
pip install ai-code-context  # or: pip install -e .

# Initialize in your repo
cd your-project/
ai-context init

# Start the API daemon
ai-context start

# Run analysis
ai-context analyze

# Scan for anti-patterns
ai-context scan

After ai-context init, the tool will:

1. Create .ai-context/ directory with graph.db and config.yml
2. Install git hooks (post-commit, pre-push)
3. Scan your codebase and build the knowledge graph
4. Detect AI tools and scan git history for AI-generated commits

---

📋 CLI Commands

Command	Description
ai-context init	Initialize AI Context in your repository
ai-context start	Start the local API daemon (port 7878)
ai-context stop	Stop the daemon
ai-context analyze	Analyze codebase and build/update the knowledge graph
ai-context scan	Scan for anti-patterns and show trust score report
ai-context score [file]	Show trust score for a specific file or all files
ai-context log-decision	Log an architectural decision to the graph
ai-context status	Show current status (graph stats, daemon, detected tools)

Example: Scan output

🤖 AI Code Quality Report

  Repository Trust Score: 74/100 ⚠️
  Grade: C | Files: 42 | High Risk: 3

  ┌──────────┬──────────────────────┬──────────────────┬──────┬─────────────────────────────┐
  │ Severity │ Type                 │ File             │ Line │ Message                     │
  ├──────────┼──────────────────────┼──────────────────┼──────┼─────────────────────────────┤
  │ HIGH     │ HARDCODED_SECRET     │ src/config.py    │ 12   │ Hardcoded secret detected   │
  │ HIGH     │ SECURITY_VULNERABILITY│ src/utils.py    │ 45   │ eval() usage detected       │
  │ MEDIUM   │ NO_ERROR_HANDLING    │ src/api/handler  │ 23   │ Async function without try  │
  └──────────┴──────────────────────┴──────────────────┴──────┴─────────────────────────────┘

---

🌐 REST API

Start the daemon and query context from any tool:

ai-context start

Endpoint	Method	Description
/health	GET	Health check with graph stats
/context?file=path	GET	Full context bundle for a file
/scores?file=path	GET	Trust scores
/scan	GET	Full anti-pattern scan
/commit	POST	Track a commit (called by git hook)
/track	POST	Track an AI-generated change
/decision	POST	Log an architectural decision
/dashboard	GET	Full dashboard data
/activity	GET	Recent activity feed
/tools	GET	Detected AI tools
/analyze	POST	Trigger full codebase analysis

Example API call

curl http://127.0.0.1:7878/context?file=src/auth/login.py

{
  "file": "src/auth/login.py",
  "trust_score": 72,
  "ai_sessions": [
    {"tool": "cursor", "timestamp": "2024-01-15T10:30:00Z"}
  ],
  "related_files": ["src/auth/utils.py", "src/models/user.py"],
  "patterns": ["Type annotations", "Structured logging"]
}

---

🎯 Trust Scoring

Score = 100 – Deductions + Boosts

Deductions (anti-patterns found)

Check	Severity	Points
Hardcoded secrets	HIGH	-30
SQL injection	HIGH	-30
Security vulnerabilities (eval, pickle)	HIGH	-30
Missing error handling	MEDIUM	-15
TODO/FIXME placeholders	MEDIUM	-15
Missing edge case handling	MEDIUM	-15
Generic variable names	LOW	-5

Boosts (good practices found)

Practice	Points
Has tests	+10
Type annotations	+5
Error handling (try/except)	+10
Follows team patterns	+15

Grades

Score	Grade
90–100	A
80–89	B
70–79	C
60–69	D
0–59	F

---

🔄 GitHub Actions

Option 1: Reusable workflow

# .github/workflows/ai-quality.yml
name: AI Quality Check
on:
  pull_request:
    branches: [main]

jobs:
  quality:
    uses: ./.github/workflows/ai-quality-check.yml
    with:
      min_trust_score: 60
      block_on_failure: true

Option 2: Composite action

- uses: ai-code-context/action@v1
  with:
    min-trust-score: 60
    block-on-failure: true

PR comments will include:

• Overall trust score with letter grade
• Critical issues with fix suggestions
• Low-trust file list
• AI tool attribution

---

📊 Web Dashboard

cd dashboard/
npm install
npm run dev

Visit http://localhost:3001 for the live dashboard.

The dashboard includes:

• Trust Score Overview — repo-wide score with trend
• High-Risk Code — files needing immediate attention
• Anti-Patterns — horizontal bar chart of detected issues
• AI Tool Comparison — side-by-side scores per tool
• Activity Feed — recent commits and AI sessions
• Team Patterns — learned coding conventions

Dashboard auto-connects to the API daemon. Falls back to demo data if the daemon isn't running.

---

📁 Project Structure

ai-code-context-graph/
├── ai_code_context/           # Core Python package
│   ├── graph/
│   │   ├── engine.py          # SQLite knowledge graph
│   │   └── queries.py         # High-level graph queries
│   ├── analyzers/
│   │   ├── parser.py          # Code analysis engine
│   │   └── patterns.py        # Team pattern detection
│   ├── tracking/
│   │   ├── git_tracker.py     # Git commit tracking + AI attribution
│   │   └── ai_detector.py     # AI tool detection
│   ├── scoring/
│   │   ├── trust_calculator.py # Trust score algorithm
│   │   └── anti_patterns.py   # Anti-pattern detection engine
│   ├── api/
│   │   └── server.py          # FastAPI REST API
│   ├── cli.py                 # Click CLI
│   ├── config.py              # Configuration management
│   └── hooks.py               # Git hook installer
├── dashboard/                 # Next.js web dashboard
│   ├── app/
│   │   ├── page.js            # Main dashboard page
│   │   ├── layout.js          # Root layout
│   │   └── globals.css        # Dark theme CSS
│   └── components/            # React components
├── github-actions/            # GitHub Actions integration
│   ├── ai-quality-check.yml   # Reusable workflow
│   └── action.yml             # Composite action
├── tests/
│   └── test_core.py           # Test suite
└── pyproject.toml             # Python package config

---

⚙️ Configuration

After ai-context init, edit .ai-context/config.yml:

# Scanning
exclude_patterns:
  - "*.min.js"
  - "vendor/*"

# Trust thresholds
min_trust_score: 60
block_below_score: true

# AI tool markers (customize per team)
ai_tool_markers:
  cursor: ["cursor", "Cursor"]
  copilot: ["Co-authored-by: GitHub Copilot"]

# API
api_port: 7878
api_host: "127.0.0.1"

---

🧪 Testing

pip install -e ".[dev]"
pytest tests/ -v

---

📄 License

MIT