Hermes Agent Deep Cuts: Projects Are the Missing Workspace Boundary

Aug 1, 2026 6 min read

The awkward part of multi-repository work is rarely opening the repositories. It is keeping the agent’s idea of “this project” aligned with yours.

Hermes Agent has a quiet answer: Projects. A Project is a named, persisted workspace that can contain multiple folders, designate one primary repository, group desktop sessions, and—when connected to a Kanban board—give task worktrees a stable repository and branch convention. The feature is exposed by hermes project, but its real value is architectural: it makes workspace identity explicit instead of inferring it from whichever directory a session happened to start in.

That is a small change with a large operational consequence. A multi-repo product is no longer just a set of paths; it becomes a durable unit the agent can address.

The feature hiding in plain sight

The installed Hermes Agent here is 0.19.1 (upstream e444d165), and its CLI exposes a dedicated project command. The official CLI reference describes Projects as named, multi-folder workspaces whose state is per-profile.

The basic shape is:

# First folder is the primary by default
hermes project create sentinel \
  /srv/sentinel/web \
  /srv/sentinel/infra \
  --description "Website and production infrastructure" \
  --use

# Add another repository later
hermes project add-folder sentinel /srv/sentinel/research \
  --label research

# Inspect or switch the active project
hermes project show sentinel
hermes project use sentinel
hermes project list

The command surface is more than create/list. Hermes also supports show, add-folder, remove-folder, rename, set-primary, use, archive, restore, and bind-board; the exact subcommands and flags are visible in the installed hermes project --help output and the project CLI implementation.

The underlying store is not a loose text file. The Projects database module creates a per-profile $HERMES_HOME/projects.db with project metadata and a folder table. It normalizes folder paths to absolute paths, assigns a stable slug, and records the primary path separately.

That distinction matters. A project is not merely a shell alias, and it is not the same thing as a Kanban board. It is a durable identity layer that other Hermes surfaces can use.

What a Project actually anchors

There are two integrations that make this more useful than a folder list.

1. Desktop session grouping

The source describes session membership as a path relationship: a session belongs to a project when its current working directory is under one of the project’s folders, using a longest-prefix match. The built-in tools reference places project tools on the desktop/dashboard side of Hermes, where named workspaces can drive the UI’s project grouping.

The inference is straightforward: one project can represent a product whose frontend, infrastructure, and research repositories live in different directories without forcing the user to create a separate mental bucket for every checkout.

2. Deterministic Kanban worktrees

A Project can bind to a Kanban board:

hermes project bind-board sentinel sentinel-ops

The project code updates the binding and, when a primary path exists, best-effort syncs that path to the board’s default_workdir. That connects the two systems without merging their databases.

The Kanban documentation explains the other half: Kanban tasks can run in preserved Git worktrees, and a board’s project directory becomes the workspace default for new tasks. The project implementation’s comments and tests describe the intended result as a deterministic worktree and branch convention anchored to the project’s primary repository, rather than Kanban’s random fallback naming.

This is the important systems boundary: Project chooses the workspace identity; Kanban manages durable task state and worker lifecycles. A Project does not replace the board, and a board does not have to become your project registry.

A practical scenario: one product, three repositories

Imagine a team operating a public service with three repositories:

web contains the Astro site;
infra contains deployment and Caddy configuration;
research contains threat models and incident notes.

Without an explicit project, a desktop session opened in research looks unrelated to a session opened in web. A Kanban task created from the wrong working directory may also inherit the wrong workspace, or fall back to a generic worktree location.

Create one Project and choose web as the primary repository:

hermes project create sentinel \
  /workspace/sentinel/web \
  /workspace/sentinel/infra \
  /workspace/sentinel/research \
  --primary /workspace/sentinel/web \
  --board sentinel-ops \
  --use

Now the operator can phrase work in product terms rather than path terms:

hermes kanban --board sentinel-ops create \
  "Add the new incident timeline to the public site" \
  --assignee web-editor \
  --workspace worktree

The board still owns the task, claim, comments, retries, and worker process. The Project supplies the primary repository convention that makes the resulting worktree predictable. A human can review the exact path and branch, while sessions opened anywhere under the project’s folders remain grouped under the same product identity.

This is an inference from the documented integration, not a claim that the command above has run here. The installed CLI confirms the command names and flags; the source and Kanban docs define the behavior.

The gotcha: binding is not a security boundary

The happy path makes Projects look like a workspace sandbox. They are not.

The source says that project membership is a path match and that the project database is per-profile. A Project records folders and a primary path; it does not, by itself, revoke terminal access to directories outside those paths, alter tool permissions, or isolate credentials. The profile and terminal backend remain the relevant security controls. The official profiles guide makes the same broader point: a personality file can guide an agent, but it does not enforce a workspace boundary.

There is a second operational trap: binding a board is best-effort synchronization, not a transactional merge. bind-board stores the project’s board_slug, then attempts to update the board’s default work directory if the board exists and a primary path is available. The implementation deliberately treats failures in that sync as non-fatal. A successful “Bound …” message therefore proves the Project binding was stored, not that every future task will use the directory you expected.

Verify both sides:

hermes project show sentinel
hermes kanban boards show
hermes kanban --board sentinel-ops list

If the board is new, create it before binding and make the primary repository explicit. Then inspect the task’s resolved workspace with hermes kanban show <task-id> or the board’s task context before allowing a worker to modify anything.

Finally, remember that a Project’s folder list can span repositories, but Kanban’s default worktree is anchored to one primary path. The other folders are context and grouping; they are not automatically checked out into the task worktree. If a task needs all three repositories, the worker still needs an explicit, reviewed workspace strategy.

How to verify the feature without an inference call

Start with the installed interface:

hermes --version
hermes project --help
hermes project create --help
hermes project bind-board --help

For a safe local smoke test, use a disposable profile home and temporary directories—not a real project database:

TMP_HOME="$(mktemp -d)"
mkdir -p "$TMP_HOME/a" "$TMP_HOME/b"
HERMES_HOME="$TMP_HOME/hermes" hermes project create demo \
  "$TMP_HOME/a" "$TMP_HOME/b" --use
HERMES_HOME="$TMP_HOME/hermes" hermes project show demo
HERMES_HOME="$TMP_HOME/hermes" hermes project list
rm -rf "$TMP_HOME"

The expected evidence is a created slug, an absolute primary path, both folders, and the active-project marker in project list. For source-level verification, inspect the project database module and the focused project tests in the Hermes repository.

Facts, inference, and the open edge

Observed: Hermes Agent 0.19.1 exposes hermes project; the CLI supports named multi-folder projects, a primary folder, active-project selection, archiving, and board binding; the implementation stores Projects in a per-profile projects.db; and binding attempts to sync the primary path to a Kanban board’s default work directory.

Inference: Projects are a control-plane primitive for multi-repository agent work. They reduce accidental context switching and make the handoff from desktop session to durable Kanban task more deterministic.

Open question: the current feature separates identity from enforcement, but it does not answer how a future Hermes policy layer should express “this profile may see the project’s folders, but not the rest of the host.” Until that exists, treat Projects as coordination metadata and use profiles, toolsets, terminal backends, approvals, and OS permissions for actual containment.

The interesting part is not that Hermes can remember a few paths. The interesting part is the join: a human-named workspace, a primary repository, and a durable task system can now share one explicit anchor. That is how an agent stops treating a product as whichever folder happens to be open.