VS Code

src/vscode/ ships a self-contained VS Code extension (hooman-vscode) that bridges hooman acp into the editor with a native Hooman chat panel in the activity bar.

Works in stable VS Code, VS Code Insiders, and compatible forks — no proposed APIs and no special subscription required. Local-first: your configuration, API keys, and sessions live in ~/.hooman on your machine — no account, no telemetry.

Install it from the VS Code Marketplace, or see the VS Code quickstart for step-by-step setup.

Features

• Streaming chat with full markdown rendering and collapsible thinking (with a “thought for Xs · ~N tokens” summary).
• Tool-call cards with live status — shell commands stream their output into the card as they run.
• Review every edit: files the agent writes appear in a pinned Changes panel. Click a file to open a native diff against its pre-edit baseline, then Keep or Undo each change (or all at once). Edits go through undo-able workspace edits, and the agent sees your unsaved buffers.
• Plan checklist pinned above the transcript, updated live as the agent works through it.
• Queue and steer: follow-ups sent mid-turn land in a Queued panel where you can edit, remove, or Send now. Steer now injects the queue as guidance into the running turn instead of waiting for it to finish.
• Attachments: add files, folders, and images via the paperclip button, drag & drop, or paste from the clipboard.
• Sessions persist: a Sessions overlay lists saved sessions grouped by day, searchable, with the ongoing one marked, click-to-open, per-session delete, and a New Chat action.
• Pill pickers in the composer for mode (Agent / Plan / Ask / Yolo), model, and reasoning effort, plus / slash-command autocomplete (/compact, /init).
• Inline permission prompts: the agent asks before running destructive tools; approve or reject right in the panel (Yolo mode auto-approves).
• Status bar item showing the current model and mode, with a spinner while a turn runs and a quick menu for all session controls.
• Token-usage footer with the latest request’s input / cached / output token counts, plus a context-window gauge and cumulative session cost — see Billing metadata.
• Model download strip: when a local llama.cpp model downloads its weights on first use, a progress strip shows percent, size, speed, and ETA above the composer.

Quick start

1. Install Node.js >= 24 (npx ships with it — that’s all the extension needs).

2. Install the extension from the Marketplace.

3. Click the Hooman icon in the activity bar and send a prompt. The extension launches the agent via npx hoomanjs acp, downloading the CLI on first use — no separate install step.

4. Pick your provider and model. Out of the box, Hooman runs a local Qwen3 model via llama.cpp (downloaded from the Hugging Face Hub on first use), with Qwen3.5 and Gemma 4 preconfigured as alternatives. To use a hosted provider instead, either:

   • click Open Settings… (gear icon in the panel title bar) to edit ~/.hooman/config.json directly, or
   • run npx hoomanjs in a terminal and use the /config workflow.

   See Configuration and Models for the full schema.

Commands

• Hooman: New Chat — start a fresh session in the chat panel.
• Hooman: Open Session… — opens the Sessions overlay: saved sessions grouped by day, searchable, ongoing marked, click-to-open, per-session delete.
• Hooman: Open Settings… — opens config.json or mcp.json from ~/.hooman/ (or $HOOMAN_HOME/), scaffolding it first if needed.
• Hooman: Show Output Channel — opens the “Hooman” output channel with the agent’s logs.
• Hooman: Delete All Sessions — deletes every persisted session after a confirmation prompt.

Extension settings

By default the extension runs the agent through npx, resolving hoomanjs on demand. If you’d rather pin a specific binary or a local build:

Setting	Default	Purpose
hooman.acp.command	npx	Executable used to launch the agent.
hooman.acp.args	["hoomanjs", "acp"]	Arguments passed to the command above.

{
  "hooman.acp.command": "node",
  "hooman.acp.args": ["/absolute/path/to/hooman/dist/cli.js", "acp"]
}

Everything else — providers, models, API keys, MCP servers, skills — is Hooman’s own configuration under ~/.hooman/, shared with the CLI.

Troubleshooting

• Nothing happens / the panel says the agent failed to start — run Hooman: Show Output Channel. It logs the spawned process’s stderr and connection activity.
• First prompt is slow — npx may be downloading hoomanjs on first use; subsequent launches use the cache.
• Wrong or no model — the agent uses your ~/.hooman/config.json. Verify it works in a terminal with npx hoomanjs exec "hello".

Development

The extension lives in src/vscode/ of the Hooman repository as a self-contained sub-package (its own package.json and dependencies, excluded from the root build).

cd src/vscode
npm install
npm run compile   # typecheck + esbuild (extension host) + vite build (webview)
npm run watch     # rebuild all three on save
npm run package   # -> hooman-vscode-<version>.vsix (fully bundled, no node_modules)

Install the packaged .vsix into any VS Code-compatible editor:

code --install-extension hooman-vscode-<version>.vsix

To debug, open the repository root in VS Code (after running npm install in src/vscode/ at least once) and press F5 — the root .vscode/launch.json and .vscode/tasks.json point at src/vscode, so there’s no need to cd in or open it as a separate workspace.

Architecture in brief: one hooman acp process serves the panel for the extension’s lifetime, with every chat session multiplexed over it as an ACP session. The extension implements the client-side ACP fs/* capabilities against VS Code’s workspace APIs (so the agent sees dirty buffers and edits are undo-able) and terminal/* via child processes. The panel UI is a SolidJS + Tailwind webview bundled by Vite; the extension host is bundled by esbuild. See src/vscode/README.md in the repository for the full breakdown.