codex-team 0.1.0__tar.gz

codex_team-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include config.example.json
+include team.py
+include test_team.py
+include test_package.py

codex_team-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+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.

codex_team-0.1.0/README.md

@@ -0,0 +1,197 @@
+# 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.

codex_team-0.1.0/config.example.json

@@ -0,0 +1,7 @@
+{
+  "agents": [
+    {"name": "publicapi", "repo": "git@github.com:SUA_ORGANIZACAO/publicapi.git"},
+    {"name": "anunciantes", "repo": "git@github.com:SUA_ORGANIZACAO/flutter_anunciantes.git"},
+    {"name": "parceiros", "repo": "git@github.com:SUA_ORGANIZACAO/flutter_parceiros.git"}
+  ]
+}

codex_team-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "codex-team"
+dynamic = ["version"]
+description = "Orchestrate local Codex agents with tmux, Git submodules, and persistent task queues."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{name = "PixPool"}]
+keywords = ["codex", "tmux", "agents", "orchestration", "git", "submodules"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: Software Development",
+  "Topic :: Utilities",
+]
+dependencies = []
+
+[project.scripts]
+codex-team = "codex_team.cli:entrypoint"
+start-git-codex-team = "codex_team.cli:start_entrypoint"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = {attr = "codex_team.cli.VERSION"}

codex_team-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

codex_team-0.1.0/src/codex_team/__init__.py

@@ -0,0 +1,4 @@
+"""Codex teams backed by tmux, Git submodules and durable task queues."""
+from .cli import VERSION as __version__
+
+__all__ = ['__version__']

codex_team-0.1.0/src/codex_team/__main__.py

@@ -0,0 +1,3 @@
+from .cli import entrypoint
+
+raise SystemExit(entrypoint())