clawcodex

ClawCodex

Una ricostruzione in Python orientata alla produzione di Claude Code — architettura reale, agente CLI affidabile

Portato dall'implementazione di riferimento TypeScript ed esteso con un runtime nativo Python

🔥 Sviluppo Attivo • Nuove Funzionalità Settimanali 🔥

⚡ Installazione Rapida

git clone https://github.com/agentforce314/clawcodex.git
cd clawcodex
python3 -m venv .venv && source .venv/bin/activate   # Python 3.10+
pip install -r requirements.txt

python -m src.cli login   # scrive la configurazione in ~/.clawcodex/config.json

python -m src.cli         # avvia il REPL

📰 Notizie

• 2026-05-16: Statistiche codebase — File Python totali: 894 file; Righe di codice Python totali: 177.428 righe (in aumento dalle 167.034 righe del 14/05/2026; ~+10.4k righe in due giorni, principalmente hardening per cancellazione ESC + parità gestione immagini).
• 2026-05-16: Parità gestione immagini (Tier C, #149/#154/#155/#156) — Pipeline immagine TS tool Read (sniff, ridimensionamento/compressione, limite base64); @image.png menzionato inline come veri ImageBlock invece di mojibake; traduzione cross-provider Anthropic image/document → OpenAI image_url/file; validazione dimensione base64 pre-API in BaseProvider.
• 2026-05-16: Affidabilità Subagent + Bash — subagenti personalizzati ora scoperti da .claude/agents/ (#151); tool_result di Bash distingue timeout da ESC-abort in modo che il modello possa distinguere i due (#152); isolamento AbortController async-subagent fissato da test di regressione in modo che l'ESC di un genitore non attivi i listener di abort di un sibling (#153); tool_result cancellato riporta in modo affidabile REJECT_MESSAGE sul percorso di produzione (#150).
• 15/05/2026 al 16/05/2026: Hardening cancellazione ESC tra provider (#144–#148) — la cancellazione a metà stream chiude la risposta HTTP in streaming entro ~50ms per ogni provider supportato (Anthropic, OpenAI, GLM, Minimax, DeepSeek, OpenRouter); estratto helper StreamAbortGuard condiviso; correzioni iterazione worker-thread LiteLLM risolvono blocchi a lunga coda su backend compatibili con OpenAI.
• 2026-05-14: Correzione latenza cancellazione ESC (#130) — la pressione di ESC ora annulla i comandi Bash in-flight e le risposte in streaming entro ~50ms, oltre alla correzione del rendering a tutta larghezza della barra colore diff (#129) e alla correzione bypass-permissions per percorsi esterni (#128).
• 2026-05-12: Documentazione Bootstrap + architettura — nuova panoramica architetturale in docs/ARCHITECTURE.md; porting bootstrap di produzione (init() memoizzato, trust boundary, launch_repl(args) unificato, fast path --bare, runner migrazione schema); loop di query principale e loop agente instradati tramite dispatch_full con caricamento tool differito.
• 2026-05-11 (v0.5.0): ClawCodex v0.5.0 rilasciato — rebranding a ClawCodex in tutta l'interfaccia utente; porting sottosistema stato reattivo (signals, store, contesto sessione, cost tracker, idoneità cache 1h); hardening layer API (limite token output, iniezione request-id, breakpoint cache a livello messaggio, fast path Haiku, watchdog + fallback non streaming, retry-with-stream); fondazione loop agente (terminale tipizzato, recupero media, guardie limite bloccante, budget token, stop hooks, fallback modello, nudging di continuazione); screenshot README aggiornato.
• 2026-05-10: Sottosistema MCP implementato — pieno supporto al Model Context Protocol con cablaggio OAuth, HTTPS, hardening XSS e I/O asincrono; superato una revisione di sicurezza multi-passaggio.
• 2026-05-10: Pass di performance — profiler all'avvio, plumbing cache prompt con latch sticky, indicizzazione ricerca bitmap + asincrona con pruning basato sul punteggio, riduzione latenza cold-start, hardening streaming.
• 2026-05-10: Ponte remoto CCR (fasi 0-5) — Direct Connect tramite cc:// e cc+unix://, trasporto Bridge v2, visualizzatore Sessione Remota, proxy upstream CCR.
• 2026-05-10: Moduli REPL standalone — modalità vim, ricerca trascrizione, cursore IME, hyperlink terminale, frame metrics, widget di pensiero, specializzazione permessi per tool, frontmatter output-styles; leggibilità trascrizione REPL e sfondi diff ANSI.
• 2026-05-08: Sistema Hooks — esecutore basato su snapshot con gate di fiducia workspace, tassonomia evento/sorgente estesa, validazione schema, iniezione ambiente.
• 2026-05-08: Coordinazione multi-agente — macchina a stati tipizzata per attività, scrittore trascrizioni JSONL, ciclo di vita attività agente, tracker progressi, routing notifica attività, DM peer SendMessage, primitive swarm, ripristino in background, modalità coordinatore + agenti worker, bridgeinoltro permessi; suite di test completa verde su main.
• 2026-05-07: Auto-memoria + concorrenza — porting sottosistema auto-memoria persistente (tipi utente / feedback / progetto / riferimento); orchestratore concorrenza e parità esecuzione tool con il riferimento TypeScript; chiusi gap sistema permessi.
• 2026-05-06: Parità Subagent — porting percorso fork-subagent; ciclo di vita asincrono subagent allineato con riferimento TypeScript.
• 2026-05-05: Rifinitura Docs — aggiunta sezione Installazione Rapida sotto l'intestazione; documentato il percorso di configurazione scritto da clawcodex login.
• 2026-04-30: Parità sottosistema Skills — Skills (progetto + utente, argomenti nominati, limiti tool) portati a parità con il riferimento TypeScript.
• 2026-04-29: UX spinner REPL — mostra tempo trascorso e conteggio token nella riga spinner REPL.
• 2026-04-27: Nuova demo — Gioco per animali stile Adopt Me (React + Vite + Vitest), generato end-to-end da ClawCodex.
• 2026-04-26: Correzione affidabilità — Risolti i fallimenti di replay in modalità pensiero DeepSeek e i prompt di permesso rumorosi.
• 2026-04-25: Supporto DeepSeek — provider DeepSeek diretto (V4 Pro / Flash tramite api.deepseek.com) più rotta OpenRouter.
• 2026-04-25: Correzione validazione API — schema opzioni AskUserQuestion corretto per la validazione API.
• 2026-04-23: Demo generate — App demo CRM, LinkedIn e Minecraft (tutte generate da ClawCodex stesso) e una sezione Demos nel README.
• 2026-04-21: Cablaggio permessi — --dangerously-skip-permissions cablato attraverso ogni punto di ingresso (REPL, TUI, -p).
• 2026-04-20: Prima release pubblica — primo commit con sorgente progetto, docs, test e configurazione build.

🎯 Perché ClawCodex?

ClawCodex è una ricostruzione in Python orientata alla produzione di Claude Code, portata dalla vera architettura TypeScript e distribuita come agente CLI funzionante, non solo un dump del codice sorgente.

Caratteristiche principali

Un vero workflow terminale in stile Claude Code in Python: risposte in streaming, chiamata di tool, recupero del contesto ed estensione del comportamento con le skill.

🚀 Provalo subito! Fancene una copia, modificalo, fallo tuo! Pull request ben accette!

✨ Caratteristiche

Esperienza Agente in Streaming

>>> /stream on
>>> Spiegame tests/test_agent_loop.py
[rispostas in streaming...]
• Lettura (tests/test_agent_loop.py) in corso...
  ↳ righe 1-180
>>> /render-last

• Vero streaming API per risposte dirette e streaming più ricco durante i loop agente guidati da tool
• Toggle /stream integrato per output live e /render-last per un rendering Markdown pulito on demand
• Progettato per demo terminali reali: testo in streaming, attività tool visibile e comportamento di fallback stabile

Runtime di Skill Programmabile

---
description: Spiega codice con diagrammi e analogie
allowed-tools:
  - Read
  - Grep
  - Glob
arguments: [path]
---

Spiega il codice in $path. Inizia con un'analogia, poi disegna un diagramma.

• Comandi slash SKILL.md basati su Markdown
• Supporta skill di progetto, skill utente, argomenti nominati e limiti di tool

Supporto Multi-Provider

Il principale vantaggio di ClawCodex è il supporto multi-provider: mentre Claude Code si concentra sui modelli Claude, noi miriamo a supportare ogni principale provider LLM tramite lo stesso runtime agente—in modo da poter scambiare fornitori, regioni e livelli di prezzo senza rinunciare a tool, skill o al loop di coding. Questa flessibilità è ciò che rende pratico il coding agentico su larga scala.

providers = ["anthropic", "openai", "glm", "minimax", "openrouter", "deepseek"]  # API compatibili con OpenAI e GLM; se ne possono aggiungere altri

REPL Interattivo (default) e TUI Testuale (opt-in)

L'interfaccia utente interattiva predefinita è il prompt_toolkit + Rich REPL inline (trascrizione nello scrollback, riga di stato consapevole dei tool). Usa clawcodex --tui o il comando slash /tui all'interno del REPL per avviare l'esperienza Textual in-app quando lo desideri.

>>> Ciao!
Assistente: Ciao! Sono ClawCodex, una reimplementazione Python...

>>> /help          # Mostra i comandi
>>> /tools         # Elenca i tool registrati
>>> /tui           # Passa al TUI Testuale
>>> /stream on     # Rendering della risposta in tempo reale
>>> /save          # Salva la sessione
>>> Tab            # Completamento automatico
>>> /explain-code qsort.py   # Esegui una skill SKILL.md (o /skill …)

# Input multi-riga: Shift+Invio, Meta/Alt+Invio, o `\` poi Invio per nuova riga; Invio semplice invia.

CLI Completa

clawcodex                       # REPL inline (default)
clawcodex --tui                 # TUI Testuale
clawcodex --stream              # REPL con rendering live
clawcodex login                 # Configura le chiavi API (interattivo)
clawcodex config                # Mostra le impostazioni basate su ~/.clawcodex/config.json
clawcodex --version             # Stringa della versione

# Non interattivo / scripting (pipe, CI, agenti)
clawcodex -p "Riassumi src/cli.py"
clawcodex -p "Ciao" --output-format json
clawcodex -p --output-format stream-json --input-format stream-json < events.ndjson

# Override per una singola esecuzione
clawcodex --provider anthropic --model claude-sonnet-4-6 -p "Ciao"
clawcodex --max-turns 10 --allowed-tools Read,Grep -p "Trova TODOs"

# Controllo dei permessi (REPL, TUI e -p rispettano tutti questi)
clawcodex --permission-mode plan                       # plan / acceptEdits / dontAsk
clawcodex --dangerously-skip-permissions -p "ls"       # bypassa tutti i controlli di permesso
clawcodex --allow-dangerously-skip-permissions         # consente il bypass di /permission-mode in seguito

--dangerously-skip-permissions disabilita ogni controllo dei permessi degli strumenti per la sessione. Raccomandato solo all'interno di container/VM sandbox senza accesso a internet. Il flag viene rifiutato quando il processo è in esecuzione come root/sudo a meno che non sia impostato IS_SANDBOX=1 o CLAUDE_CODE_BUBBLEWRAP=1.

📊 Stato

Sistemi Core

Sistema Tool (Oltre 30 Tool Implementati)