| 1 | <!-- source: README.md sha256:ebf1c69de0dc --> |
| 2 | # Codewhale |
| 3 | |
| 4 | Codewhale è un agente open source che legge il tuo progetto, modifica file, esegue comandi e verifica il proprio lavoro usando un modello ospitato o locale a tua scelta. Parti da un’attività nel terminale. Per un lavoro più grande, assegna parti del lavoro ad agenti con modelli e ruoli diversi. |
| 5 | |
| 6 |  |
| 7 | |
| 8 | *Anteprima del terminale da una build di sviluppo della v0.9.12.* |
| 9 | |
| 10 | [English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md) · [Tiếng Việt](README.vi.md) · [Bahasa Indonesia](README.id.md) · [한국어](README.ko-KR.md) · [Español](README.es-419.md) · [Português](README.pt-BR.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [繁體中文](README.zh-TW.md) · [हिन्दी](README.hi.md) · [Türkçe](README.tr.md) · [Polski](README.pl.md) · [العربية](README.ar.md) · [Català](README.ca.md) |
| 11 | |
| 12 | [](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml) |
| 13 | [](https://crates.io/crates/codewhale-cli) |
| 14 | [](https://www.npmjs.com/package/codewhale) |
| 15 | [](https://discord.gg/37gfS3ksug) |
| 16 | |
| 17 | ## Installazione |
| 18 | |
| 19 | Per una nuova installazione su macOS o Linux, usa la versione ufficiale di GitHub: |
| 20 | |
| 21 | ```bash |
| 22 | curl -fsSL https://codewhale.net/install.sh | sh |
| 23 | "$HOME/.local/bin/codewhale" |
| 24 | ``` |
| 25 | |
| 26 | L’installer seleziona l’ultima versione pubblicata. Il [registro delle modifiche](CHANGELOG.md) descrive anche la versione candidata, ancora non pubblicata, della prossima versione; queste modifiche saranno incluse nei download pubblicati solo quando la versione sarà disponibile. |
| 27 | |
| 28 | Su Windows, scarica l’installer o l’archivio adatto da [GitHub Releases](https://github.com/Hmbown/CodeWhale/releases/latest). Per aggiornare un’installazione diretta esistente, esegui `codewhale update`, oppure `codewhale update --check` per la sola verifica. L’aggiornamento mostra il percorso dell’eseguibile e conserva le build più recenti. npm e Cargo sono opzioni secondarie; consulta la [guida all’installazione](docs/INSTALL.md) per migrare da un gestore di pacchetti e configurare PATH. |
| 29 | |
| 30 | Al primo avvio, Codewhale ti aiuta a collegare un provider oppure a configurare Codewhale offline. Le risposte richiedono un modello ospitato o locale collegato. Codewhale supporta anche npm e Cargo come opzioni secondarie di distribuzione, oltre a Docker, Nix, Scoop, Android/Termux e un mirror CNB facoltativo. Le installazioni esistenti gestite da un gestore di pacchetti ricevono istruzioni per la migrazione. Consulta la [guida all’installazione e a PATH](docs/INSTALL.md). |
| 31 | |
| 32 | Il completamento con Tab si attiva con un solo comando per ogni shell — `codewhale completion bash|zsh|fish|powershell|elvish`. Consulta il [completamento della shell](docs/INSTALL.md#8-shell-completions). |
| 33 | |
| 34 | ## Utilizzo |
| 35 | |
| 36 | Apri un terminale nella cartella del tuo progetto ed esegui `codewhale`. Scegli il provider con `/provider` e il modello con `/model`. Poi descrivi un’attività concreta: |
| 37 | |
| 38 | ```text |
| 39 | Fix the failing tests and explain what changed. |
| 40 | ``` |
| 41 | |
| 42 | Oppure esegui un’attività senza aprire la TUI: |
| 43 | |
| 44 | ```bash |
| 45 | codewhale exec "fix the failing tests and explain what changed" |
| 46 | ``` |
| 47 | |
| 48 | Codewhale può leggere il tuo repository, modificare file, eseguire comandi, controllare i risultati e continuare a lavorare verso un obiettivo. Usa `/mode plan` per esplorare senza modificare file né eseguire comandi shell, e `/mode work` quando vuoi che apporti modifiche. Premi `Shift+Tab` per scegliere Ask, Auto-Review o Full Access; la [guida a modalità e permessi](docs/MODES.md) spiega cosa consente ogni opzione. |
| 49 | |
| 50 | ## Terminale, app e Computer Use |
| 51 | |
| 52 | Il terminale e i client grafici si collegano al Runtime di Codewhale, che esegue l’agente e i suoi strumenti: |
| 53 | |
| 54 | - **Terminale:** `codewhale` apre l’interfaccia interattiva; `codewhale exec` esegue un’attività da uno script o da un job di CI. |
| 55 | - **Browser locale:** `codewhale web` apre il [client web locale](docs/WEB.md) incluso, che usa lo stesso runtime. |
| 56 | - **App desktop Codewhale (GPUI):** l'app desktop nativa GPUI è la direzione del client di prodotto (decisione del 2026-09-14; la mappa delle fasi è in docs/TRANSITION.md nel repository privato codehwhale-gpui). L'app web ospitata su app.codewhale.net viene ritirata per fasi; il sito marketing, l'accesso, la fatturazione e le pagine legali e di download restano permanentemente sul web. La disponibilità è indicata nella [pagina del prodotto](https://codewhale.net/en/product). |
| 57 | |
| 58 | **Computer Use aggiunge strumenti per osservare altre applicazioni e interagire con esse.** Il plugin è incluso nel codice sorgente attuale. Controlla l’accesso richiesto e abilitalo prima dell’uso; i permessi del sistema operativo e i requisiti della piattaforma continuano ad applicarsi. Consulta la [guida a Computer Use](crates/tui/plugins/computer-use/README.md) inclusa e la [configurazione dei plugin](docs/PLUGINS.md). |
| 59 | |
| 60 | Per VS Code, l’estensione CodeWhale mantenuta dalla comunità si collega al Runtime locale da una barra laterale. Installala dal [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=HengQuWorld.brotherwhale-vscode); il codice sorgente è su [GitHub](https://github.com/HengQuWorld/CodeWhale-VSCode). |
| 61 | |
| 62 | ## Perché Codewhale |
| 63 | |
| 64 | - **Scegli i tuoi modelli.** Collega provider gestiti oppure modelli locali tramite Ollama, vLLM o SGLang. Usa `/provider` per cambiare provider e `/model` per scegliere un modello. |
| 65 | - **Mantieni il controllo.** Controlla le azioni proposte e le modifiche ai file che ne derivano. Le impostazioni di approvazione determinano quando è necessaria una revisione; Full Access continua a rispettare i limiti vincolanti delle regole. `/undo` e `/restore` aiutano a recuperare le modifiche dell’area di lavoro. |
| 66 | - **Mantieni organizzati i lavori lunghi.** Salva le sessioni, imposta un `/goal` duraturo, rivedi i workflow prima dell’esecuzione e coordina gli agenti senza trasformare le loro istruzioni interne in parte della tua conversazione. |
| 67 | - **Estendi l’agente che hai già.** Collega server MCP e skill, configura gli hook e conserva i ruoli degli agenti come file leggibili nel progetto o nelle impostazioni personali. |
| 68 | |
| 69 | Esegui `/help` nella TUI per vedere i comandi e le scorciatoie da tastiera. |
| 70 | |
| 71 | ## Sicurezza |
| 72 | |
| 73 | Codewhale viene eseguito sul tuo computer con l’accesso che gli concedi. Le modalità di approvazione e le regole del repository limitano ciò che l’agente può fare; il sandboxing facoltativo del sistema operativo aggiunge un confine di esecuzione più solido dove supportato. I prezzi sconosciuti dei modelli restano indicati come sconosciuti anziché essere segnalati come gratuiti. |
| 74 | |
| 75 | Leggi l’[ordine di autorizzazione](docs/AUTHORIZATION_ORDER.md) per conoscere l’esatta gerarchia delle regole e la [configurazione](docs/CONFIGURATION.md) per le impostazioni locali. |
| 76 | |
| 77 | ## Documentazione |
| 78 | |
| 79 | - [Provider e modelli locali](docs/PROVIDERS.md) |
| 80 | - [Team di agenti](docs/FLEET.md) |
| 81 | - [MCP](docs/MCP.md), [hook](docs/HOOKS.md) e [configurazione](docs/CONFIGURATION.md) |
| 82 | - [Client web locale](docs/WEB.md) |
| 83 | - [Tutta la documentazione](docs) |
| 84 | - [Struttura del repository e guida ai contributi](CONTRIBUTING.md#project-structure) |
| 85 | |
| 86 | ## Unisciti alla comunità |
| 87 | |
| 88 | **Segnalazioni di bug, idee per nuove funzionalità e pull request sono benvenute**, sia che usi Codewhale da mesi sia che lo provi per la prima volta. Se manca un provider, un workflow risulta scomodo o l’interfaccia del terminale ti ostacola, [apri una issue](https://github.com/Hmbown/CodeWhale/issues/new/choose) oppure [invia una pull request](CONTRIBUTING.md) per migliorarlo insieme. I primi contributi sono benvenuti e chi contribuisce mantiene il riconoscimento per il lavoro integrato. |
| 89 | |
| 90 | Unisciti a [Discord](https://discord.gg/37gfS3ksug), oppure aggiungi Hunter su WeChat (`hunterbown`) e chiedi di entrare nel gruppo Whale Brothers. |
| 91 | |
| 92 | ## Storia del progetto |
| 93 | |
| 94 | Codewhale è nato come `deepseek-tui` e conserva ancora la compatibilità con la sua configurazione e le sue sessioni. Ora è indipendente dai provider, viene mantenuto in modo autonomo e non è affiliato ad alcun provider di modelli. |
| 95 | |
| 96 | Grazie a ogni persona che ha contribuito e alle comunità open source che hanno aiutato il progetto a crescere. Consulta il [registro dei contributori](docs/CONTRIBUTORS.md). |
| 97 | |
| 98 | ## Licenza |
| 99 | |
| 100 | [MIT](LICENSE). Le parti adattate da altri progetti open source sono indicate nelle [note sui componenti di terze parti](docs/THIRD_PARTY_NOTICES.md). |
| 101 |