Auto-Context

Local-first, relevance-filtered architecture context injection for Spec Kit and Claude Code.

What is Auto-Context?

Auto-Context automatically injects relevant architecture documentation into your development workflow. It:

• Detects your current scope (feature branch, Spec Kit feature, or git diff)
• Filters architecture docs by relevance (tags, file paths, keywords)
• Respects token budgets (drops low-priority items when limits are exceeded)
• Caches deterministically (no LLM in the hot path, content-addressed cache)
• Integrates with Spec Kit hooks (before_specify, before_clarify, before_plan, before_implement)

Installation

Prerequisites

• Python 3.11+
• Spec Kit (for hook integration)
• Claude Code (optional, for SessionStart hook)

Install the Extension

specify extension add auto-context

This installs the extension and:

• Creates auto-context.yml configuration file
• Adds cache directories to .gitignore
• Sets up Spec Kit hooks

Claude Code Integration (Optional)

Add a SessionStart hook to warm the cache before your first prompt:

# In .claude/settings.local.json
{
  "hooks": {
    "SessionStart": [
      {
        "command": "auto-context refresh --quiet"
      }
    ]
  }
}

Quick Start

1. Create Architecture Context Files

Add markdown files with YAML frontmatter to .specify/context/:

---
id: system/overview
tier: system
title: System Overview
summary: One-paragraph description of the system.
---

# System Overview

Your system documentation here...

2. Define Scope with Tags

---
id: component/billing
tier: component
title: Billing Service
summary: Handles invoice issuance and Stripe webhooks.
keywords:
  - billing
  - stripe
  - invoices
applies_to:
  - apps/billing/**
---

3. Refresh the Index

auto-context refresh

4. View Context for Current Scope

auto-context show

Commands

Command	Description
auto-context refresh	Re-index sources and rebuild cache
auto-context show	Display context bundle for current scope
auto-context scope show|set|clear|detect	Inspect or override detected scope
auto-context add <id>	Scaffold a new context source file
auto-context doctor	Self-check: config + sources + cache

Configuration

Edit .specify/auto-context.yml to customize:

budgets:
  profile: default  # or 'minimal' for large repos
  profiles:
    default:
      total_tokens: 4000
      tier_limits:
        system: 800
        component: 2400
        patterns: 800

scope:
  max_files: 200
  diff_base: main

Documentation

For detailed documentation, see .specify/extensions/auto-context/README.md which includes:

• Complete command reference with exit codes
• Hook integration details
• Graceful degradation matrix
• Development setup and testing

Development

# Setup
python -m venv .venv
.venv/bin/pip install -e ".specify/extensions/auto-context[dev]"

# Tests
.venv/bin/python -m pytest .specify/extensions/auto-context/

# Lint
.venv/bin/black .specify/extensions/auto-context/
.venv/bin/ruff check .specify/extensions/auto-context/

License

MIT License - see LICENSE for details.

Status

v0.1.0 — Phase 3 US1 MVP complete. See specs/001-auto-context/ for full specification and task ledger.