| 1 | <!-- source: README.md sha256:ebf1c69de0dc --> |
| 2 | # Codewhale |
| 3 | |
| 4 | Codewhale é um agente de código aberto que lê seu projeto, edita arquivos, executa comandos e verifica o próprio trabalho usando um modelo hospedado ou local à sua escolha. Comece com uma tarefa no terminal. Para um trabalho maior, distribua partes do trabalho entre agentes com diferentes modelos e funções. |
| 5 | |
| 6 |  |
| 7 | |
| 8 | *Prévia do terminal em uma build de desenvolvimento da 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) · [Русский](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) · [Italiano](README.it.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 | ## Instalação |
| 18 | |
| 19 | Para uma nova instalação no macOS ou Linux, use a versão oficial do GitHub: |
| 20 | |
| 21 | ```bash |
| 22 | curl -fsSL https://codewhale.net/install.sh | sh |
| 23 | "$HOME/.local/bin/codewhale" |
| 24 | ``` |
| 25 | |
| 26 | O instalador seleciona a versão publicada mais recente. O [histórico de alterações](CHANGELOG.md) também descreve a versão candidata ainda não publicada da próxima versão; essas alterações só são incluídas nos downloads publicados quando a versão estiver disponível. |
| 27 | |
| 28 | No Windows, baixe o instalador ou arquivo correspondente em [GitHub Releases](https://github.com/Hmbown/CodeWhale/releases/latest). Para atualizar uma instalação direta existente, execute `codewhale update`, ou `codewhale update --check` apenas para verificar. O atualizador mostra o caminho do executável e preserva builds mais recentes. npm e Cargo são opções secundárias; consulte o [guia de instalação](docs/INSTALL.md) para migrar de um gerenciador de pacotes e configurar PATH. |
| 29 | |
| 30 | Na primeira execução, o Codewhale ajuda você a conectar um provedor ou a configurar o Codewhale offline. As respostas exigem um modelo hospedado ou local conectado. O Codewhale também oferece suporte a npm e Cargo como opções secundárias de distribuição, além de Docker, Nix, Scoop, Android/Termux e um espelho CNB opcional. Instalações existentes feitas por gerenciadores de pacotes recebem instruções de migração. Consulte a [ajuda de instalação e PATH](docs/INSTALL.md). |
| 31 | |
| 32 | O preenchimento automático com Tab é ativado com um comando por shell — `codewhale completion bash|zsh|fish|powershell|elvish`. Consulte o [preenchimento automático do shell](docs/INSTALL.md#8-shell-completions). |
| 33 | |
| 34 | ## Uso |
| 35 | |
| 36 | Abra um terminal na pasta do seu projeto e execute `codewhale`. Escolha seu provedor com `/provider` e seu modelo com `/model`. Depois, descreva uma tarefa concreta: |
| 37 | |
| 38 | ```text |
| 39 | Fix the failing tests and explain what changed. |
| 40 | ``` |
| 41 | |
| 42 | Ou execute uma tarefa sem abrir a TUI: |
| 43 | |
| 44 | ```bash |
| 45 | codewhale exec "fix the failing tests and explain what changed" |
| 46 | ``` |
| 47 | |
| 48 | O Codewhale pode ler seu repositório, editar arquivos, executar comandos, verificar resultados e continuar trabalhando em direção a um objetivo. Use `/mode plan` para explorar sem alterar arquivos nem executar comandos de shell, e `/mode work` quando quiser que ele faça alterações. Pressione `Shift+Tab` para escolher Ask, Auto-Review ou Full Access; o [guia de modos e permissões](docs/MODES.md) explica o que cada opção permite. |
| 49 | |
| 50 | ## Terminal, aplicativos e Computer Use |
| 51 | |
| 52 | O terminal e os clientes gráficos se conectam ao Runtime do Codewhale, que executa o agente e suas ferramentas: |
| 53 | |
| 54 | - **Terminal:** `codewhale` abre a interface interativa; `codewhale exec` executa uma tarefa a partir de um script ou de um job de CI. |
| 55 | - **Navegador local:** `codewhale web` abre o [cliente web local](docs/WEB.md) incluído, que usa o mesmo runtime. |
| 56 | - **Aplicativo de desktop Codewhale (GPUI):** o aplicativo de desktop nativo GPUI é a direção do cliente do produto (decisão de 2026-09-14; o mapa de fases está em docs/TRANSITION.md no repositório privado codehwhale-gpui). O aplicativo web hospedado em app.codewhale.net será descontinuado em fases; o site de marketing, o login, a cobrança e as páginas legais e de download permanecem na web permanentemente. A disponibilidade é informada na [página do produto](https://codewhale.net/en/product). |
| 57 | |
| 58 | **Computer Use adiciona ferramentas para observar outros aplicativos e interagir com eles.** O plugin está incluído no código-fonte atual. Revise o acesso solicitado e habilite-o antes de usar; as permissões do sistema operacional e os requisitos da plataforma continuam sendo necessários. Consulte o [guia de Computer Use](crates/tui/plugins/computer-use/README.md) incluído e a [configuração de plugins](docs/PLUGINS.md). |
| 59 | |
| 60 | Para VS Code, a extensão CodeWhale mantida pela comunidade se conecta ao Runtime local por uma barra lateral. Instale pelo [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=HengQuWorld.brotherwhale-vscode); o código-fonte está no [GitHub](https://github.com/HengQuWorld/CodeWhale-VSCode). |
| 61 | |
| 62 | ## Por que usar o Codewhale |
| 63 | |
| 64 | - **Escolha seus modelos.** Conecte provedores hospedados ou modelos locais por meio do Ollama, vLLM ou SGLang. Use `/provider` para trocar de provedor e `/model` para escolher um modelo. |
| 65 | - **Mantenha o controle.** Revise as ações propostas e as alterações resultantes nos arquivos. As configurações de aprovação determinam quando uma revisão é necessária; Full Access continua respeitando os limites obrigatórios das políticas. `/undo` e `/restore` ajudam a recuperar alterações no espaço de trabalho. |
| 66 | - **Mantenha trabalhos longos organizados.** Salve sessões, defina um `/goal` duradouro, revise os fluxos de trabalho antes da execução e coordene agentes sem transformar as instruções internas deles em parte da sua conversa. |
| 67 | - **Amplie o agente que você já tem.** Conecte servidores MCP e habilidades, configure hooks e mantenha as funções dos agentes como arquivos legíveis no projeto ou nas suas configurações pessoais. |
| 68 | |
| 69 | Execute `/help` na TUI para ver comandos e atalhos de teclado. |
| 70 | |
| 71 | ## Segurança |
| 72 | |
| 73 | O Codewhale é executado na sua máquina com o acesso que você conceder. Os modos de aprovação e as regras do repositório limitam o que o agente pode fazer; o sandbox opcional do sistema operacional adiciona um limite de execução mais forte quando disponível. Preços de modelos desconhecidos continuam sendo mostrados como desconhecidos, em vez de serem informados como gratuitos. |
| 74 | |
| 75 | Leia a [ordem de autorização](docs/AUTHORIZATION_ORDER.md) para conhecer a hierarquia exata das políticas e a [configuração](docs/CONFIGURATION.md) para os ajustes locais. |
| 76 | |
| 77 | ## Documentação |
| 78 | |
| 79 | - [Provedores e modelos locais](docs/PROVIDERS.md) |
| 80 | - [Equipes de agentes](docs/FLEET.md) |
| 81 | - [MCP](docs/MCP.md), [hooks](docs/HOOKS.md) e [configuração](docs/CONFIGURATION.md) |
| 82 | - [Cliente web local](docs/WEB.md) |
| 83 | - [Toda a documentação](docs) |
| 84 | - [Estrutura do repositório e guia de contribuição](CONTRIBUTING.md#project-structure) |
| 85 | |
| 86 | ## Participe da comunidade |
| 87 | |
| 88 | **Relatos de bugs, ideias de funcionalidades e pull requests são bem-vindos**, tanto de quem usa o Codewhale há meses quanto de quem está experimentando pela primeira vez. Se estiver faltando um provedor, se um fluxo de trabalho for inconveniente ou se a interface do terminal atrapalhar, [abra uma issue](https://github.com/Hmbown/CodeWhale/issues/new/choose) ou [envie um pull request](CONTRIBUTING.md) para melhorarmos juntos. Primeiras contribuições são bem-vindas, e os contribuidores mantêm o crédito pelo trabalho incorporado ao projeto. |
| 89 | |
| 90 | Participe do [Discord](https://discord.gg/37gfS3ksug), ou adicione Hunter no WeChat (`hunterbown`) e peça para entrar no grupo Whale Brothers. |
| 91 | |
| 92 | ## História do projeto |
| 93 | |
| 94 | O Codewhale começou como `deepseek-tui` e ainda preserva a compatibilidade com as configurações e sessões desse projeto. Hoje ele é neutro em relação a provedores, mantido de forma independente e não tem afiliação com nenhum provedor de modelos. |
| 95 | |
| 96 | Agradecemos a cada contribuidor e às comunidades de código aberto que ajudaram o projeto a crescer. Consulte o [registro de contribuidores](docs/CONTRIBUTORS.md). |
| 97 | |
| 98 | ## Licença |
| 99 | |
| 100 | [MIT](LICENSE). As partes adaptadas de outros projetos de código aberto estão registradas nos [avisos de terceiros](docs/THIRD_PARTY_NOTICES.md). |
| 101 |