Tooling Guide · CLI + MCP + VS Code

Run the flow where you already work

H1VE Flow brings the workflow to the developer's home turf: the terminal (the nf CLI), Claude Code (the MCP server), and your editor (the VS Code extension). They talk to the same panel API — you sign in once with nf login in the browser, no token to paste.

01 · Prerequisites

Before you start

Node.js 18.18+ installed (node --version). npm comes with it.
An account on H1VE Flow (app.h1ve.org).
That is all you need — you sign in with nf login (browser), no token to create or paste. A personal API token (PAT, nf_pat_…) is only for headless / CI (see §02). It authenticates as you (read and write); the service key is read-only.

02 · CLI — nf

Operate the flow from the terminal

The nf CLI drives the feature on your current branch — status, start, move, spec, done, blockers.

Install

npm i -g @h1veframework/clinf --version

nf login                               # opens the browser to authorize — no token to pastenf health                              # tests the connection

Tip

"No snapshots registered" from nf health is a success response — it connected; the project just has no health metrics yet.

Headless / CI (optional)

No browser (CI, a server)? Authenticate with a PAT (nf_pat_…, from app.h1ve.org/api-tokens) via two environment variables:

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

Tip

Put the export lines in your ~/.zshrc / ~/.bashrc so you don't repeat them each session. Keep the PAT safe — it's a secret, shown once.

Commands

nf login: Authorize in the browser — the normal way to sign in (no token to paste)
nf health: Latest technical-health snapshots for the project
nf status: State of the current branch's feature (stage, days active, blockers, sign-offs)
nf start [<n|id>]: Start an assigned feature: creates the branch feat/{you}/{slug} and records the slug
nf spec: Print the feature's spec (markdown)
nf move <stage>: Move the feature to another stage
nf done [--from <file>]: Submit the AI declaration (JSON) and move dev → pr
nf blocker "<desc>": Open a blocker on the feature (you become the owner)
nf connect …: Apply a credential to the local .env.local (never to the server) and register the connection inventory
nf serve: Run the local agent (127.0.0.1) so the panel's visual menu can apply credentials from the browser

Useful flags: --json (raw output for scripts) · --project <name|id> (if you belong to more than one project) · -h (full help).

Real example

nf start                                  # start the assigned feature (creates the branch)# ... work as usual (git, code, commits) ...nf status                                 # state at any timenf blocker "waiting on the Neon prod credential"nf done --from ai-declaration.json        # submit AI declaration + move dev → pr

03 · MCP Server — Claude Code

Plug the flow into your AI agent

The MCP server gives Claude Code direct access to the current branch's feature context — no copy-pasting SPECs. Plug it once; the tools show up in any project.

Install (plug into Claude Code)

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

After nf login, the server uses your session — no token in the command. -s user = available in all projects; for the current repo only, use -s local from inside it. No manual install — npx fetches the package on first run.

Headless / CI (optional)

Where no browser session exists, pass the PAT as environment variables:

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

Confirm the connection

claude mcp list       # should list "h1ve: ✔ Connected"

Inside Claude Code, run /mcp — the h1ve server appears with 6 tools.

The 6 tools

get_current_feature: Branch feature state: stage, days active, blockers, sign-offs, ai-declaration
get_spec: The feature's spec (markdown)
move_feature_stage: Move the feature to another stage (rules validated on the server)
create_blocker: Open a blocker on the feature (you become the owner)
submit_ai_declaration: Submit the feature’s AI declaration (owner dev only)
start_feature: Start an assigned feature: records the slug and returns the git switch -c to create the branch

About identity

Read tools (get_current_feature, get_spec) work with your login or the service key. Write tools (move, blocker, ai-declaration, start) require your own identity — your nf login session, or a PAT in headless/CI. The read-only service key returns SERVICE_CANNOT_WRITE.

04 · VS Code extension

See the flow in your editor

The H1VE extension surfaces the current branch's feature right inside VS Code — stage, blockers, sign-offs, and the spec — in a sidebar view, with no context switch to the dashboard. A read-only companion to the CLI and MCP.

Install

code --install-extension h1ve.h1ve-vscode

Or search "H1VE" in the Extensions view, or open it on the VS Code Marketplace. Works in VS Code and forks like Cursor.

Already ran nf login in a terminal? The extension reuses that session automatically — nothing to paste. Open the H1VE panel (the hive icon in the activity bar) on a feature branch.

No terminal session

The panel shows a "Connect to H1VE" button — or run H1VE: Set API Key to store a PAT (nf_pat_…) in the VS Code SecretStorage (never in settings).

Commands

H1VE: Set API Key: Store or clear the API key (kept in SecretStorage)
H1VE: Refresh: Reload the branch's feature state
H1VE: Open Spec: Open the feature's spec in a markdown editor

The "Branch feature" view resolves the feature from your current git branch (the slug from nf start) and refreshes every 30s. It is read-only — to act on features (start, move, spec, done), use the CLI or MCP.

05 · Troubleshooting

Common frictions

nf: command not found: Node not installed, or wrong terminal. Check node --version. On Windows, PowerShell may not expose the npm bin on PATH — use the VS Code terminal or reopen the shell after installing.
404 on install: npm propagation right after a publish. Wait a few minutes and retry.
NO_PROJECT: You belong to more than one project. Pass --project <name|id> on the CLI; the MCP resolves it from the branch context.
401 / 403: Not authorized. Re-run nf login. In headless/CI, ensure H1VE_API_KEY is a valid PAT (nf_pat_…). 403 SERVICE_CANNOT_WRITE = the read-only service key was used on a write action → sign in (or use a PAT).

06 · Variable-name compatibility

Legacy names still work

Backward compatible

The current names are H1VE_API_URL and H1VE_API_KEY — use these. The legacy names NEXUS_FLOW_API_URL / NEXUS_FLOW_API_KEY are still accepted for compatibility — if you already configured with them, you don't need to change anything. We recommend H1VE_* for new setups.