Codex Team

Linux, Python 3.10+, Git, tmux e Codex CLI autenticado. Compatibilidade conferida com Codex CLI 0.163.0 e tmux 3.3a. Usa a autenticação e o modelo configurados no Codex local; não instala SDK nem exige uma chave de API separada.

Instalar pelo pip

python3 -m pip install codex-team

Em um Python gerenciado pelo sistema operacional, use um ambiente virtual ou pipx install codex-team. Git, tmux e Codex CLI são dependências externas que precisam estar no PATH. Nenhuma biblioteca Python adicional é necessária.

codex-team --version
codex-team example-config > config.json
# Edite config.json para informar os repositórios reais.
start-git-codex-team --root /caminho/novo-time --agents config.json

O comando completo equivalente é:

codex-team start --root /caminho/novo-time --agents config.json

Também funciona como módulo: python3 -m codex_team --help. Depois da criação, use ./team dentro da pasta do time para adicionar agentes, enviar tarefas e consultar resultados. Fora dela, use por exemplo codex-team --root /caminho/novo-time status.

Iniciar a partir deste checkout

Copie config.example.json para um config.json e substitua as URLs pelos repositórios reais. Repositórios privados precisam de acesso Git/SSH na máquina. Não inclua tokens ou senhas nas URLs.

./ops/start-git-codex-team.sh --root /caminho/novo-time --agents /caminho/config.json

O diretório passado em --root precisa estar vazio ou já pertencer a este gerenciador. Por padrão a raiz é ./codex-team; sem --agents, carrega ./config.json se existir. Sem JSON, inicia apenas o controlador. Também aceita uma lista JSON diretamente, além do objeto com a chave agents. Cada agente exige name e repo; branch é opcional (branch existente no remoto).

Use --no-attach para iniciar sem anexar o terminal. O layout padrão usa painéis lado a lado; --layout windows cria uma janela por agente. Quando não há espaço para mais divisões, um novo agente ganha uma janela própria. Escolha o layout na primeira inicialização. A sessão tem nome derivado da pasta; --session equipe-x permite escolher o nome na primeira inicialização. Não reutilize o mesmo nome para times diferentes.

A raiz passa a ter:

novo-time/
├── .git/                   # Repositório Git raiz, sem commit automático
├── .gitmodules             # Projetos registrados como submódulos
├── AGENTS.md               # Instruções do controlador
├── README.md
├── team                    # Gerenciador local, executável
├── repos/
│   ├── publicapi/          # Submódulo Git
│   └── parceiros/          # Submódulo Git
└── .codex-team/             # Banco, filas, sessões e resultados locais

git submodule add deixa .gitmodules e os gitlinks no índice. O gerenciador não faz commit nem push na raiz ou nos projetos. A raiz ainda não possui remoto; configure um se quiser compartilhar a composição do time. O runtime é local e ignorado pelo Git; os arquivos versionados sozinhos não reinstalam o gerenciador em outra máquina. Preserve essa pasta para retomar este time.

Conversar com o controlador

O painel Controlador é uma sessão interativa do Codex. Você pode pedir:

Adicione um responsável chamado pagamentos para o repositório git@github.com:empresa/pagamentos.git e aguarde as tarefas.

O AGENTS.md instrui o chefe a executar:

./team add --name pagamentos --repo git@github.com:empresa/pagamentos.git

O novo projeto é cadastrado como submódulo e seu painel é aberto. Um responsável inicialmente fica ocioso; não há chamada ao modelo para apenas aguardar. Ao receber uma tarefa, o executor chama codex exec --json, registra seu thread ID e reutiliza a conversa usando codex exec resume nas tarefas seguintes.

Os painéis dos responsáveis mostram mensagens, comandos e resultados da execução. São consoles do executor, não TUIs interativas do Codex. Envie tarefas pelo controlador ou pelo comando abaixo, sem digitar no painel do responsável.

cd /caminho/novo-time
./team task publicapi --message 'Implemente o endpoint X e valide os testes.'
./team task parceiros --file /caminho/tarefa.txt
./team status
./team wait ID_DA_TAREFA --timeout 50
./team result ID_DA_TAREFA

wait retorna 0 se todas terminaram com sucesso de execução, 1 se alguma falhou ou foi interrompida, e 2 se ainda há pendentes. Leia o relatório para conferir se os critérios de aceitação e os testes passaram; done indica que a chamada Codex terminou normalmente, não substitui revisão. Não há dependências implícitas na fila: o chefe deve esperar a API antes de enviar uma integração dependente. Cada responsável executa uma tarefa por vez; repositórios diferentes trabalham em paralelo. Uma tarefa interrompida é marcada e não é reenviada automaticamente.

A fila usa SQLite e a espera ociosa dos responsáveis usa FIFO. Resultados ficam em .codex-team/results/ID.md, logs em .codex-team/logs/ID.jsonl. Esses arquivos podem conter conteúdo do projeto; não os publique inadvertidamente.

O chefe deve chamar wait/result enquanto acompanha um pedido. O gerenciador não reativa espontaneamente um controlador que já encerrou sua resposta. Ele pode distribuir várias tarefas e aguardar resultados na mesma conversa.

Permissões e escopo

O controlador usa workspace-write com aprovação on-request. Git remoto, tmux ou ações fora do sandbox podem exigir aprovação conforme sua instalação. Os responsáveis usam workspace-write e aprovação never: se uma ação não for permitida, devem relatar o impedimento ao chefe. O gerenciador não usa bypass de sandbox nem executa comandos recebidos por interpolação de shell.

A tarefa instrui cada responsável a alterar apenas seu submódulo. Isso é uma regra de coordenação, não um isolamento de leitura ou segurança entre processos que compartilham o mesmo usuário Linux. Instruções locais do repositório e configurações do Codex continuam aplicáveis.

Sair, parar e retomar

• Desconectar mantendo o trabalho: Ctrl+B, depois D.
• Voltar: ./team attach na raiz do time.
• Parar os responsáveis com segurança, em outro terminal:

cd /caminho/novo-time
./team stop --timeout 50

stop fecha a entrada de tarefas. A tarefa atual de cada responsável pode terminar, mas as pendentes ficam preservadas. Se o prazo expirar, retorna 2 e não força a interrupção. Execute stop novamente depois. O controlador e a sessão tmux permanecem abertos. Quando ele estiver ocioso e os responsáveis parados, encerre a sessão usando o nome mostrado em ./team status:

tmux kill-session -t NOME_DA_SESSAO

Para reabrir o time, reaproveite a mesma raiz:

./ops/start-git-codex-team.sh --root /caminho/novo-time

Isso restaura os painéis ausentes, as filas e os IDs das conversas dos responsáveis. Tarefas pendentes voltam a ser executadas. Se um controlador foi fechado, abre uma conversa nova que consulta o estado persistido; a conversa interativa anterior pode ser retomada manualmente pelo Codex. Nenhum arquivo modificado ou commit dos submódulos é descartado.

Validação

python3 -m unittest discover -s ops/codex-team -p 'test_*.py' -v

Os testes usam repositórios Git locais, servidor tmux isolado e um executável Codex simulado. Não fazem chamadas ao modelo, não clonam projetos reais e não alteram o servidor tmux do usuário.

Referência: execução não interativa do Codex.

Desenvolvimento e build

cd ops/codex-team
python3 -m pip install -e .
python3 -m pip install build twine
python3 -m build
python3 -m twine check dist/*

A distribuição inclui somente o gerenciador, a documentação e os exemplos; nenhum repositório de trabalho, fila, credencial ou configuração de usuário é incluído nos artefatos. A versão inicial é 0.1.0 (alpha). A implementação usa tmux; GNU screen não é um backend suportado por este pacote.