Setup — 2 Commands

pip install context-lineage
ctx setup src/

That's it. Claude Code, Cursor, and any other AI coding tool on your project will now automatically read a structured map of your codebase instead of guessing from raw source files.

Commit the generated files so every developer and every AI session uses them:

git add CLAUDE.md AGENTS.md .cursorrules
git commit -m "chore: add ContextLineage AI context"

What ctx setup generates

Why This Exists

AI coding agents fail on real codebases in two ways:

Context Overflow — Dumping all source files into the prompt burns 50,000+ tokens per turn, runs up huge API bills, and causes LLM reasoning to degrade ("Lost in the Middle" effect).

Context Starvation — Reading only file names or unstructured docs causes agents to hallucinate non-existent functions, reversed caller/callee directions, and phantom circular dependencies.

ContextLineage fixes both. It builds a structured AST knowledge graph of your codebase and serves it progressively — giving agents exactly what they need, nothing more.

What's Under the Hood

Your Python Codebase
        ↓
   ctx setup src/
        ↓
┌─────────────────────────────────────────┐
│  1. AST Dependency & Call Graph         │  Who calls what, what imports what
│  2. 4-Tier Progressive Disclosure       │  Overview → Summaries → Symbols → Source
│  3. Anti-Hallucination Verifier         │  verify_claim checks facts before writing
└─────────────────────────────────────────┘
        ↓
   CLAUDE.md / .cursorrules / AGENTS.md
        ↓
Claude Code / Cursor / Devin / Any Agent

Progressive Disclosure (how tokens are saved)

Additional CLI Commands

# Auto-fix docstring drift when your code changes
ctx validate src/ --fix

# Verify a claim before writing code (prevents hallucinations)
ctx verify "run_pipeline calls extract_data" -d src/

# Understand impact before refactoring
ctx query impact pipeline.stages.extract -d src/

# Trace call chains through your codebase
ctx query lineage pipeline.orchestrator -d src/

# Manually regenerate context files at any time
ctx setup src/

Python API

from pathlib import Path
from contextlineage.agent_skill import create_code_explorer_skill
from contextlineage.context_packer import create_context_packer

skill = create_code_explorer_skill(Path("src/"), token_budget=8000)
skill.initialize()

# Verify a claim against AST ground truth
result = skill.verify_claim("run_pipeline calls extract_data")
# → {"verified": True, "confidence": 0.95, "evidence": ["AST verified: ..."]}

# Pack context for LLM prompt injection
packer = create_context_packer(skill, max_tokens=8000)
packed = packer.pack_for_task("trace_dataflow", "pipeline.orchestrator")
prompt = f"Codebase context:\n{packed.to_markdown()}\n\nTask: {user_task}"

Real-World Benchmark

Evaluated on a 17-module real-world codebase:

Anti-hallucination accuracy: 100% (6/6 true and false claims correctly classified by AST).

→ Full benchmark details

LangChain & CrewAI

# LangChain
from contextlineage.integrations.langchain import FrontmatterLoader, FrontmatterRetriever
loader = FrontmatterLoader("manifest.json")
retriever = FrontmatterRetriever(loader.manifest, k=5, token_budget=8000)

# CrewAI
from contextlineage.integrations.crewai import create_frontmatter_tools
tools = create_frontmatter_tools("manifest.json")
agent = Agent(role="Code Explorer", tools=tools)

dbt Support (Coming Soon)

ContextLineage is expanding to dbt SQL/Jinja models — parsing {{ ref() }} and {{ source() }} DAGs, extracting column contracts from schema.yml, and providing the same progressive disclosure for dimensional modeling projects.

→ dbt Architecture Specification

Contributing

git clone https://github.com/swapnilwaramwar/ContextLineage.git
cd ContextLineage
pip install -e ".[dev]"
pytest tests/

See CONTRIBUTING.md for guidelines.