Forge: harness de codificação com IA agnóstico de modelo e CLI — guia de decisão antes do primeiro uso

Para quem é

• Para desenvolvedores que querem concluir tarefas de codificação no terminal com um CLI/TUI nativo e que desejam que cada tarefa seja roteada automaticamente para o modelo com melhor relação «custo × capacidade». É um harness de codificação com IA, agnóstico de modelo, escrito em Rust, em um único binário nativo, sem necessidade de runtime Node, Python ou Bun.
• Se você quiser usá-lo por meio de um aplicativo de desktop, apps companheiros para iOS/Android/Web ou uma API local compatível com OpenAI, a documentação oficial indica que essas formas também são oferecidas.
• Quando não é adequado: se você precisa de um método de instalação diferente de um assistente de configuração gráfico, ou depende de um ecossistema específico de plugins/extensões, as evidências não fornecem esses detalhes e não é possível confirmar; quanto a quais agentes específicos são suportados e quais ambientes de linguagem são suportados, as evidências oficiais não dizem nada — isso é desconhecido, não faça suposições por conta própria.
• Pré-requisito de uso: credenciais de modelo acessíveis. O forge setup guia a conexão de modelos, as configurações de segurança e custo, a busca, a importação e os serviços em segundo plano; as chaves de API são armazenadas no keyring do sistema operacional.

Primeira tentativa em 3 minutos

Há apenas um caminho principal recomendado: o script de instalação shell de uma linha, oficial.

1. Pré-requisito: um terminal capaz de executar shell, com acesso ao GitHub.
2. Execute no terminal:

curl -fsSL https://raw.githubusercontent.com/Adulari/forge/main/install.sh | sh

O script baixa o binário de release correspondente e o instala em ~/.local/bin.

1. Ponto de verificação de efeitos colaterais: a instalação interativa, por padrão, também instala o aplicativo Forge para desktop. Se não quiser isso, responda n quando solicitado (ou defina FORGE_DESKTOP=0 para pular). Como se trata de uma instalação que executa um script remoto via pipe, verifique por conta própria a confiança na fonte antes de executar.
2. Após a instalação, inicie o forge; na primeira execução, o fluxo forge setup é aberto automaticamente — siga as instruções para conectar modelos e as configurações de segurança/custo.
3. Para a primeira tarefa, recomenda-se escolher algo de baixo risco e de natureza analítica, por exemplo, pedir que ele explique um trecho de código ou resuma a estrutura do projeto no repositório atual. Sinal de sucesso observável: a tarefa é despachada e a resposta/análise do modelo aparece na UI do terminal. Quanto a esse processo ler ou gravar seus arquivos, executar comandos ou acessar a rede, as evidências não dizem nada — antes de executar tarefas que fazem alterações, confirme por conta própria e mantenha os pontos de verificação sob controle.

Outros modos (apenas como observação secundária): em um repositório clonado, os hooks, MCP servers, temper e regras allow dentro de .forge/ permanecem inativos até que forge trust seja executado.

Casos de uso

Caso 1: entender rapidamente um repositório desconhecido a baixo custo. Cenário: você assume um projeto de código que não conhece. Procedimento: inicie a UI de terminal do forge no diretório do repositório e faça uma tarefa analítica somente leitura, por exemplo, «resuma a estrutura e os pontos de entrada deste projeto». Ele encaminha a tarefa ao modelo adequado conforme seu mecanismo de roteamento, e você vê o resultado diretamente na TUI. Resultado esperado: uma visão geral do projeto; é uma tarefa analítica, sem modificação de arquivos.

Caso 2: execução única (headless) de uma solicitação de codificação. Cenário: uso em scripts ou quando você não quer entrar na interface interativa. Procedimento: invoque o forge em modo one-shot/headless via CLI, submetendo uma tarefa de codificação bem definida (as evidências não fornecem o formato específico dos argumentos de linha de comando; o que se pode confirmar é apenas que essa forma existe). Resultado esperado: a tarefa é roteada para o modelo ótimo escolhido por custo × capacidade e a saída é retornada. Para tarefas de codificação que envolvem modificação de arquivos ou execução de comandos, defina claramente o escopo das alterações antes de submeter; as evidências não descrevem o comportamento de efeitos colaterais, então é preciso fazer a verificação no nível do ambiente por conta própria.

Limites de uso

• Efeito colateral da instalação: o script de instalação de uma linha instala por padrão também o aplicativo de desktop (o padrão interativo é yes); recuse com n ou FORGE_DESKTOP=0.
• Fronteira de confiança no nível do repositório: os hooks, MCP servers, temper e regras allow de .forge/ em um repositório clonado ficam inativos por padrão e só entram em vigor com um forge trust explícito — este é um ponto de verificação de segurança declarado oficialmente.
• Ambiente de execução: um único binário nativo em Rust, sem dependências de Node/Python/Bun/Electron. As chaves de API ficam no keyring do sistema operacional.
• Além das limitações declaradas oficialmente, as evidências não fornecem as seguintes informações, que permanecem desconhecidas: quais clientes de agente específicos são suportados, quais linguagens naturais/de programação são suportadas e se operações de revisão ou diagnóstico leem/gravam arquivos, executam comandos ou acessam a rede. Não trate o desconhecido como «risco zero»; para qualquer tarefa que altere arquivos, execute comandos ou chame serviços externos, confirme os efeitos colaterais antes de executar.