Hermes Agent

Hermes Agent is an open-source agent runtime and CLI published by Nous Research. Its model-facing file family is four dedicated tools, read_file, write_file, patch, and search_files, with terminal and process for shell work. Every file tool returns a JSON string, and every file operation runs as a quoted shell command through the active terminal backend, so the same tools operate on local, Docker, SSH, and hosted sandbox environments. The read tool repairs unicode-equivalent file names and tells the model, refuses device files and FIFOs by type, extracts documents to text, and redacts secrets before content reaches the model.

Source

Tool inventory

There is no dedicated list tool. search_files with target="files" and pattern * is the documented listing path, and the terminal description tells the model to use it instead of ls. Two Desktop-only tools, read_terminal and close_terminal, sit in the desktop_ui toolset that the GUI gateway enables for desktop sessions; they read and close the Hermes Desktop terminal pane and are outside this page. execute_code and MCP tools are also outside it. The registry omits any tool whose availability check fails. Plugin hooks can change arguments before path policy runs (pre_tool_call) and replace the final result string (transform_tool_result); the contracts below are the core ones.

Read

Signature

read_file({ path: string, offset?: integer, limit?: integer })

path accepts an absolute, relative, or ~/ path. offset is one-based, with a schema minimum of 1 and a default of 1. limit defaults to 2000 with a schema maximum of 2000. normalize_read_pagination clamps offset to at least 1 and limit to between 1 and tool_output.max_lines (default 2000); a limit above the maximum is clamped, not rejected. The registry handler passes 500 when the limit key is absent from the call, while the schema declares 2000; a provider that fills schema defaults sends 2000.

Description

read_file: 1058 characters, 1062 bytes, 1 line, approximately 224 tokens.

read_file (1058 characters)

Read a text file with line numbers and pagination. Use this instead of cat/head/tail in terminal. Output format: 'LINE_NUM|CONTENT'. Suggests similar filenames if not found. Use offset and limit for large files. Reads exceeding ~100K characters are truncated on a line boundary and return a next_offset; continue with offset to read the rest. Jupyter notebooks (.ipynb), Word documents (.docx), and Excel workbooks (.xlsx) are auto-extracted to readable text; PDF, legacy Office (.doc/.ppt/.xls), OpenDocument, RTF, and EPUB convert too when the optional anydoc converter is available (auto-installed on first use where installs are permitted). PDF conversion reads the text layer only: scanned/image pages yield no text, and when many pages come back empty the output ends with an EXTRACTION COVERAGE WARNING listing the affected pages — follow its instructions (render pages with pdftoppm and inspect via vision_analyze, or OCR) instead of treating the extraction as complete. NOTE: Cannot read images or other binary files — use vision_analyze for images.

Path handling

Relative paths resolve, in order, against the session's recorded cwd, a registered task or session override, an absolute TERMINAL_CWD, then the process working directory. The sentinel values ., auto, and cwd count as unconfigured. ~ expands through the profile home. Host paths go through Path.resolve(), so symlinks are followed before any guard runs; container backends normalise lexically without host dereference. There is no workspace containment: absolute paths and .. are accepted by read, write, replace, and search. Only V4A patch headers reject ...

When the size probe fails, _unicode_variant_match lists the directory and compares entries after NFC normalisation and replacement of U+202F, U+00A0, U+2019, and U+2018 with plain characters. Exactly one equivalent entry is read in place of the request, and the result carries a note in hint:

Note: '<path>' not found byte-for-byte; resolved to the unicode-equivalent file '<variant>' (invisible encoding difference: NFC/NFD or special space/quote characters).

With zero or several equivalents the tool falls through to _suggest_similar_files. That scores the first 50 directory entries: same stem with a different extension scores 90, prefix in either direction 70, substring 60, reverse substring 40, same extension with 40 percent character overlap 30, and a difflib ratio of 0.8 or more scores 50. The top five become similar_files beside "error": "File not found: <path>". A per-task negative cache with a 60 second TTL returns the same JSON on a repeat miss without listing the directory again; a write to the path or any non-read tool call clears it. Pi resolves the same variants without telling the model; see Pi.

Permissions

The source states that the denylist is not a security boundary: the terminal runs as the same OS user and can cat any of these files.

Binary and conversion

Text writes to opaque document containers are refused, and an existing PDF cannot be overwritten with the text tools; see Edit, Whole-file write.

Limits

The line, per-line, and byte limits are read from tool_output in config.yaml; invalid values fall back to the defaults and the values are cached for the process.

Output

{"content": "1|import { x } from \"./x\"\n2|export const y = x", "total_lines": 2, "file_size": 44, "truncated": false, "is_binary": false, "is_image": false}

The example is reconstructed from the format code. An empty file returns content: "", total_lines: 0, and hint: "File is empty (0 bytes).". A final line without a newline is preserved: the shell cut adds one and the tool probes the last byte to remove it.

Notable

• Repeat-read guard: the same resolved path, offset, and limit with an unchanged mtime returns status: "unchanged" with the message File unchanged since last read. The content from the earlier read_file result in this conversation is still current — refer to that instead of re-reading. A second stub for the same key is a hard block. Four consecutive real reads of one region block with BLOCKED: You have read this exact file region <n> times in a row. ...; the third adds _warning. Any tool other than read_file and search_files resets the counters, and context compression clears the dedup cache.
• redact_sensitive_text runs over every returned page after the budget check. No content is injected after the read.
• Each read records an mtime stamp per task and a cross-agent read record with a partial flag when offset is above 1 or the read was truncated. The write tools use both for stale warnings.
• The read runs as sed -n '<a>,<b>p' <path> | cut -b1-<n> then wc -l through the backend, so a shell with sed, cut, wc, head, ls, and base64 is assumed. The shell clamp keeps a single 400 MB line from crossing the transport.
• Cancellation: None. The read has no abort signal; the backend exec timeout bounds it.
• Batch planning treats reads and searches as path readers and writes and patches as path writers; reader overlap runs in parallel and any writer overlap forms an ordered barrier. read_file does not take the writer's path lock, so a read from another task can overlap a write outside one planned batch.

Edit

Signature

write_file({ path: string, content: string, cross_profile?: boolean })
patch({ mode: "replace" | "patch", path?: string, old_string?: string, new_string?: string, replace_all?: boolean, patch?: string, cross_profile?: boolean })

patch has one required field, mode, with default replace. Replace mode needs path, old_string, and new_string; replace_all defaults to false. Patch mode needs patch, one V4A string with *** Begin Patch, headers *** Update File:, *** Add File:, *** Delete File:, or *** Move File: <src> -> <dst>, @@ context hunks, and *** End Patch. cross_profile opts out of a soft guard on writes into another Hermes profile's skills, plugins, cron, or memories directory. There is no delete tool outside V4A.

Description

write_file: 512 characters, 516 bytes, 1 line, approximately 108 tokens. patch: 483 characters, 483 bytes, 4 lines, approximately 107 tokens.

write_file (512 characters)

Write content to a file, completely replacing existing content. Use this instead of echo/cat heredoc in terminal. Creates parent directories automatically. OVERWRITES the entire file — use 'patch' for targeted edits. Auto-runs syntax checks on .py/.json/.yaml/.toml and other linted languages; only NEW errors introduced by this write are surfaced (pre-existing errors are filtered out). The result's verified:true means the on-disk content hash was confirmed — do NOT re-read the file to check the write landed.

patch (483 characters)

Targeted find-and-replace edits in files. Use this instead of sed/awk in terminal. Uses fuzzy matching (9 strategies) so minor whitespace/indentation differences won't break it. Returns a unified diff. Auto-runs syntax checks after editing.

REPLACE MODE (mode='replace', default): find a unique string and replace it. REQUIRED PARAMETERS: mode, path, old_string, new_string.
PATCH MODE (mode='patch'): apply V4A multi-file patches for bulk changes. REQUIRED PARAMETERS: mode, patch.

Whole-file write

write_file runs the sensitive-path, binary-document, protected-instruction, SSH-config approval, cross-profile, and display-text checks, then takes a per-path lock and hands the content to ShellFileOperations.write_file. Content travels over stdin, never in the command line. Before any byte touches disk, JSON, YAML, and TOML candidates pass a fail-closed in-process syntax gate: Refusing to write '<path>': candidate content fails <ext> syntax validation (<reason>). The file was NOT created or modified. Fix the content and retry. A lone surrogate in the content is refused the same way. Python and other linted languages keep a post-write lint delta instead.

The write is one shell script: resolve a symlink target so the link is edited rather than replaced, mkdir -p the parent, mktemp in the same directory, copy the existing mode with stat and chmod on a best-effort basis, cat stdin into the temp file, give a new file chmod =rw so the umask applies, then mv -f over the target. A trap removes the temp file on any failure. CRLF is preserved when the existing file uses it, and a UTF-8 BOM that the read layer hid is restored.

After the rename, sha256sum output is compared with the intended bytes. A mismatch is a hard error: Post-write verification failed for <path>: on-disk content hash differs from the intended write. The write did not persist correctly — re-read the file and retry. A backend without a working hash command leaves verified unset. Syntax delta and, for local backends inside a Git workspace, LSP diagnostics follow in separate fields.

Matching

Replace mode reads the whole file with cat, strips a leading BOM, and calls fuzzy_find_and_replace. Nine strategies run in order: exact, line-trimmed, whitespace-normalised, indentation-flexible, escape-normalised, trimmed-boundary, unicode-normalised, block-anchor, and context-aware. The first strategy that finds a match wins. The model is not told which strategy matched. Without replace_all, more than one match is an error that lists the locations. With replace_all, a similarity strategy that finds several matches is refused so approximate blocks are not rewritten together. When the matched strategy is not exact, an escape-drift guard refuses a new_string whose backslash escapes do not appear in the matched region. An empty or whitespace-only old_string and identical strings are errors.

An edit that is already present returns success: true with no_change: true and note: File already contains the target text — the edit appears to be already applied to <path>. No write performed; do not re-send this patch. A miss can carry a Did you mean one of these sections? snippet. After the third consecutive miss on one path the wrapper adds _hint: This is failure #<n> patching '<path>'. Stop retrying with variations of the same old_string. Either: (1) re-read the file fresh to verify current content, (2) use a longer / more unique old_string with surrounding context lines, or (3) use write_file to replace the entire file if the targeted region is hard to anchor.

Multi-file patch

Present as mode="patch". The wrapper extracts every header path, rejects .. components, runs the path policy on each, rewrites host paths in the headers to the resolved absolute targets, sorts them, and takes one lock per path in stable order. apply_v4a_patch validates every operation before any write: Patch validation failed (no files were modified): followed by one bullet per problem. Apply then runs add, delete, move, and update in order. There is no rollback. A later failure returns the diffs and file lists already produced with Apply phase failed (state may be inconsistent — run `git diff` to assess): and one bullet per failure.

Verification and mutation state

A relative path that resolves outside the active workspace root gets a lower-priority warning that names both paths and asks for an absolute path; it does not block.

Output

Notable

• Writes to /etc/, /boot/, /usr/lib/systemd/, the Docker sockets, and the Hermes config file are refused: Refusing to write to sensitive system path: <path> and Refusing to write to Hermes config file: <path>.
• Writes to AGENTS.md, CLAUDE.md, SOUL.md, .cursorrules, and immediate children of project .hermes directories always ask the user, ignore yolo and persistent allowlists, and fail closed without a human channel: BLOCKED: write to protected agent-instruction file(s) (<targets>) <reason> The user has NOT consented to this write. ....
• Opaque document containers (.doc, .docx, .xls, .xlsx, .ppt, .pptx, .odt, .ods, .odp) are never written as text; an existing PDF is not overwritten; a new .pdf path is allowed.
• Content dominated by N| numbered lines, or by the dedup status message, is refused before the write.
• The patch description promises fuzzy matching and the runtime delivers it. No notebook editor, undo tool, or checkpoint tool exists in this family.

Shell

Signature

terminal({ command: string, background?: boolean, timeout?: integer, workdir?: string, pty?: boolean, notify_on_complete?: boolean, watch_patterns?: string[] })
process({ action: "list" | "poll" | "log" | "wait" | "kill" | "write" | "submit" | "close", session_id?: string, data?: string, timeout?: integer, offset?: integer, limit?: integer })

timeout is in seconds with a schema minimum of 1; the foreground default is 180 from TERMINAL_TIMEOUT and the foreground maximum is 600 from TERMINAL_MAX_FOREGROUND_TIMEOUT. A non-positive value is rejected, and a foreground timeout above the maximum is rejected with a pointer to background=true. workdir must be absolute. pty works on local and SSH backends only. notify_on_complete and watch_patterns are mutually exclusive; when both are set the patterns are dropped. process needs session_id for every action except list, and a unique ID prefix is accepted. The Python terminal_tool function has a force argument that is absent from the model schema.

Description

terminal: 1744 characters, 1750 bytes, 11 lines, approximately 385 tokens. process: 358 characters, 358 bytes, 1 line, approximately 86 tokens.

terminal (1744 characters)

Execute shell commands on a Linux environment. Filesystem, current working directory, and exported environment variables persist between calls.

Do NOT use cat/head/tail (use read_file), grep/rg/find/ls (use search_files), sed/awk (use patch), or echo/heredoc file creation (use write_file). Reserve terminal for: builds, installs, git, processes, scripts, network, package managers, and anything that needs a shell.
NEVER pipe a build/test command through tail/head/cat to shorten output (e.g. `cargo build | tail -20`): output is auto-truncated with the full text saved to a file, and the pipe makes exit_code report the LAST pipeline command's status (tail's 0), masking real failures. Run the command bare; the same applies to `cmd || echo failed`, which also masks the exit code.
Environment state persists: activate a virtualenv or export variables once per session, not before every command.

Foreground (default): returns INSTANTLY when the command finishes, even with a high timeout — set timeout generously for long builds.
Background: set background=true (returns a session_id). Pair with notify_on_complete=true for bounded tasks; leave silent only for servers/daemons that never exit. Never use nohup/setsid/trailing '&' — use background=true so Hermes tracks the process. After starting a server, verify readiness with a health check, then act in a separate call; no blind sleep loops. Manage with process(action="poll"/"wait").
Working directory: use 'workdir' for per-command cwd. When a command changes the session cwd (cd, pushd), the result includes a "cwd" field — trust it instead of prefixing every command with 'cd'.
PTY: set pty=true for interactive CLIs (they hang without it). Pipe git output to cat if it might page.

process (358 characters)

Manage background processes started with terminal(background=true). Actions: 'list' (show all), 'poll' (check status + new output), 'log' (full output with pagination), 'wait' (block until done or timeout), 'kill' (terminate), 'write' (send raw stdin data without newline), 'submit' (send data + Enter, for answering prompts), 'close' (close stdin/send EOF).

Working directory and environment

The backend comes from TERMINAL_ENV: local by default, or docker, singularity, modal, daytona, ssh, or vercel_sandbox. Top-level and delegated tasks share one environment unless a task carries an isolation override. LocalEnvironment spawns a fresh bash for every call, restores a session snapshot of exported variables before each command, and re-reads the cwd from a file after each command, which is how the description's persistence claim is met. A cd or pushd that changes the session cwd adds a cwd field to the result. workdir sets a per-command cwd; it is validated for disallowed characters and remapped when it cannot exist inside a sandbox. Login shell: Not surveyed.

Process lifecycle

A foreground command that wraps itself in nohup, setsid, disown, or a trailing &, or that looks like a long-lived server or watcher, is returned unrun with status: "error" and guidance to resend it with background=true.

Output limits

A plugin transform_terminal_output hook can replace the bounded output before the final truncation, ANSI removal, and redaction.

Sandbox

Depends on the backend. local is direct host execution as the Hermes process account with no OS sandbox, seccomp profile, or network restriction. Docker, Singularity, Modal, Daytona, SSH, and Vercel Sandbox run the command inside their own environment, and the file tools run inside the same namespace because they issue shell commands through the same backend. The isolation those services provide was not inspected.

Approval

Before execution Hermes validates workdir, applies gateway-lifecycle and Windows self-repository hard blocks where relevant, then runs the Tirith scanner and a dangerous-command pattern list. Tirith is an external binary whose exit code is the verdict (allow, block, warn) and which is downloaded with checksum verification when absent. The pattern list covers recursive and root deletes, mkfs, dd to a block device, fork bombs, kill -1, and Windows destructive and encoded commands. A flagged command returns status: "pending_approval" with command, description, pattern_key, and allow_permanent, or status: "blocked" with Command denied: <description>. Use the approval prompt to allow it, or rephrase the command. An approved run records Command required approval (<description>) and was approved by the user. in approval. Approval scopes are once, session, or always; --yolo, the gateway /yolo toggle, and approvals.mode: off bypass the prompt, and the CLI yolo flag is frozen at import so a skill cannot flip it mid-process.

Notable

• A non-zero exit is a normal result with error: null and the real exit_code. Hermes interprets known codes, for example a no-match grep, in exit_code_meaning.
• Infrastructure connection failures return a degraded result with a reason and retry hint under the default terminal.degraded_mode: warn.
• Background output goes through the same secret redaction before it reaches the model.
• The description calls the environment persistent; the local backend achieves that with a snapshot and a cwd file around spawn-per-call processes.

Search and listing

Tools

The result is JSON with total_count, then matches, files, or counts, plus truncated, limit_reason, and warning. Five or more content matches render as one matches_text block with matches_format set to path-grouped: each file path on its own line, followed by indented '<line>: <content>' rows for matches in that file; fewer arrive as an array of path, line, and content objects. A truncated result appends [Hint: Results truncated. Use offset=<n> to see more, or narrow with a more specific pattern or file_glob.] after the JSON. A zero-result content search runs bounded probes for case-insensitive, hidden or ignored, and literal readings. A path that looks like several paths is split and the missing roots are reported. Result paths that hit the read denylist are removed and counted in _omitted; match content is secret-redacted. Three identical searches add _warning; the fourth is blocked. Pagination arguments are part of the key, so paging does not trip the guard.

Description

search_files: 435 characters, 437 bytes, 5 lines, approximately 96 tokens.

search_files (435 characters)

Search file contents or find files by name. Use this instead of grep/rg/find/ls in terminal. Ripgrep-backed, faster than shell equivalents.

Content search (target='content'): Regex search inside files. Output modes: full matches with line numbers, file paths only, or match counts.

File search (target='files'): Find files by glob pattern (e.g., '*.py', '*config*'). Also use this instead of ls — results sorted by modification time.

Errors

Every file tool returns a JSON string and the registry passes it to the model as ordinary result text; there is no error flag at the transport level. Command failures keep their real exit code with error: null. The table runs past the outline's fifteen-row guide because each condition has its own string.