Manage Named Multi-Folder Projects in Hermes

The hermes project command manages named workspaces that may span multiple folders. Projects help keep session grouping and task execution anchored to an explicit workspace instead of whichever directory happened to be active.

Official documentation: https://hermes-agent.nousresearch.com/docs/reference/cli-commands#hermes-project

Define the workspace boundary first

A project should map to one coherent product, client-safe codebase, or operational domain. Include only folders that belong under the same authority and review model. A convenient multi-folder grouping must not collapse public and private data boundaries.

Align projects with task isolation

When a project is bound to a Kanban board, tasks can follow deterministic branch and worktree conventions. The project records the workspace; it does not replace per-task acceptance criteria, code review, or secrets isolation. Keep concurrent writes in separate worktrees when the repository supports them.

Operational checklist

Name the project for a durable outcome.
Add only the required folders.
Document public and private boundaries.
Bind a Kanban board only when coordination needs it.
Define branch and worktree conventions.
Open a session and confirm the expected workspace.
Review project membership when folders move.

Common pitfalls

Using one giant project for unrelated work.
Including private data folders in a public-content workspace.
Assuming project grouping creates OS-level isolation.
Running parallel agents in the same checkout.
Leaving stale folder paths after a migration.

Verification steps

List the project and inspect every folder path.
Open a project-scoped session.
Confirm file tools resolve inside the intended workspace.
Create a harmless task and inspect its branch/worktree convention.
Verify a folder outside the project is not accidentally treated as context.
Remove or update one stale test path and list the project again.

A reliable Hermes workflow is defined by observable behavior, bounded authority, and repeatable verification—not by configuration alone.