Primeiros passos: do zero a um harness funcional

Este tutorial conduz você por toda a sua primeira configuração do Apothem. Você começa sem nada instalado e termina com uma configuração de harness real — gerada a partir de um perfil que você escreveu, verificada e confirmada como funcional. Reserve cerca de quinze minutos. Todo comando abaixo é real e pode ser copiado, colado e executado.

Ao final, você terá:

1. Instalado o Apothem pelo instalador por script.
2. Editado o perfil compartilhado que conduz todos os harnesses.
3. Materializado a configuração nativa de um harness.
4. Verificado essa configuração e confirmado uma primeira execução funcional.

Usaremos o Claude Code como harness de exemplo do início ao fim, porque ele é o padrão do instalador. As mesmas etapas se aplicam a qualquer harness suportado — troque o nome quando chegar à lista de harnesses.

O que você precisa antesCopy Anchor Link

• Um shell do tipo Unix (macOS, Linux ou WSL). O instalador do PowerShell cobre o Windows; este tutorial mostra o caminho do bash.
• Python 3.10 ou mais recente no seu PATH. Verifique com python3 --version.
• As duas bibliotecas de runtime que o motor importa do seu interpretador: click e rich. O restante da pilha (pyyaml, jsonschema) vem incorporado à árvore, então apenas essas duas precisam ser importáveis. Se click ou rich estiver ausente, o instalador para e imprime o comando de instalação. O comando de uma linha envia o script para o bash por um pipe, então ele não pode perguntar; defina APOTHEM_AUTO_INSTALL_DEPS=1 (por exemplo, curl -fsSL https://apothem.ahmedgad.com/install.sh | APOTHEM_AUTO_INSTALL_DEPS=1 bash) ou instale primeiro os dois pacotes.

O Apothem é distribuído como uma árvore de código-fonte empacotada, e não como um pacote publicado — não existe uma etapa pip install. O instalador clona a árvore e executa o motor diretamente a partir dela.

Etapa 1 — Instalar o ApothemCopy Anchor Link

Execute o instalador via rede:

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

O instalador executa estas etapas:

1. Verificação de pré-requisitos. O instalador encontra um interpretador Python 3.10+ real e confirma que as duas bibliotecas de runtime (click e rich) são importáveis. Se uma estiver faltando, ele a nomeia, para e imprime o comando de instalação; defina APOTHEM_AUTO_INSTALL_DEPS=1 para instalar sem pedir confirmação, já que uma execução por pipe não pode perguntar.
2. Posicionamento do código-fonte. A árvore empacotada é clonada em ~/.apothem (substitua esse local pela variável de ambiente APOTHEM_HOME). Uma nova execução faz checkout da tag de lançamento no clone existente, em vez de duplicá-lo.
3. Inicialização do perfil. Se você ainda não tem um perfil, o instalador copia o perfil de exemplo para ~/.config/apothem/profile.yaml, instala e verifica o Claude Code a partir dele na mesma execução, e avisa que os campos de identidade são marcadores de posição.

Você pode orientar a instalação com variáveis de ambiente. As que você provavelmente mais usará:

# Install a different user-scope harness and name the profile path explicitly.
# Put the variables on the `bash` side of the pipe: a variable placed before
# `curl` reaches only curl, not the installer.
curl -fsSL https://apothem.ahmedgad.com/install.sh | \
  APOTHEM_HARNESS=codex \
  APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
  bash

O instalador instala apenas harnesses de escopo de usuário. Instale depois um harness de escopo de projeto, indicando o projeto:

apothem install --harness cursor --project /path/to/project

Outras variáveis reconhecidas são APOTHEM_REPO e APOTHEM_REF (qual remoto clonar e qual ref do git fazer checkout; sem definir, resolve e verifica a tag de lançamento assinada mais recente; defina uma tag para fixá-la, ou main para a branch móvel, que também exige APOTHEM_ALLOW_UNVERIFIED=1, pois uma branch não é uma tag assinada), APOTHEM_ALLOW_UNVERIFIED=1 (rebaixa uma falha na verificação da assinatura da tag para um aviso e permite uma ref que não seja tag, como main), APOTHEM_SOURCE (usa um checkout local existente em vez de clonar) e APOTHEM_SKIP_VERIFY=1 (pula a verificação pós-instalação, que queremos executar, então deixe-a sem definir).

Quando o instalador conclui uma execução completa, ele imprime um banner que mostra como invocar o motor. Ele coloca um shim apothem no seu PATH (POSIX: $HOME/.local/bin; Windows: %LOCALAPPDATA%\Microsoft\WindowsApps), de modo que, assim que esse diretório estiver no PATH, você executa o motor diretamente:

apothem <command>

Se não foi possível posicionar o shim — ou se o diretório dele ainda não está no PATH —, o banner imprime uma alternativa autocontida que não precisa de shim:

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

O restante deste tutorial escreve apothem <command>; se você estiver usando a forma alternativa, anteponha o prefixo exato que o banner do instalador imprimiu.

Etapa 2 — Tornar o perfil seuCopy Anchor Link

O perfil compartilhado em ~/.config/apothem/profile.yaml é a única fonte da verdade. Cada adaptador de harness o lê e deriva dele a configuração nativa desse harness. Edite-o uma vez, e todo harness que você instalar permanece consistente.

Abra-o no editor do motor ou em qualquer editor de texto:

apothem profile edit

Um perfil mínimo e válido tem esta aparência:

identity:
  name: "Example User"
preferences:
  style: "concise"
rules:
  - "Validate external input before writing files."

Substitua o name de marcador de posição pelo seu e adicione as regras que você quer que todo harness aplique. Mantenha fictícios os valores de exemplo — o perfil foi feito para poder ser compartilhado com segurança.

Confirme que o motor lê suas edições de volta sem problemas:

apothem profile show --json

Se o YAML estiver malformado, é aqui que você verá isso — corrija e execute novamente antes de seguir em frente.

Etapa 3 — Materializar uma configuração de harnessCopy Anchor Link

Se a sua execução da Etapa 1 criou o perfil, ela já instalou o Claude Code a partir da identidade de marcador de posição. Edite o perfil na Etapa 2 e, em seguida, aplique a sua identidade com:

apothem update --harness claude-code

apothem install --harness claude-code

Isso lê o seu perfil e grava a configuração nativa do Claude Code. Para ver todos os harnesses que você pode mirar:

apothem harnesses list

Alguns harnesses têm escopo de projeto em vez de escopo de usuário, e esses precisam de um caminho --project para que o adaptador saiba onde gravar:

apothem install --harness cursor --project .

Etapa 4 — Verificar e confirmar uma primeira execuçãoCopy Anchor Link

Materializar é só metade da história. Agora confirme que a configuração foi gravada corretamente:

apothem verify --harness claude-code

verify checa se os arquivos de configuração gerenciados do harness existem e podem ser analisados. Adicione --profile PATH e ele também falha quando um arquivo instalado divergiu do que esse perfil produziria. Uma execução limpa significa que a materialização foi bem-sucedida.

Para uma verificação de saúde da máquina inteira, abrangendo todos os adaptadores registrados, execute:

apothem doctor

doctor verifica cada harness instalado (ele deve passar na verificação, e os comandos de hook registrados devem iniciar) e sai com código diferente de zero se qualquer verificação falhar. Os harnesses que você não instalou são listados, mas não o fazem falhar, então ele é um portão útil em um script de configuração.

Sua primeira execução. Abra o harness que você acabou de configurar — o Claude Code, no nosso exemplo — e inicie uma sessão em qualquer projeto. As regras e preferências que você escreveu no perfil agora fazem parte do comportamento dessa ferramenta. Essa é a primeira execução funcional: o perfil que você editou na Etapa 2 está moldando uma sessão real.

O que você construiuCopy Anchor Link

Partindo de uma máquina vazia, você instalou o Apothem, escreveu um perfil compartilhado, materializou a partir dele a configuração nativa de um harness, verificou o resultado e confirmou que ele funciona. O perfil é o artefato duradouro — altere-o uma vez e execute novamente apothem update --harness <name> para propagar a mudança para qualquer harness.

Para onde seguirCopy Anchor Link

• Adicione outra ferramenta. A lista de harnesses cobre todas as plataformas suportadas e o nome de adaptador de cada uma. Repita a Etapa 3 com um novo --harness.
• Aprofunde-se em uma única tarefa. As receitas práticas cobrem adicionar um harness, editar o perfil e conduzir o instalador. Os guias de uso cobrem escrever regras, criar planos e executar o conformity gate.
• Consulte detalhes específicos. A referência documenta cada classe de artefato e o schema do perfil, e a referência da CLI cobre todos os comandos. Cada adaptador tem sua própria página em harnesses.
• Planeje trabalho que dura além de uma sessão. O planejamento retomável explica como o Apothem externaliza o trabalho de longa duração para uma suíte .apothem/plans/ local do projeto, de modo que uma nova sessão em qualquer máquina o retome no ponto em que parou.

Próximo passo recomendadoCopy Anchor Link

Execute apothem doctor para checar a sua configuração — ele relata o estado de cada adaptador registrado, de modo que o harness que você acabou de instalar aparece como saudável, enquanto os demais aparecem como ainda não instalados — antes de passar a adicionar mais harnesses.