@edd_remonts/create-hermes-workspace

Bootstrap a Hermes Agent workspace with one command. Clones the canonical create-hermes-workspace repo, copies .env.example → .env, and prints what to do next.

Install

You don't install it — you run it. The whole point is a single npx invocation.

npx @edd_remonts/create-hermes-workspace

The first run downloads the package, executes the CLI, and exits. There's nothing to add to your package.json and nothing to remove.

Usage

# Default — creates ./hermes-workspace
npx @edd_remonts/create-hermes-workspace

# Custom folder
npx @edd_remonts/create-hermes-workspace my-projects

# Absolute path
npx @edd_remonts/create-hermes-workspace /opt/workspaces/hermes

# Help
npx @edd_remonts/create-hermes-workspace --help

# Version
npx @edd_remonts/create-hermes-workspace --version

What it does

1. Verifies you have Node 18 or higher.
2. Validates the target folder name (POSIX-safe characters only).
3. Refuses to overwrite a non-empty folder.
4. Shallow-clones eddremonts86/create-hermes-workspace from GitHub.
5. Copies the cloned .env.example to .env so you can start editing.
6. Prints a "what to do next" panel pointing you at docker compose up -d.

No telemetry, no analytics, no network calls beyond the git clone.

Requirements

• Node.js 18 or higher — to run the CLI itself.
• Git — to clone the workspace repo (brew install git, apt install git, etc.).
• SSH access to GitHub — the CLI uses [email protected]:... so the repo must be reachable over SSH. Run ssh -T [email protected] once to confirm. (If you only have HTTPS auth, see FAQ.)
• Docker — only required after the CLI finishes, to start the workspace container.

Programmatic API

This package is a CLI, not a library. It has no exported JavaScript API. If you need to script workspace creation, run the CLI from your shell:

npx --yes @edd_remonts/create-hermes-workspace "$WORKSPACE_NAME"

Exit codes:

| Code | Meaning | |------|---------| | 0 | Success. | | 2 | Pre-flight failure (invalid name, target not empty, Node < 18). | | 3 | git not found on PATH. | | 4 | git clone failed (network, auth, repo missing). | | other | Bubbled up from git clone. |

What gets cloned

The CLI pulls eddremonts86/create-hermes-workspace, which contains:

• Dockerfile + docker-compose.yml — pre-wired for the Hermes agent.
• .env.example — annotated, with only the keys a colleague must set.
• AGENTS.md — the workflow rules (superpowers methodology, 4 hard gates).
• Makefile — make up, make shell, make new-project NAME=foo, make reset.
• scripts/bootstrap.sh — non-Docker one-shot installer.
• skills/ — a curated subset of reusable skills.
• README.md — the world-class onboarding doc (this is the one to read next).

After cloning, cd into the folder and read its README. That's where the workspace workflow lives.

FAQ

Q: I have a "Permission denied (publickey)" error. A: The CLI uses SSH. Set up an SSH key on GitHub: https://docs.github.com/en/authentication/connecting-to-github-with-ssh. Or clone the repo manually with HTTPS first, then re-run the CLI.

Q: I already have a folder called hermes-workspace. A: The CLI refuses to overwrite a non-empty folder. Either remove it (rm -rf hermes-workspace) or pass a different name (npx @edd_remonts/create-hermes-workspace my-v2-ws).

Q: Can I run this on Windows? A: Yes — use WSL2 (Windows Subsystem for Linux). Run the CLI from inside your WSL distribution. Native PowerShell works for the git clone but Docker Desktop's WSL2 backend is the supported path for the container.

Q: Why isn't this just npm install -g? A: Because you don't want it globally — you want it on-demand, always at the latest version, and never on your package.json. npx is exactly the right tool for "run this once, then forget about it."

Q: How is this different from @edd_remonts/create-edd-app? A: They solve different problems:

• @edd_remonts/create-hermes-workspace (this package) → the dev environment: agent, skills, Dockerfile, env config. One per machine.
• @edd_remonts/create-edd-app → a single application: TanStack Start + Drizzle + shadcn stack. One per project.

You'll usually run this once, then run create-edd-app many times inside it.

Q: My .env was overwritten! A: The CLI only copies .env.example → .env if .env doesn't already exist (or if the target folder was just created by the clone). It will not overwrite an existing .env. If you want to re-copy, cp .env.example .env manually.

Q: How do I publish a new version? A: Inside this package's repo: npm version patch (or minor / major), then npm publish --access public. The package's scripts/publish.sh (in the workspace repo, not here) wraps that with a token-prompt dance.

Q: Is telemetry collected? A: No. The CLI makes exactly one network call: git clone. No analytics, no phone-home, no error reporting.

See also

• eddremonts86/create-hermes-workspace — the repo this CLI clones. Read its README after running the CLI.
• @edd_remonts/create-edd-app — bootstrap a new app from the edd-app-template.
• nousresearch/hermes-agent — the underlying agent runtime.
• eddremonts86/edd-app-template — the default app scaffold used inside a workspace.

License

MIT © 2026 Eduardo Inerarte. See LICENSE for the full text.

Contributing

Issues and PRs welcome at https://github.com/eddremonts86/create-hermes-workspace/issues.