contextgit

Requirements traceability for LLM-assisted software development

🌐 Official Website: contextgit.com

contextgit is a local-first, git-friendly CLI tool that maintains bidirectional traceability between business requirements, system specifications, architecture decisions, source code, and tests. Designed specifically for integration with Claude Code and similar LLM development assistants.

Why contextgit?

Traditional requirement management is slow and manual. contextgit makes it 1,355× faster with:

🔍 Instant requirement searches (12.5 min → 0.5 sec)
🔗 Automatic staleness detection (prevents $1,200-2,000 rework per incident)
📊 94% context reduction for LLM prompts (6,000 → 375 tokens)
⚡ 5-10× faster PR reviews with structured metadata
💰 Time savings: Sub-second searches vs 12+ minutes manual (see methodology)

Based on real-world measurements from dogfooding contextgit on itself.

Features

✨ Core Capabilities

Traceability Graph: Track relationships from business needs → system specs → architecture → code → tests
Staleness Detection: Automatically detect when upstream requirements change via checksum comparison
Precise Context Extraction: Extract only relevant requirements for LLM consumption
Bidirectional Links: Automatically maintain upstream/downstream relationships
Impact Analysis: Analyze downstream effects of requirement changes (v1.2+)
Circular Dependency Detection: Validate link integrity (v1.2+)

🎯 LLM-Optimized

JSON output for all commands (--format json)
Sub-second requirement searches
Extract command for precise context snippets
Designed for Claude Code workflows
MCP Server: Native Model Context Protocol integration for Claude Desktop (v1.2+)

🛠️ Developer-Friendly

Git-Friendly: Metadata in Markdown YAML frontmatter and HTML comments
Local-First: All data in .contextgit/requirements_index.yaml - no network calls
Deterministic Output: Sorted YAML for clean git diffs
Atomic Operations: Never corrupts index file
Git Hooks: Automatic scanning on commit/merge (v1.2+)
Watch Mode: Real-time file monitoring (v1.2+)

📁 Multi-Format Support (v1.2+)

Markdown (.md) - YAML frontmatter and HTML comments
Python (.py) - Docstrings and comment blocks
JavaScript/TypeScript (.js, .ts, .jsx, .tsx) - JSDoc blocks

Installation

Option 1: PyPI (Recommended)

pip install contextgit

# With optional features (v1.2+)
pip install contextgit[watch]     # Watch mode (file monitoring)
pip install contextgit[mcp]       # MCP server for Claude Desktop
pip install contextgit[all]       # All optional features

Option 2: From Source

git clone https://github.com/Mohamedsaleh14/ContextGit.git
cd ContextGit
pip install -e .

Option 3: Ubuntu/Debian Package

# Download the .deb package from releases
wget https://github.com/Mohamedsaleh14/ContextGit/releases/download/v1.2.0/contextgit_1.2.0_all.deb

# Install
sudo dpkg -i contextgit_1.2.0_all.deb

Verify Installation

contextgit --help

Quick Start

# 1. Initialize a contextgit repository (with LLM integration)
contextgit init --setup-llm

# This creates:
# - .contextgit/config.yaml
# - .contextgit/requirements_index.yaml
# - .contextgit/LLM_INSTRUCTIONS.md  ← LLM reads this
# - .cursorrules                      ← Cursor auto-detects
# - CLAUDE.md                         ← Claude Code auto-detects

# 2. Add metadata to your Markdown files
cat > docs/requirements.md << 'EOF'
---
contextgit:
  id: auto
  type: business
  title: User authentication
  status: active
---

# User Authentication

Users must be able to log in with email and password.
EOF

# 3. Scan files to build the index
contextgit scan docs/ --recursive

# 4. Check repository status
contextgit status

# 5. View requirement details
contextgit show BR-001

# 6. Extract requirement text for LLM
contextgit extract BR-001

Next Steps: See the User Guide for complete workflows and examples.

Core Commands

Initialization and Scanning

contextgit init                      # Initialize repository
contextgit init --setup-llm          # Initialize + create LLM integration files
contextgit scan docs/ --recursive    # Scan for metadata
contextgit scan --dry-run            # Preview changes

Querying and Inspection

contextgit status                    # Show project health
contextgit status --stale            # Show stale requirements
contextgit show SR-010               # Show node details
contextgit extract SR-010            # Extract requirement text
contextgit relevant-for-file src/auth.py  # Find related requirements

Linking and Synchronization

contextgit link BR-001 SR-010 --type refines  # Create manual link
contextgit confirm SR-010                     # Mark as synchronized

Utilities

contextgit next-id system            # Generate next ID (SR-001)
contextgit fmt                       # Format index for git
contextgit show SR-010 --format json # JSON output for LLMs

Validation and Analysis (v1.2+)

contextgit validate docs/ --recursive  # Validate metadata without modifying index
contextgit impact SR-010               # Show downstream impact analysis
contextgit impact SR-010 --format json # JSON output for CI/CD

Automation (v1.2+)

contextgit hooks install             # Install git hooks (pre-commit, post-merge)
contextgit hooks status              # Check hook installation status
contextgit hooks uninstall           # Remove git hooks
contextgit watch docs/               # Watch for file changes (requires watchdog)

MCP Server (v1.2+)

contextgit mcp-server                # Start MCP server for Claude Desktop

Metadata Format

contextgit supports two metadata formats in Markdown files:

YAML Frontmatter (Recommended)

---
contextgit:
  id: auto
  type: system
  title: User authentication system
  status: active
  upstream: [BR-001]
  downstream: [AR-005, C-020]
  tags: [security, auth]
---

# System Requirement: User Authentication

The system shall provide secure user authentication...

HTML Comments (Inline)

<!-- contextgit
id: auto
type: system
title: User authentication system
status: active
upstream: [BR-001]
-->

## User Authentication

The system shall provide secure user authentication...

Python Docstrings (v1.2+)

"""
contextgit:
  id: C-001
  type: code
  title: Authentication module
  upstream: [SR-010]
"""

def authenticate(email: str, password: str) -> bool:
    ...

JavaScript/TypeScript JSDoc (v1.2+)

/**
 * @contextgit
 * id: C-002
 * type: code
 * title: Login handler
 * upstream: [SR-010]
 */
export function handleLogin(req, res) {
    ...
}

Node Types and Prefixes

Type	Prefix	Purpose
`business`	BR-	Business requirements, user needs
`system`	SR-	System-level functional specs
`architecture`	AR-	Architecture decisions, ADRs
`code`	C-	Code implementation notes
`test`	T-	Test specifications
`decision`	ADR-	Design decisions

LLM Integration (Cursor & Claude Code)

contextgit is designed for seamless integration with LLM development tools.

Automatic Setup (Recommended)

contextgit init --setup-llm

This creates all LLM integration files automatically:

File	Purpose
`.contextgit/LLM_INSTRUCTIONS.md`	Comprehensive guide for any LLM (~5KB)
`.cursorrules`	Cursor IDE auto-detection
`CLAUDE.md`	Claude Code auto-detection

How it works:

Cursor reads .cursorrules → knows to use contextgit
Claude reads CLAUDE.md → knows to use contextgit
Both are directed to LLM_INSTRUCTIONS.md for full details

Common Commands

# Get precise context for implementing a requirement
contextgit extract SR-010 --format json

# Find all requirements affecting a file
contextgit relevant-for-file src/auth.py --format json

# Check for stale requirements before making changes
contextgit status --stale

# After updating code, rescan and confirm synchronization
contextgit scan src/ --recursive
contextgit confirm SR-010

All commands support --format json for easy parsing by LLMs.

See: User Guide - LLM Integration | LLM Integration Guidelines

Real-World Performance

Based on objective measurements from dogfooding:

Metric	Manual	With contextgit	Improvement
Requirement search	12.5 min	0.55 sec	1,355× faster
Staleness detection	30-60 min	<1 sec	1,800-3,600× faster
PR review time	3-5 min	30-60 sec	5-10× faster
Context extraction	Manual copy	Automated	14-29 min saved/task

Verified Benefits: 87-90% token reduction, sub-second requirement searches

See: Full Performance Evaluation (includes methodology and assumptions)

Documentation

Getting Started

📖 User Guide - Complete guide with workflows and examples
🚀 Quick Start - Get up and running in 5 minutes
💡 LLM Integration - Using with Claude Code

Design Documents

Product Overview - Vision and problem statement
User Stories - Detailed usage scenarios
System Requirements - Functional requirements
Architecture - System design
Data Model - Schemas and file formats
CLI Specification - Command reference
MVP Scope - Current and planned features

Implementation

Performance Evaluation - Real-world measurements and ROI
Implementation Complete - Architecture and modules

Requirements

Python: 3.11 or higher
Core Dependencies:
- typer >= 0.9.0 (CLI framework)
- rich >= 13.0.0 (terminal output)
- ruamel.yaml >= 0.18.0 (YAML handling)
Optional Dependencies (v1.2+):
- watchdog >= 3.0.0 (watch mode - pip install contextgit[watch])
- mcp >= 0.1.0 (MCP server - pip install contextgit[mcp])
- pydantic >= 2.0.0 (MCP schemas - included with mcp)

Development

# Clone repository
git clone https://github.com/Mohamedsaleh14/ContextGit.git
cd ContextGit

# Install in development mode
pip install -e .

# Run import validation
python3 test_imports.py

# Run system verification
python3 verify_system.py

# Check CLI help
python3 -m contextgit --help

Project Structure

contextgit/
├── cli/          # Typer command definitions
├── handlers/     # Command handlers (InitHandler, ScanHandler, etc.)
├── domain/       # Core domain (IndexManager, MetadataParser, LinkingEngine, etc.)
├── infra/        # Infrastructure (FileSystem, YAMLSerializer, OutputFormatter)
├── models/       # Data models (Node, Link, Index, Config)
├── scanners/     # File format scanners (v1.2+: Markdown, Python, JavaScript)
└── mcp/          # MCP server implementation (v1.2+)

Architecture: 4-layer design (CLI → Handlers → Domain → Infrastructure)

Contributing

Contributions are welcome! This is an MVP with many opportunities for enhancement.

How to Contribute

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with clear commit messages
Push to your fork (git push origin feature/amazing-feature)
Open a Pull Request

Areas for Contribution

VS Code extension
Additional file formats (ReStructuredText, AsciiDoc)
Performance optimization (daemon mode, lazy loading)
CI/CD integrations (GitHub Action, GitLab CI template)
Coverage reporting and analytics

See: MVP Scope and Future Work

Roadmap

Phase 1: MVP ✅ (v1.0 - Complete)

All 10 CLI commands
Metadata parsing (YAML frontmatter + HTML comments)
Traceability graph with staleness detection
JSON output for LLM integration
Git-friendly YAML output

Phase 1.2: Enhanced Features ✅ (v1.2 - Complete)

Multi-format file support (Python, JavaScript/TypeScript)
Watch mode for auto-scanning
Git hooks integration (pre-commit, post-merge, pre-push)
Metadata validation command
Impact analysis command
MCP Server for Claude Desktop integration
Circular dependency detection
Enhanced link validation

Phase 2: IDE Integration (Planned)

VS Code extension
Daemon mode for performance
Parallel file scanning

Phase 3: Team Collaboration (Future)

CI integration (GitHub Action, GitLab CI)
Coverage reporting
Team analytics

See: Full Roadmap

License

MIT License - see LICENSE file for details.

Support This Project

Sponsored by: www.cronlytic.com

If you find contextgit useful, consider supporting its development:

Your support helps maintain and improve contextgit! ☕

Author & More Projects

Mohamed Saleh

I build tools for developers. contextgit is one of several open-source projects I maintain.

🌐 Visit my website: BySaleh.com

More open-source projects
Technical blog posts
Development tutorials
Contact information

Acknowledgments

Built with Typer for CLI, Rich for terminal output
Designed specifically for Claude Code integration
Inspired by the need for better requirements traceability in LLM-assisted development

Links

Official Website: https://contextgit.com
PyPI: https://pypi.org/project/contextgit/
Repository: https://github.com/Mohamedsaleh14/ContextGit
Issues: https://github.com/Mohamedsaleh14/ContextGit/issues
Releases: https://github.com/Mohamedsaleh14/ContextGit/releases
User Guide: USER_GUIDE.md
Performance Evaluation: PERFORMANCE_EVALUATION.md

Star History

If you find this project useful, please consider giving it a ⭐ on GitHub!

Made with ❤️ by Mohamed Saleh

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
.claude/agents		.claude/agents
.contextgit		.contextgit
contextgit		contextgit
debian-package		debian-package
design		design
docs		docs
examples		examples
tests		tests
.cursorrules		.cursorrules
.gitignore		.gitignore
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
USAGE_EXAMPLE.py		USAGE_EXAMPLE.py
USER_GUIDE.md		USER_GUIDE.md
pyproject.toml		pyproject.toml
test_imports.py		test_imports.py
test_yaml_serializer.py		test_yaml_serializer.py
verify_performance.sh		verify_performance.sh
verify_system.py		verify_system.py

License

Mohamedsaleh14/ContextGit

Folders and files

Latest commit

History

Repository files navigation

contextgit

Why contextgit?

Features

Installation

Option 1: PyPI (Recommended)

Option 2: From Source

Option 3: Ubuntu/Debian Package

Verify Installation

Quick Start

Core Commands

Initialization and Scanning

Querying and Inspection

Linking and Synchronization

Utilities

Validation and Analysis (v1.2+)

Automation (v1.2+)

MCP Server (v1.2+)

Metadata Format

YAML Frontmatter (Recommended)

HTML Comments (Inline)

Python Docstrings (v1.2+)

JavaScript/TypeScript JSDoc (v1.2+)

Node Types and Prefixes

LLM Integration (Cursor & Claude Code)

Automatic Setup (Recommended)

Common Commands

Real-World Performance

Documentation

Getting Started

Design Documents

Implementation

Requirements

Development

Project Structure

Contributing

How to Contribute

Areas for Contribution

Roadmap

Phase 1: MVP ✅ (v1.0 - Complete)

Phase 1.2: Enhanced Features ✅ (v1.2 - Complete)

Phase 2: IDE Integration (Planned)

Phase 3: Team Collaboration (Future)

License

Support This Project

Author & More Projects

Acknowledgments

Links

Star History

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Contributors 2

Languages

Packages