ProductOS Agent

1. O que é o ProductOS Agent

O ProductOS Agent é um executável pequeno que você instala na sua máquina. Ele entra como você, vincula seus checkouts git locais aos repositórios que seus workspaces conectam e detecta as ferramentas de código instaladas: Claude Code e Codex.

Quando você aciona Executar na janela Entregar de uma dor, o agente executa a definição de mudança no checkout vinculado: edita, roda os testes, cria um branch, faz o commit e abre um pull request.

A execução aparece numa gaveta no ProductOS, onde você acompanha cada passo e responde às perguntas da ferramenta. O código nunca sai da sua máquina para o ProductOS; só os eventos da execução.

2. Requisitos

Na máquina onde o agente vai rodar, você precisa de:

• git instalado.
• Claude Code (comando claude) ou Codex CLI (comando codex), instalado e com login feito nesta máquina. Pode ter os dois.
• Um repositório do GitHub conectado no seu workspace do ProductOS, e um checkout dele nesta máquina.
• Opcional: o GitHub CLI (comando gh), para que o agente abra o pull request ao final.

3. Instalação

Um binário estático para Linux, macOS e Windows, amd64 e arm64. Escolha o comando da sua plataforma:

macOS

brew install productos-technology/tap/productos-agent

Linux e macOS

curl -fsSL https://productos.technology/install.sh | sh

Windows

winget install ProductOS.Agent

Ou baixe um arquivo nas releases no GitHub e coloque o binário productos-agent no seu PATH. As somas de verificação estão no arquivo checksums.txt de cada versão.

4. Primeiro uso

1. Entre com a sua conta. O comando abre o navegador, você aprova o agente e esta máquina é registrada como um dispositivo seu. O servidor é productos.technology; um ProductOS hospedado por você é passado como argumento.

   productos-agent login

2. Vincule um checkout. O remoto origin dele precisa ser um repositório conectado no seu workspace; se não for, o agente lista o que o ProductOS esperava.

   productos-agent link ~/code/my-app

3. Mantenha o agente conectado: em primeiro plano, ou como um serviço que inicia com a sua sessão (systemd no Linux, launchd no macOS, Agendador de Tarefas no Windows).

   productos-agent run
   productos-agent service install

4. No ProductOS, abra uma dor, acione Entregar, escolha esta máquina e a ferramenta e acione Executar.

productos-agent status mostra o servidor, o login, as ferramentas, o dispositivo e os checkouts vinculados; productos-agent doctor verifica cada requisito.

5. Como funciona uma execução

Do clique em Executar ao pull request, o agente segue os mesmos passos sempre:

1. A execução chega pelo canal do dispositivo e o agente responde em até 15 segundos.
2. O checkout precisa estar limpo. O agente busca o branch padrão no origin e cria a partir dele um branch com o nome que o ProductOS definiu, como productos/mob-p7-offline-drafts-are-lost.
3. A ferramenta roda sem supervisão, com a definição de mudança como instrução: edita o código e roda os testes.
4. Cada mensagem, chamada de ferramenta, arquivo alterado, teste e linha de log vira um evento na gaveta do ProductOS, em tempo real.
5. Se a ferramenta fizer uma pergunta, a execução espera. Você responde na gaveta e a sessão continua de onde parou.
6. Ao terminar, o trabalho é commitado como MOB-P7: Offline drafts are lost, com o trailer ProductOS: MOB-P7, o branch é enviado e, se gh estiver instalado, um pull request é aberto. A gaveta mostra o branch, o commit, o link do pull request e um resumo.

Você pode cancelar a qualquer momento pela gaveta: o processo da ferramenta é encerrado. Uma execução que passe de 2 horas é encerrada pelo agente.

Uma execução sempre termina num resultado legível: “Código alterado”, com a branch, o commit e o pull request; “Nada a mudar”, quando a ferramenta encontrou a mudança já no código (ela diz onde; uma pessoa confirma no painel); ou uma falha com o motivo. O que a ferramenta editou antes de uma falha ou de um cancelamento fica commitado na branch da execução, e a próxima execução parte de um checkout limpo.

6. Atualizações

Antes de cada execução, o agente compara a própria versão com o último release que o ProductOS conhece. Se estiver atrasado, ele se atualiza primeiro (o arquivo é conferido contra os checksums do release) e só então executa a mudança, já na versão nova. Ele nunca se atualiza no meio de uma execução, e uma atualização que falha nunca derruba a execução.

Com o agente ocioso, a mesma atualização acontece assim que ele souber de uma versão nova. Você também pode atualizar à mão, ou só conferir o que há:

productos-agent update
productos-agent update --check

Instalado pelo Homebrew ou pelo winget, o agente não se substitui: ele imprime o comando do gerenciador de pacotes. Uma máquina abaixo da versão mínima que o ProductOS aceita não inicia execuções até atualizar; o diálogo Entregar avisa.

Para desligar a atualização automática, defina "auto_update": false no config.json do agente ou exporte PRODUCTOS_AGENT_NO_UPDATE=1.

7. Segurança

• O agente só executa em checkouts que você vinculou, e um checkout só é vinculado quando o remoto dele corresponde a um repositório conectado no seu workspace. O servidor confere isso a cada execução.
• O dispositivo pertence à sua conta. Só você pode iniciar execuções nele; para qualquer outra pessoa, ele não existe.
• Os tokens ficam no chaveiro do sistema operacional. Os tokens de acesso duram uma hora e são renovados com rotação.
• O agente nunca recebe cookies, tokens CSRF nem segredos de ninguém. A definição de mudança não traz o nome de nenhum cliente.
• Para revogar um dispositivo, use Conta e depois Dispositivos no ProductOS, ou productos-agent logout na máquina. Isso cancela as execuções em andamento e desfaz os vínculos.

8. Problemas comuns

Dispositivo offline

O agente não está rodando ou não fala com o servidor há mais de 90 segundos. Veja o estado e volte a conectar, em primeiro plano ou pelo serviço:

productos-agent status
productos-agent run
productos-agent service start

Repositório não vinculado

A dor pertence a um produto cujo repositório não tem checkout vinculado nesta máquina. Entre no checkout e vincule:

cd ~/code/my-app
productos-agent link

Ferramenta não encontrada

A ferramenta escolhida não está no PATH desta máquina ou não tem login. Instale o Claude Code ou o Codex, entre na ferramenta e confira:

productos-agent doctor

--verbose em qualquer comando também escreve o log no terminal. O log estruturado fica em agent.log, no diretório de estado do agente; tokens e definições de mudança nunca são gravados.

9. Código e licença

O código do agente é aberto, em github.com/productos-technology/productos-agent, sob a licença MIT.

O contrato entre o agente e o servidor está em docs/reference/agent-protocol.md, no repositório do ProductOS.