How I Use Hermes Agent as a Private Software Engineering Worker

Hermes Agent is an open-source agent framework from Nous Research. It can run in a terminal, a desktop application, an IDE, or through messaging platforms such as Telegram. It can also use tools, remember durable preferences, load reusable skills, delegate bounded work, and resume earlier sessions.

Those features are useful, but they are not an operating model by themselves. I wanted something more specific: a private software engineering worker I could direct from Telegram without giving up planning, review, verification, or control over merges.

This article explains the workflow I built on top of Hermes. It is not a copy of my private configuration and it is not a replacement for the official Hermes documentation. The commands and feature details below are grounded in that documentation; the engineering controls are my own application of them.

Start with one working conversation

The official quickstart recommends getting a normal chat working before enabling gateways, automation, skills, or complex routing. That sequence is deliberately boring, which is exactly why it is useful.

Install the command-line application, run the setup wizard, choose a model, and check the installation:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

hermes setup
hermes model
hermes doctor

Then start Hermes and ask it to perform a small, verifiable task in a disposable or low-risk directory. For example, ask it to summarize a repository and identify its entry point. If the basic conversation, model, and file tools are not reliable, adding Telegram or autonomous routines only makes the failure harder to diagnose.

Hermes is provider-agnostic, but the provider choice is less important than validating three things early:

1. The selected model has enough context for multi-step tool use.
2. The model can call the tools you intend to enable.
3. A real request completes successfully before you add more layers.

Keep settings and secrets separate

Hermes separates ordinary settings from credentials:

~/.hermes/config.yaml   Non-secret settings
~/.hermes/.env          API keys and tokens

The configuration guide recommends using the CLI because it routes values to the correct place and avoids malformed YAML:

hermes config get approvals.mode
hermes config set approvals.mode smart
hermes config set security.redact_secrets true
hermes config check

I do not publish or distribute a complete config.yaml. A real configuration can contain machine-specific paths, enabled toolsets, provider choices, platform routing, and assumptions about the surrounding security boundary. Copying it verbatim would be both unsafe and misleading.

A better pattern is to document one intentional setting at a time, explain why it exists, and leave credentials to the setup wizard or environment-specific secret storage.

Add Telegram as an operator interface

Hermes can expose the same agent through several messaging platforms. I use Telegram as the operator interface because it gives me a convenient place to submit work, steer an active run, receive verification summaries, and make explicit decisions from another device.

The official Telegram guide covers creating a bot with BotFather, configuring allowed users, and starting the gateway. The shortest supported setup path is:

hermes gateway setup
hermes gateway

The bot token and allowed-user information are credentials and authorization data. They belong in secret storage and should never appear in a public article, repository, screenshot, or copied configuration example.

Connecting Telegram does not mean every conversation should share one undifferentiated context. I assign a reviewed project route to each project topic. A route identifies the expected repository, base branch, and project-management area. This routing layer is part of my workflow, not a claim about a built-in Hermes project-management standard.

The result is a simple operator experience: write in the relevant project topic, and the worker begins from the expected project rather than guessing from stale conversation or nearby files.

Give the agent the right kind of context

A dependable agent needs more than a long prompt. I split context by purpose.

Repository instructions

A repository-level AGENTS.md explains how that codebase should be changed and verified. It can name architectural boundaries, test commands, conventions, and files that require special care. These instructions travel with the source and can be reviewed like code.

Hermes supports project context files, including AGENTS.md, so the relevant instructions can be loaded when work begins in that repository.

Skills

Skills hold reusable procedures that should load only when a task needs them. Hermes uses progressive disclosure: the agent sees a compact catalog, then loads the full skill or a specific reference on demand. The skills documentation describes both bundled and agent-managed skills.

I use skills for workflows such as:

• Selecting a registered project safely.
• Planning and delivering repository changes.
• Managing Markdown tasks.
• Resuming interrupted work.
• Applying tool-specific procedures without expanding every prompt.

A skill is useful when the procedure will recur. Temporary task state does not belong in a skill.

Memory

Hermes memory is deliberately bounded. The memory documentation separates durable user preferences from durable environment or workflow facts.

I keep memory compact: preferred planning style, stable content sources, and decisions that would otherwise need to be repeated. Raw logs, transient TODOs, and large project descriptions stay elsewhere.

Sessions

Hermes stores conversations as sessions and supports resuming and searching them. The sessions guide explains continuation, named sessions, and cross-session search.

Sessions are useful evidence, but they are not my only project state. Conversations can be compressed, interrupted, or superseded. Git and task files remain the durable engineering record.

Put approval before mutation

My engineering workflow begins in read-only mode. A new change request follows this sequence:

Request
  → inspect the selected repository
  → propose a proportionate plan
  → receive operator approval
  → create a Markdown task
  → create a task branch
  → implement and verify
  → open a pull request
  → request a fresh merge decision
  → merge and clean up the branch

The planning step is not ceremony. It exposes assumptions before code makes them expensive. It also gives the operator a chance to reject unnecessary dependencies, excessive testing, unsafe changes, or a solution that solves the wrong problem.

Approval is scoped. Permission to implement a repository change does not automatically authorize deployment, infrastructure changes, credential rotation, force pushes, or unrelated external writes.

Keep project state outside the conversation

I use three complementary records:

1. Git records source changes, branches, and merge history.
2. Markdown tasks record the work lifecycle: active, blocked, review, and done.
3. Hermes sessions preserve the conversation and make earlier decisions searchable.

A task file records the intended outcome, scope, acceptance criteria, branch, pull request, progress, blockers, and verification evidence. The task lives on a separate project-management branch so it never needs to be merged into the application source.

This structure makes resumption safer. After an interruption, the worker does not simply trust the last conversational sentence. It reconciles the task, Git branch, working tree, remote branch, and pull request, then continues from the smallest evidenced next step.

Use tools proportionately

Hermes can work with files, terminals, web pages, browsers, images, memory, scheduled jobs, and delegated agents. More tools do not automatically produce a better workflow.

I use direct tools for deterministic work:

• Formatting and linting.
• Type checking.
• Builds and tests.
• Git status and diff inspection.
• Reading pull-request state.

Delegation is reserved for independent work that benefits from a fresh reasoning context. The delegation guide emphasizes that a child agent begins without the parent conversation, so its goal and context must be complete.

A delegated review is supplementary evidence, not the only delivery gate. The parent still runs the repository’s deterministic checks directly and verifies external changes by reading them back.

The same proportionality applies to tests. A static site with no client-side behavior does not need a browser automation framework merely because one is available. The minimum useful suite is often formatting, linting, type checks, a production build, and a focused artifact verifier.

Make the safety boundaries explicit

Hermes has its own security model, including user authorization, dangerous-command approvals, file-write controls, isolation options, credential filtering, and secret redaction.

I keep those product controls enabled, then add workflow-level boundaries:

• Only the configured operator can direct the worker.
• Projects are selected through reviewed routes rather than inferred paths.
• Every repository mutation begins with a visible plan.
• Destructive or unrelated external actions require immediate confirmation.
• Application changes use task branches and pull requests.
• Merge requires a fresh decision for the current reviewed head.
• Deployment is a separate operation and is not implied by merging code.
• Completion claims require read-back evidence, not a successful command alone.

These controls are intentionally redundant. Agent safety is stronger when identity, scope, filesystem permissions, Git workflow, tool behavior, and human approval reinforce one another.

What this setup gets right—and what it does not

This setup gives me a software engineering worker that is reachable from Telegram, remembers stable preferences, follows repository-specific instructions, and can carry work from planning to a verified pull request.

It does not make unattended autonomy universally safe. It does not remove the need for code review, narrowly scoped credentials, backups, or environment isolation. It also does not make every project suitable for the same verification strategy.

The main lesson is that useful autonomy comes from clear boundaries and recoverable state, not from removing every checkpoint.

If you are building a similar setup, start with one working CLI conversation. Add only the tools you need. Put project rules next to the source. Keep secrets out of examples. Make mutation and merge approvals explicit. Then use sessions, skills, memory, and messaging to improve continuity without turning chat history into your only source of truth.

Hermes changes quickly, so verify commands and configuration details against the current official documentation before applying them to your environment.