▍ Documentazione CodePalace

Guida completa all'agente di sviluppo software autonomo con memoria persistente.

1. Panoramica

CodePalace è un agente di sviluppo software autonomo con memoria persistente. Analizza il progetto, pianifica le azioni, scrive codice, esegue test e consolida le conoscenze acquisite — tutto in automatico.

Caratteristiche Principali

• Memoria Persistente — Sistema MemPalace con 10+ stanze tematiche per archiviare pattern, errori e soluzioni
• Apprendimento per Rinforzo — Reward function a 7 dimensioni che valuta ogni azione compiuta
• Dual-LLM — Un classificatore leggero per l'analisi, un modello potente per l'esecuzione
• Workflow a Fasi — analysis → planning → implementation → verification → consolidation
• Multi-Modalità — CLI, REPL interattivo, API REST, TUI terminale, TUI web
• MCP (Model Context Protocol) — Integrazione con server MCP per strumenti esterni
• Multi-Piattaforma — Linux, macOS (Intel e Apple Silicon), Windows, Docker
• Backend Rust — mempalace-rs per prestazioni fino a 10x superiori
• Aggiornamenti Automatici — codepalace self-update per restare aggiornato

2. Installazione

Linux (consigliato)

Un solo comando installa tutto: CodePalace, dipendenze Python e mempalace-rs (backend veloce in Rust).

# Installazione rapida (consigliata)
bash <(curl -sL https://git.infinitech.it/forgejo-admin/codepalace_release/raw/branch/master/install_release.sh)

# Dopo l'installazione, ricarica la shell
source ~/.bashrc

# Verifica
codepalace version

Opzioni di install_release.sh

macOS (Intel e Apple Silicon)

# Installazione rapida
bash <(curl -sL https://git.infinitech.it/forgejo-admin/codepalace_release/raw/branch/master/install_mac.sh)

Windows (PowerShell)

# Installazione rapida (consigliata)
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
irm https://git.infinitech.it/forgejo-admin/codepalace_release/raw/branch/master/install_windows.ps1 -OutFile install_windows.ps1; .\install_windows.ps1 -User

Installazione Manuale

Scarica l'archivio per la tua piattaforma dalla cartella releases/ del repository:

# 1. Scarica ed estrai l'archivio
tar xzf codepalace_VERSIONE_piattaforma.tar.gz

# 2. Esegui lo script di installazione
# Linux:
cd codepalace_VERSIONE_piattaforma && bash install_release.sh --local
# macOS:
cd codepalace_VERSIONE_piattaforma && bash install_mac.sh --user
# Windows: estrarre lo ZIP e lanciare .\install_windows.ps1 -User

# 3. Avvia CodePalace
codepalace

Installazione Solo Binario (alternativa Linux)

Per installare solo il binario precompilato senza mempalace-rs:

bash <(curl -sL https://git.infinitech.it/forgejo-admin/codepalace_release/raw/branch/master/install_release.sh)

3. Configurazione Rapida

API Key

Almeno una chiave API è necessaria per funzionare. Imposta la variabile d'ambiente:

# OpenRouter (consigliata — accesso a tutti i modelli)
export OPENROUTER_API_KEY=sk-or-v1-...

# Oppure OpenAI diretto
export OPENAI_API_KEY=sk-...

Oppure usa il flag

codepalace run -t "Task" --api-key sk-or-v1-...

Primo Task

# Esegui il tuo primo task
codepalace run -t "Crea un file hello.py che stampa Hello World"

# Specifica la directory del progetto
codepalace run -t "Aggiungi test per Calculator" -p ./myproject

# Modalità interattiva
codepalace interactive -p ./myproject

4. Comandi

run — Esecuzione Singolo Task

Esegue un task specificato con --task o --task-file e termina automaticamente.

codepalace run -t "Crea una classe Calculator con add, subtract"
codepalace run --task-file task.txt -p ./myproject
codepalace run -t "Fix bug" --thinking high

interactive — Modalità Interattiva

REPL interattivo con comandi dedicati per esplorare il progetto, gestire la memoria e controllare il flusso.

codepalace interactive -p ./myproject

# Comandi disponibili nel REPL:
# task <desc> Esegui un task
# chat <msg> Chat rapida
# dir/read/tree Esplora progetto
# git/diff/log Operazioni git
# memory <query> Cerca in memoria
# recall [room] Richiama ricordi
# status/config Info sessione
# phase [name] Cambia fase
# auto Toggle auto-approve
# obs Toggle osservazioni
# help Mostra comandi
# exit/quit/q Esci

serve — Server API REST

Avvia un server HTTP che espone l'endpoint POST /run per eseguire task via API.

codepalace serve --host 0.0.0.0 --port 8080

# Esempio di richiesta
curl -X POST http://localhost:8080/run \
 -H "Content-Type: application/json" \
 -d '{"task": "Crea un modulo auth", "project": "./myproject", "max_steps": 50}'

# Risposta:
# {"status": "success", "steps": 12, "total_reward": 0.85, "trajectory_summary": "..."}

tui — Interfaccia Terminale

Interfaccia utente ricca nel terminale basata su Textual. Supporta anche la modalità web via browser.

# TUI nel terminale
codepalace tui -p ./myproject

# TUI nel browser (richiede textual-serve)
codepalace tui --web --host 0.0.0.0 --port 8000

# Con modello specifico
codepalace tui --thinking medium

webmempalace — Dashboard MemPalace

Avvia l'interfaccia web per esplorare e gestire la memoria MemPalace.

codepalace webmempalace
codepalace webmempalace --port 8080 --debug

5. Opzioni CLI

6. Modelli LLM

CodePalace utilizza una configurazione Dual-LLM: un modello principale per l'esecuzione e un modello di classificazione per l'analisi.

Configurazione Predefinita

Entrambi i modelli sono accessibili tramite OpenRouter con una singola OPENROUTER_API_KEY. Per usare un modello diverso, usa i flag -m e --classification-model:

# Modello principale personalizzato
codepalace run -t "Refactor architecture" -m z-ai/glm-5.1 --thinking high

# Modello principale + classificatore personalizzati
codepalace run -t "Fix bug" -m z-ai/glm-5.1 --classification-model openai/gpt-4o-mini

# Usare OpenAI diretto (senza OpenRouter)
codepalace run -t "Task" --base-url https://api.openai.com/v1 --api-key sk-...

7. Sistema di Memoria (MemPalace)

Il sistema MemPalace organizza la conoscenza in stanze tematiche. Ogni azione viene registrata e le lezioni apprese vengono consultate prima di ogni nuovo task per evitare errori passati.

Stanze Disponibili

Operazioni nella REPL Interattiva

# Cerca nella memoria
memory Come gestire errori di connessione

# Richiama una stanza specifica
recall error_patterns

# Il Lesson Consultant consulta automaticamente la memoria
# prima di ogni task per evitare errori passati

Backend: mempalace-rs (Rust)

MemPalace utilizza mempalace-rs come backend primario — un binario Rust standalone ad alte prestazioni che offre velocità fino a 10x superiori rispetto al vecchio backend Python.

8. Docker

Avvio Rapido

Il modo più semplice per usare CodePalace con Docker:

# 1. Scarica l'immagine
docker pull codepalace:latest

# 2. Esegui un task (sostituisci la tua API key)
docker run -it --rm \
  -e OPENROUTER_API_KEY=sk-or-v1-... \
  -v $(pwd)/projects:/app/projects \
  codepalace run "Crea un file hello.py"

Comandi Diretti (docker run)

# Server API in background
docker run -d --name codepalace-agent \
  -e OPENROUTER_API_KEY=sk-or-v1-... \
  -p 8080:8080 \
  -v $(pwd)/projects:/app/projects \
  codepalace serve

# Modalità interattiva
docker run -it --rm \
  -e OPENROUTER_API_KEY=sk-or-v1-... \
  -v $(pwd)/projects:/app/projects \
  codepalace interactive

# TUI via browser
docker run -d --name codepalace-web \
  -e OPENROUTER_API_KEY=sk-or-v1-... \
  -p 8000:8000 \
  codepalace web

Docker Compose (Setup Persistente)

Per un setup completo e persistente con volumi dati:

# Scarica i file di configurazione
curl -sL https://git.infinitech.it/forgejo-admin/codepalace_release/raw/branch/master/docker-compose.user.yml -o docker-compose.user.yml
curl -sL https://git.infinitech.it/forgejo-admin/codepalace_release/raw/branch/master/.env.example -o .env

# Configura le API key
nano .env

# Avvia il servizio
bash install_docker.sh
# oppure manualmente:
docker compose -f docker-compose.user.yml up -d

Comandi Docker

Esempi Docker

# Esegui un singolo task
docker compose run --rm agent run "Crea una classe Calculator"

# Esegui con modello specifico
docker run -it --rm \
 -e OPENROUTER_API_KEY=sk-or-v1-... \
 -v $(pwd)/projects:/app/projects \
 codepalace run "Fix bug in parser"

# Modalità interattiva
docker run -it --rm \
 -e OPENROUTER_API_KEY=sk-or-v1-... \
 -v $(pwd)/projects:/app/projects \
 codepalace interactive

# Shell per debug
docker compose run --rm agent shell

Variabili d'Ambiente Docker

# Build standard (senza ONNX Runtime)
docker build -f Dockerfile.alpine -t codepalace:alpine .

# Build con ONNX Runtime (~100MB aggiuntivi)
docker build -f Dockerfile.alpine --build-arg INCLUDE_ONNX=true -t codepalace:alpine-onnx .

docker run -it --rm \
 -e OPENROUTER_API_KEY=sk-or-v1-... \
 -v $(pwd)/projects:/app/projects \
 codepalace:alpine serve

9. File di Configurazione

models.json

Configurazione persistente di modello, temperatura, lingua e altri parametri. Si trova nella directory del progetto o in ~/.codepalace/.

{
 "model": "z-ai/glm-5.1",
 "classification_model": "openai/gpt-4o-mini",
 "base_url": "https://openrouter.ai/api/v1",
 "temperature": 0.7,
 "thinking": "medium",
 "language": "it",
 "context_max_tokens": 64000,
 "mempalace_backend": "rust",
 "json_mode": true
}

user_config.json

Configurazione utente e progetto che sovrascrive i valori predefiniti. Si trova nella directory del progetto o in ~/.codepalace/. Specifica solo i parametri che vuoi cambiare.

Come scrivere una buona description

Una description efficace dovrebbe contenere:

• Tipo di progetto — cosa fa l'applicazione
• Stack tecnologico — linguaggi, framework, librerie principali
• Convenzioni — naming, stile del codice, type hints
• Vincoli — file da non toccare, dipendenze da non aggiornare
• Workflow — test obbligatori, processi di build

Esempio di user_config.json

{
 "user_id": "Mario",
 "current_project": "my_app",
 "current_project_path": "/home/mario/projects/my_app",
 "project_metadata": {
    "name": "MyApp",
    "version": "2.0.0",
    "author": "Mario Rossi",
    "description": "App web Flask per gestione ordini. Backend REST API in Python/Flask, frontend Vue.js. Usare type hints ovunque. Convenzione naming: snake_case per Python, camelCase per JS. Non modificare i file in legacy/. Test con pytest prima di ogni commit.",
    "language": "python",
    "frameworks": ["flask", "vue"]
 },
 "thinking": "medium",
 "git_auto_commit": true
}

Parametri principali

Directory di Configurazione

CodePalace utilizza due directory distinte per separare configurazione e dati:

Variabili d'Ambiente

10. Disinstallazione e Aggiornamento

Aggiornamento

# Aggiornamento automatico
codepalace self-update

# Oppure re-lancia lo script di installazione
bash <(curl -sL https://git.infinitech.it/forgejo-admin/codepalace_release/raw/branch/master/install_release.sh)

# Con install_release.sh
bash <(curl -sL https://git.infinitech.it/forgejo-admin/codepalace_release/raw/branch/master/install_release.sh) --update

Disinstallazione

# Rimuovi il binario
rm ~/.local/bin/codepalace

# Rimuovi l'applicazione
rm -rf ~/.local/share/codepalace

# Rimuovi la configurazione (opzionale — conserva i dati!)
rm -rf ~/.codepalace

# Rimuovi i dati MemPalace (opzionale)
rm -rf ~/.mempalace

11. Gestione Licenza

CodePalace è distribuito con licenza proprietaria. La licenza è gestita tramite il sistema License Manager integrato.

Verifica Licenza

# Controlla lo stato della licenza
codepalace license status

# Mostra i dettagli della licenza
codepalace license info

Tipi di Licenza

12. Esempi d'Uso

Esecuzione Base

# Esegui un singolo task
codepalace run -t "Crea una classe Calculator con add, subtract"

# Task da file
codepalace run --task-file task.txt -p ./myproject

# Specifica progetto
codepalace run -t "Fix bug in parser" -p ./myproject

Ragionamento Avanzato

# Ragionamento esteso (migliore per task complessi)
codepalace run -t "Refactor the auth module" --thinking high

# Ragionamento bilanciato
codepalace run -t "Add input validation" --thinking medium

# Senza ragionamento extra (più veloce, più economico)
codepalace run -t "Add a comment" --thinking normal

Modalità Sicura

# Read-only: l'agente può solo leggere, non scrivere
codepalace interactive -p ./myproject --read-only

# Sandbox: comandi shell ristretti
codepalace run -t "Analyze code" --sandbox

# Disabilita git auto-commit
codepalace run -t "Fix bug" --no-git

Ottimizzazione Contesto

# Disabilita features per risparmiare token
codepalace run -t "Quick fix" \
 --no-dedup \
 --no-compression \
 --no-prompt-caching

# Limita step massimi
codepalace run -t "Simple task" --max-steps 10

# Context window più ampia per progetti grandi
codepalace run -t "Refactor" --context-max-tokens 128000

Server API

# Avvia il server
codepalace serve --host 0.0.0.0 --port 8080

# Invia un task via curl
curl -X POST http://localhost:8080/run \
 -H "Content-Type: application/json" \
 -d '{
    "task": "Crea un modulo di autenticazione",
    "project": "./projects/myapp",
    "max_steps": 50
 }'

Debug

# Log completo (prompt e risposte LLM)
codepalace run -t "Debug this" --debug-logging

# Temperatura alta per soluzioni creative
codepalace run -t "Design a new architecture" --temperature 0.7