ctx — Extrator de Contexto de Código para IA
AFS-Agentics/ctx
Contexto estruturado para agentes de IA — sem ruído, sem desperdício
Ver no GitHubCLI Python que escaneia codebases e gera sumários estruturados otimizados para agentes de IA como Claude Code, Copilot e Cursor. Extrai tipos de projeto, arquivos-chave, superfície de API e mudanças git sem desperdício de tokens.
Instalação
npx convez-ai AFS-Agentics/ctx1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Alimentar agentes de IA com contexto preciso de projetos em desenvolvimento
- Integrar em pipelines CI/CD para análise de código assistida por IA
- Onboarding padronizado de projetos em equipes usando IA-assisted development
Veredito

Ferramenta focada e bem-executada que resolve um problema real: preparar código para agentes de IA sem manual copy-pasting. Zero dependências e suporte a 15+ linguagens a tornam prática para fluxos automáticos. Ideal para quem já usa Claude Code ou Copilot em escala.
README
A tradução para o português deste README ainda está na fila.

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.
ctxgives 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, andmodule/namespacedeclarations
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
--diffand--jsondiff 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