メニュー
Operate the personal Hermes fork that uses fork/main as an upstream mirror and fork/prod as the canonical deploy branch. Covers install, update, maintainer sync flow, and Telegram topic scoping.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/Git-on-my-level/hermes-agent --skill hermes-fork-prodコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SOC 職業分類に基づく
SKILL.md を表示中
| name | hermes-fork-prod |
| description | Operate the personal Hermes fork that uses fork/main as an upstream mirror and fork/prod as the canonical deploy branch. Covers install, update, maintainer sync flow, and Telegram topic scoping. |
| version | 0.2.0 |
Use this skill when working with the personal Hermes fork hosted at Git-on-my-level/hermes-agent.
The fork uses this structure:
origin remote → upstream Hermes: NousResearch/hermes-agentfork remote → personal fork: Git-on-my-level/hermes-agentfork/main → clean mirror of upstream main (+ rescued prod-only patches)fork/prod → integration branch = upstream + all custom patches (canonical deploy branch)prod branch → should track fork/prodKey invariant: fork/prod is always a superset of fork/main. Anything merged to prod survives syncs.
Set the host-local update channel once:
# ~/.hermes/config.yaml
updates:
remote: fork
branch: prod
Then deploy agents simply run:
hermes update
/update uses the same channel. Do not patch hermes update internals for fork routing — config is enough.
Use the shared fresh-install script from the global memory repo:
~/hermes-global-memory/scripts/install-hermes-fork-prod.sh
What it does:
Git-on-my-level/hermes-agentprodfork points to the personal forkorigin points to upstream~/.local/bin/hermescd ~/.hermes/hermes-agent
git fetch origin --prune
git fetch fork --prune
git checkout prod || git checkout -b prod --track fork/prod
git reset --hard fork/prod
./venv/bin/python -m pip install -e .
The prod branch is an integration branch: it always contains upstream main plus any custom patches you've merged directly to prod.
origin/main ──rebase──→ fork/main ──merge──→ fork/prod
(upstream mirror) (upstream + our patches)
Key invariant: fork/prod is always a superset of fork/main. Commits merged directly to prod (via PR or GitHub merge button) are never lost — they're rescued onto main first, then flow into prod naturally.
prod must allow push + force-push (for recovery scenarios)main and prod should exist and track their respective fork/* remotesRun the update script:
cd ~/.hermes/hermes-agent
./scripts/update-prod-branch.sh # live run
DRY_RUN=1 ./scripts/update-prod-branch.sh # preview what would happen
That script does:
origin and fork remotes (with prune)main — rebase local main onto origin/main, push fork/mainfork/prod not on main, cherry-pick them onto main, push updated fork/mainprod — merge main into prod (fast-forward if possible, merge commit if histories diverged)fork/prodThis ensures:
prod survive syncs (they get rescued to main, then merged forward)main stays a clean upstream mirror (all prod-only patches are also on main)If step 4 (cherry-pick) or step 5 (merge) hits conflicts:
git add <resolved-files> → git cherry-pick --continue (or git merge --continue)If conflicts are too numerous to resolve manually, use the clean reset approach below.
When upstream has drifted so much that rebasing produces unmanageable conflicts:
Analyze which prod patches survive — identify non-merge commits on prod not in upstream:
git log --oneline prod --not origin/main --no-merges
Create an isolated worktree:
cd ~/.hermes/hermes-agent
git worktree add -b sync/prod-vN /tmp/hermes-prod-sync origin/main
Export old prod patches for reference:
mkdir /tmp/hermes-prod-sync/patches
for hash in <still-needed-commit-hashes>; do
git format-patch -1 "$hash" -o /tmp/hermes-prod-sync/patches/
done
Re-apply patches adapted to current code — do NOT git am literally. Read each patch for INTENT and implement it in the current code structure. Use subagents (Codex preferred), batched by dependency group (infrastructure first, then gateway, then CLI, then trivial).
Validate syntax after every subagent batch (see *** corruption pitfall below).
Run tests:
python3 -m pytest tests/... -x -q -o "addopts="
Push:
cd ~/.hermes/hermes-agent
git checkout prod
git reset --hard /tmp/hermes-prod-sync # or git fetch fork && git reset --hard fork/sync/prod-vN
git push fork prod --force-with-lease
git worktree remove /tmp/hermes-prod-sync
The previous workflow (rebase prod onto main then force-push prod) had a critical flaw: any commit merged directly to prod was silently clobbered on every sync. The force-push overwrote fork/prod with the rebased content, losing whatever was only on prod.
The new approach inverts the direction:
main → overwrite → prod (destructive)prod-only commits → main → merge → prod (additive)Benefits:
prod are never lostmain still stays clean (it's the upstream mirror + rescued patches)--force-with-leaseThis fork supports inbound Telegram topic allowlists on the prod line.
It also supports session-scoped model settings for Telegram topics: each topic/session can retain its own model, provider, and base_url in the persisted session state. That means different topics can effectively run different models/providers, and /new clears conversation state without resetting the active model settings.
Add to config:
platforms:
telegram:
extra:
allowed_inbound_targets:
- "CHAT_ID:THREAD_ID"
Behavior:
Example:
allowed_inbound_targets: ["-1003502111905:2"]allowed_inbound_targets: ["-1003502111905:7"]This allows multiple Hermes bots to share one Telegram supergroup while each bot only responds in its assigned topic.
Use worktrees for feature and PR branches, not for the live deploy checkout.
Example:
git worktree list
# /Users/dazheng/.hermes/hermes-agent [prod]
# /Users/dazheng/.hermes/hermes-agent-pr-foo [feat/foo]
Recommended rule:
~/.hermes/hermes-agent should be the canonical launchd-managed deploy checkoutprodprod worktree for the live service unless you also deliberately bind the venv, editable install, and launchd plist to that same pathWhy:
venv in ~/.hermes/hermes-agent but editable install / runtime code in ~/.hermes/hermes-agent-prod-worktree is brittlehermes update, editable installs, and launchd path generation derive from the current project rootImportant operational finding:
~/.hermes/hermes-agent/venv but the editable package points at ~/.hermes/hermes-agent-prod-worktreeIf the desired state is "launchd-managed prod branch, not a worktree deployment", collapse back to a single checkout:
cd ~/.hermes/hermes-agent
git worktree remove ~/.hermes/hermes-agent-prod-worktree
git fetch fork --prune
git checkout prod || git checkout -b prod --track fork/prod
git reset --hard fork/prod
./venv/bin/python -m pip install -e '.[all]'
./venv/bin/python -m hermes_cli.main gateway install --force
Then verify all of these point to the same base repo path (~/.hermes/hermes-agent):
hermes --version → Project:pip show hermes-agent → Editable project location:WorkingDirectoryhermes_cli.main / gateway.platforms.telegramhermes update on the prod branch should pull from fork/prod, not origin/main or fork/main.
Important nuance discovered in production:
fork is not enoughprodmain before pulling, a deployed prod checkout can silently drift back onto the wrong lineCurrent detection order for prod installs:
~/.hermes/install-channel containing prodprod branch upstream resolves to fork/prodprod and refs/remotes/fork/prod existsmain / origin/mainSo even if a user temporarily lands on a feature branch or detached HEAD, hermes update should converge back to the prod line when the install-channel metadata or prod tracking metadata is present.
If you are validating the live prod branch, inspect hermes_cli/update_channel.py and hermes_cli/main.py and confirm:
(channel="prod", remote="fork", branch="prod")prod before updatemacOS operational finding:
/update succeed while Telegram stays downlaunchctl kickstart -k gui/$UID/<label> plus bounded restart healthchecksIf you ever see diverged histories:
git branch -vv
# * prod 7478c55d [fork/prod: ahead 8, behind 5] ...
The update command will auto-reset to match fork/prod. Manual fallback:
cd ~/.hermes/hermes-agent-prod-worktree
git fetch fork
git reset --hard fork/prod
Be careful deleting remote branches in this fork because one branch is literally named prod while the remote is named fork, so the remote-tracking ref appears as fork/prod.
That makes commands like:
git push fork --delete fork/prod
ambiguous-looking and easy to misuse. It deletes the remote branch named prod on remote fork (because git push <remote> --delete <branch> interprets the argument as a remote branch name, not a remote-tracking ref).
For destructive cleanup, prefer explicit ref syntax:
git push fork :refs/heads/stale-branch-name
Examples:
# delete the stale remote branch literally named "fork/prod"
git push fork :refs/heads/fork/prod
# delete the canonical prod branch only if you truly mean it
git push fork :refs/heads/prod
After any remote branch deletion, immediately verify with:
git fetch fork --prune
git branch -r | grep 'fork/.*prod'
After changing a bot to prod and/or topic scoping:
cd ~/.hermes/hermes-agent-prod-worktree # or main repo if no worktree
git branch --show-current
git rev-parse HEAD
git rev-parse fork/prod
Expected:
prodfork/prod unless there are new unpushed local commitsThen restart the gateway and verify:
/status works in the assigned topicCritical deployment check for topic allowlists:
allowed_inbound_targets is active just because it is present in config.Failure mode to watch for:
allowed_inbound_targets~/.hermes/hermes-agent on main/new can still respond in other topics/new or /reset resets conversation state only; it does not claim topic ownership.allowed_inbound_targets.main for updates; use hermes update from prod.*** corruptionWhen delegating file edits to subagents (Codex, GLM subagents, etc.), their patch tools can silently replace actual code with *** in files that contain redacted or placeholder content (API keys, auth types, token values). This produces syntactically invalid Python that passes visual review if you only look at surrounding context.
Symptoms:
SyntaxError: closing parenthesis ')' does not match opening parenthesis '{'api_key_env_vars=*** "ZAI_API_KEY" or models = _fetch_github_models(api_key=*** timeout=timeout)(\\\"Z.AI / GLM\\\", ...Prevention:
.py files:
for f in <modified-files>; do
python3 -c "import ast; ast.parse(open('$f').read()); print('$f ok')"
done
*** in modified files: grep -n '=\\*\\*\\*' file.pygit checkout origin/main -- path/to/corrupted_file.py
# then manually apply just the prod-specific change
Root cause: The subagent's patch tool appears to match and replace content that looks like redacted placeholders, sometimes overwriting actual code that happens to be adjacent. Files with many redacted values (auth.py, models.py, doctor.py, setup.py) are highest risk.