| 1 | <!-- source: README.md sha256:604da19bff2c --> |
| 2 | <div align="center"> |
| 3 | |
| 4 | <picture> |
| 5 | <source media="(prefers-color-scheme: dark)" srcset="brand/wordmark-inverted.svg"> |
| 6 | <img src="brand/wordmark.svg" alt="Codewhale" width="320"> |
| 7 | </picture> |
| 8 | |
| 9 | **L’agente di programmazione open source che funziona con qualsiasi modello.** |
| 10 | |
| 11 | Codewhale legge il tuo progetto, modifica i file, esegue comandi e controlla il proprio |
| 12 | lavoro — nel tuo terminale, con un modello ospitato o locale a tua scelta. |
| 13 | |
| 14 | [](https://github.com/codewhale-hq/CodeWhale/actions/workflows/ci.yml) |
| 15 | [](https://crates.io/crates/codewhale-cli) |
| 16 | [](https://www.npmjs.com/package/codewhale) |
| 17 | [](LICENSE) |
| 18 | [](https://discord.gg/37gfS3ksug) |
| 19 | |
| 20 | [Sito web](https://codewhale.net) · [Documentazione](docs/README.md) · [Changelog](CHANGELOG.md) · [Contribuire](CONTRIBUTING.md) |
| 21 | |
| 22 | [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) |
| 23 | |
| 24 | <img src="web/public/codewhale-tui-8ba2bbf.png" alt="Una sessione di terminale di Codewhale" width="760"> |
| 25 | |
| 26 | <sub>Acquisizione reale del terminale di una nuova installazione — nessun output simulato.</sub> |
| 27 | |
| 28 | </div> |
| 29 | |
| 30 | ## Installazione |
| 31 | |
| 32 | macOS e Linux: |
| 33 | |
| 34 | ```bash |
| 35 | curl -fsSL https://codewhale.net/install.sh | sh |
| 36 | ``` |
| 37 | |
| 38 | Il programma di installazione scarica in `~/.local/bin` binari con checksum verificato. Se |
| 39 | `codewhale` risponde poi «command not found», esegui l’unica riga PATH che l’installer |
| 40 | stampa, oppure consulta [Aggiungere al PATH](docs/INSTALL.md#put-it-on-your-path). |
| 41 | Aggiorna in qualsiasi momento con `codewhale update`. |
| 42 | |
| 43 | <details> |
| 44 | <summary><b>Windows, npm, Cargo e altre vie</b></summary> |
| 45 | |
| 46 | ```bash |
| 47 | winget install HunterBown.CodeWhale # Windows x64 (or Scoop, or the installer from GitHub Releases) |
| 48 | npm install -g codewhale # wraps the same release binaries |
| 49 | cargo install codewhale-cli --locked # build from crates.io |
| 50 | ``` |
| 51 | |
| 52 | Docker, Nix, Homebrew su Linux, Android/Termux, download manuali con verifica del checksum |
| 53 | e il mirror CNB opzionale sono descritti nella |
| 54 | [guida all’installazione](docs/INSTALL.md). Scegli una sola via: più installazioni |
| 55 | sulla stessa macchina finiscono per contendersi il `PATH`. |
| 56 | |
| 57 | </details> |
| 58 | |
| 59 | ## Avvio rapido |
| 60 | |
| 61 | 1. **Apri il tuo progetto.** Esegui `codewhale` nella cartella su cui vuoi lavorare. |
| 62 | 2. **Collega un modello.** Esegui `/provider` (o premi `F3`) per aggiungere una chiave |
| 63 | ospitata o scegliere un runtime locale. Se Ollama è già in esecuzione con un modello di |
| 64 | chat, Codewhale passa a quello da solo. Usa `/model` per cambiare modello. |
| 65 | 3. **Dagli un compito concreto.** |
| 66 | |
| 67 | ```text |
| 68 | Fix the failing tests and explain what changed. |
| 69 | ``` |
| 70 | |
| 71 | Lo stesso compito gira senza interfaccia da uno script o da un job di CI: |
| 72 | |
| 73 | ```bash |
| 74 | codewhale exec "fix the failing tests and explain what changed" |
| 75 | ``` |
| 76 | |
| 77 | Esegui `/help` per i comandi e le scorciatoie da tastiera. |
| 78 | |
| 79 | ## Modi di eseguirlo |
| 80 | |
| 81 | Ogni client pilota lo stesso Runtime Codewhale locale, quindi sessioni, strumenti e |
| 82 | permessi si comportano allo stesso modo ovunque. |
| 83 | |
| 84 | | Comando | Cosa fa | |
| 85 | | --- | --- | |
| 86 | | `codewhale` | L’interfaccia interattiva nel terminale | |
| 87 | | `codewhale exec "…"` | Un turno senza interfaccia da uno script o dalla CI, con JSON in streaming | |
| 88 | | `codewhale web` | Il [client browser locale](docs/WEB.md) incluso, su `127.0.0.1` | |
| 89 | | `codewhale review --pr N` | Una [revisione di pull request](docs/GITHUB_ACTION.md) a scopo consultivo; la pubblicazione è facoltativa | |
| 90 | | Runtime API | Una [API HTTP locale](docs/RUNTIME_API.md) per thread, eventi e approvazioni | |
| 91 | |
| 92 | Un’app desktop nativa (GPUI) è in sviluppo come client del prodotto per gli utenti con |
| 93 | account; consulta la |
| 94 | [pagina del prodotto](https://codewhale.net/en/product) per la disponibilità. L’[estensione VS Code](https://marketplace.visualstudio.com/items?itemName=HengQuWorld.brotherwhale-vscode) |
| 95 | mantenuta dalla comunità si connette allo stesso Runtime da una barra laterale ([sorgente](https://github.com/HengQuWorld/CodeWhale-VSCode)). |
| 96 | |
| 97 | ## Cosa fa |
| 98 | |
| 99 | - **Qualsiasi modello, nessun vincolo.** Oltre 40 percorsi di provider integrati — Anthropic, |
| 100 | DeepSeek, Google, Mistral, Moonshot, OpenAI, OpenRouter, xAI e altri — più |
| 101 | qualsiasi endpoint compatibile con OpenAI e modelli locali tramite Ollama, vLLM o SGLang. |
| 102 | [Provider](docs/PROVIDERS.md) |
| 103 | - **Resti tu al controllo.** La modalità Plan esplora senza modificare nulla; Work |
| 104 | e Operate apportano modifiche. Le posture di approvazione decidono quando una chiamata a uno |
| 105 | strumento richiede il tuo consenso, `/undo` e `/restore` ripristinano le modifiche |
| 106 | all’area di lavoro, e `/receipts` elenca ogni file, comando e approvazione di una sessione. |
| 107 | [Modalità](docs/MODES.md) · [Ricevute](docs/RECEIPTS.md) |
| 108 | - **Pensato per i lavori lunghi.** Imposta un `/goal` duraturo, delega lavoro circoscritto a |
| 109 | [sub-agenti](docs/SUBAGENTS.md), avvia [team di agenti](docs/FLEET.md) supervisionati |
| 110 | con un controllo prima della spesa, oppure scrivili come |
| 111 | [workflow](docs/WORKFLOW_AUTHORING.md) versionati nel repository. |
| 112 | - **Estendi ciò che già usi.** Collega [server MCP](docs/MCP.md), installa |
| 113 | [skill](docs/SKILLS.md) e [plugin](docs/PLUGINS.md), esegui |
| 114 | [hook](docs/HOOKS.md) sugli eventi di sessione e di strumento e carica i |
| 115 | [plugin di Claude Code](docs/CLAUDE_PLUGIN_COMPAT.md) esistenti. |
| 116 | - **Computer Use.** Un plugin incluso aggiunge strumenti per osservare e usare altre |
| 117 | applicazioni. Controlla i suoi accessi e abilitalo prima dell’uso. |
| 118 | [Guida](crates/tui/plugins/computer-use/README.md) |
| 119 | |
| 120 | ## Modalità e permessi |
| 121 | |
| 122 | | | Si sceglie con | Opzioni | |
| 123 | | --- | --- | --- | |
| 124 | | **Modalità** — cosa sta facendo l’agente | `Tab` o `/mode` | Plan (esplorare, nessuna modifica) · Work (modificare ed eseguire) · Operate (portare avanti un obiettivo con passaggi pianificati e verificati) | |
| 125 | | **Postura** — quando chiede prima | `Shift+Tab` | Ask · Auto-Review · Full Access | |
| 126 | |
| 127 | Full Access rispetta comunque i limiti rigidi delle policy. La |
| 128 | [guida a modalità e permessi](docs/MODES.md) spiega ogni opzione. |
| 129 | |
| 130 | ## Sicurezza |
| 131 | |
| 132 | Codewhale gira sulla tua macchina con gli accessi che gli concedi. Le posture di approvazione |
| 133 | e le regole del repository limitano ciò che l’agente può fare, e i comandi vengono eseguiti in |
| 134 | una sandbox del sistema operativo dove supportata (Seatbelt su macOS; bubblewrap su Linux è |
| 135 | facoltativo). `/preview-request` mostra la richiesta esatta, con i dati oscurati, prima che |
| 136 | venga inviato qualcosa. I prezzi dei modelli sconosciuti restano sconosciuti invece di essere |
| 137 | indicati come gratuiti. |
| 138 | |
| 139 | Consulta l’[ordine di autorizzazione](docs/AUTHORIZATION_ORDER.md), |
| 140 | la [sandbox](docs/SANDBOX.md) e la [telemetria](docs/TELEMETRY.md) — i contatori |
| 141 | di utilizzo sono attivi per impostazione predefinita e `codewhale config set telemetry false` li disattiva. |
| 142 | |
| 143 | ## Documentazione |
| 144 | |
| 145 | | Per iniziare | Per approfondire | |
| 146 | | --- | --- | |
| 147 | | [Installazione](docs/INSTALL.md) | [Configurazione](docs/CONFIGURATION.md) | |
| 148 | | [Provider e modelli locali](docs/PROVIDERS.md) | [Architettura](docs/ARCHITECTURE.md) | |
| 149 | | [Modalità e permessi](docs/MODES.md) | [Runtime API](docs/RUNTIME_API.md) | |
| 150 | | [Scorciatoie da tastiera](docs/KEYBINDINGS.md) | [Creare plugin](docs/PLUGIN_AUTHORING.md) | |
| 151 | | [Revisione PR su GitHub](docs/GITHUB_ACTION.md) | [Tutta la documentazione](docs/README.md) | |
| 152 | |
| 153 | ## Comunità |
| 154 | |
| 155 | Segnalazioni di bug, idee per nuove funzioni e pull request sono benvenute, che tu usi |
| 156 | Codewhale da mesi o lo stia provando per la prima volta. Se manca un provider o un workflow è |
| 157 | scomodo, [apri una issue](https://github.com/codewhale-hq/CodeWhale/issues/new/choose) o |
| 158 | [invia una pull request](CONTRIBUTING.md). I primi contributi sono benvenuti, e |
| 159 | chi contribuisce mantiene il riconoscimento per il lavoro integrato. La |
| 160 | [struttura del repository](CONTRIBUTING.md#project-structure) è un buon punto di partenza. |
| 161 | |
| 162 | Unisciti al [Discord](https://discord.gg/37gfS3ksug), oppure aggiungi Hunter su WeChat |
| 163 | (`hunterbown`) e chiedi di entrare nel gruppo Whale Brothers. |
| 164 | |
| 165 | ## Storia e licenza |
| 166 | |
| 167 | Codewhale è nato come `deepseek-tui` e legge ancora la configurazione e le sessioni di quel |
| 168 | progetto. Ora è indipendente da qualsiasi provider, mantenuto in modo autonomo e non è |
| 169 | affiliato ad alcun fornitore di modelli. Grazie a |
| 170 | [tutti i contributori](docs/CONTRIBUTORS.md) e alle comunità open source che |
| 171 | hanno aiutato la sua crescita. |
| 172 | |
| 173 | [MIT](LICENSE). Le parti adattate da altri progetti open source sono riportate negli |
| 174 | [avvisi di terze parti](docs/THIRD_PARTY_NOTICES.md). |
| 175 |