ctx — AI-Ready Code Context Extractor

ctx is a zero-dependency CLI tool that scans your codebase and produces concise, structured context summaries optimized for AI coding agents like Claude Code, GitHub Copilot (Codex), and Cursor. Instead of dumping your entire codebase into a prompt, ctx extracts the essentials — project type, key files, public API surface, and git changes — in the format your agent understands best.

🎯 Why ctx? AI agents work better with focused context. ctx gives them exactly what they need: what the project is, what files matter, what changed, and where the APIs are. No noise. No token waste.

Who is this for?

• Developers using AI coding agents who want to give their agent precise project context without manual copy-pasting
• Teams onboarding to AI-assisted development who want a standardized way to share project context
• CI/CD pipelines that inject code context into agent-based review workflows
• Anyone who's ever said "Claude, here's my entire repo — figure it out" and regretted it

Features

• Zero dependencies — core functionality uses only Python stdlib
• Multiple output formats — human-readable, agent-optimized (Claude/Codex/Cursor), JSON
• Smart project detection — auto-detects 15+ project types (Python, Rust, Go, Node.js, C++, C#, Java, and more)
• Git diff summaries — see what changed at a glance, not a wall of diff text
• .gitignore-aware — respects your existing gitignore rules
• Blazing fast — walks only relevant files, skips binaries and build artifacts
• Safe limits — caps at 500 files and 512 KB per file to keep output manageable

Installation

Via pip (recommended)

pip install git+https://github.com/AFS-Agentics/ctx.git

Via pipx (isolated)

pipx install git+https://github.com/AFS-Agentics/ctx.git

Manual setup

# Clone the repo
git clone https://github.com/AFS-Agentics/ctx.git
cd ctx

# Install in editable mode
pip install -e .

# Or just run directly
./ctx.py --help

Optional: Rich formatting

For colorized output, install with the optional rich dependency:

pip install -e ".[rich]"

Quick Start

# Scan current directory
ctx

# Scan a specific project
ctx ~/projects/my-app

# Get git diff summary
ctx --diff

# Claude-optimized markdown (paste directly into Claude)
ctx --agent claude

# JSON for tooling
ctx --json

Usage Examples

Basic project scan

$ ctx
==========================================================
  ctx — Code Context Summary
==========================================================
  Path:   /Users/me/projects/my-app
  Type:   🐍 Python
  Lang:   Python
  Files:  42
==========================================================

── Key Files ──────────────────────────────────────────────
  📄 pyproject.toml
  📄 src/app.py
  📄 src/models.py
  📄 src/main.py

── Public API / Module Boundaries ────────────────────────
  src/app.py:
      def create_app
      class AppConfig
  src/models.py:
      class User
      class Post
      def get_user

Single file analysis

$ ctx src/main.py

==========================================================
  ctx — Code Context Summary
==========================================================
  Path:   src/main.py
  Type:   📦 Single file
  Lang:   Python
  Files:  1
==========================================================

── Public API / Module Boundaries ────────────────────────
  src/main.py:
      def main
      class Application

Agent-optimized output

# Claude format — full markdown with sections
$ ctx --agent claude

# Codex format — concise bullets
$ ctx --agent codex

# Cursor format — YAML-like structured data
$ ctx --agent cursor

Claude output:

# Code Context Summary

## Overview

- **Path**: /Users/me/projects/my-app
- **Project Type**: Python
- **Language**: Python
- **Files Scanned**: 42

## Key Files

- `pyproject.toml`
- `src/app.py`
- `src/models.py`

## Public API / Module Boundaries

src/app.py: def create_app class AppConfig

## Git Diff Summary

- **Files changed**: 3
- **Added**: 1, **Removed**: 0, **Modified**: 2

Codex output:

Context: /Users/me/projects/my-app
Project: Python | Lang: Python | Files: 42

Files:
  • pyproject.toml
  • src/app.py

API:
  • src/app.py:
  •     def create_app
  •     class AppConfig

Cursor output:

context:
  path: /Users/me/projects/my-app
  project_type: Python
  language: Python
  files_count: 42

key_files:
  - pyproject.toml
  - src/app.py

modules:
  - src/app.py:
  -     def create_app
  -     class AppConfig

Git diff summary

# Show what's changed since last commit
$ ctx --diff

── Git Diff Summary ───────────────────────────────────────
  Staged (2 files):
   M src/app.py
   A src/new_feature.py
  Unstaged (1 files):
   M src/models.py

JSON output

$ ctx --json | jq '.project.type'
"Python"

$ ctx --json | jq '.git_diff'
{
  "files_changed": 3,
  "added": 1,
  "removed": 0,
  "modified": 2,
  "staged_files": ["src/app.py", "src/new_feature.py"],
  "unstaged_files": ["src/models.py"],
  "summary": "Staged (2 files)..."
}

CLI Reference

usage: ctx [-h] [--diff] [--agent {claude,codex,cursor}] [--json] [path]

AI-Ready Code Context Extractor. Scan codebases and produce context summaries
optimized for AI agents.

positional arguments:
  path                  File or directory to analyze (default: current directory)

options:
  -h, --help            show this help message and exit
  --diff                Include git diff summary
  --agent {claude,codex,cursor}
                        Format output for a specific AI agent
  --json                Output machine-readable JSON

Examples:
  ctx                        Scan current directory
  ctx /path/to/project       Scan specific path
  ctx --diff                 Show git diff summary
  ctx --agent claude         Claude-optimized markdown
  ctx --agent codex          Codex-optimized bullets
  ctx --agent cursor         Cursor YAML-like format
  ctx --json                 Machine-readable JSON

Configuration

ctx works out of the box with zero configuration. It auto-detects:

• Project type — looks for pyproject.toml, Cargo.toml, package.json, go.mod, and more
• Language — detects from file extensions when no project file is found
• Key files — entry points like main.py, index.js, lib.rs, app.py
• Public API — extracts class, def/function/fn, and module/namespace declarations

Skip behavior

The following directories are always skipped (not strictly configurable — open a PR if you need customization):

Category	Directories
Version control	.git
Dependencies	node_modules, .venv, venv, vendor
Build artifacts	build/, target/, dist/, __pycache__, .tox
IDE	.idea, .vscode
Binary extensions	.pyc, .pyo, .so, .dylib, .dll, .class, .o, .obj
Media files	.png, .jpg, .jpeg, .gif, .ico, .pdf, .zip, .tar, .gz, .mp3, .mp4

You can add more by modifying the SKIP_DIRS, SKIP_EXTS constants in ctx.py, or by adding entries to your .gitignore.

System Requirements

• Python 3.10+ (3.9 may work but is not tested)
• git (optional, only needed for --diff and --json diff data)
• 50 KB disk space (the tool itself)
• No external dependencies required

Project Structure

ctx/
├── ctx.py              # Main CLI tool (361 lines, single file)
├── pyproject.toml      # Package configuration
├── README.md           # This file
├── LICENSE             # MIT License
└── .gitignore          # Git ignore rules

Supported Project Types

Signature File	Detected Language
Cargo.toml	Rust 🦀
go.mod	Go 🔷
pyproject.toml	Python 🐍
package.json	Node.js 🟢
CMakeLists.txt	C/C++
Makefile	C/C++
composer.json	PHP
Gemfile	Ruby
mix.exs	Elixir
*.csproj	C#
*.sln	.NET
pom.xml	Java
build.gradle	Java

For projects without a signature file, the language is inferred from the most common file extension.

Agent Format Compatibility

Agent	Format	Prompt Optimization
Claude	Markdown with ## sections	Best for Claude 3.5/4 Sonnet and Opus — uses clear headings and code fences
Codex	Compact bullets with •	Best for GitHub Copilot Chat and Codex — minimal tokens, scan-friendly
Cursor	YAML-like structured data	Best for Cursor composer — structured key-value pairs for easy parsing

License

MIT License — see the LICENSE file for details.

Development

# Clone and install
git clone https://github.com/AFS-Agentics/ctx.git
cd ctx
pip install -e ".[rich]"

# Run tests
python3 -m doctest ctx.py -v  # if you add doctests

# Use it on itself
./ctx.py
./ctx.py --agent claude
./ctx.py --json