Referência de Configuração do Autohand

June 23, 2026 · View on GitHub

Referência completa de todas as opções de configuração em ~/.autohand/config.json (ou .yaml/.yml).

Dica: A maioria das configurações abaixo pode ser alterada interativamente usando o comando /settings em vez de editar o arquivo manualmente.

Referências localizadas：

Índice

Localização do Arquivo de Configuração

O Autohand procura a configuração nesta ordem:

  1. Variável de ambiente AUTOHAND_CONFIG (caminho personalizado)
  2. ~/.autohand/config.yaml
  3. ~/.autohand/config.yml
  4. ~/.autohand/config.json (padrão)

Você também pode sobrescrever o diretório base:

export AUTOHAND_HOME=/caminho/personalizado  # Altera ~/.autohand para /caminho/personalizado

Variáveis de Ambiente

VariávelDescriçãoExemplo
AUTOHAND_HOMEDiretório base para todos os dados do Autohand/caminho/personalizado
AUTOHAND_CONFIGCaminho personalizado do arquivo de configuração/caminho/para/config.json
AUTOHAND_API_URLEndpoint da API (sobrescreve configuração)https://api.autohand.ai
AUTOHAND_SECRETChave secreta da empresa/equipesk-xxx
AUTOHAND_PERMISSION_CALLBACK_URLURL para callback de permissão (experimental)http://localhost:3000/callback
AUTOHAND_PERMISSION_CALLBACK_TIMEOUTTimeout para callback de permissão em ms5000
AUTOHAND_NON_INTERACTIVEExecutar em modo não-interativo1
AUTOHAND_YESAuto-confirmar todos os prompts1
AUTOHAND_NO_BANNERDesabilitar banner de inicialização1
AUTOHAND_STREAM_TOOL_OUTPUTStream output das ferramentas em tempo real1
AUTOHAND_DEBUGHabilitar logging de debug1
AUTOHAND_THINKING_LEVELDefinir nível de raciocínionormal
AUTOHAND_CLIENT_NAMEIdentificador do cliente/editor (definido por extensões ACP)zed
AUTOHAND_CLIENT_VERSIONVersão do cliente (definido por extensões ACP)0.169.0

Nível de Raciocínio

A variável de ambiente AUTOHAND_THINKING_LEVEL controla a profundidade do raciocínio que o modelo usa:

ValorDescrição
noneRespostas diretas sem raciocínio visível
normalProfundidade de raciocínio padrão (padrão)
extendedRaciocínio profundo para tarefas complexas, mostra processo de pensamento mais detalhado

Isso é tipicamente definido por extensões cliente ACP (como Zed) através do dropdown de configuração.

# Exemplo: Use raciocínio extendido para tarefas complexas
AUTOHAND_THINKING_LEVEL=extended autohand --prompt "refatore este módulo"

Configurações do Provedor

provider

Provedor LLM ativo a ser usado.

ValorDescrição
"openrouter"API OpenRouter (padrão)
"ollama"Instância local do Ollama
"llamacpp"Servidor local llama.cpp
"openai"API OpenAI diretamente
"mlx"MLX em Apple Silicon (local)
"llmgateway"API unificada LLM Gateway

openrouter

Configuração do provedor OpenRouter.

{
  "openrouter": {
    "apiKey": "sk-or-v1-xxx",
    "baseUrl": "https://openrouter.ai/api/v1",
    "model": "your-modelcard-id-here"
  }
}
CampoTipoObrigatórioPadrãoDescrição
apiKeystringSim-Sua chave de API do OpenRouter
baseUrlstringNãohttps://openrouter.ai/api/v1Endpoint da API
modelstringSim-Identificador do modelo (ex.: your-modelcard-id-here)

ollama

Configuração do provedor Ollama.

{
  "ollama": {
    "baseUrl": "http://localhost:11434",
    "port": 11434,
    "model": "llama3.2"
  }
}
CampoTipoObrigatórioPadrãoDescrição
baseUrlstringNãohttp://localhost:11434URL do servidor Ollama
portnumberNão11434Porta do servidor (alternativa ao baseUrl)
modelstringSim-Nome do modelo (ex.: llama3.2, codellama)

llamacpp

Configuração do servidor llama.cpp.

{
  "llamacpp": {
    "baseUrl": "http://localhost:8080",
    "port": 8080,
    "model": "default"
  }
}
CampoTipoObrigatórioPadrãoDescrição
baseUrlstringNãohttp://localhost:8080URL do servidor llama.cpp
portnumberNão8080Porta do servidor
modelstringSim-Identificador do modelo

openai

Configuração da API OpenAI.

{
  "openai": {
    "apiKey": "sk-xxx",
    "baseUrl": "https://api.openai.com/v1",
    "model": "gpt-4o"
  }
}
CampoTipoObrigatórioPadrãoDescrição
apiKeystringSim-Chave de API da OpenAI
baseUrlstringNãohttps://api.openai.com/v1Endpoint da API
modelstringSim-Nome do modelo (ex.: gpt-4o, gpt-4o-mini)

mlx

Provedor MLX para Macs Apple Silicon (inferência local).

{
  "mlx": {
    "baseUrl": "http://localhost:8080",
    "port": 8080,
    "model": "mlx-community/Llama-3.2-3B-Instruct-4bit"
  }
}
CampoTipoObrigatórioPadrãoDescrição
baseUrlstringNãohttp://localhost:8080URL do servidor MLX
portnumberNão8080Porta do servidor
modelstringSim-Identificador do modelo MLX

llmgateway

Configuração da API unificada LLM Gateway. Fornece acesso a múltiplos provedores LLM através de uma única API.

{
  "llmgateway": {
    "apiKey": "sua-chave-api-llmgateway",
    "baseUrl": "https://api.llmgateway.io/v1",
    "model": "gpt-4o"
  }
}
CampoTipoObrigatórioPadrãoDescrição
apiKeystringSim-Chave de API do LLM Gateway
baseUrlstringNãohttps://api.llmgateway.io/v1Endpoint da API
modelstringSim-Nome do modelo (ex.: gpt-4o, claude-3-5-sonnet-20241022)

Obtendo uma Chave de API: Visite llmgateway.io/dashboard para criar uma conta e obter sua chave de API.

Modelos Suportados: O LLM Gateway suporta modelos de múltiplos provedores incluindo:

  • OpenAI: gpt-4o, gpt-4o-mini, gpt-4-turbo
  • Anthropic: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022
  • Google: gemini-1.5-pro, gemini-1.5-flash

Configurações do Workspace

{
  "workspace": {
    "defaultRoot": "/caminho/para/projetos",
    "allowDangerousOps": false
  }
}
CampoTipoPadrãoDescrição
defaultRootstringDiretório atualWorkspace padrão quando nenhum é especificado
allowDangerousOpsbooleanfalsePermitir operações destrutivas sem confirmação

Segurança do Workspace

O Autohand bloqueia automaticamente operações em diretórios perigosos para prevenir danos acidentais:

  • Raízes de filesystem (/, C:\, D:\, etc.)
  • Diretórios home (~, /Users/<user>, /home/<user>, C:\Users\<user>)
  • Diretórios do sistema (/etc, /var, /System, C:\Windows, etc.)
  • Montagens WSL do Windows (/mnt/c, /mnt/c/Users/<user>)

Esta verificação não pode ser ignorada. Se você tentar executar o autohand em um diretório perigoso, verá um erro e deverá especificar um diretório de projeto seguro.

# Isto será bloqueado
cd ~ && autohand
# Erro: Diretório de Workspace Inseguro

# Isto funciona
cd ~/projetos/my-app && autohand

Veja Segurança do Workspace para detalhes completos.

Configurações da Interface

{
  "ui": {
    "theme": "dark",
    "autoConfirm": false,
    "readFileCharLimit": 300,
    "showCompletionNotification": true,
    "showThinking": true,
    "useInkRenderer": false,
    "terminalBell": true,
    "checkForUpdates": true,
    "updateCheckInterval": 24
  }
}
CampoTipoPadrãoDescrição
theme"dark" | "light""dark"Tema de cores para saída do terminal
autoConfirmbooleanfalsePular prompts de confirmação para operações seguras
readFileCharLimitnumber300Máximo de caracteres exibidos em tools de leitura/busca (o conteúdo completo ainda é enviado ao modelo)
showCompletionNotificationbooleantrueMostrar notificação do sistema quando a tarefa terminar
showThinkingbooleantrueExibir o raciocínio/processo de pensamento do LLM
useInkRendererbooleanfalseUsar renderizador baseado em Ink para UI sem flicker (experimental)
terminalBellbooleantrueTocar sineta do terminal quando a tarefa terminar (mostra badge na aba/dock)
checkForUpdatesbooleantrueVerificar atualizações da CLI na inicialização
updateCheckIntervalnumber24Horas entre verificações de atualização (usa resultado em cache dentro do intervalo)

Nota: readFileCharLimit afeta apenas a exibição no terminal para read_file, search e search_with_context. O conteúdo completo ainda é enviado ao modelo e armazenado nas mensagens de ferramentas.

Sineta do Terminal

Quando terminalBell está habilitado (padrão), o Autohand toca a sineta do terminal (\x07) quando uma tarefa é concluída. Isso aciona:

  • Badge na aba do terminal - Mostra um indicador visual de que o trabalho foi concluído
  • Bounce do ícone no Dock - Chama sua atenção quando o terminal está em segundo plano (macOS)
  • Som - Se os sons do terminal estiverem habilitados nas configurações do seu terminal

Configurações específicas por terminal:

  • macOS Terminal: Preferências > Perfis > Avançado > Sineta (Visual/Audível)
  • iTerm2: Preferências > Perfis > Terminal > Notificações
  • VS Code Terminal: Configurações > Terminal > Integrated: Enable Bell

Para desabilitar:

{
  "ui": {
    "terminalBell": false
  }
}

Renderizador Ink (Experimental)

Quando useInkRenderer está habilitado, o Autohand usa renderização de terminal baseada em React (Ink) ao invés do spinner ora tradicional. Isso fornece:

  • Saída sem flicker: Todas as atualizações de UI são agrupadas através da reconciliação do React
  • Recurso de fila de trabalho: Digite instruções enquanto o agente trabalha
  • Melhor manipulação de entrada: Sem conflitos entre handlers de readline
  • UI composável: Base para recursos avançados de UI futuros

Para habilitar:

{
  "ui": {
    "useInkRenderer": true
  }
}

Nota: Este recurso é experimental e pode ter casos extremos. A UI padrão baseada em ora permanece estável e totalmente funcional.

Verificação de Atualização

Quando checkForUpdates está habilitado (padrão), o Autohand verifica novas versões na inicialização:

> Autohand v0.6.8 (abc1234) ✓ Up to date

Se uma atualização estiver disponível:

> Autohand v0.6.7 (abc1234) ⬆ Update available: v0.6.8
  ↳ Run: curl -fsSL https://autohand.ai/install.sh | sh

Como funciona:

  • Busca a última versão na API do GitHub
  • Armazena resultado em cache em ~/.autohand/version-check.json
  • Verifica apenas uma vez a cada updateCheckInterval horas (padrão: 24)
  • Não-bloqueante: a inicialização continua mesmo se a verificação falhar

Para desabilitar:

{
  "ui": {
    "checkForUpdates": false
  }
}

Ou via variável de ambiente:

export AUTOHAND_SKIP_UPDATE_CHECK=1

Configurações do Agente

Controle o comportamento do agente e limites de iteração.

{
  "agent": {
    "maxIterations": 100,
    "enableRequestQueue": true,
    "debug": false
  }
}
CampoTipoPadrãoDescrição
maxIterationsnumber100Máximo de iterações de ferramentas por solicitação do usuário antes de parar
enableRequestQueuebooleantruePermitir que usuários digitem e enfileirem solicitações enquanto o agente trabalha
debugbooleanfalseHabilitar output de debug detalhado (logs do estado interno do agente para stderr)

Modo Debug

Habilite o modo debug para ver logging detalhado do estado interno do agente (iterações do loop react, construção de prompts, detalhes da sessão). O output vai para stderr para não interferir com o output normal.

Três formas de habilitar o modo debug (em ordem de precedência):

  1. Flag da CLI: autohand -d ou autohand --debug
  2. Variável de ambiente: AUTOHAND_DEBUG=1
  3. Arquivo de configuração: Definir agent.debug: true

Fila de Solicitações

Quando enableRequestQueue está habilitado, você pode continuar digitando mensagens enquanto o agente processa uma solicitação anterior. Sua entrada será enfileirada e processada automaticamente quando a tarefa atual for concluída.

  • Digite sua mensagem e pressione Enter para adicionar à fila
  • A linha de status mostra quantas solicitações estão enfileiradas
  • As solicitações são processadas em ordem FIFO (primeiro a entrar, primeiro a sair)
  • Tamanho máximo da fila é 10 solicitações

Configurações de Permissões

Controle granular sobre permissões de ferramentas.

{
  "permissions": {
    "mode": "interactive",
    "whitelist": [
      "run_command:npm *",
      "run_command:bun *",
      "run_command:git status"
    ],
    "blacklist": ["run_command:rm -rf *", "run_command:sudo *"],
    "rules": [
      {
        "tool": "run_command",
        "pattern": "npm test",
        "action": "allow"
      }
    ],
    "rememberSession": true
  }
}

mode

ValorDescrição
"interactive"Solicitar aprovação em operações perigosas (padrão)
"unrestricted"Sem prompts, permitir tudo
"restricted"Negar todas as operações perigosas

whitelist

Array de padrões de ferramentas que nunca requerem aprovação.

["run_command:npm *", "run_command:bun test"]

blacklist

Array de padrões de ferramentas que são sempre bloqueados.

["run_command:rm -rf /", "run_command:sudo *"]

rules

Regras de permissão granulares.

CampoTipoDescrição
toolstringNome da ferramenta para corresponder
patternstringPadrão opcional para corresponder contra argumentos
action"allow" | "deny" | "prompt"Ação a tomar

rememberSession

TipoPadrãoDescrição
booleantrueLembrar decisões de aprovação para a sessão

Permissões Locais do Projeto

Cada projeto pode ter suas próprias configurações de permissão que sobrescrevem a configuração global. Estas são armazenadas em .autohand/settings.local.json na raiz do seu projeto.

Quando você aprova uma operação de arquivo (editar, escrever, excluir), ela é automaticamente salva neste arquivo para que não seja perguntado novamente para a mesma operação neste projeto.

{
  "version": 1,
  "permissions": {
    "whitelist": [
      "apply_patch:src/components/Button.tsx",
      "write_file:package.json",
      "run_command:bun test"
    ]
  }
}

Como funciona:

  • Quando você aprova uma operação, ela é salva em .autohand/settings.local.json
  • Da próxima vez, a mesma operação será auto-aprovada
  • Configurações locais do projeto são mescladas com configurações globais (local tem prioridade)
  • Adicione .autohand/settings.local.json ao .gitignore para manter configurações pessoais privadas

Formato do padrão:

  • nome_ferramenta:caminho - Para operações de arquivo (ex: apply_patch:src/file.ts)
  • nome_ferramenta:comando args - Para comandos (ex: run_command:npm test)

Visualizando Permissões

Você pode visualizar suas configurações de permissão atuais de duas formas:

Flag da CLI (Não-interativo):

autohand --permissions

Isso exibe:

  • Modo de permissão atual (interactive, unrestricted, restricted)
  • Caminhos do workspace e arquivo de configuração
  • Todos os padrões aprovados (whitelist)
  • Todos os padrões negados (blacklist)
  • Estatísticas resumidas

Comando Interativo:

/permissions

Em modo interativo, o comando /permissions fornece as mesmas informações mais opções para:

  • Remover itens da whitelist
  • Remover itens da blacklist
  • Limpar todas as permissões salvas

Modo Patch

O modo patch permite gerar um patch compatível com git sem modificar seus arquivos de workspace. Isso é útil para:

  • Revisão de código antes de aplicar mudanças
  • Compartilhar mudanças geradas por IA com membros da equipe
  • Criar conjuntos de mudanças reproduzíveis
  • Pipelines CI/CD que precisam capturar mudanças sem aplicá-las

Uso

# Gerar patch para stdout
autohand --prompt "adicionar autenticação de usuário" --patch

# Salvar em arquivo
autohand --prompt "adicionar autenticação de usuário" --patch --output auth.patch

# Pipe para arquivo (alternativa)
autohand --prompt "refatorar handlers de api" --patch > refactor.patch

Comportamento

Quando --patch é especificado:

  • Auto-confirmar: Todas as confirmações são automaticamente aceitas (--yes implícito)
  • Sem prompts: Nenhum prompt de aprovação é mostrado (--unrestricted implícito)
  • Apenas visualização: Mudanças são capturadas mas NÃO são escritas em disco
  • Segurança aplicada: Operações na blacklist (.env, chaves SSH, comandos perigosos) ainda são bloqueadas

Aplicando Patches

Destinatários podem aplicar o patch usando comandos git padrão:

# Verificar o que seria aplicado (dry-run)
git apply --check changes.patch

# Aplicar o patch
git apply changes.patch

# Aplicar com merge 3-way (lida melhor com conflitos)
git apply -3 changes.patch

# Aplicar e stagear mudanças
git apply --index changes.patch

# Reverter um patch
git apply -R changes.patch

Formato do Patch

O patch gerado segue o formato de diff unificado do git:

diff --git a/src/auth.ts b/src/auth.ts
new file mode 100644
--- /dev/null
+++ b/src/auth.ts
@@ -0,0 +1,15 @@
+export function authenticate(user: string, password: string) {
+  // Implementação aqui
+}
+
diff --git a/src/index.ts b/src/index.ts
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,5 +1,7 @@
 import express from 'express';
+import { authenticate } from './auth';
+
 const app = express();
+app.use(authenticate);

Códigos de Saída

CódigoSignificado
0Sucesso, patch gerado
1Erro (falta --prompt, permissão negada, etc.)

Combinando com Outras Flags

# Usar modelo específico
autohand --prompt "otimizar queries" --patch --model gpt-4o

# Especificar workspace
autohand --prompt "adicionar testes" --patch --path ./meu-projeto

# Usar configuração personalizada
autohand --prompt "refatorar" --patch --config ~/.autohand/work.json

Exemplo de Fluxo de Trabalho em Equipe

# Desenvolvedor A: Gerar patch para uma feature
autohand --prompt "implementar dashboard de usuário com gráficos" --patch --output dashboard.patch

# Compartilhar via git (criar PR com apenas o arquivo patch)
git checkout -b patch/dashboard
git add dashboard.patch
git commit -m "Add dashboard feature patch"
git push

# Desenvolvedor B: Revisar e aplicar
git fetch origin patch/dashboard
git apply dashboard.patch
# Executar testes, revisar código, então commitar
git add -A && git commit -m "feat: add user dashboard with charts"

Configurações de Rede

{
  "network": {
    "maxRetries": 3,
    "timeout": 30000,
    "retryDelay": 1000
  }
}
CampoTipoPadrãoMáxDescrição
maxRetriesnumber35Tentativas de retry para requisições de API falhas
timeoutnumber30000-Timeout da requisição em milissegundos
retryDelaynumber1000-Atraso entre retries em milissegundos

Configurações de Telemetria

A telemetria está desabilitada por padrão (opt-in). Habilite para ajudar a melhorar o Autohand.

{
  "telemetry": {
    "enabled": false,
    "apiBaseUrl": "https://api.autohand.ai",
    "batchSize": 20,
    "flushIntervalMs": 60000,
    "maxQueueSize": 500,
    "maxRetries": 3,
    "enableSessionSync": false,
    "companySecret": ""
  }
}
CampoTipoPadrãoDescrição
enabledbooleanfalseHabilitar/desabilitar telemetria (opt-in)
apiBaseUrlstringhttps://api.autohand.aiEndpoint da API de telemetria
batchSizenumber20Número de eventos para agrupar antes do auto-flush
flushIntervalMsnumber60000Intervalo de flush em milissegundos (1 minuto)
maxQueueSizenumber500Tamanho máximo da fila antes de descartar eventos antigos
maxRetriesnumber3Tentativas de retry para requisições de telemetria falhas
enableSessionSyncbooleanfalseSincronizar sessões para a nuvem para recursos de equipe
companySecretstring""Segredo da empresa para autenticação da API

Agentes Externos

Carregar definições de agentes personalizados de diretórios externos.

{
  "externalAgents": {
    "enabled": true,
    "paths": ["~/.autohand/agents", "/equipe/compartilhado/agents"]
  }
}
CampoTipoPadrãoDescrição
enabledbooleanfalseHabilitar carregamento de agentes externos
pathsstring[][]Diretórios para carregar agentes

Configurações da API

Configuração da API backend para recursos de equipe.

{
  "api": {
    "baseUrl": "https://api.autohand.ai",
    "companySecret": "sk-team-xxx"
  }
}
CampoTipoPadrãoDescrição
baseUrlstringhttps://api.autohand.aiEndpoint da API
companySecretstring-Segredo da equipe/empresa para recursos compartilhados

Também pode ser definido via variáveis de ambiente:

  • AUTOHAND_API_URL → api.baseUrl
  • AUTOHAND_SECRET → api.companySecret

Configurações de Autenticação

Configuração de autenticação para recursos protegidos.

{
  "auth": {
    "token": "seu-token-de-autenticação",
    "refreshToken": "seu-refresh-token",
    "expiresAt": "2024-12-31T23:59:59Z"
  }
}
CampoTipoObrigatórioDescrição
tokenstringSimToken de acesso atual
refreshTokenstringNãoToken para renovar o token de acesso
expiresAtstringNãoData/hora de expiração do token (ISO)

Configurações de Skills Comunitárias

Configurações para o registro de skills comunitárias.

{
  "communitySkills": {
    "registryUrl": "https://skills.autohand.ai",
    "cacheDuration": 3600,
    "autoUpdate": false
  }
}
CampoTipoPadrãoDescrição
registryUrlstringhttps://skills.autohand.aiURL base do registro de skills
cacheDurationnumber3600Duração do cache em segundos
autoUpdatebooleanfalseAtualizar skills automaticamente quando desatualizados

Configurações de Compartilhamento

Controle como sessões e workspaces são compartilhados.

{
  "share": {
    "enabled": true,
    "defaultVisibility": "private",
    "allowPublicLinks": false,
    "requireApproval": true
  }
}
CampoTipoPadrãoDescrição
enabledbooleantrueHabilitar recursos de compartilhamento
defaultVisibilitystring"private"Visibilidade padrão: private, team, public
allowPublicLinksbooleanfalsePermitir criação de links públicos
requireApprovalbooleantrueRequerer aprovação antes de compartilhar

Sincronização de Configurações

Sincronize suas configurações entre dispositivos.

{
  "sync": {
    "enabled": false,
    "autoSync": true,
    "syncInterval": 300,
    "conflictResolution": "ask"
  }
}
CampoTipoPadrãoDescrição
enabledbooleanfalseHabilitar sincronização de configurações
autoSyncbooleantrueSincronizar automaticamente quando houver mudanças
syncIntervalnumber300Intervalo de sincronização em segundos
conflictResolutionstring"ask"Como resolver conflitos: ask, local, remote

Configurações de Hooks

Configure hooks personalizados para eventos do Autohand.

{
  "hooks": {
    "preCommand": "~/.autohand/hooks/pre-command.sh",
    "postCommand": "~/.autohand/hooks/post-command.sh",
    "onError": "~/.autohand/hooks/on-error.sh",
    "onComplete": "~/.autohand/hooks/on-complete.sh"
  }
}
CampoTipoDescrição
preCommandstringScript executado antes de cada comando
postCommandstringScript executado após cada comando
onErrorstringScript executado quando ocorre um erro
onCompletestringScript executado quando uma tarefa é concluída

Variáveis de ambiente disponíveis nos hooks:

  • AUTOHAND_HOOK_TYPE - Tipo do hook (preCommand, postCommand, etc.)
  • AUTOHAND_COMMAND - Comando sendo executado
  • AUTOHAND_EXIT_CODE - Código de saída (apenas postCommand e onError)
  • AUTOHAND_SESSION_ID - ID da sessão atual

Configurações MCP

Configuração do Model Context Protocol (MCP) para integração com servidores de ferramentas.

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"],
        "env": {
          "HOME": "/home/user"
        }
      },
      "sqlite": {
        "command": "uvx",
        "args": ["mcp-server-sqlite", "--db-path", "/path/to/db.sqlite"]
      }
    }
  }
}
CampoTipoDescrição
commandstringComando para iniciar o servidor MCP
argsarrayArgumentos para o comando
envobjectVariáveis de ambiente adicionais

Os servidores MCP fornecem ferramentas adicionais que podem ser chamadas pelo agente. Cada servidor é identificado por um nome único e iniciado automaticamente quando necessário.

Configurações da Extensão Chrome

Configurações para a extensão do Chrome do Autohand.

{
  "chrome": {
    "extensionId": "seu-extension-id",
    "nativeMessaging": true,
    "autoLaunch": false,
    "preferredBrowser": "chrome"
  }
}
CampoTipoPadrãoDescrição
extensionIdstring-ID da extensão Chrome instalada
nativeMessagingbooleantrueHabilitar comunicação via native messaging
autoLaunchbooleanfalseAbrir Chrome automaticamente ao iniciar
preferredBrowserstring"chrome"Navegador preferido: chrome, chromium, edge, brave

A extensão Chrome permite interação com páginas web e automação de browser. O native messaging permite comunicação bidirecional entre a CLI e a extensão.

Sistema de Skills

Skills são pacotes de instruções que fornecem instruções especializadas ao agente de IA. Eles funcionam como arquivos AGENTS.md sob demanda que podem ser ativados para tarefas específicas.

Locais de Descoberta de Skills

Skills são descobertos de múltiplos locais, com fontes posteriores tendo precedência:

LocalID da FonteDescrição
~/.codex/skills/**/SKILL.mdcodex-userSkills de usuário Codex (recursivo)
~/.claude/skills/*/SKILL.mdclaude-userSkills de usuário Claude (um nível)
~/.autohand/skills/**/SKILL.mdautohand-userSkills de usuário Autohand (recursivo)
<projeto>/.claude/skills/*/SKILL.mdclaude-projectSkills de projeto Claude (um nível)
<projeto>/.autohand/skills/**/SKILL.mdautohand-projectSkills de projeto Autohand (recursivo)

Comportamento de Auto-Cópia

Skills descobertos de locais Codex ou Claude são automaticamente copiados para o local Autohand correspondente:

  • ~/.codex/skills/ e ~/.claude/skills/ → ~/.autohand/skills/
  • <projeto>/.claude/skills/ → <projeto>/.autohand/skills/

Skills existentes em locais Autohand nunca são sobrescritos.

Formato SKILL.md

Skills usam frontmatter YAML seguido de conteúdo markdown:

---
name: my-skill-name
description: Breve descrição do skill
license: MIT
compatibility: Funciona com Node.js 18+
allowed-tools: read_file write_file run_command
metadata:
  author: your-name
  version: "1.0.0"
---

# My Skill

Instruções detalhadas para o agente de IA...
CampoObrigatórioTamanho MáxDescrição
nameSim64 charsAlfanumérico minúsculo com hífens apenas
descriptionSim1024 charsBreve descrição do skill
licenseNão-Identificador de licença (ex: MIT, Apache-2.0)
compatibilityNão500 charsNotas de compatibilidade
allowed-toolsNão-Lista separada por espaços de ferramentas permitidas
metadataNão-Metadados adicionais chave-valor

Prefixos de Entrada

O Autohand suporta prefixos especiais na entrada do prompt:

PrefixoDescriçãoExemplo
/Comandos slash/help, /model, /quit, /exit
@Menções de arquivo (autocomplete)@src/index.ts
$Menções de skill (autocomplete)$frontend-design, $code-review
!Executar comandos terminal diretamente! git status, ! ls -la

Menções de Skills ($):

  • Digite $ seguido de caracteres para ver skills disponíveis com autocomplete
  • Tab aceita a sugestão principal (ex: $frontend-design)
  • Skills são descobertos de ~/.autohand/skills/ e <projeto>/.autohand/skills/
  • Skills ativados são anexados ao prompt como instruções especiais para a sessão atual
  • Painel de preview mostra metadados do skill (nome, descrição, estado de ativação)

Comandos Shell (!):

  • Comandos executam no seu diretório de trabalho atual
  • Output exibido diretamente no terminal
  • Não vai para o LLM
  • Timeout de 30 segundos
  • Retorna ao prompt após execução

Comandos Slash

/skills — Gerenciador de Pacotes

ComandoDescrição
/skillsListar todos os skills disponíveis
/skills use <nome>Ativar um skill para a sessão atual
/skills deactivate <nome>Desativar um skill
/skills info <nome>Mostrar informações detalhadas do skill
/skills installExplorar e instalar do registro comunitário
/skills install @<slug>Instalar um skill comunitário por slug
/skills search <consulta>Pesquisar no registro de skills comunitários
/skills trendingMostrar skills comunitários em tendência
/skills remove <slug>Desinstalar um skill comunitário
/skills newCriar um novo skill interativamente
/skills feedback <slug> <1-5>Avaliar um skill comunitário

/learn — Consultor de Skills com LLM

ComandoDescrição
/learnAnalisar projeto e recomendar skills (escaneamento rápido)
/learn deepEscaneamento profundo do projeto (lê arquivos fonte) para resultados mais precisos
/learn updateRe-analisar projeto e regenerar skills LLM gerados desatualizados

/learn utiliza um fluxo LLM em duas fases:

  1. Fase 1 — Análise + Ranking + Auditoria: Escaneia a estrutura do projeto, audita skills instalados buscando redundâncias/conflitos, e classifica skills comunitários por relevância (0-100).
  2. Fase 2 — Geração (condicional): Se nenhum skill comunitário pontuar acima de 60, oferece gerar um skill personalizado adaptado ao seu projeto.

Os skills gerados incluem metadados (agentskill-source: llm-generated, agentskill-project-hash) para que /learn update possa detectar mudanças no código e regenerar skills desatualizados.

Geração Automática de Skills (--auto-skill)

O flag --auto-skill gera skills sem o fluxo interativo do consultor:

autohand --auto-skill

Isso irá:

  1. Analisar a estrutura do projeto (package.json, requirements.txt, etc.)
  2. Detectar linguagens, frameworks e padrões
  3. Gerar 3 skills relevantes usando LLM
  4. Salvar skills em <projeto>/.autohand/skills/

Para uma experiência interativa mais precisa, use /learn dentro de uma sessão.

Exemplo Completo

Formato JSON (~/.autohand/config.json)

{
  "provider": "openrouter",
  "openrouter": {
    "apiKey": "sk-or-v1-sua-chave-aqui",
    "baseUrl": "https://openrouter.ai/api/v1",
    "model": "your-modelcard-id-here"
  },
  "ollama": {
    "baseUrl": "http://localhost:11434",
    "model": "llama3.2"
  },
  "workspace": {
    "defaultRoot": "~/projetos",
    "allowDangerousOps": false
  },
  "ui": {
    "theme": "dark",
    "autoConfirm": false,
    "showCompletionNotification": true,
    "showThinking": true,
    "terminalBell": true,
    "checkForUpdates": true,
    "updateCheckInterval": 24
  },
  "agent": {
    "maxIterations": 100,
    "enableRequestQueue": true,
    "debug": false
  },
  "permissions": {
    "mode": "interactive",
    "whitelist": ["run_command:npm *", "run_command:bun *"],
    "blacklist": ["run_command:rm -rf /"],
    "rememberSession": true
  },
  "network": {
    "maxRetries": 3,
    "timeout": 30000,
    "retryDelay": 1000
  },
  "telemetry": {
    "enabled": false,
    "apiBaseUrl": "https://api.autohand.ai",
    "batchSize": 20,
    "flushIntervalMs": 60000,
    "maxQueueSize": 500,
    "maxRetries": 3,
    "enableSessionSync": false,
    "companySecret": ""
  },
  "auth": {
    "token": "seu-token-de-autenticação",
    "refreshToken": "seu-refresh-token"
  },
  "communitySkills": {
    "registryUrl": "https://skills.autohand.ai",
    "cacheDuration": 3600,
    "autoUpdate": false
  },
  "share": {
    "enabled": true,
    "defaultVisibility": "private",
    "allowPublicLinks": false,
    "requireApproval": true
  },
  "sync": {
    "enabled": false,
    "autoSync": true,
    "syncInterval": 300,
    "conflictResolution": "ask"
  },
  "hooks": {
    "preCommand": "~/.autohand/hooks/pre-command.sh",
    "postCommand": "~/.autohand/hooks/post-command.sh",
    "onError": "~/.autohand/hooks/on-error.sh",
    "onComplete": "~/.autohand/hooks/on-complete.sh"
  },
  "mcp": {
    "servers": {}
  },
  "chrome": {
    "extensionId": "",
    "nativeMessaging": true,
    "autoLaunch": false,
    "preferredBrowser": "chrome"
  },
  "externalAgents": {
    "enabled": false,
    "paths": []
  },
  "api": {
    "baseUrl": "https://api.autohand.ai"
  }
}

Formato YAML (~/.autohand/config.yaml)

provider: openrouter

openrouter:
  apiKey: sk-or-v1-sua-chave-aqui
  baseUrl: https://openrouter.ai/api/v1
  model: your-modelcard-id-here

ollama:
  baseUrl: http://localhost:11434
  model: llama3.2

workspace:
  defaultRoot: ~/projetos
  allowDangerousOps: false

ui:
  theme: dark
  autoConfirm: false
  showCompletionNotification: true
  showThinking: true
  terminalBell: true
  checkForUpdates: true
  updateCheckInterval: 24

agent:
  maxIterations: 100
  enableRequestQueue: true
  debug: false

permissions:
  mode: interactive
  whitelist:
    - "run_command:npm *"
    - "run_command:bun *"
  blacklist:
    - "run_command:rm -rf /"
  rememberSession: true

network:
  maxRetries: 3
  timeout: 30000
  retryDelay: 1000

telemetry:
  enabled: false
  apiBaseUrl: https://api.autohand.ai
  batchSize: 20
  flushIntervalMs: 60000
  maxQueueSize: 500
  maxRetries: 3
  enableSessionSync: false
  companySecret: ""

auth:
  token: seu-token-de-autenticação
  refreshToken: seu-refresh-token

communitySkills:
  registryUrl: https://skills.autohand.ai
  cacheDuration: 3600
  autoUpdate: false

share:
  enabled: true
  defaultVisibility: private
  allowPublicLinks: false
  requireApproval: true

sync:
  enabled: false
  autoSync: true
  syncInterval: 300
  conflictResolution: ask

hooks:
  preCommand: ~/.autohand/hooks/pre-command.sh
  postCommand: ~/.autohand/hooks/post-command.sh
  onError: ~/.autohand/hooks/on-error.sh
  onComplete: ~/.autohand/hooks/on-complete.sh

mcp:
  servers: {}

chrome:
  extensionId: ""
  nativeMessaging: true
  autoLaunch: false
  preferredBrowser: chrome

externalAgents:
  enabled: false
  paths: []

api:
  baseUrl: https://api.autohand.ai

Estrutura de Diretórios

O Autohand armazena dados em ~/.autohand/ (ou $AUTOHAND_HOME):

~/.autohand/
├── config.json          # Configuração principal
├── config.yaml          # Configuração alternativa YAML
├── device-id            # Identificador único do dispositivo
├── error.log            # Log de erros
├── feedback.log         # Submissões de feedback
├── sessions/            # Histórico de sessões
├── projects/            # Base de conhecimento do projeto
├── memory/              # Memória do nível do usuário
├── commands/            # Comandos personalizados
├── agents/              # Definições de agentes
├── tools/               # Meta-ferramentas personalizadas
├── feedback/            # Estado do feedback
└── telemetry/           # Dados de telemetria
    ├── queue.json
    └── session-sync-queue.json

Diretório a nível de projeto (na raiz do seu workspace):

<projeto>/.autohand/
├── settings.local.json  # Permissões locais do projeto (adicione ao gitignore)
├── memory/              # Memória específica do projeto
└── skills/              # Skills específicas do projeto

Flags da CLI (Sobrescrever Configuração)

Estas flags sobrescrevem as configurações do arquivo:

FlagDescrição
--model <modelo>Sobrescrever modelo
--path <caminho>Sobrescrever raiz do workspace
--worktree [nome]Executar sessão em git worktree isolado (nome opcional do worktree/branch)
--tmuxIniciar em uma sessão tmux dedicada (implica --worktree; não pode ser usado com --no-worktree)
--add-dir <caminho>Adicionar diretórios adicionais ao escopo do workspace (pode ser usado múltiplas vezes)
--config <caminho>Usar arquivo de configuração personalizado
--temperature <n>Definir temperatura (0-1)
--yesAuto-confirmar prompts
--dry-runVisualizar sem executar
--unrestrictedSem prompts de aprovação
--restrictedNegar operações perigosas
--auto-skillGerar skills automaticamente com base na análise do projeto (veja também /learn para consultor interativo)
--setupExecutar o assistente de configuração para configurar ou reconfigurar o Autohand
--aboutMostrar informações sobre o Autohand (versão, links, informações de contribuição)
--sys-prompt <valor>Substituir completamente o prompt do sistema (string inline ou caminho de arquivo)
--append-sys-prompt <valor>Anexar ao prompt do sistema (string inline ou caminho de arquivo)

Personalização do Prompt do Sistema

O Autohand permite personalizar o prompt do sistema usado pelo agente de IA. Isso é útil para fluxos de trabalho especializados, instruções personalizadas ou integração com outros sistemas.

Flags da CLI

FlagDescrição
--sys-prompt <valor>Substituir completamente o prompt do sistema
--append-sys-prompt <valor>Anexar conteúdo ao prompt do sistema padrão

Ambas as flags aceitam:

  • String inline: Conteúdo de texto direto
  • Caminho de arquivo: Caminho para um arquivo contendo o prompt (auto-detectado)

Detecção de Caminho de Arquivo

Um valor é tratado como caminho de arquivo se:

  • Começa com ./, ../, /, ou ~/
  • Começa com uma letra de unidade do Windows (ex., C:\)
  • Termina com .txt, .md, ou .prompt
  • Contém separadores de caminho sem espaços

Caso contrário, é tratado como string inline.

--sys-prompt (Substituição Completa)

Quando fornecido, substitui completamente o prompt do sistema padrão. O agente NÃO carregará:

  • Instruções padrão do Autohand
  • Instruções do projeto AGENTS.md
  • Memórias de usuário/projeto
  • Skills ativas
# String inline
autohand --sys-prompt "Você é um especialista em Python. Seja conciso." --prompt "Escreva hello world"

# De arquivo
autohand --sys-prompt ./prompt-personalizado.txt --prompt "Explique este código"

--append-sys-prompt (Anexar ao Padrão)

Quando fornecido, anexa conteúdo ao prompt do sistema padrão completo. O agente continuará carregando todas as instruções padrão.

# String inline
autohand --append-sys-prompt "Sempre use TypeScript em vez de JavaScript" --prompt "Crie uma função"

# De arquivo
autohand --append-sys-prompt ./diretrizes-equipe.md --prompt "Adicione tratamento de erros"

Precedência

Quando ambas as flags são fornecidas:

  1. --sys-prompt tem precedência total
  2. --append-sys-prompt é ignorado

Suporte a Múltiplos Diretórios

O Autohand pode trabalhar com múltiplos diretórios além do workspace principal. Isso é útil quando seu projeto tem dependências, bibliotecas compartilhadas ou projetos relacionados em diretórios diferentes.

Flag da CLI

Use --add-dir para adicionar diretórios adicionais (pode ser usado múltiplas vezes):

# Adicionar um único diretório adicional
autohand --add-dir /caminho/para/lib-compartilhada

# Adicionar múltiplos diretórios
autohand --add-dir /caminho/para/lib1 --add-dir /caminho/para/lib2

# Com modo irrestrito (auto-aprovar gravações em todos os diretórios)
autohand --add-dir /caminho/para/lib-compartilhada --unrestricted

Comando Interativo

Use /add-dir durante uma sessão interativa:

/add-dir              # Mostrar diretórios atuais
/add-dir /caminho/dir # Adicionar um novo diretório

Restrições de Segurança

Os seguintes diretórios não podem ser adicionados:

  • Diretório home (~ ou $HOME)
  • Diretório raiz (/)
  • Diretórios do sistema (/etc, /var, /usr, /bin, /sbin)
  • Diretórios do sistema Windows (C:\Windows, C:\Program Files)
  • Diretórios de usuário Windows (C:\Users\username)
  • Montagens WSL do Windows (/mnt/c, /mnt/c/Windows)