Open Kioku

---

Primeira Vitória: 2 Comandos

npm install -g open-kioku
ok setup agent cursor --repo . --apply

Use claude em vez de cursor para Claude Code. Um comando indexa o repositório, escreve a configuração MCP no escopo do repositório e as orientações do agente, e verifica se o servidor local responde (execute sem --apply para pré-visualizar; nada é gravado). Depois, peça evidências em uma tarefa real:

ok context "reap the doctor's MCP probe child process" --format markdown

Esta é a saída real neste repositório, truncada: … marca linhas cortadas, e cada unidade primária é recolhida ao seu intervalo de linhas e primeira linha. O commit que fez essa alteração tocou exatamente um arquivo, e ele é o primeiro resultado:

# Task: reap the doctor's MCP probe child process

## Confidence
- Overall: `Medium` (`0.74`)
- Caveats:
  - exact symbol/reference evidence is absent
  - runtime corroboration is absent
- Components:
  …
  - `exact_references` score `0.25`, weight `0.20`, contribution `0.05`
  …
  - `task_relevance` score `1.00`, weight `0.20`, contribution `0.20`
  …
## Retrieval
…
- Attempted: `lexical, document, exact_semantic, graph, validation, git_history, runtime`
- Succeeded: `lexical, document, exact_semantic, graph, validation, git_history`
…
- Exact-authority selections: `0`; ambiguity/unresolved signals: `0`
- Retrieval confidence: `Medium` (qualitative ContextPack confidence, not a calibrated probability)
- Caveats:
  - no runtime traces, logs, or incidents are ingested for this repository
  …
## Primary Context
### crates/open-kioku-cli/src/reports/status_setup_doctor.rs
Lines 1-107  `fn file_path_for_symbol(store: &dyn MetadataStore, symbol: &Symbol) -> anyhow::Result<PathBuf> {`
### crates/open-kioku-core/src/process.rs
Lines 66-180  `fn proc_status_peak_rss_bytes() -> Option<u64> {`
…

O rótulo é Medium, não mais alto, por uma razão que o pacote declara: a tarefa não nomeia um identificador que o índice resolva exatamente e este repositório não tem índice SCIP, então exact_reference_count é 0 (exact_references pontua 0.25; Exact-authority selections é 0), o que limita a pontuação a 0.74 e o rótulo a Médio. Artefatos de runtime também estão ausentes; essa é a segunda ressalva, e ela reduz a pontuação, não a faixa. Exact é reservado para pacotes com pelo menos uma seleção de autoridade exata; uma correspondência lexical, por melhor que seja, não o conquista. A tarefa é formulada como o assunto do commit de correção, então o histórico do git corrobora o primeiro arquivo junto com a correspondência lexical. Todo pacote diz quais fluxos de evidência foram executados, quais tiveram sucesso e o que está faltando. Evidência ausente reduz a confiança declarada; nunca é encoberta.

O Que Você Obtém

ok plan "change token expiration" --format json > plan.json   # context, impact, tests, edit boundary, caveats
# ...edit with your normal agent or editor...
ok verify --plan plan.json --git                               # the real diff against the declared boundary

ok plan (ou a ferramenta MCP plan_change) retorna contexto primário com proveniência, candidatos de impacto divididos em estruturalmente comprovados e heurísticos, alvos de validação em camadas por evidência, um limite de edição (caminhos permitidos, com cautela, proibidos) e ressalvas explícitas. ok verify lê os arquivos realmente alterados e relata, por exemplo, [out_of_boundary] go/shipping/carrier.go: path is outside the saved plan boundary. Um código de saída verde de um executor de testes não é prova de que os arquivos certos foram alterados; isto é.

Por baixo: definições exatas, referências e caminhos de dependência do código-fonte (e SCIP opcional) são autoritativos. Sinais lexicais, semânticos, de histórico, de teste e de runtime podem reordenar a recuperação; eles não podem sobrescrever a verdade do repositório.

O Que Mudou na 4.0.0

Lançada em 2026-09-11. Execute ok index após atualizar: o formato de armazenamento do índice mudou, e um índice pré-4.0 retém evidências de relacionamento e diz isso (ok impact, ok plan, ok context, e as ferramentas MCP sobre eles recusam com run ok index em vez de responder a partir de um grafo vazio). A lista completa, com o commit e o método por trás de cada número, está em CHANGELOG.md.

• 16 ferramentas MCP, abaixo de 58. Cada uma responde a uma pergunta que nenhuma outra ferramenta responde; um nome aposentado responde com para onde sua capacidade foi. Seis descrições que diziam o que seus nomes sugeriam agora dizem o que a implementação faz, e structural_search foi removido porque não existia correspondência estrutural. docs/mcp-tools.md traz a tabela de migração.
• regex_search faz regex. Ele despachava para busca lexical ranqueada; agora avalia o padrão linha por linha sobre o texto indexado e relata arquivos varridos e paradas antecipadas. ok search <pattern> --regex é o equivalente em CLI.
• O índice relata o que não indexou. Cobertura por linguagem com cada omissão atribuída a um motivo de pular, em ok index, ok doctor, ok status e repo_status. Uma regra de ingestão havia descartado silenciosamente 25 arquivos Java de um repositório.
• Mais da região certa. Unidades selecionadas cobriram 3–22% das linhas que um commit real alterou, mesmo quando o arquivo estava certo; os três principais arquivos agora se ampliam para o símbolo envolvente e blocos adjacentes. Participação de linhas alteradas mostradas dentro de 8k tokens, 626 casos locais pareados, nenhum caso pior, cerca de três vezes os tokens: Java 0.216 → 0.248, Go 0.207 → 0.299, TypeScript 0.155 → 0.335, Python 0.130 → 0.203 (docs/ranking.md, benchmarks/commit-derived/region-widening-ab.json).
• Palavras da tarefa alcançam os identificadores do repositório. ChannelsUtils Tests alcança ChannelUtilsTests sem modelo, rede ou re-indexação. Neutro em benchmarks de assunto de commit por construção; em 259 consultas perturbadas R@5 0.656 → 0.699, MRR +0.036 (IC 95% +0.015 a +0.062), um limite superior por design (docs/ranking.md).
• Arestas de arquivos derivados. Um arquivo gerado e sua origem, ou um teste e o módulo em homenagem ao qual foi nomeado, entram na análise de impacto como possibilidades rotuladas: uma origem declarada carrega sua prova, uma convenção de nomenclatura é marcada como heurística (docs/graph-model.md).

O Que Esperar

A recuperação é medida no caminho de produção (ok context, o mesmo construtor por trás de ok plan e da ferramenta MCP build_context_pack) em quatro repositórios reais, cada um indexado em um commit base fixo. Cada caso é um commit posterior: a consulta é sua linha de assunto, a resposta são os arquivos de origem que ele alterou. Os casos são divididos cronologicamente; ambas as divisões são verificadas diariamente, e a tabela mostra a retenção.

Corpus	Casos de retenção	R@5	R@20	MRR
Java, cerca de 10k arquivos	113	0.566	0.708	0.516
Aplicação Go, ~800 arquivos	84	0.690	0.821	0.539
TypeScript, ~900 arquivos	167	0.826	0.880	0.683
Biblioteca Python, ~4k arquivos	199	0.663	0.754	0.543

• R@5 — a participação de tarefas em que pelo menos um arquivo alterado pelo commit está nos cinco primeiros resultados.
• R@20 — o mesmo dentro dos vinte primeiros resultados, aproximadamente todo o pacote de contexto.
• MRR — a média de 1 / posição do primeiro arquivo correto; 1.0 significa que sempre foi o primeiro, 0.5 é o que você obtém se o primeiro arquivo correto fosse sempre o segundo, ou o primeiro metade das vezes e nunca encontrado no resto.

Leia claramente. Em um repositório Java de cerca de dez mil arquivos, o arquivo certo está nos cinco primeiros cerca de metade das vezes e no pacote cerca de sete em dez; em um repositório TypeScript de cerca de novecentos arquivos, no pacote quase nove em dez e nos cinco primeiros cerca de quatro em cinco. Esse é o piso a partir do qual o agente começa antes de olhar qualquer coisa, e é o número a observar. Consultas exatas (definições, referências, caminhos de dependência) e o loop plano → edição → verificação ficam em cima disso.

Essas linhas de base foram congeladas em 2026-09-25 a partir de uma execução de matriz de runner Linux hospedado do commit bd5d06ab, e uma segunda execução do mesmo commit produziu pontuações idênticas (além dos tempos). .github/workflows/commit-derived-bench.yml as re-deriva diariamente; o trabalho falha quando uma métrica observada cai mais de 0.03 abaixo de sua linha de base congelada, ou quando uma família de tarefas roteada de 34 ou mais casos cuja composição de casos não mudou cai mais de max(0.03, 2/n) abaixo da sua própria. As consultas são assuntos de commit, não texto de issue, então os números não são comparáveis com benchmarks publicados que usam texto de issue. Descrições do corpus, ambas as divisões, os scripts e a política de regressão: docs/retrieval-benchmark.md; linhas de base congeladas: benchmarks/commit-derived/.

Mais dois fatos medidos:

• Quando a tarefa não tem resposta. No fixture congelado de 30 casos, nenhum dos cinco casos sem ouro é apresentado como resposta: a taxa de falso positivo sem ouro é 0.0 (o teto do IC é 0.25), e a estratégia consultiva de pacote de contexto roteado na mesma execução (cc4:routed_contextpack) não retorna nenhum deles acima de Low. Um pacote de baixa confiança ainda lista candidatos; ele diz ao chamador para não confiar neles em vez de retornar nada. benchmarks/retrieval-baseline.json
• Embeddings neurais locais opcionais. O perfil neural local padrão (um modelo int8 de 149M parâmetros, fixado por digest) melhorou cada métrica nos corpora Go e TypeScript contra um controle do mesmo dia, em cerca de +0.025 MRR, em runners hospedados de 4 vCPU / 16 GB. Real, mas modesto; as correções de ranqueamento lexical lançadas no mesmo dia valeram cerca de quatro vezes mais. docs/embedding-providers.md

Medido em Escala

As alegações de desempenho são observações vinculadas a um build identificável, publicadas com método e ressalvas. O registro de escala ponta a ponta mais recente valida a linhagem de lançamento 3.1.0 no commit de origem 3959fdfb6ca27d0c279b635fca7fc1b7935d4889 em um grande repositório Java, no mesmo host e protocolo do registro público anterior. A 4.0.0 mudou o formato de armazenamento do índice e não foi re-executada neste corpus; a tabela descreve a 3.1.0. As mudanças medidas da própria 4.0.0 estão listadas com seus commits e métodos em CHANGELOG.md.

Medição (linhagem v3.1.0, ponta a ponta)	Resultado
Arquivos de origem rastreados / arquivos Java	16.537 / 12.580
Arquivos / símbolos / blocos indexados	13.607 / 247.499 / 248.107
Nós / arestas do grafo	402.844 / 1.522.135
Índice estrutural a frio	19m 28s
Consulta exata de classe, processo novo	0,02–0,05s
Referências exatas / busca lexical, processo novo	0,74s / 0,24s
Build semântico plano exato	495.606 vetores em 58,8s; 0 falhas
Build HNSW persistente	495.606 vetores em 10m 19s; 0 falhas

Contra main em c96f61a no corpus e host idênticos (metodologia): inicialização por comando ~14s → sub-segundo, consulta exata de classe 13,9s (retornando um symbol not found incorreto) → 0,02s com a classe correta, índice estrutural a frio 40m 40s → 19m 28s. O índice repetido reproduziu totais idênticos e quatro leitores de grafo paralelos concluíram com zero falhas de bloqueio. A identidade do repositório é omitida, então este é um registro de escala em vez de um corpus reproduzível: evidência legível por máquina · metodologia · registro anterior: evidência v3.0.4.

Mais artefatos: escala semântica local, 51.349 vetores, HNSW persistente auto-selecionado, build novo em 21,70s, 0 vetores obsoletos / 0 falhos (demo/proof/ann-50k-dogfood.json); plano → edição → validação → verificação através do runner com política, 2 aprovados, 0 violações de limite, veredito final warn porque evidência mais forte estava ausente (demo/proof/verification-dogfood.json); uma auditoria de repositório público, 4.600+ arquivos, 46.000+ símbolos, 8.900+ testes indexados em 33,1s (docs/large-repo-proof.md).

Estes são tempos de workstation local, não garantias universais.

Instalação

Canal	Como
npm (recomendado)	npm install -g open-kioku — o wrapper puxa @open-kioku/{darwin-arm64,linux-x64,linux-arm64,win32-x64} (fontes sob packages/)
crates.io	cargo install open-kioku-cli ou cargo binstall open-kioku-cli
Lançamentos do GitHub	Binários com SHA256SUMS, SBOM.cargo-metadata.json, PROVENANCE.json e atestações de proveniência de build do GitHub (docs/release-trust.md)
Plugin Claude Code	claude_plugin.json e .claude-plugin/
Plugins Cursor / Codex	.cursor-plugin/ · .codex-plugin/
Diretórios MCP	Glama (glama.json) · Smithery (smithery.yaml)
A partir do código-fonte	git clone https://github.com/shivyadavus/open-kioku.git && cargo install --path open-kioku/crates/open-kioku-cli

Conecte um Agente

ok setup agent claude --repo . --apply    # Claude Code: index + .mcp.json + managed skill, then a live MCP check
ok setup agent cursor --repo . --apply    # Cursor: index + .cursor/mcp.json + managed rule
ok mcp install codex  --repo .            # Codex: prints the TOML server entry
ok mcp install gemini --repo .            # Gemini CLI: prints the JSON server entry

ok setup agent --apply está configurado para claude e cursor; todos os outros clientes listados por ok mcp install --help recebem um snippet de configuração somente leitura de ok mcp install <client>. O servidor MCP é local, somente leitura e fala stdio. Ele anuncia 16 ferramentas — uma por pergunta que nada mais responde — cada uma com orientações de uso, esquemas de entrada/saída, anotações de segurança e categorias de roteamento, e um teste de regressão de metadados rejeita novas ferramentas que omitam qualquer um desses itens. As ferramentas de memória e erros em tempo de execução aparecem apenas quando esses recursos estão configurados; as capacidades de arquitetura, histórico e propriedade são entregues via CLI (ok architecture …, ok history …, ok contract show).

Guias passo a passo: Claude Code · Cursor · Codex · Gemini CLI · CI: open-kioku-action (docs/github-action.md)

Cada cliente ok mcp install, com o formato de configuração gerado e como confirmar a conexão: docs/guides/cross-harness-setup.md

Por que Local

• Sem índice hospedado e sem upload de código-fonte: tudo fica no diretório .ok/ do repositório, e ok prove compartilha contagens e pontuações sem trechos de código-fonte.
• O MCP é somente leitura por padrão; edições de código-fonte permanecem no seu editor normal ou no harness do agente.
• A execução de comandos e downloads de modelos são controlados por políticas, caminhos semelhantes a segredos são bloqueados e a negação de rede falha de forma fechada, em vez de degradar silenciosamente.

docs/security-model.md · SECURITY.md · docs/release-trust.md

Como é Medido

• Corpora derivados de commits em repositórios reais, executados todas as noites: docs/retrieval-benchmark.md (derive com scripts/commit-derived-cases.py, pontue com scripts/score-context-cases.py, compare com scripts/compare-commit-derived-report.py).
• O fixture congelado de 30 casos com uma divisão de validação retida e limites de CI: ok retrieval-bench . --cases-file benchmarks/retrieval-cases.json --min-cases 30.
• Suites de fluxo de trabalho, relacionamento e contratos: docs/workflow-benchmarks.md · docs/relationship-benchmark.md · docs/contract-benchmarks.md.
• Registros de escala e dogfood: docs/proof.md e demo/proof/.

Mudanças de limites são mudanças de produto e são revisadas como tal; um limite nunca é reduzido para deixar o CI verde.

Mais de Um Repositório

A recuperação semântica é opcional e local (ok --repo . semantic index, depois ok search "authorization expiry" --hybrid); a aquisição de modelos exige consentimento explícito e é recusada sob negação de rede (docs/semantic-search.md, docs/vector-index.md). Indexe projetos individualmente e vincule-os em um workspace (ok index --mode cross-project --workspace <dir>, ok architecture fleet). Exporte e importe índices conhecidos como bons para reutilização em equipe e CI (ok --repo . snapshot export --quality best, ok --repo . index --from-snapshot auto); a memória pessoal é excluída de snapshots compartilhados por padrão. Detecte arquitetura, verifique políticas e crie contratos de mudança limitados (ok --repo . architecture detect, ok --repo . contract create "update API boundary"). O histórico do Git é ativado por padrão com uma janela limitada; rastreamentos de execução e relatórios de cobertura são entradas locais opcionais que nunca superam a verdade exata do código-fonte.

Suporte a Idiomas

A análise Tree-sitter e a extração de símbolos cobrem Rust, Python, TypeScript/TSX, JavaScript/JSX, Go e Java. YAML e JSON são analisados estruturalmente; a indexação de arquivos/chunks também cobre TOML, SQL, Markdown, Terraform e outros textos de repositório. A resolução com reconhecimento de idioma adiciona semânticas de escopo, importação, receptor/tipo, contenção e herança onde suportado.

Definições e referências exatas de Java a partir de um índice scip-java: docs/guides/java-scip.md

Comandos Úteis

ok --repo . search "token expiration handler"
ok --repo . symbol definition PolicyGate
ok --repo . symbol refs PolicyGate
ok --repo . impact --file src/auth.rs
ok --repo . tests --changed src/auth.rs
ok --repo . context "change token expiration" --format markdown
ok --repo . plan "change token expiration" --format markdown
ok --repo . verify --plan /tmp/plan.json --git
ok --repo . history similar --task "change token expiration" --path src/auth.rs
ok prove . --task "change token expiration"

Todos os 38 comandos de nível superior

Comandos atuais de nível superior (38): init, index, snapshot, watch, status, doctor, setup, demo, search, semantic, symbol, explain, impact, path, tests, context, retrieve-context, plan, preflight, verify-boundary, verify, contract, bench, workflow-bench, retrieval-bench, relationship-bench, contract-bench, eval, prove, adr, ui, architecture, history, patch, memory, mcp, scip e graph.

Referência completa das ferramentas MCP: docs/mcp-tools.md

Estrutura do Repositório

Este é um workspace Cargo de 43 crates com uma direção estrita de dependência descendente: CLI / MCP → inteligência do agente (context, impact, tests, plan, patch, actions) → kernel de inteligência de código (ingest, parse, tree-sitter, resolution, graph, architecture) → armazenamento e busca (storage-sqlite, search-tantivy). open-kioku-core contém os contratos de evidência, grafo e relatórios; integrações opcionais (scip, lsp, semantic, vector, qdrant, sentry) retornam diagnósticos explícitos de desabilitado/não suportado, em vez de degradar silenciosamente.

Arquitetura: docs/architecture.md · Mapa de crates: docs/crate-map.md · Armazenamento: docs/storage-model.md

Desenvolvimento

cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all
scripts/validate-docs.sh
ok retrieval-bench . --cases-file benchmarks/retrieval-cases.json --min-cases 30
ok workflow-bench . --cases-file benchmarks/workflow-cases.json --limit 10

Liderado por mantenedores e com código-fonte disponível sob Elastic-2.0; veja CONTRIBUTING.md antes de abrir um pull request.

---