Tools & Toolsets — AI's Hands

Tools & Toolsets — AI’s Hands

Welcome back to our series! Last time, we talked about what makes Hermes Agent tick. Today, we’re rolling up our sleeves and getting our hands dirty — literally. Because in the world of AI agents, tools are the hands. And Hermes just made getting those hands ready a whole lot easier.

The Two-Minute Miracle

Here’s the good news: you can go from zero to chatting with your AI agent in under two minutes. No PhD required. No wrestling with dependency hell. Just a simple install command.

The easiest path? If you’re on macOS or Windows, just download the Hermes Desktop installer from our website. It handles everything — the command-line app, the desktop app, all of it. One download, done.

Prefer the command line? We’ve got you covered there too:

# Linux / macOS / WSL2 / Android (Termux)
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows users, fire up PowerShell:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

That’s it. Seriously.

What Happens Behind the Scenes?

The installer is like a personal assistant for your computer. It automatically handles:

• Python 3.11 (via uv, no sudo needed)
• Node.js v26 (for browser automation and WhatsApp bridge)
• ripgrep (for lightning-fast file searches)
• ffmpeg (for audio conversion in text-to-speech)

You don’t need to install any of these manually. The installer detects what’s missing and grabs it for you. The only prerequisite? Git. On Linux, make sure curl and xz-utils are available too.

Where Does Everything Go?

Depending on how you install, your files land in different places:

Installer	Code lives at	hermes binary	Data directory
Per-user	~/.hermes/hermes-agent/	~/.local/bin/hermes	~/.hermes/
Root-mode	/usr/local/lib/hermes-agent/	/usr/local/bin/hermes	/root/.hermes/

The root-mode layout is perfect for shared machines where one install serves everyone. Per-user config (auth, skills, sessions) still stays private under each user’s ~/.hermes/.

After Installation: Your First Chat

Reload your shell and you’re ready:

source ~/.bashrc   # or: source ~/.zshrc
hermes             # Start chatting!

Want to tweak things later? There’s a command for everything:

hermes model          # Choose your LLM provider and model
hermes tools          # Configure which tools are enabled
hermes gateway setup  # Set up messaging platforms
hermes config set     # Set individual config values
hermes config get     # Inspect individual config values
hermes setup          # Or run the full setup wizard

The Fastest Path: Nous Portal

Here’s a pro tip. Instead of juggling API keys for every tool, use the Nous Portal. One subscription covers 300+ models plus the Tool Gateway — that’s web search, image generation, TTS, and cloud browser all in one.

hermes setup --portal

One command. Logs you in, sets Nous as your provider, and turns on the Tool Gateway. No key juggling, no configuration headaches.

Beyond Built-ins: MCP and Connections

Built-in tools are only part of the story. Hermes can also load tools dynamically from MCP servers, and those show up with the prefix mcp__<server>__ — for example, mcp__github__create_issue for the github MCP server. See the MCP Integration docs at https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp for configuration.

There’s also a single manage_connections tool that handles both kinds of external app. A target is either a managed connector ("gmail" or {"name": "gmail"}, authorized through the Nous gateway) or a local MCP server ({"name": "linear", "mcp": true}, an entry in mcp_servers). Managed actions are status (each connector lists its accounts: alias, label, status, active), connect, reconnect (which repairs only what isn’t connected; force: true restarts a working one), and rename. A connect or reconnect target may carry an account name ({"name": "gmail", "alias": "work"}): connect with a new name adds another account, and reconnect with a name repairs only that account and deletes nothing. rename takes one target, {"name": "gmail", "alias": "work", "to": "office"}; alias may be the app label of an unnamed account. MCP actions — install, enable, and authorize — apply only to mcp: true targets. On the desktop app, the terminal UI, and the classic CLI, every action shows a card and blocks until each target is connected, skipped, or the 300-second deadline passes; the result lists targets as connected, skipped, or not_connected and carries no link. An MCP install collects the entry’s setup values in the card, runs the entry’s OAuth from the card when it has one (the user opens the link; nothing opens by itself), and saves configuration, tokens, and values together when the server accepts the token. A connected MCP target carries tools (the registered names) and tools_listing, and those tools are callable through tool_describe/tool_call in the same turn. A target with discovery_error is authorized but its tools could not be listed; call install or authorize for it again to retry discovery without new consent. On surfaces with no card (messaging, scripted dispatch), managed targets return a connect_url per app for the user to open, and an MCP target runs at once: authorize and an OAuth install return the authorization URL, other installs and enable report the outcome, and a missing credential comes back as failed naming the variable to set. It can’t disconnect, remove, or revoke an account — the user does that.

One thing to know: the deadline for a single call is five minutes, fixed by the backend when the call starts — reopening the chat or restarting the desktop never extends it. And the tool only appears when the Nous Portal has enabled connectors for the signed-in account (the managed_tools claim on its token), so other sessions won’t see it.

A Quick Tour of the Tool Registry

Curious how big the toolbox actually is? The current registry holds roughly 85 tools. A few highlights: 4 browser tools (browser_exec, browser_cdp, browser_dialog, browser_vault); 4 file tools; 2 terminal tools (terminal, process_manage); 11 desktop-GUI tools (read_terminal, close_terminal, desktop_preview, drive_preview, annotate_preview, read_window_below, focus_pane, react_to_message, gui_tour, show_tip, set_theme — desktop-app sessions only); 2 web tools; 5 Feishu tools; 5 Yuanbao tools; 14 kanban tools (registered when the kanban dispatcher spawns the agent); 1 project tool (desktop_project, for desktop/GUI sessions); 2 Discord tools; and 3 video tools (video_generate, xai_video_edit, xai_video_extend). Alongside those sit a handful of standalone tools like memory, clarify, delegate_task, execute_code, cronjob_manage, session_search, skill_view/skill_manage/skills_list, text_to_speech, image_generate, vision_analyze, video_analyze, todo_list, computer_use, and x_search.

Two of the four browser tools are the ones you’ll touch most: browser_exec and browser_vault. They drive whichever browser session is current — the Chromium Hermes launched itself, a cloud browser, or the one attached with /browser connect. browser_exec runs Python with pre-imported helpers (new_tab, goto_url, wait_for_load, page_info, js, fill_input, click_at_xy, capture_screenshot, cdp, ensure_real_tab) against a real browser; browser state persists across calls while Python variables do not, session isolates parallel tasks, timeout_s defaults to 300 (max 1800), and it needs the terminal toolset. browser_vault uses saved logins, passwords, cards, addresses and one-time codes on the current page without letting the secrets into the conversation — actions list, fill, save_login, enter_code, unlock. browser_cdp and browser_dialog are offered only while a CDP endpoint is configured (/browser connect, BROWSER_CDP_URL or browser.cdp_url) and act on that browser; launched and cloud sessions don’t bring them.

Heads up: some tools that used to be built in now live in the plugin catalog. The Honcho tools (honcho_profile, honcho_search, honcho_context, honcho_reasoning, honcho_conclude) moved to the Honcho memory provider plugin — install it with hermes plugins install honcho. The Home Assistant tools (ha_list_entities, ha_get_state, ha_list_services, ha_call_service, toolset homeassistant) moved to the homeassistant catalog plugin — install it with hermes plugins install homeassistant. And the Spotify tools (spotify_playback, spotify_devices, spotify_queue, spotify_search, spotify_playlists, spotify_albums, spotify_library, toolset spotify) are no longer built-in either: they come from the spotify catalog plugin (hermes plugins install spotify, then hermes spotify login).

Two more toolsets are worth knowing about, because they only show up in the desktop app. The catalog toolset is enabled for sessions whose source is the desktop app, whichever backend it’s connected to — CLI, TUI, hermes -z, cron, kanban, and messaging sessions never get it, even when a config list names it, and all does not include it. Remove it with agent.disabled_toolsets: [catalog]. Its tool, manage_catalog, is deferred behind tool_search by default: search lists catalog plugins and hub skills matching query (optionally one kind) with id, kind, display, tier, platforms, and installed (present in this chat’s profile) and changes nothing; install takes items: [{kind, id}] and shows one approval card with a row per item (Install, Advanced, Skip), where an unknown id or a plugin this OS cannot run is drawn failed with the reason. An approved row installs into this chat’s profile (or the profile chosen under Advanced) at the catalog’s reviewed commit, with the same kill list, security scan, and live activation as the Plugins tab, so the plugin’s MCP tools and skills are usable in that profile’s open chats at once. The result lists each row as connected (with tools and skill), skipped, failed (with detail), or not_connected; a failed row ends the wait like an installed or skipped one, and an install turns on a catalog plugin that is on disk but not enabled. The model cannot pass a source, commit, profile, or setting. Anywhere else the call returns the hermes plugins install / hermes skills install command to run instead. The setup toolset is enabled by the desktop setup profile’s own config (platform_toolsets.cli), and again only desktop sessions get its tools; all does not include it and hermes tools does not list it. Its tool, setup_choose, shows one card in the setup chat: kind is question, accent, theme, layout, connectors, plugins, tour, or fork, and question is the card’s heading. options is required — up to 12 {id, label, detail?} rows with unique ids replace the app’s own list, and [] shows the app’s list for a picker or asks for free text for kind question.

Two of the standalone tools deserve a closer look. cronjob_manage is the unified scheduled-task manager: use action="create", "list", "update", "pause", "resume", "run", or "remove" to manage jobs, with support for skill-backed jobs that carry one or more attached skills (skills=[] on update clears them). Cron runs happen in fresh sessions with no current-chat context. And desktop_project bundles the three Project verbs into one action enum: create makes a desktop Project (a named workspace) and switches this chat into it — pass path to anchor it to a repo or folder; list shows the desktop Projects and which one is active; switch moves this chat into an existing Project (by name, slug, or id), moving the session workspace to the project’s primary folder.

One more caveat for the file tools: for local files, a full unredacted read (including all pages of the same file version), a successful write_file, or your own patch of a file you had read in full supplies a whole-file baseline. Reading a smaller region afterward does not discard that baseline while the bytes remain unchanged. A file changed by another writer, an unread file, a file patched without a full read, or a view with hidden/redacted or clamped content still needs a full current read before replacement; patch remains available for targeted edits. Writes made through terminal commands or execute_code do not establish a write_file baseline.

Asking the User: The clarify Tool

Sometimes the agent needs to check in before it acts. That’s what clarify is for: it asks the user one or more questions when the agent needs clarification, feedback, or a decision before proceeding. Every call passes questions, an array of 1–5 entries (a single question is a one-entry array). Each question supports three modes:

1. Single-select multiple choice — up to 4 choices; the user picks one or types their own answer via a 5th ‘Other’ option.
2. Multi-select multiple choice — multi_select=true renders checkboxes and returns a list of selected choices.
3. Open-ended — no choices; the user types a free-form response.

Choices are ordered best-first, so the first one is labelled (Recommended) on every surface and is the default highlight; the label is presentation only and is stripped from the answer the agent reads. On the classic CLI multi-select uses Space-to-toggle checkboxes; on messaging platforms without native checkbox UIs the user replies with comma/space-separated numbers (e.g. “1, 3”) or the option text.

Because questions holds up to 5 independent questions (each with its own choices and multi_select), the agent can batch several clarification needs into a single prompt instead of asking sequentially. The result is {responses, outcome}: a responses array in the same order, each entry with the question text, choices_offered, a status (answered, skipped or unanswered) and user_response (null unless answered). outcome is submitted, cancelled, timed_out or undelivered.

How it looks depends on where you are:

• Desktop shows every question on one card. Picks and typed answers stage locally, and one Confirm and continue button (enabled once at least one question has an answer) submits the whole batch; blank questions are skipped. Staged answers stay editable until that confirm. Skip cancels the whole batch.
• TUI and CLI show a compact status list (✓ answered / ▸ active / · pending) with only the active question’s choices expanded. Enter locks the active answer and jumps to the next unanswered question; Tab moves between questions to answer in any order; an empty submit skips that question; Esc cancels the batch.
• Messaging platforms (Telegram, Discord, …) ask the questions one at a time, one card per question. Reply skip to skip one question. If the user stops responding, the remaining questions are not sent.

If the prompt times out part-way, answers the user already locked are kept: the tool result carries them with "outcome": "timed_out" and marks the rest "status": "unanswered", so the agent can distinguish a deliberate skip from an absent user. On messaging platforms the result also carries a "notice" saying why the wait ended ([user did not respond within Nm], or [clarify prompt could not be delivered] when the platform rejected the card — Hermes first retries the question as a plain numbered-list message, and only reports this when that fails too; [clarify prompt could not be delivered: no chat surface] when the run has no chat to prompt in), so an undelivered prompt is never reported as user inactivity.

Moving Machines?

Already running Hermes elsewhere? You don’t need to rebuild from scratch:

• Full backup restore: hermes import
• Single agent transfer: hermes profile import

Just remember: profile exports exclude credentials by design, so for a true backup, use hermes backup.

A Note for the Adventurous

If you’re a developer who wants to contribute or run from a specific branch, you can clone the repo and install from source. Check out the Development Setup section in our Contributing guide for details.

And for the security-conscious? Running Hermes as a dedicated unprivileged user is fully supported. The only step that needs root is Playwright’s --with-deps for browser automation.

Your Hands Are Ready

That’s it. Your AI agent now has hands — tools for searching, browsing, generating images, and more. The installation is the easy part. The fun part is figuring out what you’ll build with them.

Next time, we’ll dive into what those tools can actually do. Until then, happy chatting!