Bug: `codegraph install --target hermes` corrupts `config.yaml` — drops `hermes-cli` and breaks nested YAML indentation

[lyrumu]

Description

Running codegraph install --target hermes -y corrupts the platform_toolsets section of Hermes Agent's ~/.hermes/config.yaml. The installer:

1. Drops hermes-cli from the cli toolset list
2. Shifts indentation — all other tool entries (browser, clarify, code_execution, etc.) that were under cli: are moved up to the platform_toolsets level, breaking YAML structure
3. Shifts platform indentation — entries under telegram:, discord: etc. also shift by one level

After the corruption, Hermes cannot parse config.yaml:

hermes config: Failed to parse /home/user/.hermes/config.yaml:
while parsing a block mapping
  in "/home/user/.hermes/config.yaml", line 502, column 3
expected <block end>, but found '-'
  in "/home/user/.hermes/config.yaml", line 504, column 3.
Falling back to default config — every user override is being IGNORED.

All user configuration (model settings, auxiliary providers, custom toolsets) is silently lost until the YAML is manually repaired.

Environment

Item	Detail
CodeGraph version	v0.9.5 (self-contained bundle, installed via official install.sh)
OS	Windows 11 23H2 (build 22631) + WSL2
WSL2 distro	Ubuntu 24.04 LTS
Hermes Agent	latest main branch (local git clone at ~/.hermes/hermes-agent/)
Hermes config path	~/.hermes/config.yaml
Hermes install method	git clone + pip install -e .
CodeGraph install command	codegraph install --target hermes -y
Node.js (host)	v22.x (not used by self-contained bundle)

Reproduction

Step 1 — Start with a real Hermes ~/.hermes/config.yaml:

A fresh hermes setup generates this platform_toolsets section by default:

platform_toolsets:
  cli:
    - hermes-cli
    - browser
    - clarify
    - code_execution
    - computer_use
    - cronjob
    - delegation
    - file
    - image_gen
    - memory
    - messaging
    - session_search
    - skills
    - terminal
    - todo
    - tts
    - video
    - vision
    - web
  telegram:
    - hermes-telegram
  discord:
    - hermes-discord
  whatsapp:
    - hermes-whatsapp
  slack:
    - hermes-slack
  signal:
    - hermes-signal
  homeassistant:
    - hermes-homeassistant
  qqbot:
    - hermes-qqbot
  yuanbao:
    - hermes-yuanbao
  teams:
    - hermes-teams
  google_chat:
    - hermes-google_chat

Step 2 — Run the install command:

codegraph install --target hermes -y

Output says success:

◆  Hermes Agent: Updated ~/.hermes/config.yaml
●  Hermes Agent: Start a new Hermes session for MCP changes to take effect.
◇  Done! Restart your agent to use CodeGraph.

Step 3 — Check the corrupted result:

The platform_toolsets section now reads:

platform_toolsets:
  cli:
    - mcp-codegraph       # ← ADDED (correct), but `hermes-cli` was DROPPED
  - browser               # ← WRONG: moved up to platform_toolsets level
  - clarify               # ← same
  - code_execution
  - computer_use
  - cronjob
  - delegation
  - file
  - image_gen
  - memory
  - messaging
  - session_search
  - skills
  - terminal
  - todo
  - tts
  - video
  - vision
  - web
  telegram:
  - hermes-telegram       # ← WRONG indentation (should be 4 spaces)
  discord:
  - hermes-discord
  whatsapp:
  - hermes-whatsapp
  slack:
  - hermes-slack
  signal:
  - hermes-signal
  homeassistant:
  - hermes-homeassistant
  qqbot:
  - hermes-qqbot
  yuanbao:
  - hermes-yuanbao
  teams:
  - hermes-teams
  google_chat:
  - hermes-google_chat

Step 4 — Verify the YAML is broken:

python3 -c "import yaml; yaml.safe_load(open('~/.hermes/config.yaml'))"
# → YAMLError: while parsing a block mapping

hermes mcp list
# → Failed to parse config.yaml, falling back to default config
# → No MCP servers configured

Expected Behavior

After codegraph install --target hermes, the config should be:

platform_toolsets:
  cli:
    - hermes-cli          # ← PRESERVED
    - mcp-codegraph       # ← ADDED (by installer)
    - browser             # ← PRESERVED, correct 4-space indentation
    - clarify
    - code_execution
    - terminal
    - web
  telegram:
    - hermes-telegram     # ← PRESERVED, correct indentation
  discord:
    - hermes-discord

The mcp_servers.codegraph section (added further down in the file) is written correctly — the bug is isolated to the platform_toolsets section.

Additional Observations

1. --print-config is correct — Running codegraph install --print-config hermes outputs the expected config, complete with hermes-cli preserved and proper indentation. The config-generation logic is fine.

2. Only the file-write step corrupts it — The bug is in the YAML file patching/writing step, not in the config template generation.

3. mcp_servers section is written correctly — The CodeGraph MCP server definition under mcp_servers: is added with correct indentation and works when applied manually.

Root Cause Hypothesis

The diff between the backup (before install) and the corrupted file tells the story:

--- backup/config.yaml (before install)
+++ corrupted config.yaml (after install)

 502a503
 >     - hermes-cli              ← installer ADDED this (somehow)
 504,521c505,522
-  - browser                     ← was at platform_toolsets level (WRONG in output)
-  - clarify
+    - browser                   ← correctly under cli: (in backup, after manual fix)
+    - clarify
 523c524
-  - hermes-telegram             ← wrong indent (2 spaces in corrupted)
+    - hermes-telegram           ← correct indent (4 spaces in backup)

Note: In the diff above, the < lines are from the corrupted output; the > lines are from a manually repaired backup that has the correct structure.

This suggests the installer's YAML writer is not properly tracking nesting depth. It appears to:

• Read the YAML as lines, not as a parsed document tree
• Find the platform_toolsets.cli list and add mcp-codegraph to it
• But when serializing back, it doesn't account for the original indentation depth of all other items in that block

The fact that hermes-cli was also dropped (even though --print-config includes it) suggests the writer may be replacing the entire platform_toolsets.cli content with a new flat list instead of merging into the existing list.

Workaround

Do not run codegraph install on an existing Hermes config. Instead, use --print-config to see the intended snippet and apply it manually:

codegraph install --print-config hermes

Then edit ~/.hermes/config.yaml to:

1. Add the mcp_servers.codegraph block
2. Add - mcp-codegraph to the platform_toolsets.cli list (keeping - hermes-cli and all other items)

[colbymchenry]

Fixed in #461 — thanks for the detailed report (and especially for capturing the diff against a backup, which made the root cause easy to confirm).

Root cause: Hermes serializes config.yaml with PyYAML's default block style, where list items sit at the same indent as the parent mapping key:

platform_toolsets:
  cli:
  - hermes-cli      # indent 2, same column as `cli:`
  - browser

The previous line-based YAML patcher used a ^ \S heuristic to find the end of the cli: block, which mistook that first - hermes-cli line for the next sibling key. So the patcher saw the cli: block as empty, and then spliced - mcp-codegraph at indent 4 before the existing items — promoting - browser, - clarify, …, and even the next platform's telegram: to invalid positions. Your observation in the bug report that "hermes-cli was dropped" turned out to be a symptom of the YAML no longer parsing, not an actual line removal — Hermes silently fell back to the default config, hiding the entire platform_toolsets map.

Fix: a new listChildBlock helper recognizes - lines as list-item continuations (not sibling keys), finds the real end of the block at the next sibling mapping key, and detects the indent existing items already use so - mcp-codegraph is appended at the same indent. The 4-space-nested layout (what --print-config shows) still works the same way.

End-to-end verified against a real hermes-agent install on the exact config from your bug report:

• hermes mcp list → codegraph codegraph serve --mcp all ✓ enabled
• hermes tools --summary → mcp-codegraph and codegraph both enabled in the CLI toolset, alongside browser, file, terminal, web, …
• hermes mcp test codegraph → ✓ Connected (264ms) ✓ Tools discovered: 10 (search, context, callers, callees, impact, node, explore, status, files, trace)
• Re-running codegraph install --target hermes reports Unchanged; the file still has exactly one mcp-codegraph and one codegraph: server block.

Also validated the installer test suite on macOS, Linux (Docker node:22-bookworm), and Windows 11 (Parallels). The fix will ship in the next release (currently in [Unreleased] in CHANGELOG.md).