Setup — 2 Commands

pip install context-lineage
ctx setup src/

That's it. Claude Code, Cursor, and other coding agents receive a compact command index (~219 tokens). It tells them when to run ContextLineage for live, AST-grounded pointers instead of loading a stale module dump into every session.

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 as actionable file:line pointers — giving agents the exact 20–50 lines they need to inspect directly from source.

What's Under the Hood

Your Python Codebase
        ↓
   ctx setup src/
        ↓
┌─────────────────────────────────────────┐
│  1. AST Dependency & Call Graph         │  Who calls what, what imports what
│  2. Pointer-First Navigation            │  Exact file.py:L1-L2 targets (ctx query -p)
│  3. Docstring Frontmatter Governance    │  Zero-drift CI/CD verification (ctx validate / ctx sync)
│  4. Anti-Hallucination Verifier         │  verify_claim checks facts before writing code
└─────────────────────────────────────────┘
        ↓
   CLAUDE.md / .cursorrules / AGENTS.md
        ↓
Claude Code / Cursor / Devin / Antigravity / Any Agent

2-Step Agent Navigation Workflow

[Agent Query]  →  ctx query symbol <name> -p  →  Returns: "engine.py:38-99 (process_claim)"
     ↓
[Targeted Read] →  Agent reads ONLY lines 38-99  →  100% verified correctness, 92% token savings

Key CLI Commands

# 1. Pointer-first navigation (find exact file and line ranges)
ctx query symbol OrchestratorEngine.process_claim -d src/ -p

# 2. Trace call chains through your codebase with line pointers
ctx query lineage pipeline.orchestrator -d src/ -p

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

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

# 5. Auto-sync docstring YAML frontmatter across the repo in one command
ctx sync src/

# 6. Check docstring drift in CI/CD (exits 1 if drift found)
ctx validate src/

Real-World Benchmark

Evaluated against an enterprise orchestration service:

→ Full benchmark details · Comparison Report

Frequently Asked Questions

Have questions about how ContextLineage compares to Graphify, Tree-sitter tools, or how CI/CD governance works?

→ Read the FAQ (Frequently Asked Questions)

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=3000)
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=3000)
packed = packer.pack_for_task("trace_dataflow", "pipeline.orchestrator")
prompt = f"Codebase context:\n{packed.to_markdown()}\n\nTask: {user_task}"

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.