Why use a Hermes Project?
Hermes can read files, run commands, and change code. Before working, it still needs to know the correct repository, branch, rules, and validation commands.
A Hermes Project provides that context through one primary folder. When the Project is active, the Hermes session, file browser, terminal, and Git review use the same folder.
The resulting structure is:
Hermes Project
→ repository folder
→ project files and rules
→ terminal
→ Git status and diff
→ validation commands
The Project does not replace Git or the package manager. It connects the Hermes session to the correct place of work.
Preparing a local repository
The repository can be cloned with GitHub CLI or regular Git:
gh repo clone <owner>/<repository> ./<repository>
or:
git clone https://github.com/<owner>/<repository>.git
After cloning, inspect the repository identity:
git status --short --branch
git remote -v
git log -1 --oneline --decorate
These checks confirm:
- the active branch is known;
- upstream points to the correct remote;
- the working tree has no unintended changes;
- the base commit can be reported before work begins.
The repository can live in any manageable location, for example:
~/projects/<repository>
or:
~/.hermes/projects/<repository>
Creating the Hermes Project
In Hermes Desktop, create a Project and select the repository folder as its primary folder.
Name: <project-name>
Primary folder: /path/to/<repository>
The active Project moves the session context to that folder. Hermes can then read project files and run commands without requesting the repository path for every task.
A Project stores the working-folder relationship rather than a copy of the source code:
Hermes Project
→ Project name
→ primary folder
→ session relationship
Git repository
→ source code
→ branches and commits
→ remote
If the repository folder moves, the Project's primary folder needs to be updated.
Detecting the runtime and package manager
Before installing dependencies, inspect the repository manifest and lockfile.
| File | Typical tool |
|---|---|
bun.lock | Bun |
package-lock.json | npm |
pnpm-lock.yaml | pnpm |
yarn.lock | Yarn |
pyproject.toml | uv, Poetry, or pip |
Cargo.toml | Cargo |
go.mod | Go modules |
Treat the lockfile as the dependency source of truth. Examples that preserve locked resolution:
bun install --frozen-lockfile
npm ci
pnpm install --frozen-lockfile
yarn install --frozen-lockfile
Run only the command that matches the repository. The README and project scripts remain the main references for setup steps.
Giving Hermes project context
Hermes needs repository rules in addition to its location. Rules can live in files such as:
.hermes.md
AGENTS.md
CLAUDE.md
.cursorrules
.cursor/rules/*.mdc
Useful content includes:
# Project rules
- Use the package manager that matches the lockfile.
- Read relevant files before editing code.
- Do not touch credential files.
- Run available lint, type-check, tests, and build commands.
- Inspect the diff before creating a commit.
Project rules reduce assumptions, but they do not replace validation. Hermes still needs to run commands and report their actual output.
Finding validation commands
Validation scripts usually live in the project manifest or README.
For a JavaScript or TypeScript project, common examples are:
bun run check
bun run tsc
bun run test
bun run build
Script names vary. Some repositories use lint, typecheck, or test:unit. Hermes should inspect package.json before selecting commands.
A build may also require environment variables. If it stops because a value is missing, read the error and project documentation. Use a valid test value without putting secrets in the repository.
Coding workflow inside the Project
The relationship between the parts is:
For a task, Hermes follows this sequence:
- confirm the active Project and repository;
- inspect the branch and Git status;
- read relevant rules and files;
- make changes within scope;
- run repository validation;
- inspect the diff and report results.
This sequence keeps working location, rules, changes, and validation evidence in one context.
Boundary between the Project and repository
A Hermes Project simplifies navigation and keeps session context. Git remains the source of history and synchronization.
The Project does not automatically:
- create commits;
- choose a safe branch;
- resolve conflicts;
- install unrequested dependencies;
- decide that a passing build proves product correctness;
- push changes to a remote without instruction.
Those decisions still follow repository rules and user approval.
Expected setup result
Setup is complete when Hermes can open the Project, recognize the repository, run the appropriate commands, and show Git and validation results without guessing the work location.
The same pattern works for Bun, npm, Python, Rust, Go, or other stacks. Project commands change, while the Hermes Project continues to provide stable working context.