Metadata-Version: 2.4
Name: codex-team
Version: 0.1.0
Summary: Orchestrate local Codex agents with tmux, Git submodules, and persistent task queues.
Author: PixPool
Keywords: codex,tmux,agents,orchestration,git,submodules
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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

```bash
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.

```bash
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 é:

```bash
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.

```bash
./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:

```text
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:

```bash
./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.

```bash
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:

```bash
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`:

```bash
tmux kill-session -t NOME_DA_SESSAO
```

Para reabrir o time, reaproveite a mesma raiz:

```bash
./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

```bash
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](https://developers.openai.com/codex/noninteractive).

## Desenvolvimento e build

```bash
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.
