agent-hub CLI

O agent é um executor local — recebe comandos já resolvidos pelo servidor (provider, model, thread) e executa. Toda a orquestração, resolução de estado e gestão de workspaces/prompts é feita pelo Dashboard e Cloud Functions.

Requisitos

• Node.js 22 ou superior

Instalação

npm install -g agent-hub-agent

Quick Start

# 1. Inicializar configuração
agent-hub config init "meu-agent"

# 2. Autenticar com Google e registrar o agent
agent-hub login

# 3. Adicionar projetos locais
agent-hub projects add /caminho/do/projeto

# 4. Iniciar o agent
agent-hub

Após iniciar, o agent fica escutando comandos enviados pelo Dashboard em tempo real.

O que o agent faz

• Executa prompts nos LLMs (Claude, Codex, Gemini) conforme instruções do servidor
• Gerencia projetos locais — adicionar, remover, renomear diretórios via CLI
• Escuta comandos em tempo real via Firestore e executa localmente
• Reporta presença (heartbeat) via Realtime Database
• Captura diffs git antes/depois da execução
• Processa attachments (download, transcrição)
• Mantém threads em memória para reusar contexto dentro da mesma sessão

O que o agent NÃO faz

• Não decide qual provider ou model usar — vem resolvido do servidor
• Não gerencia workspaces — exclusivo do Dashboard
• Não gerencia prompts — exclusivo do Dashboard
• Não resolve threads/sessões — vem pré-resolvido pelo Cloud Functions
• Não faz rate limiting ou validação de comandos — feito no servidor

Flags globais

| Flag | Descrição | |------|-----------| | -C <dir> / --app-dir <dir> | Diretório de configuração (padrão: ~/.agent-hub) | | --config <path> | Caminho direto para o arquivo de configuração | | --version / -v | Exibe a versão |

agent-hub -C /custom/config projects list

config

Gerencia o arquivo config.json do diretório de configuração.

agent-hub config init "meu-agent"
agent-hub config path
agent-hub config get [key]
agent-hub config add <key> <value> [--type string|number|boolean|json]
agent-hub config set <key> <value> [--type string|number|boolean|json]

set é um alias de add. Chaves como core.agentProvider, tasksEnabled, tasksMaxParallel e models por provider são gerenciadas pelo Dashboard e não podem ser alteradas pela CLI.

projects

Gerencia os projetos do agent no Firestore. Projetos são diretórios locais que o agent usa como contexto ao executar tarefas.

Listar projetos

agent-hub projects list

Adicionar projeto

# Diretório atual com nome automático (basename do path)
agent-hub projects add

# Path explícito com nome e tags
agent-hub projects add /code/api --name api --tag backend

| Flag | Atalho | Descrição | |------|--------|-----------| | --name <nome> | -n | Nome do projeto (padrão: basename do path) | | --tag <tag> | -t | Tag (repetível) |

Escanear diretório

# Adiciona todas as pastas filhas como projetos
agent-hub projects scan /code

# Com tag aplicada a todos
agent-hub projects scan /code --tag work

Escaneia um diretório e registra cada subpasta como projeto. Ignora pastas ocultas (.xxx) e pula projetos já registrados (por path ou nome). Sem argumento, usa o diretório atual.

Remover, habilitar, desabilitar, renomear

agent-hub projects remove api
agent-hub projects disable api
agent-hub projects enable api
agent-hub projects rename api api-v2

Projetos desabilitados (enabled: false) são ignorados pelo agent ao carregar, mas permanecem registrados.

Prompts por projeto

Cada projeto pode ter prompts associados:

agent-hub projects prompts list meu-projeto
agent-hub projects prompts add meu-projeto --name "review" --text "Revise o código"
agent-hub projects prompts remove meu-projeto review

Tags, model, provider override e workspaces são gerenciados pelo Dashboard.

daemon

Controla o processo daemon do agent.

agent-hub daemon start
agent-hub daemon stop
agent-hub daemon restart
agent-hub daemon status

Arquivos de controle em <config_dir>/:

• daemon.pid — PID do processo
• daemon.log — logs de saída

login

Autentica com Google e registra o agent.

agent-hub login

Durante o registro, o agent gera um par de chaves Ed25519 localmente. A chave privada é salva no config e nunca sai da máquina. A chave pública é enviada ao servidor.

status

Mostra status de autenticação e registro do agent.

agent-hub status

rotate-key

Gera um novo par de chaves Ed25519 e atualiza a chave pública no servidor.

agent-hub rotate-key

Use quando:

• Suspeitar que o agent foi comprometido
• Quiser rotacionar as chaves periodicamente
• Migrar de um agent que ainda usa chave simétrica (versões anteriores)

Após rotacionar, reinicie o agent para usar a nova chave.

Segurança

O agent usa autenticação Ed25519 (mesmo modelo do GitHub SSH):

• O agent gera um par de chaves localmente no login ou rotate-key
• A chave privada fica apenas no config local (~/.agent-hub/config.json) — nunca trafega pela rede
• A chave pública é armazenada no Firestore
• Para executar comandos, o agent assina cada request com a chave privada
• O servidor verifica a assinatura com a chave pública
• Sem chave Ed25519, o agent não inicia (exceto em modo emulator)
• A chave pode ser revogada instantaneamente pelo dashboard

Modelo de proteção

| Cenário | Proteção | |---------|----------| | Interceptação de rede | Assinatura é única por request (timestamp) — não reutilizável | | Vazamento do Firestore | Só tem a chave pública — inútil sem a privada | | Comprometimento de um agent | Outros agents não são afetados (chaves independentes) | | Suspeita de invasão | Revogar chave pelo dashboard bloqueia o agent na hora |

Transcrição de áudio

O agent pode transcrever áudios/vídeos enviados pelo dashboard. A transcrição acontece localmente na máquina do agent.

Setup com faster-whisper (Ubuntu)

# Instalar dependências
sudo apt install -y python3 python3-venv

# Criar ambiente
mkdir -p ~/.agent-hub/stt
python3 -m venv ~/.agent-hub/stt/.venv
~/.agent-hub/stt/.venv/bin/pip install faster-whisper

Criar ~/.agent-hub/stt/transcribe.py:

#!/usr/bin/env python3
import sys
from faster_whisper import WhisperModel

if len(sys.argv) < 2:
    print("usage: transcribe.py <audio_file>", file=sys.stderr)
    sys.exit(2)

model = WhisperModel("small", device="cpu", compute_type="int8")
segments, info = model.transcribe(sys.argv[1], vad_filter=True)
text = " ".join(seg.text.strip() for seg in segments).strip()

if not text:
    sys.exit(1)
print(text)

Configurar o agent

chmod +x ~/.agent-hub/stt/transcribe.py
agent-hub config set runtime.audioTranscribeCmd "~/.agent-hub/stt/.venv/bin/python ~/.agent-hub/stt/transcribe.py {file}"
agent-hub config set runtime.audioTranscribeTimeoutMs 180000

O comando deve imprimir o transcript em stdout. {file} é substituído pelo caminho do arquivo de mídia. Se audioTranscribeCmd não estiver configurado, o arquivo é enviado direto ao provider (funciona com modelos que suportam visão para imagens).