How Hermes's agents work: one agreement, one launcher, one environment.
Every coding worker, reviewer and study-guide author is a profile of the Hermes agent harness. A coding task is a card on Hermes's kanban board. The worker that takes it gets a container of its own and a branch of its own, and owns the codebase while it works. This repository holds everything that makes that true on a host.
| Path | What it is |
|---|---|
working-agreement.md |
The agreement every agent reads, in every repository. |
profiles/<name>/ |
A Hermes profile: intro.md opens its prompt, profile.json is its configuration. |
workbench/Containerfile |
The image a profile's shell, file and code tools run in. |
setup.sh |
Puts all of this on a host. |
bin/ |
Commands for work in any repository: committer, agent-trash, agent-session-recover. |
skills/ |
Skills for Claude Code and Codex sessions in any repository. |
cloud/ |
The Claude app's cloud environments: common.sh and a setup script per repository (<name>.sh), app-script, which prints the loader the app keeps for one, and github-sync, which keeps a repository's GitHub copy up to date without deleting the branches cloud sessions push. |
-
A card. An agent, or Hermes himself, writes the task: the outcome, why it matters, and what done means. It goes on the board assigned to
worker, with a worktree workspace on the repository's clean clone:hermes kanban create "<title>" --body-file task.md \ --assignee worker --workspace worktree:$HOME/workbench/<repo>
Inside the harness the same thing is
kanban_createwith assigneeworker, workspace kindworktreeand workspace path/home/hermes/workbench/<repo>. -
A worker. The board's dispatcher, which runs inside the Hermes gateway, starts
hermes -p worker chat -q "work kanban task <id>". Kanban makes a git worktree at~/workbench/<repo>/.worktrees/<task-id>on branchwt/<task-id>. -
A workbench. The agent runs on the host, but its shell, file and code tools run in a rootless podman container made from
localhost/workbench:latestfor this one task. The container sees~/workbenchand a shared package cache. It has no keys, no tokens, no SSH, no~/.hermesand none of Hermes's own working copies, so the worker cannot push or reach an account. Inside, the worker can install, build and rebuild whatever the task needs. -
A review. The worker commits on its branch and hands the card to the
reviewerprofile. The dispatcher starts the reviewer in its own container. It sees~/workbenchthrough a layer of its own, so it builds and tests the branch in place and nothing it writes reaches the worker's files. The reviewer reads the branch, runs what matters, and gives one verdict: it approves and the card is done, it sends the card back to the worker with each defect named, or it blocks the card with a question for Hermes. -
A merge. The agent that made the card reads the diff once the card is done, merges the branch and pushes to
origin, Hermes's own Git server.A card that builds on another card's work waits for that merge, not for the other card's
done: the board starts a--parentchild the minute its parent is done, on a worktree cut from amainthat does not hold the parent's work yet. Park such a card withhermes kanban schedule <id> "<reason>"when you make it, and release it withhermes kanban unblock <id>after the merge.
Each profile runs on the one model its profile.json names. There is no
fallback chain: a run that cannot reach its model fails with the provider's
own error.
An Ashwren study guide is written in rounds on the host sim. Ashwren's
tools/run-guide.sh starts each round as hermes -p author --oneshot and
names the guide's work directory as the container's one volume, at
/workspace. The round sees that folder and nothing else of the host, and has
no network. The profile's settings leave terminal.docker_volumes out on
purpose: a volume set in the profile would replace the one the launch names.
Hermes can also give work to Claude Code in the cloud: in the Claude desktop
app, Code, a new session in the cloud environment of the repository. The
environments are Red Acre, Kestrel, Marquee, Hearth, Nomad
and Ashwren, each on its hermes-os/<name> repository. The session runs on
a VM of Anthropic's, clones the repository from GitHub and pushes its work to a
claude/... branch there. It holds no keys and cannot reach the Git server.
Each environment, as set in the app:
- Network access: Limited, with Allow package managers (the default). The setup scripts' downloads are on that list; a test checks their hosts.
- Setup script: the loader
cloud/app-script <name>prints. It downloadscloud/common.sh,cloud/<name>.shandworking-agreement.mdfrom this repository's GitHub copy and runscloud/<name>.sh, which installs what the repository's gate needs and writes the working agreement, with what is different in the cloud and notes on the repository, as the session's~/.claude/CLAUDE.md. A change pushed here reaches an environment when the app next builds its cache, about weekly; to make it build at once, change the date in the loader's text and save. - Environment variables:
BASH_DEFAULT_TIMEOUT_MS=600000andBASH_MAX_TIMEOUT_MS=1800000(builds outlast the 2-minute default). Red Acre also hasJOBS=4(the VM's cores, for its build scripts).
A cloud branch comes home like a worker's: Foreman fetches it from GitHub, a worker card checks and finishes it, the reviewer judges it, and Foreman merges it on the Git server.
The Git server's push mirror would delete those branches: it runs
git push --mirror, which removes every GitHub branch the server lacks. So a
repository that takes cloud sessions has no push mirror. Instead,
./setup.sh github-sync <name> on the iMac runs cloud/github-sync every two
minutes: it pushes the server's branches and tags to GitHub and deletes
nothing there. A branch deleted on the Git server therefore stays on GitHub:
delete it there too. A Forgejo branch filter does not help: the server pushes
with --mirror even then, and still deletes the other branches.
A host needs the Hermes agent with its gateway running, rootless podman,
git and python3, and SSH access to the Git server for the clones.
git clone git@git.imhermes.dev:hermes/coding-agent-system.git ~/Projects/hermes-os/coding-agent-system
cd ~/Projects/hermes-os/coding-agent-system
./setup.sh links # the working agreement as ~/AGENTS.md and ~/.claude/CLAUDE.md
./setup.sh tools # bin/ into ~/.local/bin; skills/ into ~/.agents/skills and ~/.claude/skills
./setup.sh worker # build the image, then write the profile
./setup.sh reviewer
./setup.sh author # on each guide host (the iMac, the Air, sim)
./setup.sh repo <name> # the workers' clean clone ~/workbench/<name>, made or fast-forwarded
./setup.sh github-sync <name> # on the iMac only: GitHub's copy of <name>, for cloud sessionsThe board must not split a card by itself (the owner's decision, 2026-11-12).
The gateway that starts first runs the board and reads the setting from its
own profile, so turn it off in every profile that runs a gateway on the
host: hermes -p <profile> config set kanban.auto_decompose false, and
-p default for the root profile (without -p the command writes to the
profile of the session that runs it).
Every command can be run again. ./setup.sh <profile> brings the profile back
to exactly what this repository says: its settings, its SOUL.md, and its
skills. links and tools make links into this checkout, so a git pull
here updates the agreement, the commands and the skills on the host; tools
also removes the link of a command or skill that was deleted here. Profiles and
the image are copies, so run ./setup.sh <profile> again after a pull that
changes profiles/ or workbench/.
setup.sh does not sign a profile in. Each profile needs its model provider's
sign-in on the host, held by the Hermes process and never by the container.
Workers see a repository as it is on the Git server. Push what a task depends
on, then run ./setup.sh repo <name> before making the card.
Make profiles/<name>/ with two files, then run ./setup.sh <name>:
intro.md: who the agent is, what its workbench is, and how it hands work back. It opens the profile'sSOUL.md.profile.json:description: one line, shown in Hermes's profile list.agreement:trueputsworking-agreement.mdafter the intro.skills: names of skills bundled with Hermes, copied into the profile.config: Hermes settings ashermes config settakes them, such as the model, the toolsets, and the container's image, volumes and limits.
The tests set up every folder under profiles/, so a new profile is covered
when it is added.
python3 -m unittest discover -s testsAGENTS.md says what an agent working here must know.
Parts of bin/ and skills/ are adapted from Peter Steinberger's
agent-scripts work. STEIPETE_AGENT_SCRIPTS_LICENSE and
OPENCLAW_AGENT_SKILLS_LICENSE carry the licenses of the adapted material.
Everything else is MIT licensed under LICENSE.