Hooman

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 Ink-powered configure workflow for app config, prompts, 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 — README.

Features

• Multiple LLM providers: ollama, openai, tensorzero, anthropic, google, bedrock, groq, moonshot, 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
• Skill discovery from local ~/.hooman/skills folders
• Bundled prompt harness toggles (behaviour, communication, execution, guardrails); coding guidance ships as the built-in hooman-coding skill
• Built-in research sub-agent runner (research) with configurable concurrency
• Toolkit-oriented architecture with configurable tools, prompts, memory, and transports
• Interactive terminal UI for chat and configuration

Requirements

• Node.js >= 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:

npx hoomanjs configure
npx hoomanjs chat

# or install globally
npm i -g hoomanjs

Or with Bun:

bunx hoomanjs configure
bunx hoomanjs chat

Recommended first run:

1. Run hooman configure to choose your LLM provider and model.
2. Start chatting with hooman chat.
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 - lets Hooman schedule recurring prompts and automations, so routine checks and follow-ups run on time.
• jiraxmcp - gives Hooman direct Jira Cloud access to search issues, update tickets, and help drive sprint workflows.
• slackxmcp - connects Hooman to Slack so it can read channel context, draft updates, and post actions where your team already works.
• tgfmcp - enables Telegram bot workflows, making it easy to route notifications and respond from agent-driven chats.
• 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

npm install

Run locally:

npm run dev -- --help

Or use the dev alias:

npm run build
node dist/cli.js --help

Link the CLI locally:

npm link
hooman --help

Commands

hooman exec

Run a single prompt once.

hooman exec "Summarize the current repository"

Use a specific session id:

hooman exec "What changed?" --session my-session

Skip interactive tool approval (allows every tool call; use only when you trust the prompt and environment):

hooman exec "Summarize this repo" --yolo

Start in ask mode (narrower tool surface, no plan lifecycle tools; see Session mode):

hooman exec "Map the architecture" --mode ask

hooman chat

Start an interactive stateful chat session.

hooman chat

Optional initial prompt:

hooman chat "Help me prioritize the next task"

Resume or pin a session id:

hooman chat --session my-session

Skip the in-chat tool approval UI (same semantics as exec --yolo):

hooman chat --yolo

Start in ask mode:

hooman chat --mode ask

Session mode

exec, chat, and daemon accept -m / --mode with:

• default (default): normal tool surface and approvals.
• ask: read-oriented, narrower surface (similar to interactive plan mode) but without enter_plan_mode / exit_plan_mode.

In chat, /mode can also switch to plan (includes plan tools and a plan document workflow). ACP sessions can set hooman.sessionMode to default, 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.

hooman daemon

Resume or pin a session id:

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):

hooman daemon --yolo

Optional --mode ask matches exec / chat (narrow surface without plan lifecycle tools).

Log raw notification payloads:

hooman daemon --debug

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.ltm.enabled
• LTM embed model is fixed in Hooman as DEFAULT_LTM_EMBED_MODEL (not configurable in config.json).
• LTM embed GPU: defaults to CPU so memory_search does not stall on flaky GPU init; set HOOMAN_LTM_LLAMA_GPU=auto (or metal / vulkan / cuda) to match QMD-style acceleration. On startup, Hooman preloads the embed model once (see stderr: Loading LTM embedding model…).
• tools.wiki.enabled
• tools.agents.enabled (enables built-in run_agents tool)
• tools.agents.concurrency

Long-term memory uses SQLite + sqlite-vec at $HOOMAN_HOME/ltm.sqlite and local GGUF embeddings via node-llama-cpp (model cache under $HOOMAN_HOME/ltm-models). See @tobilu/qmd-style requirements for native SQLite extensions where applicable.

The wiki tool uses a local QMD index: after page writes, pages under $HOOMAN_HOME/wiki/pages (default ~/.hooman/wiki/pages) are indexed into $HOOMAN_HOME/wiki/.qmd/index.sqlite. See @tobilu/qmd for SQLite extension requirements (e.g. macOS Homebrew SQLite) and on-first-use embedding model downloads.

hooman configure

Open the Ink configuration workflow.

hooman configure

The configure UI currently lets you:

• edit app configuration values
• 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 confirmation
• search, install, refresh, and remove skills

hooman acp

Run Hooman as an Agent Client Protocol (ACP) agent over stdio.

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 and _meta.systemPrompt
• when _meta.systemPrompt is provided, it is appended to the agent system prompt with a section break
• session configuration includes hooman.sessionMode (default, plan, or ask); see Session mode

Configuration Layout

Hooman stores its data in:

~/.hooman/

Important files and folders:

• config.json - app name, LLM provider/model, tool flags, LTM/wiki settings, compaction
• ltm.sqlite - long-term memory vectors + rows (created when LTM is used)
• ltm-models/ - downloaded GGUF embedding weights for LTM
• instructions.md - system instructions used to build the agent prompt
• mcp.json - MCP server definitions
• skills/ - installed skills
• sessions/ - persisted session data
• acp-sessions/ - persisted ACP session metadata and message snapshots

Example config.json

The canonical on-disk shape uses a llms array (non-empty): each item has name, options (provider, model, params), and default. The bundled hooman-config skill documents the full schema. The JSON below uses a single llm object only as a shorthand for the active profile’s options fields.

{
  "name": "Hooman",
  "llm": {
    "provider": "ollama",
    "model": "gemma4:e4b",
    "params": {}
  },
  "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
    },
    "ltm": {
      "enabled": false,
      "embed": {
        "model": "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf"
      }
    },
    "wiki": {
      "enabled": false
    },
    "agents": {
      "enabled": true,
      "concurrency": 3
    }
  },
  "compaction": {
    "ratio": 0.75,
    "keep": 5
  }
}

Tool approvals are session-scoped and are not persisted in config.json.

Supported llm.provider values (in config.json these live under each llms[].options.provider entry):

• ollama
• openai
• tensorzero
• anthropic
• google
• bedrock
• groq
• moonshot
• xai

Supported search.provider values:

• brave
• exa
• firecrawl
• serper
• tavily

Provider Notes

Ollama

Good default for local usage. Example:

{
  "provider": "ollama",
  "model": "gemma4:e4b",
  "params": {}
}

OpenAI

Uses Strands OpenAIModel (Chat Completions). apiKey is optional if OPENAI_API_KEY is set. Use clientConfig for a custom base URL or other OpenAI client options (OpenAI-compatible proxies and gateways).

Example:

{
  "provider": "openai",
  "model": "gpt-5",
  "params": {
    "apiKey": "..."
  }
}

OpenAI-compatible gateways that put token usage on the last streamed chunk together with choices are handled via a small stream shim so usage still surfaces in the UI.

Bifrost

Use bifrost (not openai) when routing through a Bifrost OpenAI-compatible gateway to Moonshot / Kimi. Set clientConfig.baseURL to the gateway origin only (e.g. http://localhost:8080); /openai/v1 is appended automatically. Same params shape as OpenAI, implemented with StrandsBifrostModel: delta.reasoning streaming, synthetic delta.role when missing, reasoning_content replay for tool turns, and final-chunk usage handling.

{
  "provider": "bifrost",
  "model": "moonshot/kimi-k2.6",
  "params": {
    "apiKey": "dummy-key",
    "clientConfig": {
      "baseURL": "http://localhost:8080"
    }
  }
}

TensorZero

Use for a TensorZero gateway’s OpenAI-compatible HTTP API (for example /openai/v1). Same general params shape as OpenAI (apiKey, clientConfig.baseURL, etc.), but implemented with StrandsTensorZeroModel so gateway-specific streaming works end-to-end: reasoning carried in tensorzero_extra_content shows as thinking in the chat UI, and usage metadata is normalized.

Gateway features such as tag-scoped rate limits use TensorZero tags on each request. Set them in config under the nested params object (Strands forwards that object onto the Chat Completions body), for example tensorzero::tags.user_id.

{
  "provider": "tensorzero",
  "model": "tensorzero::function_name::chat",
  "params": {
    "apiKey": "your-tensorzero-or-gateway-key",
    "clientConfig": {
      "baseURL": "http://localhost:3000/openai/v1"
    },
    "params": {
      "tensorzero::tags": {
        "user_id": "your-stable-user-or-tenant-id"
      }
    }
  }
}

Use tensorzero when the backend is TensorZero; use bifrost for Bifrost → Kimi; use openai for the official OpenAI API or generic Chat Completions proxies that do not need those gateway-specific stream shapes.

Anthropic

Uses Strands AnthropicModel (Anthropic Messages API). apiKey or authToken, optional baseURL and headers (merged into clientConfig), optional clientConfig, and model fields such as temperature and maxTokens. A prebuilt client is not configurable from JSON.

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "params": {
    "apiKey": "...",
    "temperature": 0.7
  }
}

Google

Uses Strands GoogleModel on top of @google/genai. Top-level options like apiKey, client, clientConfig, and builtInTools are supported; other values go into Google generation params.

{
  "provider": "google",
  "model": "gemini-2.5-flash",
  "params": {
    "apiKey": "...",
    "temperature": 0.7,
    "maxOutputTokens": 2048,
    "topP": 0.9,
    "topK": 40
  }
}

Bedrock

Supports region, clientConfig, and optional apiKey, with all other values forwarded as Bedrock model options.

{
  "provider": "bedrock",
  "model": "anthropic.claude-sonnet-4-20250514-v1:0",
  "params": {
    "region": "us-east-1",
    "clientConfig": {
      "profile": "dev",
      "maxAttempts": 3,
      "credentials": {
        "accessKeyId": "AKIA...",
        "secretAccessKey": "...",
        "sessionToken": "..."
      }
    },
    "temperature": 0.7,
    "maxTokens": 1024
  }
}

You can also rely on the AWS default credential chain (recommended) by setting environment variables such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optionally AWS_SESSION_TOKEN.

Groq

Uses the Vercel AI SDK Groq provider (@ai-sdk/groq) on top of Strands VercelModel. Provider-specific settings apiKey, baseURL, and headers are picked up; other values are forwarded into the model config (temperature, maxTokens, etc.). Defaults to GROQ_API_KEY from the environment when no apiKey is supplied.

{
  "provider": "groq",
  "model": "gemma2-9b-it",
  "params": {
    "apiKey": "...",
    "temperature": 0.7
  }
}

Moonshot

Uses the Vercel AI SDK Moonshot provider (@ai-sdk/moonshotai) on top of Strands VercelModel. Provider-specific settings apiKey, baseURL, headers, and fetch are picked up; other values are forwarded into the model config (temperature, maxTokens, providerOptions, etc.). Defaults to MOONSHOT_API_KEY from the environment when no apiKey is supplied. Moonshot reasoning models such as kimi-k2-thinking can be configured through params.providerOptions.moonshotai.

{
  "provider": "moonshot",
  "model": "kimi-k2.5",
  "params": {
    "apiKey": "...",
    "temperature": 0.7
  }
}

xAI

Uses the Vercel AI SDK xAI provider (@ai-sdk/xai) on top of Strands VercelModel. Provider-specific settings apiKey, baseURL, and headers are picked up; other values are forwarded into the model config (temperature, maxTokens, etc.). Defaults to XAI_API_KEY from the environment when no apiKey is supplied.

{
  "provider": "xai",
  "model": "grok-4.20-non-reasoning",
  "params": {
    "apiKey": "...",
    "temperature": 0.7
  }
}

MCP Configuration

mcp.json is stored as:

{
  "mcpServers": {}
}

Example stdio server

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {
        "EXAMPLE": "1"
      },
      "cwd": "/tmp"
    }
  }
}

Example streamable HTTP server

{
  "mcpServers": {
    "remote": {
      "type": "streamable-http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

Example SSE server

{
  "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.
• 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:

~/.hooman/skills

Skills are discovered by scanning direct child directories for SKILL.md. The configure 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:

npm install

Run the CLI:

npm run dev -- --help

Run typecheck:

npm run typecheck

License

MIT. See LICENSE.