agentleFS
TheArcForgeTheArcForge/hades-plugin/CLAUDE.md

hades-plugin

CLAUDE.md3 starsChanged 3 months agoMITView on GitHub

This is a Unity project with Hades installed. You have 33 MCP tools that give you deep structural understanding of the project — a knowledge graph of every scene, prefab, script, asset, and their dependencies. Use them. Before answering questions about this project, before writing code, before suggesting changes — query the graph. Your first instinct should be to understand what exists, not to grep through files. Bash is for things the graph doesn't cover: reading file contents, running commands,…

The file

We split this CLAUDE.md into the rules it gives an agent

3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before answering questions about this project, before writing code, before suggesting changes — query the graph.

    line 7
  2. Distinctive:

    When you need to change scenes, prefabs, components, or assets — use the MCP tools, not file editing.

    line 42
  3. Distinctive:

    After it runs, retry the failed call — it should succeed.

    line 71

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

Hades — Agent Guidelines

This is a Unity project with Hades installed. You have 33 MCP tools that give you deep structural understanding of the project — a knowledge graph of every scene, prefab, script, asset, and their dependencies. Use them.

Core principle: structural context first

Before answering questions about this project, before writing code, before suggesting changes — query the graph. Your first instinct should be to understand what exists, not to grep through files.

Instead of...Do this first
grep -r "PlayerController"search_by_name + find_references_to — find it in the graph with all its references
find . -name "*.cs" to understand the projectget_project_summary — structured overview with counts and architecture
Reading scene files as YAMLget_scene_summary + inspect_asset — parsed structure, not raw text
Guessing what depends on somethingtrace_dependencies — recursive dependency trace through the graph
Reading a prefab file to understand itinspect_asset — structured hierarchy without instantiating

Bash is for things the graph doesn't cover: reading file contents, running commands, editing code. The graph is for understanding project structure, finding relationships, and navigating the codebase.

How to approach common questions

"Tell me about this project" → get_project_summary → get_scene_summary for key scenes → get_memory_summary for documented decisions

"Where is X used?" / "What would break if I remove X?" → search_by_name to find it → find_references_to for incoming references → trace_dependencies for outgoing dependencies

"How does [feature] work?" → search_by_name for related scripts → find_references_to to see where they're used → get_scene_summary / inspect_asset to see how they're assembled → then read the actual code

"I want to add/change [feature]" → First understand what exists (graph queries above) → check project memory via recall_memory for relevant decisions/conventions → then propose the approach

"Something is broken" → project_get_console_log for errors → hades_status to verify graph is current → search the graph for related components → then investigate

Project memory

This project may have documented decisions, patterns, and conventions in .arcforge/memory/. Use recall_memory to search for relevant context before making architectural suggestions. Use propose_memory_update to suggest documenting new decisions — never edit memory files directly.

Modifying the project

When you need to change scenes, prefabs, components, or assets — use the MCP tools, not file editing. Unity assets are binary or complex YAML that should not be hand-edited:

  • Scenes: scene_apply (batch ops: create, addComponent, setProperties, setReference, removeComponent, addListener, removeListener, delete, reparent, rename, select) / scene_manage (batch ops: save, create, open, duplicate)
  • Prefabs: prefab_apply (batch ops: create, instantiate, applyOverrides, editProperty, createVariant)
  • Materials: material_apply (batch ops: create, setProperty, assign, duplicate, swapShader)
  • Animation: animation_apply (batch ops: assignController, assignClip, createController, editController)
  • References: scene_apply's setReference op (for wiring up object references between components)

For C# scripts: write and edit code files normally with your editor tools. Use script_editing_session (action: "begin" / "end") to batch multiple script changes before triggering recompilation.

Recovering a stalled MCP connection (macOS)

If an MCP tool call returns "Server hades unavailable" or "No Unity instance found" while the Unity Editor process is still running, the editor's main thread is napped — typically right after a recompile/domain reload, or after a deep idle. A running server keeps itself registered via a background heartbeat, but a torn-down server (post-reload) needs one main-thread tick to re-register, which a napped editor won't give it.

Bringing Unity to the foreground for a moment un-naps it and lets it re-register. Run the helper (it captures your current frontmost app and restores focus afterward, so it doesn't leave you staring at Unity):

<hades-package>/Scripts/wake-unity.sh        # ~2s focus round-trip, then retry the MCP call

Or inline, if you don't have the script path handy:

PREV=$(osascript -e 'tell application "System Events" to name of first application process whose frontmost is true')
osascript -e 'tell application "Unity" to activate'
sleep 2
osascript -e "tell application \"System Events\" to set frontmost of process \"$PREV\" to true"

After it runs, retry the failed call — it should succeed. (Routine idle no longer needs this; the background heartbeat keeps a running server registered on its own.)

Available commands

  • /hades:status — graph state, server status, memory summary
  • /hades:rebuild-graph — regenerate knowledge graph from current project state
  • /hades:show-traces — inspect recent tool call traces (observability)
  • /hades:validate-memory — check memory files against graph
  • /hades:show-proposals — review pending memory update proposals
  • /hades:export-traces — export traces for analysis

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.