PEP-Agentes

Gerencie o protocolo PEP para Codex e Claude Code por CLI, interface gráfica ou executável Windows.

O PEP-Agentes centraliza instalação, atualização, diagnóstico, reparo e remoção das instruções PEP em projetos locais ou no escopo global do usuário. O mesmo core atende múltiplos providers e mantém recursos empacotados dentro do próprio pacote Python para funcionar de forma consistente em Windows, Linux, venv, PyPI e instalação direta pelo GitHub.

python -m pip install pep-agentes
pep version
pep install all --here

Índice

• Por que existe
• Instalação
• Uso rápido
• Providers
• Escopos
• Referência da CLI
• Interface gráfica
• Arquitetura
• Build para Windows
• Release e PyPI
• Documentação
• Solução de problemas
• Segurança e privacidade
• Licença e autoria

Por que existe

Manter instruções de agentes em vários projetos tende a gerar cópias divergentes, arquivos manuais fora de sincronia e configurações diferentes entre Codex e Claude Code.

O PEP-Agentes resolve isso com um gerenciador único que:

• instala e atualiza blocos gerenciados sem sobrescrever conteúdo manual fora dos marcadores;
• mantém providers independentes para Codex e Claude Code;
• oferece status, doctor, repair e uninstall pelo mesmo core;
• suporta instalação local por projeto ou global;
• disponibiliza CLI, GUI e artefatos Windows;
• empacota os recursos necessários dentro da wheel, evitando dependência de caminhos externos como share/pep-agentes.

Instalação

PyPI

python -m pip install pep-agentes

Confirme a instalação:

pep version

GitHub

Versão atual da branch principal:

python -m pip install "git+https://github.com/DaviKdS/pep-agentes-v1.git"

Versão específica:

python -m pip install "git+https://github.com/DaviKdS/pep-agentes-v1.git@v1.2.1"

Checkout local

git clone https://github.com/DaviKdS/pep-agentes-v1.git
cd pep-agentes-v1
python -m pip install -e .

Mais detalhes: docs/instalacao.md.

Uso rápido

Instalar Codex e Claude Code no projeto atual:

pep install all --here

Verificar o estado:

pep status all --here

Diagnosticar instalação global:

pep doctor all --global

Atualizar e sobrescrever apenas os arquivos gerenciados:

pep update all --here --force

Reparar um provider:

pep repair codex --global

Remover:

pep uninstall all --here

Providers

Codex

Após a instalação:

$pepcodex corrigir o login
$pepcodex MODE=review revisar esta branch
$pepcodex MODE=debug investigar o erro 500

Compatibilidade opcional com prompt legado:

pep install codex --global --legacy-prompt

Claude Code

pep install claude --here

O PEP mantém o bloco gerenciado em CLAUDE.md e instala o comando /pep no escopo correspondente.

Escopos

Exemplo:

pep install codex --path "C:/Projetos/MeuApp"

Referência da CLI

pep install [claude|codex|all]    instala recursos PEP
pep update [claude|codex|all]     atualiza recursos gerenciados
pep uninstall [provider]           remove recursos gerenciados
pep repair [provider]              repara instalação parcial/desatualizada
pep status [provider]              mostra o estado atual
pep doctor [provider]              diagnostica ferramentas e instalação
pep version                        mostra a versão instalada

Opções de escopo:

--here
--path CAMINHO
--global
--legacy-prompt
--force

Referência detalhada: docs/cli.md.

Interface gráfica

Instale as dependências opcionais:

python -m pip install "pep-agentes[app]"

No checkout do repositório:

python scripts/pep_gui.py

O PEP-Agentes Manager permite selecionar provider, ação e escopo, além de executar diagnóstico e consultar o estado da instalação sem editar arquivos manualmente.

Arquitetura

pep-agentes-v1/
├── pep/
│   ├── cli.py
│   ├── core/
│   ├── providers/
│   ├── services/
│   └── resources/
│       ├── claude/
│       ├── codex/
│       └── prompts/
├── scripts/
├── docs/
├── installer/
├── tests/
├── pyproject.toml
└── genpyexe.toml

Fluxo interno

CLI / GUI
   ↓
services.manager
   ↓
provider selecionado
   ↓
core de paths / markers / models
   ↓
arquivos do projeto ou escopo global

Os recursos de runtime ficam em pep/resources/ e são distribuídos como package-data. Essa abordagem evita caminhos dependentes de sys.prefix/share e torna a wheel mais previsível entre plataformas.

Detalhes: docs/arquitetura.md.

Build para Windows

O backend preferencial é o GenPyEXE.

python -m pip install -r requirements-app.txt
python -m pip install -r requirements-build.txt
python scripts/build_windows.py

Artefatos esperados:

PEP-Agentes-1.2.1-Portable-x64.exe
pep-agentes-1.2.1-setup-x64.exe
PEP-Agentes-1.2.1-SHA256SUMS.txt

O GenPyEXE é dependência de build, não de runtime.

Release e PyPI

Tags v* acionam o workflow de release.

Fluxo protegido:

tag v1.2.1
   ↓
build Windows
   ↓
build da wheel
   ↓
instalação real da wheel no Windows
   ↓
GitHub Release + artefatos
   ↓
publish-pypi aguarda build-windows
   ↓
build + instalação real da wheel no Linux
   ↓
publicação no PyPI

A publicação no PyPI depende explicitamente da validação do job Windows. Se a instalação da wheel falhar no Windows, o job de publicação não é executado.

Build local do pacote:

python -m pip install build twine
python -m build --outdir python-dist
python -m twine check python-dist/*

Documentação

Solução de problemas

pep não é reconhecido

Descubra a pasta de scripts do Python:

python -c "import sysconfig; print(sysconfig.get_path('scripts'))"

Verifique se o launcher foi criado nessa pasta e se ela está no PATH.

Wheel tentando instalar em D:share\...

Esse problema existia na versão 1.2.0 por causa do uso de data-files. A partir da 1.2.1 os recursos ficam dentro do pacote pep/resources e são distribuídos via package-data.

Diagnóstico completo

pep doctor all --global
pep status all --global

Mais casos: docs/solucao-de-problemas.md.

Segurança e privacidade

• não armazena tokens, senhas ou chaves;
• não envia o conteúdo dos projetos para um backend próprio;
• preserva conteúdo manual fora dos blocos PEP gerenciados;
• usa arquivos locais e caminhos explícitos;
• GitHub Actions usa Trusted Publishing para publicação no PyPI;
• a release só publica o pacote após validações reais de instalação.

Consulte também SECURITY.md.

Licença e autoria

Licenciado sob Apache License 2.0. Consulte LICENSE.

Autor e mantenedor: Davi Kasmirski dos Santos / DaviKdS.