diff --git a/README.md b/README.md index 632f800..8e7db5e 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,83 @@ +# ctx — anti-tokens CLI para Claude Code + +> Analise seu projeto localmente. Envie ao Claude resumos densos, não arquivos brutos. + +**Status:** alpha — em desenvolvimento ativo. Interfaces podem mudar. + +## Por que usar + +Cada token que o Claude lê tem custo e consome janela de contexto. Ao trabalhar em projetos grandes, o Claude frequentemente gasta milhares de tokens apenas lendo arquivos para construir um modelo mental antes de fazer qualquer trabalho real. + +`ctx` roda localmente, analisa seu projeto com ferramentas especializadas por linguagem (Roslyn para C#, tree-sitter para TypeScript), e emite resumos compactos em markdown que dão ao Claude tudo que ele precisa em uma fração dos tokens. + +### Benchmark + +Teste real: análise de "o que preciso mudar para adicionar uma feature" em projeto em produção. +Ambas as sessões iniciadas com `/clear` — condições equivalentes. + +| Teste | Consumo de janela de contexto | +|-------|-------------------------------| +| Sem ctx | +7% | +| Com ctx | +3% | + +**Economia: 57%.** Em sessões longas de desenvolvimento, onde o Claude faz a mesma exploração várias vezes ao longo da conversa, essa economia acumula. + +## Instalação + +```sh +go install github.com/ricarneiro/ctx/cmd/ctx@latest +``` + +Requer Go 1.22+. + +## Uso + +```sh +# Contexto git: commits recentes, status, info da branch +ctx git + +# Detectar stack e emitir visão geral do projeto +ctx auto project + +# Estrutura de projeto C# (requer .NET SDK) +ctx csharp project + +# Outline de arquivo C#: tipos, métodos, assinaturas +ctx csharp outline src/MyService.cs + +# Listar erros de compilação +ctx csharp errors +``` + +Toda saída é markdown UTF-8 no stdout. Redirecione onde precisar: + +```sh +ctx csharp project | clip # Windows +ctx csharp project | pbcopy # macOS +``` + +Ou referencie em um `CLAUDE.md`: + +```markdown +Run `ctx csharp project` to get the project overview before making changes. +``` + +## Contribuindo + +Contribuições são bem-vindas. Clone o repositório, faça suas alterações e abra um Pull Request. Para mudanças grandes, abra uma issue primeiro para alinhar o escopo. + +```sh +git clone https://github.com/ricarneiro/CTX.git +cd CTX +go build -o ctx.exe ./cmd/ctx +``` + +## Licença + +MIT — veja [LICENSE](LICENSE). + +--- + # ctx — anti-tokens CLI for Claude Code > Analyze your codebase locally. Feed Claude dense summaries, not raw files. @@ -6,13 +86,21 @@ ## Why -Every token Claude reads costs money and burns context window. When working on -a large C# or React codebase, Claude often spends thousands of tokens just -reading files to build a mental model before doing any actual work. +Every token Claude reads costs money and burns context window. When working on a large codebase, Claude often spends thousands of tokens just reading files to build a mental model before doing any actual work. -`ctx` runs locally, analyzes your project with language-aware tools (Roslyn for -C#, tree-sitter for TypeScript), and emits compact markdown summaries that give -Claude everything it needs in a fraction of the tokens. +`ctx` runs locally, analyzes your project with language-aware tools (Roslyn for C#, tree-sitter for TypeScript), and emits compact markdown summaries that give Claude everything it needs in a fraction of the tokens. + +### Benchmark + +Real test: analyzing "what needs to change to add a feature" on a production project. +Both sessions started with `/clear` — equivalent conditions. + +| Test | Context window usage | +|------|----------------------| +| Without ctx | +7% | +| With ctx | +3% | + +**Savings: 57%.** In long development sessions, where Claude performs the same exploration repeatedly throughout a conversation, the savings compound. ## Installation @@ -20,8 +108,7 @@ Claude everything it needs in a fraction of the tokens. go install github.com/ricarneiro/ctx/cmd/ctx@latest ``` -Requires Go 1.22+. Binaries for common platforms will be published after the -MVP is validated. +Requires Go 1.22+. ## Usage @@ -55,65 +142,15 @@ Or reference it in a `CLAUDE.md`: Run `ctx csharp project` to get the project overview before making changes. ``` -## Architecture - -`ctx` uses a plugin system. Each stack (`git`, `csharp`, `react`, `auto`) is a -plugin that implements the `core.Plugin` interface and registers itself via -`init()`. - -``` -core.Plugin interface - Name() string - Version() string - ShortDescription() string - Command(ctx *core.Context) *cobra.Command -``` - -In the MVP, plugins are compiled into the binary. Future plan: migrate to -subprocess dispatch (binaries named `ctx-csharp`, `ctx-react` in PATH), same -pattern as `kubectl` plugins. - -C# analysis uses a separate helper process (`tools/roslyn-helper/`) written in -C# with Roslyn. The helper communicates with `ctx` via JSON-RPC over -stdin/stdout. This lets us use the best tool for the job without pulling a .NET -runtime into the Go binary. - -See `docs/DECISIONS.md` for the full rationale behind each architectural choice. - -## Development - -### Prerequisites -- Go 1.26+ -- .NET SDK 10.0+ (for Roslyn helper) -- golangci-lint (`go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest`) - -### Build -```sh -go build -o ctx.exe ./cmd/ctx -``` - -### Tests & lint -```sh -go vet ./... -golangci-lint run ./... -``` - -### Pre-commit hooks -```sh -git config core.hooksPath .githooks -# On Linux/macOS also: chmod +x .githooks/pre-commit -``` - -### Roslyn helper -```sh -cd tools/roslyn-helper -dotnet publish src/RoslynHelper -c Release -r win-x64 --self-contained false -o publish/ -``` - ## Contributing -Contributions welcome. See `CONTRIBUTING.md` (coming soon) for guidelines. -Open an issue first if you plan a large change. +Contributions are welcome. Clone the repository, make your changes, and open a Pull Request. For large changes, open an issue first to align on scope. + +```sh +git clone https://github.com/ricarneiro/CTX.git +cd CTX +go build -o ctx.exe ./cmd/ctx +``` ## License