Codeen

Codeen — agente de codificação com interface TUI (Text User Interface) que edita ficheiros e executa comandos de shell no teu nome, com confirmação obrigatória antes de cada ação destrutiva.

Inspirado no loop minimalista de MinimalAgent (chama o LLM → executa a ação decidida → alimenta o resultado de volta → repete), o Codeen expande essa base com uma interface interativa (Textual), suporte a múltiplos provedores de LLM com tool calling nativo, detecção automática do ambiente (incluindo Termux/Android) e adaptação de comandos de shell entre plataformas.

Funcionalidades

• Interface TUI construída com Textual: histórico colorido da conversa, input de comando e modais de confirmação.
• Multi-provedor com tool calling nativo (não parseia texto livre):
  • Anthropic (Claude)
  • OpenAI (GPT)
  • Google (Gemini)
  • Qualquer provedor compatível com OpenAI (DeepSeek, Ollama local, LM Studio, OpenRouter, Together, Groq, etc.) — basta apontar base_url.
• Confirmação obrigatória: antes de editar um ficheiro ou correr um comando, o que será feito é mostrado na TUI e o agente só avança com o teu "sim". Nunca executa nada sem a tua autorização.
• Detecção de ambiente: detecta SO, Termux, arquitetura da CPU (incluindo armv7l 32-bit do Android) e as ferramentas disponíveis, adaptando os comandos de shell (bash no Termux/Unix, cmd no Windows).
• Diff claro de edições antes de aplicar, usando difflib unificado.
• Configuração persistente em ~/.codeen/config.json, com chaves mascaradas ao serem exibidas.

Requisitos

• Python >= 3.10 (funciona no 3.11/3.12 do Termux, Linux, macOS e WSL).
• Conexão com a internet e uma chave de API de algum provedor suportado.
• Em Termux: pkg install python git (o resto é resolvido no arranque).

Não há dependências nativas para compilar — só Python puro (textual + httpx).

Instalação

Termux (Android) — foco primário

pkg update && pkg upgrade
pkg install python git
pip install --upgrade pip
pip install codeen

Linux

pip install --user codeen

macOS / Windows (WSL)

pip install codeen

Para contribuir ou correr em modo desenvolvimento:

git clone <este-repositorio>
cd codeen
pip install -e ".[dev]"

Configuração da primeira chave de API

# Exemplo com Anthropic
codeen config set anthropic.api_key sk-ant-xxx

# Outros provedores
codeen config set openai.api_key sk-xxx
codeen config set google.api_key AIza...

# Escolhe o provedor ativo
codeen config set active_provider anthropic   # openai | google

As chaves também podem ser providenciadas por variáveis de ambiente (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY), que servem como fallback quando não houver chave na configuração.

As chaves são sempre exibidas mascaradas (sk-***7890). Nunca são escritas em logs nem no histórico da conversa.

Para inspecionar a configuração corrente:

codeen config list
codeen providers

Uso

Inicia a TUI:

codeen

Ecrã principal:

┌ Codeen  anthropic/claude-sonnet-4-5 ─────────────────────────────┐
│ ... histórico da conversa ...                                   │
│ [yellow]Proposta: run_command 'ls -la'[/yellow]                  │
│ [dim]Aprovado: run_command[/dim]                                │
│ [dim]Resultado (run_command): ok[/dim]                          │
└─ Digite uma tarefa... ──────────────────────────────────────────┘

Comandos dentro da TUI:

Tecla	Ação
Enter (no input)	Envia a tarefa para o agente
p	Alterna o provedor ativo
c	Limpa o histórico da conversa
q	Sai

Fluxo de cada tarefa:

1. Descreves a tarefa em linguagem natural.
2. O agente lista e lê o contexto do projeto (list_files, read_file).
3. Propõe a próxima ação — edit_file (mostra um diff) ou run_command (mostra o comando exato).
4. Um modal exige a tua confirmação (y/Sim ou n/Não).
5. O resultado (diff aplicado / stdout + código de saída) é mostrado e o ciclo continua até concluir ou até o limite de iterações.

Comandos CLI

codeen                       # inicia a TUI
codeen doctor                # diagnóstico do ambiente
codeen config set <chave> <valor>
codeen config get <chave>
codeen config unset <chave>
codeen config list
codeen providers             # lista provedores e estado das chaves
codeen --version

Como o loop do agente funciona

O núcleo (codeen/agent/loop.py) segue o mesmo princípio do MinimalAgent:

mensagens = [sistema + contexto_do_projeto, tua_tarefa]
loop:
  resposta = provedor.chat(mensagens, ferramentas)
  se a resposta contiver tool_calls:
      para cada chamada:
        se for ação de escrita/execução:
            pede confirmação (modal y/n)          <-- confirmação obrigatória
        executa a ferramentas
        alimenta o resultado de volta às mensagens
  senão:
      devolve a resposta final e termina

A diferença fundamental em relação ao MinimalAgent: as chamadas de função são feitas via tool calling nativo da API de cada provedor, e nenhuma ação que modifique o sistema é executada sem a tua confirmação explícita.

Arquitetura

codeen/
├── cli.py                  # CLI: codeen, doctor, config
├── environment.py          # deteção de SO, Termux, arch, ferramentas, shell
├── config.py               # persistência ~/.codeen/config.json, mascaramento
├── providers/
│   ├── base.py             # tipos comuns (Message, ToolCall, ToolDef)
│   ├── anthropic.py        # Claude
│   ├── openai.py           # OpenAI + compatíveis
│   └── google.py           # Gemini
├── agent/
│   ├── context.py          # prompt de sistema + recolha de contexto
│   └── loop.py             # ciclo do agente (com approver)
├── tools/
│   ├── base.py             # ToolResult + BaseTool
│   ├── file_tools.py       # list_files, read_file (read-only, sem confirmação)
│   ├── edit_tool.py        # edit_file, write_file (com diff, confirmação)
│   ├── shell_tool.py       # run_command, adaptado à plataforma
│   └── registry.py         # esquemas + despacho de ferramentas
└── tui/
    ├── app.py              # app Textual principal
    ├── confirm.py          # modal de confirmação de ações
    └── provider_screen.py  # ecrã de seleção de provedor

Provedores

A camada de provedor traduz o formato interno neutro (Message, ToolCall) para o payload HTTP de cada API e volta a converter a resposta para o mesmo formato. Usa httpx diretamente, por modo a manter dependências leves e evitar builds nativos.

Provedor	Endpoint	Envio de tool calls
Anthropic	POST /v1/messages (x-api-key)	tool_use / tool_result
OpenAI	POST /chat/completions (Authorization: Bearer)	tool_calls / tool
Google	POST /v1beta/models/{model}:generateContent (x-goog-api-key)	functionCall / functionResponse
OpenAI-like	aponta base_url para o provedor compatível	idêntico a OpenAI

Ferramentas (tool calling)

Ferramenta	Confirmação	Descrição
list_files	não	lista a estrutura do projeto
read_file	não	lê um ficheiro com números de linha
edit_file	sim	substitui uma string exacta; mostra o diff
write_file	sim	cria ou reescreve um ficheiro; mostra o diff
run_command	sim	executa um comando de shell; mostra o comando exacto

As leituras são consideradas seguras e executadas diretamente (são o "ler o contexto necessário" do passo 2 do loop). Qualquer escrita ou execução requer confirmação.

Testes

pytest            # suite de testes (inclui TUI headless)

Cobertura: deteção de ambiente, config (com env e máscaras), tradução de mensagens de cada provedor (via httpx.MockTransport), tools (diff, shell, escopo de caminhos), o loop do agente (confirmação/recusa, leituras sem confirmação) e a TUI (fluxo de confirmação aprovado/recusado e troca de provedor).

Personalização

• Variável AGENT_MAX_ITERATIONS / codeen config set max_iterations N limita o número de ciclos do agente (padrão: 20).
• Coloca CODEN_DIR para usar um directório de config alternativo (~/.codeen por defeito).
• O sistema é montado para ser extendida: basta implementar Provider em providers/ e registar a fábrica em providers/registry.py.

Limites de segurança

• O Codeen nunca escreve, lê ou transmite chaves directamente do ambiente de execução. As chaves vêm do utilizador (via configurador ou env vars).
• As leituras/escritas de ficheiros estão limitadas ao directório de trabalho do projecto.
• Comandos de shell exigem confirmação em cada iteração.
• Não contém lógica de análise de segurança nem testes de intrusão.