Koine

CLI que injeta contexto multi-camada (usuário, agente, referências, contexto da pasta) em harnesses de IA terminal — Claude Code, Antigravity (agy), GitHub Copilot CLI, OpenCode, Codex CLI.

Por que existe

Agentes de IA terminal abrem cada sessão zeradas. O usuário precisa repetir, a cada turno, quem é, em que projeto trabalha, qual padrão da casa, qual contexto da pasta. Repetir contexto consome tempo, polui prompts e degrada qualidade da resposta.

Koine resolve isso separando o que normalmente vem embaralhado em "memória de agente":

1. Harness — koine carrega o contexto e o entrega ao cliente IA pelo canal que ele oferece, sem escrever nada na sua pasta de trabalho
2. Habilidades — skills kn-* que o agente invoca durante a sessão
3. Base de conhecimento — bundle OKF com perfis, escopos, domínios e referências; propriedade do usuário
4. Sistema de arquivos — recomendado, não obrigatório

Cada camada evolui em ritmo próprio. O agente IA passa a "já saber" quem você é, no que está trabalhando e onde está, sem precisar contar de novo a cada turno.

Pré-requisitos

Para Koine fazer sentido, você precisa de:

• Python 3.12+ — o Koine é distribuído como aplicação Python (koine.pyz). macOS: brew install python; Windows: instalador oficial em https://www.python.org/downloads/ (ou o Python da sua TI); Linux: gerenciador do sistema (apt install python3 etc.).
• Um cliente IA terminal suportado — Claude Code, Antigravity, GitHub Copilot CLI, OpenCode ou Codex CLI. Tabela abaixo na seção Clientes IA suportados.
• Node.js 18+ (recomendado 22+) — necessário para instalar Claude Code e Copilot CLI via npm. Download: https://nodejs.org/.
• Homebrew (opcional em macOS) — gerenciador recomendado para instalar Node e clientes IA. Instalar: https://brew.sh/.

Se você rodar koine instalar sem cliente IA detectado, o próprio instalador orienta o que falta com comandos por OS — não precisa decorar nada agora.

Instalação

macOS / Linux

curl -fsSL https://github.com/jrunic/koine/releases/latest/download/install.sh | sh

Windows (Command Prompt — recomendado em estações corporativas)

curl -L -o install.bat https://github.com/jrunic/koine/releases/latest/download/install.bat
install.bat

install.bat é 100% cmd.exe — não chama PowerShell em nenhum ponto. Roda em estação onde o powershell.exe está bloqueado por política, sem admin. Requer curl.exe (padrão desde o Windows 10 1803) e Python ≥ 3.12 no PATH.

Windows (PowerShell — alternativa)

iwr -useb https://github.com/jrunic/koine/releases/latest/download/install.ps1 | iex

Upgrade da v0.3.x (Go)

Rode o mesmo one-liner do seu sistema. O installer substitui os atalhos kn-* da instalação Go pelos wrappers Python e preserva ~/.config/koine/ e ~/.local/share/koine/ intocados — escopos, aliases e agentes continuam onde estavam. Nada a migrar.

Plataformas suportadas: qualquer sistema com Python ≥ 3.12 (macOS, Linux, Windows).

Guia completo — variantes (versão pinada, espelho interno), verificação e solução de problemas: docs/guias/instalacao.md.

Ambiente que bloqueia até o Python? Use o modo skills: baixe koine-skills.zip da release e siga o instalar-koine.md dentro do zip.

Atualização

Depois de instalado, atualize para a última versão com um comando:

koine atualizar

Baixa a release mais recente, verifica o SHA256SUMS, refresca o vault (preservando seus domínios) e regenera os wrappers. Roda 100% em Python — sem PowerShell e sem executável — para estações corporativas com política restritiva. Fixe uma versão com KOINE_VERSAO=vX.Y.Z koine atualizar ou aponte um espelho interno com KOINE_BASE_URL. Detalhes em docs/referencias/cli.md.

Conferir os arquivos de configuração

koine validar

Varre o frontmatter da sua configuração e da pasta atual e aponta o que está torto — valor com : sem aspas (o Koine lê, mas outras ferramentas não) e YAML que nem ele consegue ler, com linha e coluna. Não escreve nada.

Primeira sessão em 3 comandos

# 1. Finalizar configuração (o installer já roda isto; repita só para reconfigurar)
koine instalar

# 2. Abrir primeira sessão com Hermes
kn-claude hermes koine
# (substitua kn-claude pelo wrapper do seu cliente: kn-agy, kn-copilot, kn-opencode, kn-codex)

# 3. Dentro da sessão, Hermes inicia automaticamente:
#    /kn-01-recebe-usuario

/kn-01-recebe-usuario é a skill de onboarding. Hermes te entrevista em 4 rodadas e configura:

• Seu arquivo de usuário (idioma, fuso horário, estilo)
• Seu primeiro escopo de trabalho
• Sua primeira pasta de trabalho real (com CONTEXTO.md)
• Seu primeiro agente operacional (criado via /kn-03-cria-agente)

Para o passo a passo completo (incluindo pré-requisitos detalhados, estimativas de tempo, e resolução de problemas): ver docs/tutoriais/onboarding-completo.md.

Skills kn-*

Distribuídas no vault e disponíveis após koine instalar:

Skill	Quando invocar
/kn-01-recebe-usuario	Onboarding inicial (1× por usuário; Hermes dispara automaticamente em pasta de bootstrap)
/kn-02-mantem-catalogo	Criar/ajustar arquivo do usuário, escopo, contexto de pasta, ou domínio
/kn-03-cria-agente	Criar novo agente operacional especializado em um tipo de trabalho
/kn-04-conecta-o-paseo	Preparar o acesso de fora do computador — opcional, só para quem vai operar do celular
/kn-11-mantem-referencia	Catalogar conhecimento (pessoa, decisão, aprendizado) durante o trabalho
/kn-12-prepara-contexto	Materializar o contexto na pasta e regenerar os índices de domínio sem o binário (modo skills)
/kn-13-sabatina-plano	Sabatinar um plano ou processo — entrevista que confere o que você afirma contra a evidência real
/kn-14-organiza-workspaces	Registrar pastas de trabalho no orquestrador, para abri-las do celular
/kn-21-escreve-design	Escrever o DESIGN.md de uma marca do escopo — cores, tipografia, tom visual
/kn-22-gera-imagem	Gerar imagem na identidade da marca via imagio
/kn-23-gera-marca-prelo	Derivar o payload de marca do prelo para PDF na identidade
/kn-24-gera-pdf	Converter um .md do trabalho em PDF na marca do escopo
/kn-99-encerra-sessao	Fechar sessão escrevendo diário e distribuindo aprendizados

Detalhes em docs/referencias/habilidades.md.

Acesso de fora do computador

Além do terminal, o Koine tem um caminho para orquestrador de sessões — o que permite abrir uma sessão pelo celular, na sua pasta de trabalho, com o seu contexto e o seu agente, ditando em português.

koine paseo-info            # quais dos seus clientes têm esse caminho

Dois dos cinco clientes não têm caminho por aí, pelo jeito como sobem — e configurá-los assim mesmo falha em silêncio, com uma sessão que responde sem o seu contexto. Por isso a configuração é uma conversa guiada (/kn-04-conecta-o-paseo), não um trecho para copiar.

Comece pelo tutorial de acesso pelo celular. A explicação diz o que muda, o que não muda e o que custa.

Clientes IA suportados

Cliente	Comando	Mecanismo
Claude Code	kn-claude	--add-dir + bundle em cache
Antigravity (agy)	kn-agy	--add-dir + bundle em cache
GitHub Copilot CLI	kn-copilot	COPILOT_CUSTOM_INSTRUCTIONS_DIRS + bundle em cache
OpenCode	kn-opencode	OPENCODE_CONFIG + JSON em cache
Codex CLI	kn-codex	-c model_instructions_file + arquivo em cache

Em nenhum deles o Koine escreve na sua pasta de trabalho. O pacote de contexto é descartável e vive em ~/.cache/koine/.

Documentação

Começando do zero? Tutorial — Onboarding completo

Quer usar do celular? Tutorial — acesso pelo celular

• Tutoriais — passo a passo para começar
• Guias — como resolver problemas específicos, incluindo a marca do escopo (família kn-2N: pré-requisitos, ordem de uso, o que cada skill produz) e sabatinar um processo (como preparar e conduzir a /kn-13); para o acesso remoto, o guia e voz em português com serviço pago
• Referências — CLI, schema do CONTEXTO.md, habilidades, o que o Koine escreve no orquestrador, formato OKF
• Explicações — por que cada decisão de design, incluindo por que um orquestrador de sessões
• Decisões — ADRs

Desenvolvimento

Ver CONTEXTO.md para stack, padrões e como contribuir.

python3 -m venv .venv && .venv/bin/pip install pytest
.venv/bin/pytest -q

Licença

MIT.