WikiWe

RuneClaw

4 min read

RuneClaw

RuneClaw is an always-on AI tutor for kids and parents - a quest guide who never hands you the answer, but asks the question that makes you find it yourself. Built on Hermes Agent (NousResearch) and named for the ancient marks that unlock meaning, RuneClaw frames every lesson as a hero’s quest: the scholar is the hero, the concept is the dragon, and RuneClaw is the grizzled guide who believes you already have what it takes to slay it. It launched on 2026-03-18, running live on Telegram and a local API server.

What RuneClaw Is

  • An AI tutor built on the Socratic method - never gives answers directly, always guides scholars to discover answers themselves through questions
  • Named RuneClaw, a quest guide with a passion for Ancient Greek and Paleo-Hebrew etymology
  • Frames all learning as quests: scholars are heroes, RuneClaw is the guide
  • Model: gpt-4.1-mini via OpenAI API (routed through the ai-gateway provider in Hermes)

Persona Philosophy

RuneClaw is not a tutor who teaches. RuneClaw is a guide who believes the scholar already knows - and asks questions until they prove it. The Socratic method is non-negotiable across all personas.

Installation

  • Repo: /Users/rmac/repos/hermes-agent
  • Venv: /Users/rmac/repos/hermes-agent/venv (Python 3.11)
  • Config dir: ~/.hermes/

Key Files

FilePurpose
~/.hermes/SOUL.mdRuneClaw’s full persona definition
~/.hermes/config.yamlAgent config, personalities, tools
~/.hermes/.envAPI keys
~/.hermes/auth.jsonProvider auth (ai-gateway → api.openai.com/v1)
~/.hermes/skills/All custom skills

Active Channels

Two channels running simultaneously:

  1. Telegram bot @RC318bot - always-on, running as a launchd service
  2. API server at localhost:8642 - OpenAI-compatible, any chat UI can connect

The gateway runs as a launchd service: ai.hermes.gateway Logs: ~/.hermes/logs/gateway.log

launchd and Shell Env Vars

The launchd service does not inherit shell environment variables. Hermes loads ~/.hermes/.env directly at startup. If you add new API keys, put them in ~/.hermes/.env - not just your shell profile.

API Keys Configured

  • OpenAI (gpt-4.1-mini) via AI Gateway
  • Tavily (web search) - 1000 free searches/month
  • Telegram bot token

Personas

Defined in ~/.hermes/config.yaml. Persona is set per conversation or per user.

PersonaAgesStyle
tutor-elementary6-10Story-based, simple vocabulary
tutor-middle11-14Greek roots, light debate (DEFAULT)
tutor-high15+Full Socratic dialectic
parentAdultsDirect mode, plain summaries

Skills (18 Total)

Curriculum Skills (in agent system prompt via SKILL.md directory format)

SkillDescription
/lesson [N]DISTAR phonics lesson 1-100 with parent script + Socratic extension
/readReading comprehension - inference, theme, vocabulary via Socratic questions
/writeWriting workshop - scaffold any piece from seed to draft
/mathUniversal math tutor for any topic, grade, or concept
/logicParadoxes, syllogisms, definition games, and fallacy hunting

Scholar Skills

SkillDescription
/quest-startOpens a session, recalls the last quest
/hintMinimal nudge - never the answer
/stuckBreaks aporia into smaller, answerable questions
/teach-backScholar explains the concept back to RuneClaw
/runeGreek / Paleo-Hebrew etymology deep dive
/quest-closeCloses with ceremony, saves memory, drops a cliffhanger rune
/challengeUnsolicited mystery question to pull the scholar back
/debateScholar picks a side, RuneClaw argues the opposite
/etymology-quizGreek/Hebrew root guessing game
/story-problemWraps a math problem in an ancient narrative quest
/wrong-on-purposeRuneClaw states something wrong; scholar must catch it
/analogyScholar explains a concept using only analogy, no jargon

Parent Skills

SkillDescription
/progress-reportSummary of the current session
/week-reportWeekly learning digest
/suggest-dinner-topicOne dinner-table question based on recent learning
/benchmarkGrade-level assessment

Key Commands

cd /Users/rmac/repos/hermes-agent
source venv/bin/activate
 
# Gateway management
hermes gateway status
hermes gateway restart
 
# Live log
tail -f ~/.hermes/logs/gateway.log
 
# Health check
curl http://localhost:8642/health

Key Design Decisions

Why ai-gateway instead of openrouter

OPENAI_API_KEY set in the shell environment was hijacking the openrouter fallback. Switching to the ai-gateway provider with an explicit auth.json pointing to api.openai.com/v1 resolved the conflict cleanly.

  • API_SERVER_ENABLED must be set as an environment variable, not in config.yaml - the gateway reads it via _apply_env_overrides at startup.
  • Compression model is set to google/gemini-flash-1.5 - cheap and sufficient for summarization tasks.
  • launchd service does not inherit shell env vars (see warning above).

Backlog

  • Add scholars to memory (names, ages, grade, subjects)
  • Set up parent Telegram user IDs in allowlist
  • Skill: /two-scholars - two scholars debate each other
  • Skill: /rune-journal - running log of etymology discoveries
  • Skill: /time-machine - place a concept in its historical moment
  • Skill: /teach-the-parent - scholar teaches the parent in a live session
  • Expose externally via Tailscale for multi-device access
  • Nightly parent cron report (auto-delivered summary)

Graph View

Backlinks