read_file as a Safe Operation

+15 Mana ✨
Hermes File Tools Reference(DOCUMENTATION)

Introduction

The read_file tool is the lowest-risk way for Hermes to interact with your filesystem. It reads a text file, returns the contents with line numbers and optional pagination, and changes nothing. Reading is the bottom rung of the risk ladder, and it is where good agent workflows usually start.

Key Concepts

  • Read operation: A tool call that returns information without modifying any state on disk, in the database, or in the world.
  • Idempotent: An operation you can run repeatedly with the same result. Reads are idempotent; writes and executions usually are not.
  • Trust boundary: The point at which an action could meaningfully change something. Reads do not cross it. Writes and executes do.

Real World Context

When you start a debugging session with Hermes, the agent almost always opens with reads: read_file('src/index.ts'), read_file('package.json'), maybe search_files for a symbol. None of those calls can harm your project, even if the agent is confused or wrong about what to do next. That property is why reads are the default starting point: cheap to do, impossible to regret.

Deep Dive

read_file does three things you should be comfortable with:

  1. Reads with line numbers. Output is annotated like 12: const x = 5;, which makes it easy for the agent to refer to specific lines in follow-up tool calls (especially patch).
  2. Paginates large files. You can pass offset and limit to read a slice. This avoids dumping a 10,000-line file into context.
  3. Refuses non-text files. Binary files (images, executables) are not handled; for images you use vision_analyze, for video video_analyze.

Because read_file cannot mutate anything, it does not trigger the approval system (Section 3.5). The agent uses it freely.

A few other tools are also pure reads:

  • search_files: ripgrep-backed search across file contents and names. Returns matches and locations.
  • web_search: searches the web. Returns titles, URLs, descriptions.
  • web_extract: converts a URL to markdown. Reads a remote page; does not modify it.
  • vision_analyze, video_analyze: read an image or video and describe it.

All of these are at the bottom of the risk gradient. They are the agent's safe scaffolding: gather information first, then decide whether to mutate anything.

Common Pitfalls

  1. Reading the wrong file repeatedly because of stale context: After many turns, the agent may forget what it has already read. If you see a redundant read_file of the same path, your context is getting noisy.
  2. Confusing read with cat: cat in the terminal also reads, but going through terminal invokes a higher-risk path and loses line numbers. read_file is purpose-built and should be preferred.

Best Practices

  1. Let the agent read first: When asking Hermes to change something, do not pre-summarize the file. Let it read, then act. The cost is small and the precision is much higher.
  2. Prefer dedicated read tools over terminal: read_file over cat, search_files over grep. The dedicated tools are safer, paginated, and easier to audit.

Summary

  • read_file is the canonical safe operation: returns content, changes nothing.
  • Read tools are idempotent and do not trigger approval gates.
  • Other read tools include search_files, web_search, web_extract, vision_analyze, video_analyze.
  • Good agent workflows start with reads and only escalate to writes or executes when needed.

Code Examples

yaml
# A typical first-step read in an agent session
tool_call:
  name: read_file
  arguments:
    path: src/auth/login.ts
    offset: 1
    limit: 100

# Returned content arrives with line numbers:
#  1: import { compare } from 'bcrypt';
#  2: import { signJwt } from '../jwt';
#  ...
✓ Completed