Ferret
Português (Brasil)
Discord (abre em uma nova aba) X (abre em uma nova aba) GitHub (abre em uma nova aba) Download

Usando o Ferret

Enviar a agentes

Rode seu agente de programação no terminal integrado e entregue a ele uma revisão com um clique. Claude Code e Codex são os exemplos mais comuns, mas qualquer agente da lista abaixo funciona, assim como uma CLI que você mesmo adicionar. Você também pode copiar a instrução para um agente que roda em outro lugar ou publicar a revisão no GitHub.

#Revisar os apontamentos

Cada cartão da aba Apontamentos permite:

  • Editar o título e o pedido ali mesmo
  • Alternar entre Enviar / Não enviar
  • Ver gravação (vai até aquele momento) e Substituir imagem (escolher outro quadro)
  • Confirmar / Marcar como Precisa de revisão, Mesclar com o próximo, Excluir

Filtrar por progresso mostra ou oculta os apontamentos por status (por exemplo, Somente os que aguardam a sua revisão); Mostrar tudo remove o filtro.

O cabeçalho tem Desfazer, Abrir pasta, Copiar para o Agent, Enviar ao GitHub / GitLab, Organizar e Enviar ao Agent. As falas que não viraram apontamento aparecem em Falas excluídas, onde Restaurar como apontamento as traz de volta.

A aba Apontamentos

#Rodar agentes no terminal integrado

Quando um projeto abre, o Ferret inicia uma aba de terminal para cada agente de Configurações → Agents → Iniciar ao abrir um projeto, na pasta do projeto e no modo normal do agente. O padrão é Claude Code e Codex:

claude
codex

Você pode escolher outros agentes da lista de suportados (eles iniciam na ordem em que você os escolher) ou nenhum.

Os pedidos de permissão continuam ativos

Registrar ou clonar um projeto não faz o Ferret confiar nele. Agentes como Claude Code e Codex perguntam se você confia na pasta na primeira vez e continuam perguntando antes de editar arquivos ou executar comandos. Para permitir que os agentes pulem pedidos de permissão, aprovações e o sandbox em um projeto em que você confia, ative isso para esse projeto em Configurações → Agents → Pular pedidos de permissão e confirme. O Ferret adiciona a flag de pular permissões própria de cada agente, quando ela é conhecida; agentes sem uma flag conhecida mantêm os pedidos. A partir daí, isso vale só para os agentes que você mesmo abrir na pasta desse projeto; os agentes iniciados quando o projeto abre sempre mantêm os pedidos. Flags de pular permissões digitadas nos argumentos são ignoradas.

Se nenhum agente estiver selecionado, abre-se um shell comum. O menu + abre um Novo terminal, inicia qualquer um dos seus agentes em uma nova aba ou leva a Configurações de Agents…. A caixa de busca dele também encontra abas, URLs salvas e arquivos.

As abas mostram o estado do agente: Em execução, Aguardando entrada, Concluído (não lido), Ocioso. Na barra lateral, um projeto com um agente em execução fica marcado, então você vê isso sem trocar de projeto.

Arrastando abas e painéis do terminal para dividir, mover e transformá-los de volta em abas.

Arraste para dividir. Arraste uma aba, ou um painel pela alça (que aparece quando uma aba está dividida), e solte:

  • no quarto externo da borda de um painel: Dividir à esquerda / Dividir à direita / Dividir acima / Dividir abaixo
  • no centro de um painel: Abrir como aba (um painel sai da divisão e vira uma aba própria)
  • na faixa fina ao redor de toda a área do terminal: Dividir toda a área à esquerda e assim por diante (quando há 2 ou mais painéis)
  • na barra de abas: Colocar como aba aqui

Os processos continuam rodando enquanto você os move, e uma aba que fica vazia é fechada. Divisões pelo teclado:

AçãomacOSWindows / Linux
Novo terminal⌘TCtrlT
Dividir à direita⌘DCtrlShiftD
Dividir abaixo⌘⇧DAltShiftD
Fechar painel / aba⌘WCtrlW

#Agentes suportados

O Ferret não está preso a um único agente. Ele reconhece os agentes de programação abaixo: consegue iniciá-los, detectá-los em um terminal para o Enviar ao Agent e mostrar se estão instalados. Configurações → Agents os lista com Instalado / Não encontrado, um botão Instalar quando o fornecedor publica um instalador de uma linha, e o comando e os argumentos de cada um.

Não está na lista? Configurações → Agents → Adicionar agent personalizado registra qualquer CLI ou script wrapper (um nome, um comando e, opcionalmente, o nome do processo usado para reconhecê-lo), ou adicione-o a agents.customAgents no settings.json. Agentes que rodam fora do Ferret podem usar Copiar para o Agent.

Alguns recursos dependem do agente e, por enquanto, estão limitados ao Claude Code e ao Codex:

  • Contas e uso: alternar entre vários logins e o medidor de limite de uso no rodapé.
  • Organizar: roda com o seu login do Claude Code ou do Codex, ou com uma API de LLM que você configurar.

#Enviar ao Agent / Copiar para o Agent

Da aba Apontamentos para o agente no terminal integrado com Enviar ao Agent.
  1. Clique em Enviar ao Agent. Por padrão (Automático (aba atual ou um agent em execução)), o envio vai para o agente da aba de terminal atual ou para um que esteja em execução. Use a seta ao lado do botão (Escolha o agent de destino) para escolher um agente ou uma aba específica.
  2. O Ferret escreve a instrução na entrada do agente e a envia. Acompanhe o progresso no terminal.

Se nenhum agente estiver em execução, o Ferret inicia um primeiro e envia assim que ele estiver pronto. Nada é enviado enquanto o agente aguarda uma resposta a um pedido de permissão. Responda no terminal primeiro.

Copiar para o Agent coloca a mesma instrução na área de transferência para um agente que roda em outro lugar (outro terminal, IDE ou app). Só os apontamentos marcados como Enviar são incluídos. O vídeo nunca é incluído.

#Verificação de aceitação com um modelo de decisão

O agente corrige os apontamentos e verifica cada um com o modelo de decisão até que todos sejam aprovados.

Ative isso e o seu agente de programação confere o próprio trabalho em relação a cada apontamento antes de informar que terminou. O Ferret não julga nada por conta própria: ele dá ao agente um modelo de decisão (qualquer API compatível com System One) e, no feedback.md, diz a ele para repetir até que todos os apontamentos sejam aprovados.

  1. O agente implementa os apontamentos.
  2. Para cada apontamento, ele faz uma captura de tela DEPOIS (com a mesma viewport e o mesmo estado da página da imagem ANTES) e envia ao modelo de decisão uma requisição com o texto do apontamento, a linha "Done when" dele e as imagens ANTES/DEPOIS.
  3. Um apontamento é aprovado quando P(done) é pelo menos o limiar (padrão 0.7) e a escolha é done. O agente corrige o restante e reavalia todos os apontamentos a cada rodada, e só para quando todos são aprovados na mesma rodada ou por um motivo honesto que ele precisa declarar: a API está inacessível, um apontamento está fora do escopo ou um apontamento está travado com as pontuações inalteradas.
  4. A lista final de Concluído / Não concluído inclui as pontuações de cada apontamento e o número de rodadas.

Configure em Configurações → Modelo de decisão e ative Adicionar a verificação do modelo de decisão às instruções do agent. As predefinições só preenchem os campos; todos os campos continuam editáveis, e Personalizado funciona com qualquer API compatível.

PredefiniçãoURL da requisiçãoModelosChave
Ollama (padrão)http://localhost:11434/v1/systemoneclef-flash, clef (leem imagens); nimble, tev1 (só texto)nenhuma, gratuito
Cloudflare Workers AIhttps://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/cloudflare/{model}clef-flash, clef (leem imagens)CLOUDFLARE_API_TOKEN (permissão Workers AI); ID da conta pelo campo ou por CLOUDFLARE_ACCOUNT_ID
Vercel AI Gatewayhttps://ai-gateway.vercel.sh/typesafe/v1/systemonetypesafe-ai/jev, convaiinnovations/laya (só texto)AI_GATEWAY_API_KEY
TypeSafehttps://api.typesafe.ai/v1/systemonejev-latest, jev-preview (só texto)TYPESAFE_API_KEY
Personalizadoqualquer URL completaqualquerBearer, um cabeçalho personalizado ou nenhuma; cabeçalhos extras permitidos

Para o Ollama, instale-o (0.35.1 ou posterior para Clef / Clef Flash) e baixe o modelo em um terminal. O Ferret não executa instaladores:

ollama pull clef-flash

As chaves vêm do campo de chave (salva junto com suas outras chaves de API), de uma variável de ambiente que você indicar (o ambiente do app, o .env do projeto ou ~/.ferret/.env) ou de apiKey no settings.json. Cabeçalhos extras podem ler valores de variáveis de ambiente com ${VAR}.

Como a chave fica fora dos prompts

Os agentes nunca veem a sua chave. O Ferret roda um relay local em 127.0.0.1 e entrega a cada terminal FERRET_DECISION_URL (o relay, com um token por terminal), FERRET_DECISION_MODEL e FERRET_DECISION_IMAGES (durante uma versão, os nomes antigos MOVIE_ADE_DECISION_* também são definidos). O relay adiciona a chave e os cabeçalhos e encaminha a requisição sem alterações, então prompts, o feedback.md e as transcrições dos agentes não contêm segredos. Os terminais abertos depois que você muda as configurações passam a usá-las.

O Cloudflare difere da documentação do System One em dois pontos (verificados na API real): as imagens precisam ser data URIs (data:image/jpeg;base64,…; caso contrário, 422 "image must be an embedded base64 data URI"), e a resposta vem envolvida como { "result": { … }, "success": true } (os erros voltam como { "success": false, "errors": [ … ] }). A predefinição do Cloudflare define Codificação das imagens como data URI, os agentes recebem isso como FERRET_DECISION_IMAGE_FORMAT, e as instruções dizem a eles para ler .result quando existir. O relay repassa as duas direções sem alterações. Para usar uma Global API Key em vez de um API token, defina Autenticação como Sem chave e adicione os cabeçalhos X-Auth-Email: ${CLOUDFLARE_EMAIL} e X-Auth-Key: ${CLOUDFLARE_API_KEY}.

Só o Clef e o Clef Flash leem imagens. Com um modelo só de texto, desative Enviar imagens ANTES/DEPOIS; o agente então avalia só pelo texto, o que é menos confiável.

Ollama e imagens grandes

O Ollama 0.35.0 limita as requisições a /v1/systemone a 64 KiB, então requisições com capturas de tela falham com HTTP 413. As instruções dizem ao agente para reduzir as duas imagens a no máximo 1024px de largura em JPEG (qualidade em torno de 70). Se ainda receber 413, atualize o Ollama para 0.35.1 ou posterior, ou troque para o Cloudflare Workers AI.

#Uso da API no rodapé

As chamadas de decisão passam pelo relay, então o Ferret consegue contá-las. O item do rodapé ao lado do medidor de uso do agente mostra o modelo de decisão e as chamadas, tokens e custo do dia (por exemplo clef-flash · 42 calls · 18.3k tok). Clique nele para ver hoje, este mês, por projeto, por modelo e por tipo (decisão / transcrição / organização), além das últimas 50 chamadas.

O custo só aparece quando a API o informa (o Vercel AI Gateway informa) ou quando você define preços por 1M de tokens em Configurações → Modelo de decisão; caso contrário, aparece "—". Só metadados são registrados (horário, projeto, modelo, status, latência, tamanho, número de imagens, tokens, custo), nunca imagens, textos ou chaves, em ~/.ferret/usage/decision-YYYY-MM.jsonl, um arquivo por mês.

#Personalizar a instrução

Edite Configurações → Agents → Instruções para o Agent. Duas variáveis são expandidas:

VariávelExpande para
{{path}}Caminho absoluto do feedback.md
{{relpath}}Caminho relativo ao projeto: .ferret/reviews/<id>/feedback.md

Deixe em branco para usar o padrão. O tamanho máximo é de 2000 caracteres, e Redefinir instruções restaura o padrão. Exemplo:

Read {{relpath}} and the PNGs next to it. Fix only findings marked to send, one commit per finding, then run the tests.

A configuração é armazenada como agentPrompt no settings.json.

#Enviar ao GitHub ou ao GitLab (issue / comentário em PR ou MR)

Enviar ao GitHub publica a revisão como uma nova issue ou como um comentário em um dos seus pull requests abertos. A autenticação fica a cargo da GitHub CLI (abre em uma nova aba). O Ferret nunca lê nem armazena um token.

  1. Instale o gh: brew install gh (macOS), winget install --id GitHub.cli (Windows) ou veja cli/cli (abre em uma nova aba).
  2. Configurações → GitHub / GitLab → Fazer login no terminal executa gh auth login --web -h github.com no terminal integrado.
  3. Clique em Enviar ao GitHub, escolha Criar uma nova Issue ou um PR e revise o Título e o Corpo (editáveis).
  4. Marque a caixa de confirmação e clique em Criar Issue ou Publicar comentário.

Detalhes:

  • O repositório vem de git remote get-url origin.
  • O Ferret executa gh issue create --repo … --title … --body-file - ou gh pr comment <n> --repo … --body-file -.
  • O corpo é o feedback.md sem as linhas de imagem (as imagens não são enviadas), com até 60.000 caracteres.
  • Os PRs candidatos são os seus próprios PRs abertos (até 30).

Se GH_TOKEN ou GITHUB_TOKEN estiver definido, o gh o usa primeiro, e o painel de configurações avisa sobre isso.

GitLab. Quando o origin é um projeto do GitLab (gitlab.com ou um GitLab autogerenciado), o mesmo botão envia ao GitLab pela GitLab CLI (abre em uma nova aba) (glab): uma nova issue ou um comentário em um dos seus merge requests abertos. Faça login com Configurações → GitHub / GitLab, que executa glab auth login (com --hostname para um GitLab autogerenciado) no terminal integrado. O Ferret nunca lê nem armazena o token e avisa quando GITLAB_TOKEN está definido.

Pedido de estrela. Depois do seu primeiro Enviar ao Agent, e quando você chega a 3, 10 e 30 revisões concluídas, o Ferret pode pedir que você dê uma estrela a ele no GitHub. Ele pede no máximo 3 vezes, com pelo menos 3 dias de intervalo, e nunca durante uma gravação. Dar estrela no GitHub dá a estrela pelo seu próprio login do gh (ou abre o GitHub se o gh não estiver disponível), e Não perguntar novamente encerra os pedidos. Você também pode dar a estrela em Ajuda → Dar estrela ao Ferret no GitHub.

#Instalar ferramentas CLI e fazer login nelas

Configurações → Ferramentas CLI lista ferramentas de linha de comando de que seus agentes costumam precisar, mostra quais estão instaladas e a versão delas, e executa o comando oficial de instalação ou de login para o seu sistema em uma nova aba de terminal:

  • Hospedagem Git: gh, glab
  • IA e modelos: Ollama, Cloudflare wrangler
  • Deploy: Vercel, Netlify, Fly.io, Railway, Heroku
  • Nuvem e serviços: Supabase, Firebase, Stripe, Google Cloud (gcloud), AWS, Azure, Docker

Quando uma ferramenta não tem um instalador oficial de uma linha para o seu sistema, Documentação abre a página de instalação dela. A lista verifica de novo sozinha quando uma instalação termina.

Ajude a traduzir esta página no GitHub (abre em uma nova aba)