Guia de Ferramentas · CLI + MCP + VS Code

Rode o fluxo onde você já trabalha

O H1VE Flow traz o workflow para o território do desenvolvedor: o terminal (a CLI nf), o Claude Code (o MCP server) e o seu editor (a extensão do VS Code). Eles falam com a mesma API do painel — você entra uma vez com nf login no navegador, sem colar token.

01 · Pré-requisitos

Antes de começar

Node.js 18.18+ instalado (node --version). O npm vem junto.
Uma conta no H1VE Flow (app.h1ve.org).
É só isso — você entra com nf login (navegador), sem criar nem colar token. Um token pessoal de API (PAT, nf_pat_…) é só para headless / CI (veja §02). Ele autentica como você (leitura e escrita); a service key é somente leitura.

02 · CLI — nf

Opere o fluxo pelo terminal

A CLI nf conduz a feature na sua branch atual — status, start, move, spec, done, blockers.

Instalar

npm i -g @h1veframework/clinf --version

Entrar

nf login                               # abre o navegador para autorizar — sem colar tokennf health                              # testa a conexão

Dica

"No snapshots registered" do nf health é uma resposta de sucesso — ele conectou; o projeto só ainda não tem métricas de saúde.

Headless / CI (opcional)

Sem navegador (CI, um servidor)? Autentique com um PAT (nf_pat_…, de app.h1ve.org/api-tokens) por duas variáveis de ambiente:

export H1VE_API_URL="https://app.h1ve.org"export H1VE_API_KEY="nf_pat_..."      # seu PAT

Dica

Coloque as linhas export no seu ~/.zshrc / ~/.bashrc para não repeti-las a cada sessão. Guarde o PAT com cuidado — é um segredo, exibido uma única vez.

Comandos

nf login: Autoriza no navegador — o jeito normal de entrar (sem colar token)
nf health: Últimos snapshots de saúde técnica do projeto
nf status: Estado da feature da branch atual (estágio, dias ativos, blockers, sign-offs)
nf start [<n|id>]: Inicia uma feature atribuída: cria a branch feat/{você}/{slug} e registra o slug
nf spec: Imprime a spec da feature (markdown)
nf move <stage>: Move a feature para outro estágio
nf done [--from <file>]: Submete a AI declaration (JSON) e move dev → pr
nf blocker "<desc>": Abre um blocker na feature (você vira o dono)
nf connect …: Aplica uma credencial ao local .env.local (nunca ao servidor) e registra o inventário de conexões
nf serve: Roda o agente local (127.0.0.1) para o menu visual do painel aplicar credenciais pelo navegador

Flags úteis: --json (saída crua para scripts) · --project <name|id> (se você pertence a mais de um projeto) · -h (ajuda completa).

Exemplo real

nf start                                  # inicia a feature atribuída (cria a branch)# ... trabalhe normalmente (git, código, commits) ...nf status                                 # estado a qualquer momentonf blocker "aguardando a credencial de prod do Neon"nf done --from ai-declaration.json        # submete a AI declaration + move dev → pr

03 · MCP Server — Claude Code

Plugue o fluxo no seu agente de IA

O MCP server dá ao Claude Code acesso direto ao contexto da feature da branch atual — sem copiar e colar SPECs. Plugue uma vez; as tools aparecem em qualquer projeto.

Instalar (plugar no Claude Code)

claude mcp add h1ve -s user -- npx -y @h1veframework/mcp

Depois do nf login, o server usa a sua sessão — sem token no comando. -s user = disponível em todos os projetos; só para o repo atual, use -s local de dentro dele. Sem install manual — o npx busca o pacote na primeira execução.

Headless / CI (opcional)

Onde não há sessão de navegador, passe o PAT como variáveis de ambiente:

claude mcp add h1ve -s user \  -e H1VE_API_URL=https://app.h1ve.org \  -e H1VE_API_KEY=nf_pat_... \  -- npx -y @h1veframework/mcp

Confirmar a conexão

claude mcp list       # deve listar "h1ve: ✔ Connected"

Dentro do Claude Code, rode /mcp — o server h1ve aparece com 6 tools.

As 6 tools

get_current_feature: Estado da feature da branch: estágio, dias ativos, blockers, sign-offs, ai-declaration
get_spec: A spec da feature (markdown)
move_feature_stage: Move a feature para outro estágio (regras validadas no servidor)
create_blocker: Abre um blocker na feature (você vira o dono)
submit_ai_declaration: Submete a AI declaration da feature (só o dev dono)
start_feature: Inicia uma feature atribuída: registra o slug e devolve o git switch -c para criar a branch

Sobre a identidade

Tools de leitura (get_current_feature, get_spec) funcionam com o seu login ou com a service key. Tools de escrita (move, blocker, ai-declaration, start) exigem a sua identidade — a sua sessão do nf login, ou um PAT em headless/CI. A service key (somente leitura) retorna SERVICE_CANNOT_WRITE.

04 · Extensão VS Code

Veja o fluxo no seu editor

A extensão H1VE mostra a feature da branch atual dentro do VS Code — estágio, blockers, sign-offs e a spec — numa view da barra lateral, sem trocar de contexto pro dashboard. Uma companheira somente leitura da CLI e do MCP.

Instalar

code --install-extension h1ve.h1ve-vscode

Ou busque "H1VE" na Extensions view, ou abra no Marketplace do VS Code. Funciona no VS Code e em forks como o Cursor.

Entrar

Já rodou nf login num terminal? A extensão reusa essa sessão automaticamente — nada pra colar. Abra o painel H1VE (o ícone da colmeia na barra de atividades) numa branch de feature.

Sem sessão no terminal

O painel mostra um botão "Connect to H1VE" — ou rode H1VE: Set API Key para guardar um PAT (nf_pat_…) no SecretStorage do VS Code (nunca em settings).

Comandos

H1VE: Set API Key: Guarda ou limpa a API key (mantida no SecretStorage)
H1VE: Refresh: Recarrega o estado da feature da branch
H1VE: Open Spec: Abre a spec da feature num editor de markdown

A view "Branch feature" resolve a feature pela sua branch git atual (o slug do nf start) e atualiza a cada 30s. É somente leitura — para agir sobre as features (start, move, spec, done), use a CLI ou o MCP.

05 · Solução de problemas

Fricções comuns

nf: command not found: Node não instalado, ou terminal errado. Confira node --version. No Windows, o PowerShell pode não expor o bin do npm no PATH — use o terminal do VS Code ou reabra o shell após instalar.
404 no install: Propagação do npm logo após uma publicação. Espere alguns minutos e tente de novo.
NO_PROJECT: Você pertence a mais de um projeto. Passe --project <name|id> na CLI; o MCP resolve pelo contexto da branch.
401 / 403: Não autorizado. Rode nf login de novo. Em headless/CI, garanta que H1VE_API_KEY é um PAT válido (nf_pat_…). 403 SERVICE_CANNOT_WRITE = a service key (somente leitura) foi usada numa ação de escrita → entre (ou use um PAT).

06 · Compatibilidade de nomes de variável

Os nomes legados ainda funcionam

Retrocompatível

Os nomes atuais são H1VE_API_URL e H1VE_API_KEY — use estes. Os nomes legados NEXUS_FLOW_API_URL / NEXUS_FLOW_API_KEY ainda são aceitos por compatibilidade — se você já configurou com eles, não precisa mudar nada. Recomendamos H1VE_* para novas configurações.