Hooman

The full-stack open-source agentic ecosystem.
Local-first with llama.cpp & MLX. BYOK or your own inference endpoints.
CLI · VS Code · ACP · daemon channels · Design mode — one MIT-licensed runtime.

Website · Docs · VS Code Extension

Hooman is a mature, local-first AI agent runtime for teams that want the full stack — not a thin chat wrapper. It reads your codebase, edits files, runs commands, automates channels, and ships design artifacts — from a terminal, VS Code, or any Agent Client Protocol client.

Open source (MIT). No account. No telemetry. Bring your own keys, point at private inference endpoints, or run fully offline with llama.cpp / MLX. Config, secrets, and sessions stay in ~/.hooman.

Surface	What it is
hooman chat	Stateful Ink TUI with modes, slash commands, and live cost/context
hooman exec	One-shot agent runs for scripts and CI
hooman daemon	Channel-driven MCP automation (Slack, Telegram, cron, …) with a live terminal dashboard
hooman acp	ACP agent over stdio — powers the VS Code extension and editors like Zed
Design mode	HTML → preview → Figma / Sketch / PDF / PPTX

Quick start

macOS & Linux:

curl -fsSL https://raw.githubusercontent.com/vaibhavpandeyvpz/hooman/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/vaibhavpandeyvpz/hooman/main/install.ps1 | iex

Or skip the installer and run npx hoomanjs / bunx hoomanjs, or install with npm i -g hoomanjs / bun add -g hoomanjs. On first run (when ~/.hooman/config.json is missing), a setup wizard asks for an inference provider and search; then chat starts. Re-run anytime with hooman setup. Full walkthrough: Getting Started.

Docker

The multi-architecture image includes Node.js 24, the latest npm, Bun/bunx, uv/uvx, Go, Git, ripgrep, native build tools, and Playwright Chromium for JavaScript, Python, Go, and browser-based workflows. hooman chat is the default command.

docker run --rm -it \
  --ipc=host \
  -v hooman-data:/home/hooman/.hooman \
  -v "$PWD:/workspace" \
  ghcr.io/vaibhavpandeyvpz/hooman:latest

Run setup once to create config.json in the hooman-data volume. To use existing host configuration instead, mount it read-write with -v "$HOME/.hooman:/home/hooman/.hooman". The container runs as the non-root hooman user (UID/GID 1000), and its working directory is /workspace; mount a project there so Hooman can operate on it.

Pass another CLI command after the image name when needed:

docker run --rm ghcr.io/vaibhavpandeyvpz/hooman:latest --version
docker run --rm -it -v hooman-data:/home/hooman/.hooman ghcr.io/vaibhavpandeyvpz/hooman:latest setup
docker run --rm -i -v hooman-data:/home/hooman/.hooman -v "$PWD:/workspace" ghcr.io/vaibhavpandeyvpz/hooman:latest exec "Summarize this repository"

Release tags publish latest, the full version, and major/minor tags; the current main branch publishes edge. Alpine is not used because Hooman's Playwright browser features require glibc and do not support Alpine's musl runtime.

Why Hooman

• Full-stack, not single-surface — CLI, VS Code, ACP, daemon channels, and Design mode share one runtime and one local config.
• Local-first by default — first-run setup offers llama.cpp (GGUF) and Apple Silicon MLX; weights download on demand; no API key required to start.
• Enterprise-friendly — MIT license, BYOK, OpenAI-compatible custom base URLs, no telemetry, data residency under your control.
• Most-featured agent toolkit — Agent / Plan / Ask / Design modes, MCP + OAuth, skills, subagents, approvals, background shell jobs, context & cost tracking.

Features

• Providers: anthropic, azure, bedrock, google, groq, llama-cpp, minimax, mlx, moonshot, ollama, openai, openrouter, xai — see Models
• Modes: agent / plan / ask / design plus a separate Yolo auto-approve toggle — see Modes and Design
• MCP: stdio, streamable-http, sse with OAuth (DCR + CIMD), lazy tool discovery, optional Playwright browser MCP, and hooman daemon channels — see MCP
• Skills: bundled built-ins (including hooman-design), ~/.hooman/skills, and project-local .hooman/skills — see Skills
• Tools: filesystem (respects .gitignore), ripgrep grep, background shell (run_in_background / shell_output / shell_stop), ask_user, and read-only launch_subagent kinds — see Tools
• VS Code: native chat panel with Mermaid, plan checklists, Changes keep/undo, fork/copy, turn revert, and background-terminals strip — see VS Code

See the full documentation for CLI commands, configuration, provider setup, and more.

Related

Looking for a focused web UI for chat and agent configuration with a lighter surface on top of the same stack? See Zero — README.

Development

npm install
npm run dev -- --help    # run the CLI with tsx
npm run typecheck        # tsc --noEmit
npm run build            # tsc + copy bundled assets to dist/

After making any code change, run both npm run typecheck and npm run build. See AGENTS.md for the full repository layout and contributor notes, and Development in the docs for the release workflow.

License

MIT. See LICENSE.

Built by Vaibhav Pandey · GitHub · LinkedIn