Hooman

Hooman is a hackable AI agent toolkit for local workflows. It is built with TypeScript, Strands Agents SDK, and Ink.

Node.js TypeScript Ink Build GitHub Repo stars GitHub last commit

Hooman screenshot

It gives you a practical toolkit to build and run agent workflows: - a one-shot `exec` command for single prompts - a stateful `chat` interface for iterative sessions - a `daemon` command for channel-driven MCP automation - an in-chat `/config` workflow (Ink-powered) for general settings, models, MCP servers, and installed skills - an `acp` command for running Hooman as an Agent Client Protocol (ACP) agent over stdio ## Related **Looking for a focused web UI** for chat and agent configuration with lighter surface on top of the same stack? See [**Zero**](https://github.com/vaibhavpandeyvpz/zero) — [README](https://github.com/vaibhavpandeyvpz/zero#readme). ## Features - Multiple LLM providers: `anthropic`, `azure`, `bedrock`, `google`, `groq`, `minimax`, `moonshot`, `ollama`, `openai`, `openrouter`, `xai` - Local configuration under `~/.hooman` - Optional web search tool with provider selection (`brave`, `exa`, `firecrawl`, `serper`, or `tavily`) - MCP server support via `stdio`, `streamable-http`, and `sse` - MCP server `instructions` support: server-provided instructions are appended to the agent system prompt - MCP channel notifications: `hooman daemon` subscribes to servers that advertise `hooman/channel` - Runtime skills via Strands `AgentSkills`, loading bundled built-in skills plus local `~/.hooman/skills` - Bundled prompt harness toggles (`behaviour`, `communication`, `execution`, `guardrails`); coding guidance ships as the built-in `hooman-coding` skill - Built-in read-only subagent tools (`subagent_research`, `subagent_review`, `subagent_test_investigator`) - Built-in `grep` tool backed by ripgrep (`rg`), with runtime bootstrap when `rg` is not available on PATH - Toolkit-oriented architecture with configurable tools, prompts, and transports - Interactive terminal UI for chat and configuration ## Requirements - [Node.js](https://nodejs.org) `>= 24` - npm for package installs and JavaScript tooling - Provider credentials or local model runtime depending on the LLM you choose ## Usage Fastest way to get started without cloning the repo: ```bash npx hoomanjs # or install globally npm i -g hoomanjs ``` Or with Bun: ```bash bunx hoomanjs ``` Recommended first run: 1. Start chatting with `hooman` (same as `hooman chat`). 2. Run `/config` in chat to choose your LLM provider and model, and to manage MCP servers and skills. 3. Use `hooman exec "your prompt"` for one-off tasks. ## Must have For the best experience, set up both: 1. **MCP servers** for on-demand tools in `chat` / `exec` (task APIs, messaging, schedulers, etc.). 2. **MCP channels** for event-driven automation with `hooman daemon` (notifications become agent prompts). Suggested MCP servers from this ecosystem: - [`cronmcp`](https://github.com/vaibhavpandeyvpz/cronmcp) - lets Hooman schedule recurring prompts and automations, so routine checks and follow-ups run on time. - [`jiraxmcp`](https://github.com/vaibhavpandeyvpz/jiraxmcp) - gives Hooman direct Jira Cloud access to search issues, update tickets, and help drive sprint workflows. - [`slackxmcp`](https://github.com/vaibhavpandeyvpz/slackxmcp) - connects Hooman to Slack so it can read channel context, draft updates, and post actions where your team already works. - [`tgfmcp`](https://github.com/vaibhavpandeyvpz/tgfmcp) - enables Telegram bot workflows, making it easy to route notifications and respond from agent-driven chats. - [`wappmcp`](https://github.com/vaibhavpandeyvpz/wappmcp) - brings WhatsApp Web messaging into Hooman for customer or team communication automations. For production deployments, still review permissions and use least-privilege credentials/tokens for each integration. ## Install ```bash npm install ``` Run locally: ```bash npm run dev -- --help ``` Or use the dev alias: ```bash npm run build node dist/cli.js --help ``` Link the CLI locally: ```bash npm link hooman --help ``` ## Commands ### `hooman exec` Run a single prompt once. ```bash hooman exec "Summarize the current repository" ``` Use a specific session id: ```bash hooman exec "What changed?" --session my-session ``` Skip interactive tool approval (allows every tool call; use only when you trust the prompt and environment): ```bash hooman exec "Summarize this repo" --yolo ``` Start in **ask** mode (narrower tool surface, no plan lifecycle tools; see [Session mode](#session-mode)): ```bash hooman exec "Map the architecture" --mode ask ``` ### `hooman chat` Start an interactive stateful chat session. ```bash hooman ``` Equivalent explicit form: ```bash hooman chat ``` Optional initial prompt: ```bash hooman chat "Help me prioritize the next task" ``` Resume or pin a session id: ```bash hooman chat --session my-session ``` Skip the in-chat tool approval UI (same semantics as `exec --yolo`): ```bash hooman chat --yolo ``` Start in ask mode: ```bash hooman chat --mode ask ``` ### Chat commands Inside an interactive `chat` session, type `/` to discover slash commands: - `/model` - pick or set the chat model for this session. - `/mode` - switch the session mode (`agent`, `ask`, `plan`); see [Session mode](#session-mode). - `/yolo` - toggle auto-approve of tool calls (`on` / `off`). - `/init` - generate or refresh `AGENTS.md` for the current project. - `/compact` - compact the conversation history now and persist the result. - `/new` - start a fresh chat session. - `/config` - launch the configuration workflow (see below). ### Session mode `exec`, `chat`, and `daemon` accept **`-m` / `--mode`** with: - **`agent`** (default): normal tool surface and approvals. - **`plan`**: planning workflow with a reduced tool surface plus `enter_plan_mode` / `exit_plan_mode`. - **`ask`**: read-oriented, narrower surface (similar to interactive **plan** mode) but **without** `enter_plan_mode` / `exit_plan_mode`. In **`chat`**, `/mode` can switch between **agent**, **ask**, and **plan**. **ACP** sessions can set `hooman.sessionMode` to `agent`, `plan`, or `ask`. ### `hooman daemon` Run a long-lived daemon that **always** subscribes to MCP servers advertising the `hooman/channel` capability and feeds each received notification into the agent as a queued prompt. ```bash hooman daemon ``` Resume or pin a session id: ```bash hooman daemon --session my-daemon ``` Skip remote channel permission relay and allow every tool call from daemon turns (same risk profile as `exec` / `chat` with `--yolo`): ```bash hooman daemon --yolo ``` Optional `--mode ask` matches `exec` / `chat` (narrow surface without plan lifecycle tools). Log raw notification payloads: ```bash hooman daemon --debug ``` ### `hooman config` Print the effective runtime `config.json` for the current working directory in the same shape as `config.json`, with credential-like values redacted. ```bash hooman config ``` ### Feature Flags Runtime tool and prompt switches are controlled from `config.json`: - `search.enabled` - `search.provider` (`brave`, `exa`, `firecrawl`, `serper`, or `tavily`) - `search.brave.apiKey` - `search.exa.apiKey` - `search.firecrawl.apiKey` - `search.serper.apiKey` - `search.tavily.apiKey` - `prompts.behaviour` - `prompts.communication` - `prompts.execution` - `prompts.guardrails` - `tools.todo.enabled` - `tools.fetch.enabled` - `tools.filesystem.enabled` - `tools.shell.enabled` - `tools.sleep.enabled` - `tools.subagents.enabled` (enables built-in subagent tools) ### `/config` The interactive configuration workflow is launched from inside a `chat` session with the `/config` slash command (there is no separate top-level `configure` command). It takes over the terminal on the alternate screen buffer while open, and restores the chat session on exit. Any config changes are picked up when the session re-bootstraps. ```text /config ``` The configuration UI currently lets you: - manage general settings such as name, prompts, tools, and compaction - manage models and providers with field-by-field editors - choose search provider and set its API key - toggle bundled harness prompts (`behaviour`, `communication`, `execution`, `guardrails`) - edit `instructions.md` in your `$VISUAL` / `$EDITOR` (cross-platform fallback included) - add, edit, and delete MCP servers with field-by-field editors and confirmation - search, install, refresh, and remove skills ### `hooman acp` Run Hooman as an Agent Client Protocol (ACP) agent over stdio. ```bash hooman acp ``` ACP notes: - ACP sessions are stored under the active Hooman data directory in `acp-sessions/` - ACP loads MCP servers passed on `session/new` and `session/load`, in addition to Hooman's local `mcp.json` - ACP `session/new` and `session/load` support `_meta.userId` - session configuration includes `hooman.sessionMode` (`agent`, `plan`, or `ask`); see [Session mode](#session-mode) ## Configuration Layout Hooman stores its data in: ```text ~/.hooman/ ``` Important files and folders: - `config.json` - app name, reusable provider configs, model configs, tool flags, and compaction - `instructions.md` - system instructions used to build the agent prompt - `mcp.json` - MCP server definitions - `skills/` - installed skills - `bin/` - runtime-managed helper binaries (including bootstrapped `rg` for the `grep` tool when system `rg` is unavailable) - `cache/` - runtime caches used by tools and subsystems - `sessions/` - persisted session data - `acp-sessions/` - persisted ACP session metadata and message snapshots ### Repo-local runtime overlays At runtime, Hooman resolves configuration in this order: 1. `~/.hooman/config.json` and `~/.hooman/mcp.json` 2. `/config.json` and `/mcp.json` (if present) 3. matching files in nested directories from git root to current working directory Nearest files win when keys overlap. For app config (`config.json`): - plain objects are deep-merged - scalar values are overridden by the nearest file - `providers` and `llms` are merged by `name` (nearest entry with the same name replaces inherited entries) For MCP config (`mcp.json`): - `mcpServers` is merged by server name (nearest entry with the same name wins) Notes: - Runtime overlays apply to `chat`, `exec`, `daemon`, and `acp` bootstraps. - `hooman config` prints only the merged effective `config.json` shape with credential-like values redacted. - The `/config` UI and `hooman mcp auth/logout/auth-status` still target home config (`~/.hooman/*`) directly. - Keep secrets in home config unless you explicitly want project-scoped credentials. `grep` tool binary resolution order: 1. Use system `rg` when available. 2. Else use cached `~/.hooman/bin/rg` (or `rg.exe` on Windows). 3. Else download and verify a platform-specific ripgrep release into `~/.hooman/bin/`. ## Example `config.json` The on-disk shape uses a reusable **`providers`** array plus a non-empty **`llms`** array. Each provider stores a runtime `provider` id plus provider-specific `options`; each LLM references a provider by name, stores its model `options`, and marks one entry as the default. The bundled **hooman-config** skill documents the full schema. ```json { "name": "Hooman", "providers": [ { "name": "Ollama", "provider": "ollama", "options": {} } ], "llms": [ { "name": "Default", "provider": "Ollama", "options": { "model": "gemma4:e4b" }, "default": true } ], "search": { "enabled": false, "provider": "brave", "brave": {}, "exa": {}, "firecrawl": {}, "serper": {}, "tavily": {} }, "prompts": { "behaviour": true, "communication": true, "execution": true, "guardrails": true }, "tools": { "todo": { "enabled": true }, "fetch": { "enabled": true }, "filesystem": { "enabled": true }, "shell": { "enabled": true }, "sleep": { "enabled": true }, "subagents": { "enabled": true } }, "compaction": { "ratio": 0.75, "keep": 5 } } ``` Tool approvals are session-scoped and are not persisted in `config.json`. Hooman enables Strands `ContextOffloader` by default with file-backed storage under `~/.hooman/sessions/offloaded-content`, so large tool results can be previewed in-context and retrieved later without bloating the active conversation window. Supported `providers[].provider` values registered in this release (see `src/core/models/index.ts`): - `anthropic` - `azure` - `bedrock` - `google` - `groq` - `minimax` - `moonshot` - `ollama` - `openai` - `openrouter` - `xai` Supported `search.provider` values: - `brave` - `exa` - `firecrawl` - `serper` - `tavily` ## Provider Notes Provider entries now look like: ```json { "name": "MiniMax", "provider": "minimax", "options": { "apiKey": "..." } } ``` LLM entries reference a provider by name and carry normalized model options: ```json { "name": "MiniMax M3", "provider": "MiniMax", "options": { "model": "MiniMax-M3", "temperature": 1, "maxTokens": 4096 }, "default": true } ``` Supported provider option fields: - `anthropic`: `apiKey`, optional `baseURL`, optional `headers`, optional `thinking` - `azure`: optional `resourceName`, optional `baseURL`, optional `apiKey`, optional `headers`, optional `apiVersion`, optional `useDeploymentBasedUrls` - `bedrock`: `region`, `accessKeyId`, `secretAccessKey`, optional `sessionToken`, optional `apiKey` - `google`: `apiKey` - `groq`: `apiKey`, optional `baseURL`, optional `headers` - `minimax`: `apiKey`, optional `headers`, optional `thinking` - `moonshot`: `apiKey`, optional `baseURL`, optional `headers` - `ollama`: optional `baseURL`, optional `thinking` - `openai`: `apiKey`, optional `baseURL`, optional `headers` - `openrouter`: `apiKey`, optional `baseURL`, optional `headers` - `xai`: `apiKey`, optional `baseURL`, optional `headers` Normalized LLM option fields: - `model` - optional `temperature` - optional `maxTokens` Notes: - Google maps normalized `maxTokens` to the SDK's `maxOutputTokens` internally. - Azure uses the Vercel AI SDK `@ai-sdk/azure` provider. Set the LLM `model` to your Azure deployment name, not the raw OpenAI model id. - Ollama maps normalized `temperature` into Ollama `options.temperature`. - MiniMax uses the Anthropic-compatible endpoint `https://api.minimax.io/anthropic` automatically. - Moonshot defaults `baseURL` to `https://api.moonshot.ai/v1` when it is omitted. - OpenRouter defaults `baseURL` to `https://openrouter.ai/api/v1` when it is omitted, and model names are usually provider-qualified ids such as `anthropic/claude-3.5-sonnet`. - Bedrock can rely on the AWS default credential chain when explicit credentials are not provided. ## MCP Configuration Detailed design notes for planned OAuth-enabled remote MCP support live in [docs/mcp-oauth-design.md](docs/mcp-oauth-design.md). `mcp.json` is stored as: ```json { "mcpServers": {} } ``` At runtime, project-local `mcp.json` files are merged on top of `~/.hooman/mcp.json` from git root to current directory. On name conflicts, the nearest `mcpServers.` entry wins. ### Example stdio server ```json { "mcpServers": { "filesystem": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"], "env": { "EXAMPLE": "1" }, "cwd": "/tmp" } } } ``` ### Example streamable HTTP server ```json { "mcpServers": { "remote": { "type": "streamable-http", "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer token" } } } } ``` ### Example OAuth-capable remote server ```json { "mcpServers": { "linear": { "type": "streamable-http", "url": "https://example.com/mcp", "oauth": { "enabled": true, "clientId": "optional-pre-registered-client", "scopes": ["read", "write"], "callbackPort": 19876 } } } } ``` ### Example SSE server ```json { "mcpServers": { "legacy": { "type": "sse", "url": "https://example.com/sse", "headers": { "Authorization": "Bearer token" } } } } ``` ## MCP Notes - MCP server `instructions` from the protocol `initialize` response are appended to Hooman's system prompt, after local `instructions.md` and session-specific prompt overrides. - Hooman reads these instructions automatically from connected MCP servers when building the agent. - Remote MCP OAuth helpers are available via: - `hooman mcp auth ` - `hooman mcp logout ` - `hooman mcp auth-status` - `hooman daemon` subscribes to MCP servers that advertise the experimental `hooman/channel` capability (always on; there is no opt-out flag). - Hooman also reads `hooman/user`, `hooman/session`, and `hooman/thread` capability paths so daemon turns preserve origin metadata from the source channel. - When a matching notification is received, Hooman uses `params.content` as the prompt if it is a string; otherwise it JSON-stringifies the notification params and sends that to the agent. - Daemon mode processes notifications sequentially and reuses the same agent session over time. - Tool calls from daemon turns are no longer blanket auto-approved: if the originating MCP server supports `hooman/channel/permission`, Hooman relays a remote approval request back to that source; otherwise the tool call is denied. - `exec`, `chat`, and `daemon` accept `--yolo` to bypass those approval paths and allow all tools without prompting or relay. ## Skills Skills are installed under: ```text ~/.hooman/skills ``` At runtime, Hooman uses the Strands `AgentSkills` plugin to load: - bundled built-in skills shipped with Hooman - user-installed skills under `~/.hooman/skills` The local skills folder is treated as a parent directory of skill subdirectories, where each installed skill should live in its own folder containing `SKILL.md`. When a session starts, the plugin injects available skill metadata into the system prompt and exposes the `skills` tool so the model can activate a skill and load its full instructions on demand. The `/config` workflow can: - search the public skills catalog - install a skill from a source string, repo, URL, or local path - refresh installed skills - remove installed skills with confirmation ## Development Install dependencies: ```bash npm install ``` Run the CLI: ```bash npm run dev -- --help ``` Run typecheck: ```bash npm run typecheck ``` Build the project: ```bash npm run build ``` After making any code change, run both verification steps: ```bash npm run typecheck npm run build ``` ## License MIT. See `LICENSE`.