Instalação

O Apothem é instalado em menos de dois minutos e funciona junto da sua configuração de harness existente. Cada via executa o mesmo motor autocontido — a árvore de código-fonte carrega suas dependências incorporadas e é executada a partir de um checkout no Python 3.10 ou mais recente do sistema (consulte o runtime autocontido).

Dois pré-requisitos são compartilhados por todas as vias: o Python 3.10 ou mais recente do sistema no PATH, com os pacotes click e rich importáveis sob ele. O shim do npm (canal 2), a extensão da família VS Code (canal 4) e os bootstraps de linha de comando (canais 5–7) precisam adicionalmente do Node.js 18 ou mais recente para executar o npx. O Python 3.10 e o Node.js 18 e 20 já passaram do fim de vida upstream; eles continuam suportados e testados, mas versões mais recentes são preferíveis (consulte Pré-requisitos de relance). A seção própria de cada canal abaixo repete seus pré-requisitos exatos, um comando pronto para copiar e uma etapa de verificação.

Escolha um canalCopy Anchor Link

Oito canais de instalação estão disponíveis. Escolha pela forma como você já trabalha.

Cada via é idempotente: executar novamente é seguro e converge para o mesmo estado.

1. Plugin do Claude CodeCopy Anchor Link

Pré-requisitos: Claude Code e o Python 3.10+ do sistema no PATH.

A via do plugin é executada inteiramente dentro do Claude Code. Ela empacota o motor do Apothem com seus comandos de barra, trabalhadores delegados, skills, regras e hooks, todos executáveis a partir da árvore autocontida do plugin:

/plugin marketplace add ahmed-g-gad/apothem
/plugin install apothem@apothem

Após a instalação, o conjunto de comandos do Apothem, os trabalhadores delegados incluídos, as skills e os quatro output-styles (escolha um com /output-style ou a partir de /config) ficam disponíveis em cada sessão do Claude Code. O plugin distribui cada comando como uma skill, um SKILL.md com o detalhe que carrega sob demanda em uma pasta references/ ao lado dele, então o Claude Code o invoca com o prefixo do plugin: /apothem:plan-spec, /apothem:security-audit e os demais. Dois nomes são ocupados pelo próprio Claude Code: /plan entra no modo de planejamento e /code-review executa a revisão integrada, então digite /apothem:plan e /apothem:code-review para os comandos do Apothem. Quando o motor do Apothem é instalado no Claude Code em vez do plugin, as mesmas skills são gravadas em ~/.claude/skills/ sem prefixo, e uma skill pessoal code-review substitui o /code-review integrado (seu alias /review ainda executa o integrado). Dois nomes, projectify e workflow, também são skills nativas; a skill nativa é a que o plugin e a instalação do motor distribuem, e não uma skill derivada do comando. Consulte Claude Code para ver como os comandos são divididos, e Comandos de barra para o catálogo completo de comandos.

Verifique: execute /plugin dentro do Claude Code e confirme que apothem aparece listado como instalado, ou consulte o relatório de desvio a partir de um terminal:

npx @ahmed-g-gad/apothem verify --harness claude-code

2. Shim do npm (npx)Copy Anchor Link

Pré-requisitos: Node.js 18+ (para o npx) e o Python 3.10+ do sistema no PATH. O shim localiza o interpretador e encaminha cada comando da CLI para o motor incluído — nada é colocado permanentemente no seu sistema. Ele tenta python3, python e depois py -3, nessa ordem; defina APOTHEM_PYTHON como o caminho de um interpretador para tentá-lo primeiro, que é o que você precisa quando o Python está instalado mas não está no PATH, ou quando há várias versões e você quer uma específica. O interpretador que você indicar ainda precisa passar na verificação do Python 3.10+; quando não passa, o shim recorre a python3, python e depois py -3.

npx @ahmed-g-gad/apothem install --harness claude-code

Em uma máquina sem perfil, este primeiro install cria o perfil inicial em ~/.config/apothem/profile.yaml e informa isso. Seus campos de identidade são marcadores de posição: personalize-os (npx @ahmed-g-gad/apothem profile edit) e depois execute o comando novamente com update no lugar de install para aplicá-los.

Ele também é executado diretamente a partir do repositório:

npx github:ahmed-g-gad/apothem install --harness claude-code

Cada comando da referência da CLI funciona nesta forma; use npx @ahmed-g-gad/apothem no lugar de apothem. Esta também é a via de instalação para o OpenCode e para todas as outras ferramentas que não expõem um registro separado de plugins ou extensões — o Apothem as sincroniza diretamente no diretório de configuração nativo delas (npx @ahmed-g-gad/apothem install --harness opencode).

Verifique:

npx @ahmed-g-gad/apothem --version
npx @ahmed-g-gad/apothem verify --harness claude-code

3. Instaladores de uma única etapaCopy Anchor Link

Pré-requisitos: o Python 3.10+ do sistema no PATH (o instalador se oferece para adicionar os pré-requisitos click / rich para você); git e gpg para a instalação pela rede, que clona o código-fonte e verifica a tag de lançamento assinada (o Git for Windows traz ambos).

Os scripts de instalação resolvem a tag de lançamento assinada mais recente, verificam sua assinatura, colocam a árvore de código-fonte do Apothem em ~/.apothem nessa tag, criam um perfil inicial quando nenhum existe, materializam seu primeiro harness e verificam o resultado, tudo em uma única execução. O perfil inicial traz campos de identidade com marcadores de posição: edite-o e depois execute apothem update --harness <name> para aplicar os seus. Executar novamente é idempotente: uma árvore existente recebe um novo checkout na tag resolvida e o harness é materializado novamente. A instalação verificada e fixada por tag é a via padrão e recomendada.

Importe primeiro, uma vez, a chave de assinatura do mantenedor. O instalador para quando a chave não está no seu chaveiro. Confira se a impressão digital é 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163, valor publicado em SECURITY.md. No Windows, o git verify-tag lê o chaveiro do gpg que vem com o Git for Windows, por isso a importação roda pelo bash do próprio Git:

curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import
gpg --fingerprint 70396FED9C634163

& "$env:ProgramFiles\Git\bin\bash.exe" -c 'curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import && gpg --fingerprint 70396FED9C634163'

curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

irm https://apothem.ahmedgad.com/install.ps1 | iex

Os mesmos scripts vêm em um checkout sob scripts/installer/ — install, uninstall e update nas formas .sh, .ps1 e .bat — de modo que você pode executá-los diretamente após clonar:

APOTHEM_HARNESS=claude-code sh scripts/installer/install.sh                                 # POSIX
$env:APOTHEM_HARNESS = 'claude-code'; pwsh -NoProfile -File scripts/installer/install.ps1   # Windows

Modelo de confiançaCopy Anchor Link

Sem APOTHEM_REF definido, o instalador resolve a tag de lançamento vMAJOR.MINOR.PATCH mais alta e faz o checkout dela — nunca da branch main em movimento. Antes que qualquer configuração seja materializada, a assinatura da tag obtida é verificada com git verify-tag; uma tag não assinada, adulterada ou não verificável aborta a instalação antes que qualquer coisa seja gravada. Uma tag assinada cuja chave pública do mantenedor ainda não está no chaveiro local aborta, em vez disso, com orientações para importar a chave: importe a chave como mostrado acima, confira a impressão digital com o valor publicado em SECURITY.md e execute novamente. Fixe um lançamento específico com APOTHEM_REF:

APOTHEM_REF=vMAJOR.MINOR.PATCH sh -c "$(curl -fsSL https://apothem.ahmedgad.com/install.sh)"

Substitua vMAJOR.MINOR.PATCH por uma tag da página de lançamentos. A tag de lançamento mais antiga é uma tag leve, sem assinatura própria, de modo que a verificação de tag aborta nela mesmo que seu commit seja assinado; todas as tags de lançamento posteriores são anotadas e assinadas. A seção de assinatura de lançamentos do SECURITY.md lista cada tag e como verificá-la.

Substituições explícitas relaxam o padrão. APOTHEM_ALLOW_UNVERIFIED=1 rebaixa uma falha de verificação para um aviso e prossegue, para uso air-gapped, local ou para instalar um lançamento anterior à assinatura de tags. APOTHEM_REF=main faz o checkout da branch em movimento sem verificação somente junto com APOTHEM_ALLOW_UNVERIFIED=1. Com APOTHEM_REF=main sozinho, o instalador busca main em APOTHEM_HOME e, em seguida, aborta antes que qualquer configuração seja materializada, porque uma branch não é uma tag de lançamento assinada. Um checkout local via APOTHEM_SOURCE não busca nada e pula a verificação.

APOTHEM_VERIFY=checksum é o meio-termo para um host que ainda não tem a chave pública do mantenedor: em vez de clonar, o instalador baixa o arquivo de plataforma do lançamento e seu SHA256SUMS, aborta em caso de divergência de digest antes de extrair qualquer coisa e avisa que um digest correspondente prova que o arquivo é aquele que o lançamento lista, não quem o publicou.

O motor então é executado diretamente a partir da árvore colocada. Todas as dependências de terceiros, exceto click e rich, estão incorporadas dentro da árvore de código-fonte, e o próprio ponto de entrada coloca esse diretório de dependências incorporadas no sys.path:

PYTHONPATH="$HOME/.apothem/src" python -m apothem <command>

Ambos os scripts leem as mesmas variáveis de ambiente de configuração (APOTHEM_HOME, APOTHEM_REPO, APOTHEM_REF, APOTHEM_ALLOW_UNVERIFIED, APOTHEM_VERIFY, APOTHEM_RELEASE_BASE, APOTHEM_SOURCE, APOTHEM_HARNESS, APOTHEM_PROFILE, APOTHEM_SKIP_VERIFY, APOTHEM_AUTO_INSTALL_DEPS, APOTHEM_BIN_DIR); consulte Variáveis de ambiente do instalador para a tabela completa e Runtime autocontido para entender como funciona o modelo de invocação python -m.

O comando apothem. Após uma instalação bem-sucedida, o instalador grava um shim apothem que encaminha para o motor incluído — no POSIX em $HOME/.local/bin, no Windows em %LOCALAPPDATA%\Microsoft\WindowsApps (um diretório de usuário que já está no PATH padrão do Windows). O instalador nunca edita seu PATH. Assim que o diretório estiver no PATH, você executa apothem <command> diretamente, sem PYTHONPATH manual.

Verifique:

apothem verify --harness claude-code

# or, before the shim is on PATH, from the bundled source:
PYTHONPATH="$HOME/.apothem/src" python -m apothem verify --harness claude-code

4. Extensão da família VS CodeCopy Anchor Link

Pré-requisitos: VS Code, Node.js 18+ e o Python 3.10+ do sistema no PATH.

A extensão Apothem for VS Code está disponível no Visual Studio Marketplace como ahmed-g-gad.apothem-vscode: instale-a pela visualização Extensões ou com code --install-extension ahmed-g-gad.apothem-vscode. Ela também é instalada a partir de um pacote apothem.vsix: code --install-extension apothem.vsix, ou o comando Install from VSIX… do editor. O fluxo de trabalho de lançamento assina o pacote e o anexa a cada GitHub Release. Os lançamentos publicados antes de o fluxo de trabalho empacotar a extensão não trazem nenhum .vsix; quando o lançamento mais recente não o traz, gere o pacote a partir de um checkout com a versão do vsce travada em tools/vsce/ (essa versão do vsce exige Node.js 22 ou posterior): execute npm ci --prefix tools/vsce --ignore-scripts e depois cd vscode-extension && ../tools/vsce/node_modules/.bin/vsce package --no-dependencies --out apothem.vsix. Uma cópia instalada a partir de um apothem.vsix anterior tem o identificador ahmed-g-gad.apothem; desinstale-a (code --uninstall-extension ahmed-g-gad.apothem) para que as duas cópias não registrem os mesmos comandos. Uma única extensão cobre os editores da família VS Code. Seus comandos de paleta (Apothem: Install, Verify, Update, Uninstall, Doctor) executam o mesmo motor por meio do executor configurado (npx @ahmed-g-gad/apothem@<extension version> por padrão, de modo que a extensão executa a versão do motor com a qual foi distribuída; aponte a configuração de usuário apothem.runner para um checkout local para executar a partir do código-fonte). Install, Verify, Update e Uninstall perguntam sobre qual harness agir, oferecendo primeiro o harness do próprio editor; all é uma opção, nunca o padrão. A configuração apothem.runner tem escopo de máquina, de modo que um workspace não pode alterá-la, e a extensão é executada somente em um workspace confiável.

Verifique: execute o comando Apothem: Verify a partir da paleta de comandos do editor, ou a partir de um terminal:

npx @ahmed-g-gad/apothem verify --harness claude-code

5. Bootstrap de linha de comando (host de extensão)Copy Anchor Link

Pré-requisitos: sua ferramenta host de linha de comando, Node.js 18+ e o Python 3.10+ do sistema no PATH.

Instale o Apothem como uma extensão diretamente a partir do repositório — o comando traz o host e o slug de harness exatos:

gemini extensions install https://github.com/ahmed-g-gad/apothem

Esta extensão é um bootstrap, não a instalação completa por si só: ela carrega um arquivo de contexto do Apothem e adiciona um comando /apothem que invoca o motor pelo shell (npx @ahmed-g-gad/apothem). Materialize o harness completo executando a instalação por meio dela:

npx @ahmed-g-gad/apothem install --harness gemini-cli --project .

Verifique:

npx @ahmed-g-gad/apothem verify --harness gemini-cli --project .

6. Bootstrap de linha de comando (host qwen-code)Copy Anchor Link

Pré-requisitos: sua ferramenta host de linha de comando, Node.js 18+ e o Python 3.10+ do sistema no PATH.

Instale o Apothem como uma extensão --harness qwen-code diretamente a partir do repositório:

qwen extensions install ahmed-g-gad/apothem

Como a extensão do canal 5, esta é um bootstrap: ela carrega um arquivo de contexto do Apothem e invoca o motor pelo shell. Materialize o harness completo executando a instalação por meio dela:

npx @ahmed-g-gad/apothem install --harness qwen-code

Verifique:

npx @ahmed-g-gad/apothem verify --harness qwen-code

7. Bootstrap de linha de comando (host de plugin)Copy Anchor Link

Pré-requisitos: sua ferramenta host de linha de comando, Node.js 18+ e o Python 3.10+ do sistema no PATH.

Adicione o repositório como um marketplace de plugins e depois instale o plugin — o comando traz o host e o slug de harness exatos:

codex plugin marketplace add ahmed-g-gad/apothem --sparse .agents/plugins --sparse plugins/apothem
codex plugin add apothem@apothem

Os dois caminhos --sparse buscam apenas a listagem do marketplace e o plugin, não o repositório inteiro; um clone completo pode ultrapassar o limite de clone de 30 segundos do host em um disco lento, como uma unidade do Windows sob o WSL.

Como as extensões dos canais 5 e 6, este é um bootstrap que invoca o motor pelo shell. O plugin inclui uma skill de entrada; seu manifesto é um plugin.json na raiz, e a página de harness do host do plugin descreve o layout e o que o plugin deixa para o motor. Materialize o harness completo executando a instalação por meio dele:

npx @ahmed-g-gad/apothem install --harness codex

Verifique:

npx @ahmed-g-gad/apothem verify --harness codex

8. Motor direto (python -m apothem)Copy Anchor Link

Pré-requisitos: o Python 3.10+ do sistema com os pacotes click e rich importáveis, além de um checkout do repositório. Node.js não é necessário.

Execute o motor diretamente a partir de um clone. O ponto de entrada coloca as dependências incorporadas (src/apothem/_vendor) no sys.path, de modo que, com click e rich importáveis, PYTHONPATH=src é toda a configuração necessária:

git clone https://github.com/ahmed-g-gad/apothem
cd apothem
PYTHONPATH=src python -m apothem install --harness claude-code

Assim como no shim do npm, um primeiro install em uma máquina sem perfil cria o perfil inicial em ~/.config/apothem/profile.yaml e continua.

Verifique:

PYTHONPATH=src python -m apothem verify --harness claude-code

Verifique qualquer instalaçãoCopy Anchor Link

Cada canal acima indica seu próprio comando de verificação. As duas formas gerais são:

PYTHONPATH="$HOME/.apothem/src" python -m apothem verify --harness claude-code

npx @ahmed-g-gad/apothem verify --harness claude-code

Substitua o nome do harness pelo adaptador que você instalou; consulte a lista de harnesses para todos os nomes suportados. Para verificar de uma só vez cada adaptador instalado (sua verificação e seus comandos de hook), execute doctor no lugar de verify --harness NAME, na mesma forma que você usou acima: apothem doctor, PYTHONPATH="$HOME/.apothem/src" python -m apothem doctor ou npx @ahmed-g-gad/apothem doctor. Para a via do plugin, execute /plugin dentro do Claude Code e confirme que apothem aparece listado como instalado.

Pré-requisitos de relanceCopy Anchor Link

• Python 3.10 ou posterior — as vias que o localizam fazem isso pelo nome, e os nomes diferem de uma via para outra. O shim do npm tenta python3, python e depois py -3. Os instaladores tentam python3, python e os nomes com versão, de python3.14 até python3.10.
• click e rich importáveis sob esse interpretador — as duas dependências voltadas ao terminal que o motor não incorpora. Os instaladores verificam ambas, indicam o que estiver faltando e se oferecem para instalá-lo para você — com sua confirmação, ou automaticamente com --yes (-Yes no PowerShell) ou APOTHEM_AUTO_INSTALL_DEPS=1. Em todos os outros canais, um pacote ausente interrompe o motor com um erro (código de saída 1) que indica o comando exato para o interpretador que ele encontrou, com as restrições de versão contra as quais o Apothem é testado (<interpreter> -m pip install "click==…" "rich>=…"); com --json, o mesmo erro chega como um envelope JSON com o código runtime.dependency_missing.
• Node.js 18 ou posterior — apenas as vias que executam npx: o shim do npm (2), a extensão da família VS Code (4) e os bootstraps de linha de comando (5–7).
• Runtimes em fim de vida. O Python 3.10 chegou ao fim de vida upstream em 2026-10-01, e o Node.js 18 e o 20, em 2025-04-30 e 2026-04-30. O Apothem ainda os suporta como seus pisos declarados e testa cada um deles no CI, mas eles não recebem mais correções de segurança upstream, então prefira o Python 3.11 ou mais recente e o Node.js 22 ou mais recente. A política de pisos de runtime explica como um piso é elevado.
• Git — apenas a via do instalador, e somente para a forma pela rede (o script clona o código-fonte; um checkout local não precisa de clone).
• Claude Code — apenas a via do plugin. O VS Code e a ferramenta host própria de cada bootstrap de linha de comando são necessários apenas para o seu próprio canal (4–7).

Próximos guiasCopy Anchor Link