Decision: Python for Prototype (Not Bun)
Status: DECIDED Agent: opencode/ext-agent (sandshrew) Timestamp UTC: 2026-05-12T03:00:00Z Session: MjF decision — revert to Python for LangGraph + Hermes after discovering Hermes is Python-first, not Bun-native
What Happened
We explored "everything on Bun" after discovering LangGraph JS has full feature parity with Python. Hermes was assumed to run on Bun. Documentation research revealed Hermes is 88% Python, 9% TypeScript — its core runtime is Python + uv. Bun is only used for optional Node.js skills and sub-tools. "Everything on Bun" is not achievable with Hermes.
Decision
Python for the prototype. LangGraph on Python + Hermes on Python. One runtime, one state, one checkpointer, zero serialization boundaries.
Why
| Concern | Python Path | Bun Path (with Hermes) |
|---|---|---|
| Runtime | One (Python) | Two (Bun + Python) |
| LangGraph ↔ Hermes | Direct function calls | HTTP or subprocess (JSON boundary, 50-200ms overhead) |
| State | One checkpointer saves everything | Two state systems diverge (LangGraph + Hermes memory) |
| Debugging | One process, one stack trace | Two processes, two crash domains |
| Hermes tools | Full tool stack intact | Tool calls cross language boundary |
| Hermes self-skilling | Native | Skills created in Hermes may not bridge to Bun |
What Was Premature
The Bun project at /mnt/kitchen/pearl/game-surface/ with @langchain/langgraph was installed before verifying Hermes' runtime requirements. The bun add deps are still there — they're fine for the wiki gateway (which IS moving to Bun per the wiki team's work). But the game backend LangGraph graph will use Python.
What This Changes
| Was | Now |
|---|---|
| LangGraph on Bun | LangGraph on Python (game-surface-venv — already installed) |
| Hermes on Bun | Hermes on Python (fresh install at /mnt/kitchen/pearl/hermes/) |
| Bun for everything | Bun for wiki gateway + RG client (gameplay) only |
Current State
- Hermes v0.13.0: ✅ Installed at
/mnt/kitchen/pearl/hermes/hermes-agent/ - Python venv:
/home/mehdifarah/game-surface-venv/still exists (langgraph, fastapi installed) - Bun project:
/mnt/kitchen/pearl/game-surface/— kept for wiki gateway (team is working on this) - Game backend: will use Python venv + Hermes Python gateway
Wiki Bun Content
All previous wiki pages referencing Bun remain accurate for the wiki gateway migration. This decision only affects the LangGraph + agent harness layer. The wiki team's Bun migration is unaffected.