Skip to content

About

Portable, model-neutral engineering policy, skills, hooks, and repository enforcement for coding agents.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

coding-agent-system

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.

How a task flows

  1. 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_create with assignee worker, workspace kind worktree and workspace path /home/hermes/workbench/<repo>.

  2. 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 branch wt/<task-id>.

  3. 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:latest for this one task. The container sees ~/workbench and a shared package cache. It has no keys, no tokens, no SSH, no ~/.hermes and 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.

  4. A review. The worker commits on its branch and hands the card to the reviewer profile. The dispatcher starts the reviewer in its own container. It sees ~/workbench through 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.

  5. 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 --parent child the minute its parent is done, on a worktree cut from a main that does not hold the parent's work yet. Park such a card with hermes kanban schedule <id> "<reason>" when you make it, and release it with hermes 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.

Study-guide authors

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.

Cloud sessions

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 downloads cloud/common.sh, cloud/<name>.sh and working-agreement.md from this repository's GitHub copy and runs cloud/<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=600000 and BASH_MAX_TIMEOUT_MS=1800000 (builds outlast the 2-minute default). Red Acre also has JOBS=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.

Set up a host

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 sessions

The 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.

Add a profile

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's SOUL.md.
  • profile.json:
    • description: one line, shown in Hermes's profile list.
    • agreement: true puts working-agreement.md after the intro.
    • skills: names of skills bundled with Hermes, copied into the profile.
    • config: Hermes settings as hermes config set takes 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.

Develop

python3 -m unittest discover -s tests

AGENTS.md says what an agent working here must know.

Attribution

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.

About

Portable, model-neutral engineering policy, skills, hooks, and repository enforcement for coding agents.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages