ctx — Context Engine

Maintainers e AI agents: leia CLAUDE.md antes de fazer qualquer mudança.

CLI Rust que dá ao seu agente de codificação mapas curados de repositório, busca semântica em docs, compressão de output, grafo de chamadas em 7 linguagens e integração via MCP/hooks — tudo em um único binário 100% local.

🌐 Site oficial: https://jaimejunr.github.io/context-engine/

Install

Sem Rust instalado — um comando pega o build certo para o seu OS:

# Linux / macOS
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/JaimeJunr/context-engine/releases/latest/download/ctx-engine-installer.sh | sh

# Windows (PowerShell)
irm https://github.com/JaimeJunr/context-engine/releases/latest/download/ctx-engine-installer.ps1 | iex

Já tem Rust? Use cargo:

cargo install ctx-engine

Configura seu agente em um comando — escreve hook PreToolUse + MCP server no ~/.claude/settings.json:

ctx install --agent claude-code

Reabra a sessão do Claude Code e o agente passa a usar ctx automaticamente para compressão de comandos e consulta de grafo/repo map.

Desinstalar

ctx uninstall --agent claude-code   # remove só o que o ctx instalou (preserva o resto)

Plataformas suportadas

OS	Arquitetura
Linux	x86_64, aarch64
macOS	x86_64 (Intel), aarch64 (Apple Silicon)
Windows	x86_64

📖 Próximos passos:

• Quick Start — em 5 minutos, primeiro mapa de repo
• Integração com Agentes — detalhes do hook + MCP
• Análise de Concorrentes — comparação técnica vs RTK, CodeGraph, Context Mode, QMD

Documentação completa: docs/INDEX.md.

Por que ctx?

O único CLI que cobre 4 eixos competitivos em um binário Rust único, 100% local: hook de reescrita automática, MCP server nativo, compressão de output e busca semântica de docs.

	ctx	RTK	CodeGraph	Context Mode	QMD
Hook PreToolUse auto-rewrite	✅	✅	❌	❌	❌
MCP server nativo	✅	❌	✅	✅	✅
Compressão de output de comando	✅	✅	❌	✅	❌
Repo map curado (BM25 + PageRank)	✅	❌	❌	❌	❌
Busca semântica em docs (RAG local)	✅	❌	❌	parcial (FTS5)	✅
Token budget com binary search	✅	❌	❌	❌	❌
Grafo de chamadas (callers/callees/trace/impact)	✅	❌	✅	❌	❌
Ranking de relevância em resultados de grafo	✅	❌	❌	❌	❌
Budget de tokens em outputs de grafo	✅	❌	❌	❌	❌
Session continuity (PreCompact)	🚧	❌	❌	✅	❌
100% local (sem API externa)	✅	✅	✅	✅	✅
Single binary Rust nativo	✅	✅	❌ (TS)	❌ (TS)	❌ (TS)
Cobertura de comandos exec	17 famílias	100+ comandos	n/a	parcial	n/a
Linguagens (grafo)	7 (TS, Py, Rb, Go, Rust, Java, Groovy)	n/a	19+	n/a	5 (AST)
Multi-agente installer	1 (Claude Code)	13	5	15	parcial
Stars (referência)	—	53k	22k	15.5k	25.5k

Onde ganhamos clarissimamente:

• Único com hook + MCP server + compressão + RAG + repo map + grafo de chamadas no mesmo binário.
• Único com Token Budget via binary search (maximiza arquivos respeitando limite de tokens).
• Único com BM25 + Personalized PageRank híbrido para ranqueamento de repo map.
• Único com ranking de relevância à query em resultados de grafo (callers ranqueados por BM25 + número de sites). CodeGraph devolve lista crua sem ranking.
• Único com budget de tokens em outputs de grafo — trace/impact respeitam limite. CodeGraph pode estourar contexto.

Onde estamos atrás (assumido, com plano):

• Cobertura de comandos do exec (17 famílias vs 100+ do RTK) — ver análise e roadmap.
• Multi-agente installer (só Claude Code hoje; trait AgentInstaller pronto para Cursor/Codex/opencode).
• Linguagens no grafo (7 vs 19+ do CodeGraph — falta C#, PHP, Swift, Kotlin, Scala, Dart, Svelte, Vue, Lua).
• Dispatch dinâmico / herança / framework routing (URL → handler) — CodeGraph faz, nós não.
• Live file watcher — re-indexamos sob demanda, não automaticamente.

Cobertura ctx exec (17 famílias)

Categoria	Comandos
VCS	git status/log/diff/show/branch/tag/stash/blame/push/pull/add/commit/fetch (push/commit reduzem a ok <sha>)
Build/Test Rust	cargo test/build/check/clippy/fmt/run/install
Build/Test JS/TS	npm/yarn/pnpm (install/test/build/run), jest, vitest
Linters JS/TS	tsc, eslint, prettier, biome
Linters Python	ruff, mypy, pytest
Linters Go	go test, go build, go vet, golangci-lint
Linters Ruby	rubocop, rspec, rake
JVM	gradle/gradlew/mvn/mvnw (test/build/package/install/verify), grails
Containers	docker ps/images/logs/compose, kubectl get/logs/describe (logs com dedup inteligente)
Cloud AWS	aws logs/sts/s3/ec2/lambda/iam/dynamodb/cloudformation (DynamoDB unwrap, IAM policy strip)
IaC	terraform plan/apply/init/validate, tofu plan/apply/init/validate
GitHub	gh pr/issue/run
Filesystem	ls, find, tree, grep/rg/ag
Network/Data	curl/wget, jq, sqlite3

Features

• ctx map — repo map curado: extrai assinaturas via Tree-Sitter, ranqueia com BM25 + Personalized PageRank, respeita .gitignore, output em texto/JSON dentro de orçamento de tokens.
• ctx catalog — RAG local: indexa documentação, gera embeddings via endpoint OpenAI-compatible (Ollama, etc), busca por intenção.
• ctx exec — proxy universal: aplica filtros de compressão por família (git, cargo, npm, docker, kubectl, aws, gh, gradle, maven, pytest, etc), persiste métricas.
• ctx graph — grafo de símbolos resolvido (callers/callees/trace/impact/node) em 7 linguagens. Resultados ranqueados por relevância à query e respeitam token budget.
• ctx install --agent claude-code — configura hook PreToolUse (auto-rewrite de git status → ctx exec git status) e MCP server (ctx_exec, ctx_search, ctx_map, ctx_list) num único comando idempotente.
• ctx mcp serve — MCP server stdio expondo 4 tools com schema JSON gerado via rmcp + schemars.
• Arquitetura modular com 3 camadas (pipelines/, integrations/, shared/) preparada para crescer sem virar mono-arquivo.

Estrutura do Código

src/
├── pipelines/               LÓGICA DE DOMÍNIO
│   ├── map/                 Scanner → Extractor → Ranker → Budget → Output
│   ├── catalog/             Chunker → Indexer → Embedder → Searcher → Reranker
│   └── exec/                Filtros por família + métricas
│
├── integrations/            INTERFACES EXTERNAS
│   ├── agents/              Hooks + MCP entries (Claude Code, futuros Cursor/Codex)
│   └── mcp/                 MCP server stdio com 4 tools
│
└── shared/                  UTILITÁRIOS CROSS-CUTTING
    ├── cache.rs             SQLite ~/.cache/context_engine/
    ├── config.rs            ~/.ctx/config.toml
    ├── tokenizer.rs
    └── workspace.rs

Detalhes em docs/architecture/modules.md.

Linguagens Suportadas

Linguagem	ctx map (assinaturas)	ctx graph (callers/callees)	Framework router
TypeScript / TSX	✅	✅	NestJS ✅
JavaScript / JSX	✅	✅	—
Python	✅	✅	🚧
Ruby	✅	✅	Rails ✅
Groovy	✅	✅	Grails ✅
Rust	✅	✅	🚧
Java	✅	✅	🚧 (Spring planejado)
Go	—	✅	🚧 (Gin/chi/mux planejados)
C#, PHP, Swift, Kotlin, Scala, Dart, Vue, Svelte, Lua	🚧	🚧	🚧

Dependência opcional

ctx catalog (busca semântica em docs) usa embeddings via endpoint OpenAI-compatible. Ollama local é o caminho recomendado:

ollama serve
ollama pull nomic-embed-text   # embedder padrão
ollama pull llama3.2            # reranker padrão

Sem Ollama, ctx search ainda funciona em modo léxico (sem embeddings).

Uso

ctx map — repo map curado

ctx map \
  --title "CAP-123: Adicionar validação de CPF" \
  --dirs "src/models,src/validators" \
  --max-tokens 4000

Opções: --max-tokens N, --format json, --seeds dir1,dir2 (Personalized PageRank), --top N.

ctx catalog — busca semântica em docs

ctx add meu-projeto --source ./docs --include "**/*.md"
ctx index meu-projeto --with-embed
ctx search meu-projeto "como funciona o pipeline de dados?"

ctx exec — compressão de output

ctx exec cargo test          # comprime output de testes
ctx exec git status          # idem
ctx exec report              # relatório de tokens economizados

ctx graph — grafo de chamadas

ctx graph index --dirs src                    # indexa o projeto
ctx graph callers apply_pipeline              # quem chama esta função?
ctx graph trace handle_request --depth 3      # cadeia até este símbolo
ctx graph impact migrate_db                   # o que quebra se eu mudar?
ctx graph callers run --query "exec proxy" --max-tokens 800   # ranqueado por relevância

ctx mcp — MCP server

ctx mcp tools                # lista tools expostas pelo server
ctx mcp serve                # sobe MCP server em stdio (long-running)

Configuração

Global (~/.ctx/config.toml):

[llm]
endpoint = "http://localhost:11434"
embedder = "nomic-embed-text"
reranker = "llama3.2"

Per-projeto (.ctx/config.toml, gerado por ctx init):

[map]
dirs = ["src", "lib"]
max_depth = 15
ignore_extra = ["**/fixtures/**"]

Documentação Completa

• docs/INDEX.md — hub central
• docs/architecture/ — design interno, padrões, extensão
• docs/guides/ — how-to, quick-start, integração com agentes
• docs/map/, docs/search/, docs/exec/ — docs por pipeline
• docs/competitors/ — análise de RTK, CodeGraph, Context Mode, QMD

Desenvolvimento

cargo test --locked --all-features                       # 214 testes
cargo clippy --all-targets --all-features -- -D warnings # lint estrito
cargo fmt -- --check                                     # formatação
cargo run -- map --help                                  # ajuda dos subcomandos

Git Hooks (Lefthook):

• pre-commit: cargo fmt --check + cargo clippy
• pre-push: cargo test --locked --all-features

Licença

MIT (veja LICENSE)