ai-context-cli

Repository: context-tool

This repository consolidates the previous context-ai and ai-context-cli workspaces into one clean Git repository while keeping the current Python package and CLI name: ai-context-cli / context.

ai-context-cli is a local command-line tool for turning a repository into reusable AI-ready context.

It scans a project, classifies files, applies read policies, scores relevance, persists the resulting context in a local .context/ workspace, and lets you reuse that data across documentation, inspection, export, snapshot, and diff workflows.

What It Does

Initializes a local .context/ workspace inside a repository.
Scans the codebase while respecting .gitignore and .contextignore.
Detects stack signals such as primary language, ecosystems, package managers, and entrypoints.
Builds a persisted current context snapshot with inventory, highlights, selected files, and warnings.
Reuses cached per-file analysis for faster incremental rescans.
Generates a technical CONTEXT.md document from the persisted context.
Saves named snapshots and compares them later with JSON diffs.

Why This Exists

LLM workflows often need a compact but trustworthy view of a repository rather than a raw dump of every file.

This tool tries to produce that view locally and deterministically:

broad enough to understand the project,
selective enough to avoid noise,
persistent enough to compare changes over time.

Installation

Quick Local Bootstrap

bash init.sh
.venv/bin/context --help

The bootstrap script:

creates .venv/ if it does not already exist,
upgrades pip,
installs the project in editable mode with dev dependencies.

Manual Installation

Requirements:

Python 3.11+

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e ".[dev]"

Quick Start

Initialize a repository once:

context init

Scan the repository and persist the active context:

context scan

Inspect the current persisted summary:

context inspect

Generate a technical Markdown document:

context auto-doc

Save a baseline and compare against later scans:

context save baseline
context scan
context diff save:baseline

Recommended Workflows

First-Time Setup

context init
context scan
context inspect

Generate Project Documentation

context scan
context auto-doc --force

Compare Repository State Over Time

context scan
context save baseline

# make changes in the repository

context scan
context diff save:baseline

Export Context for Another Tool

context scan
context export -o context-export.json

Command Reference

`context init [PATH]`

Create the .context/ workspace in the target directory.

Useful option:

--force: repairs recreatable base files if the workspace already exists.

`context scan`

Run a repository scan and persist the result as .context/current.json.

Useful options:

--no-history: skip writing an immutable history snapshot.
--full-rescan: ignore reusable cache entries for this run.

The command prints a concise operational summary including:

context_id
candidate file count
selected file count
scan duration
history status
cache hits and misses

`context inspect`

Inspect the persisted current context as JSON.

Examples:

context inspect
context inspect --path src/ai_context_cli/cli.py

`context auto-doc`

Render a technical Markdown document from the persisted current context.

Examples:

context auto-doc
context auto-doc -o docs/PROJECT_CONTEXT.md
context auto-doc --force

Default output file:

CONTEXT.md

`context export`

Export the persisted current context as JSON.

Examples:

context export
context export -o current-context.json
context export -o current-context.json --force

Current limitation:

only --from current is supported in this phase

`context history`

List persisted scan history as JSON.

Example:

context history --limit 5

`context save NAME`

Save the current persisted context under a stable name.

Example:

context save baseline

Current limitation:

only --from current is supported in this phase

Saved references are later addressed as save:NAME.

`context load SOURCE_REF`

Load a persisted reference into current.json.

Examples:

context load current
context load save:baseline

Supported references in this phase:

current
save:NAME

`context diff REF_A [REF_B]`

Compare two persisted context references and print a JSON diff.

Examples:

context diff save:baseline
context diff current save:baseline

Behavior:

with one argument, compares REF_A against current
with two arguments, compares REF_A and REF_B explicitly

Supported references depend on stored context data and currently include:

current
save:NAME

Generated Files and Directories

After context init, the tool creates:

.context/
  config.json
  state.json
  current.json            # created after scan/load
  history/
    index.json
  saves/
    index.json
  cache/
    index.json
    files/
.contextignore

Key artifacts:

.context/current.json: active persisted context.
.context/history/: immutable scan snapshots when history writing is enabled.
.context/saves/: named snapshots created with context save.
.context/cache/: incremental per-file cache used by rescans.
.contextignore: local exclusion rules specific to this tool.
CONTEXT.md: generated technical documentation from context auto-doc.

Configuration

Project configuration lives in .context/config.json.

Default keys:

respect_gitignore
write_history_by_default
max_inventory_entries
max_inline_files
max_inline_bytes
full_read_max_bytes
excerpt_read_max_bytes
excerpt_head_lines
excerpt_tail_lines
excerpt_max_bytes
force_include
force_exclude

Typical use cases:

reduce inline volume for large repositories,
force-include important files that would otherwise be skipped,
force-exclude directories or files that add noise,
disable history writing for lightweight workflows.

Example configuration:

{
  "schema_version": "1.0",
  "respect_gitignore": true,
  "write_history_by_default": true,
  "max_inventory_entries": 2000,
  "max_inline_files": 150,
  "max_inline_bytes": 2000000,
  "full_read_max_bytes": 131072,
  "excerpt_read_max_bytes": 262144,
  "excerpt_head_lines": 60,
  "excerpt_tail_lines": 20,
  "excerpt_max_bytes": 8192,
  "force_include": [],
  "force_exclude": []
}

Ignore Behavior

The scanner combines multiple exclusion layers:

hard excludes such as .context/ and VCS directories,
built-in default ignore patterns for common generated or binary files,
.gitignore rules when enabled,
.contextignore rules,
explicit force_include and force_exclude config lists.

The initial .contextignore is intentionally conservative and includes common secrets and binary artifacts such as:

.env
.env.*
*.pem
*.key
*.crt
*.p12

How Scanning Works

At a high level, a scan does the following:

Resolves the project root by finding the nearest parent directory that contains .context/.
Walks the repository and filters files through the ignore engine.
Detects stack signals from the discovered file set.
Chooses a read strategy per file: full, excerpt, or metadata.
Reuses cache entries when file fingerprints and parser version still match.
Scores files for relevance and selects the most useful content under configured budgets.
Persists the resulting context and optional history snapshot.

This means the persisted output is not just a file list. It is a structured view of the repository with:

project metadata,
stack detection,
inventory entries,
selected file content,
highlights,
warnings,
scan stats.

JSON Outputs

The persisted context JSON includes these top-level sections:

schema_version
context_id
created_at
tool
project
scan
stack
highlights
inventory
selected_files
warnings

The diff JSON includes these top-level sections:

ref_a
ref_b
summary
files
stack
stats

Development

Run the test suite:

.venv/bin/pytest

The project uses:

setuptools for packaging
Typer for the CLI
pytest for tests
pathspec for ignore-style matching

Notes and Current Scope

The tool is currently focused on local filesystem workflows.
export and save only support current as the source reference in this phase.
load and diff currently work with persisted references such as current and save:NAME.
The project is optimized for text-heavy repositories and intentionally excludes many generated and binary assets by default.

License

This project is distributed under the terms of the license in LICENSE.