Hades
In the underworld of your Unity project, nothing is hidden from Hades. And now, nothing is hidden from your AI agent.
Hades is Unity-aware AI infrastructure for Claude Code. It's a standalone desktop app — a menu-bar app on macOS, a tray app on Windows (beta) — that builds a queryable knowledge graph of your entire Unity project — every scene, prefab, script, asset, and dependency — so your AI agent knows your project's structure instead of guessing at it. Out of the box you get 32 MCP tools, 22 skills, and 6 commands. Everything runs locally, and everything is version-controllable.
One prompt — "which prefabs and scenes break if I change
EnemyAI?" Stock Claude Code reads ~200k tokens of YAML, finds 1 prefab, misses 3 variants, and tells you to add code that breaks them. Hades answers correctly — 4 prefabs, 3 scenes — in 7 tool calls for 27% less cost. That gap is the whole project. → see the full side-by-side breakdown
Know, don't guess
Most AI tools search and predict: they grep for text that looks relevant and let the model infer the rest. The answers are probabilistic — and often wrong in ways you can't see.
Hades lets your agent know and analyze. When it asks "what references PlayerController," it reads a structural fact from the graph, not a guess from scattered snippets. Dependency analysis traces real edges. Ask the same question twice, get the same answer. One graph query replaces a dozen file reads — and the agent never makes you explain your project twice.
What Hades gives your AI agent
How the pieces fit together
flowchart TD
Agent["AI Agent<br/>(Claude Code)"]
Agent <-->|"32 MCP tools over HTTP<br/>127.0.0.1:7823"| Hades
subgraph Hades["Hades — standalone desktop app<br/>menu bar on macOS · tray on Windows"]
Graph["Graph<br/>project knowledge graph"]
Asphodel["Asphodel<br/>persistent, version-controlled"]
Charon["Charon<br/>observability"]
end
Graph -->|"indexes"| Unity["Unity Project<br/>scenes · prefabs · scripts · assets"]
Asphodel -->|"stored as"| Mem[".arcforge/memory/*.md"]
Graph -.->|"traced by"| Charon
Asphodel -.->|"traced by"| Charon
Hades <-.->|"optional: live-Editor actions"| Plugin["Unity plugin<br/>(installed into your project)"]
Plugin -.-> Unity
Your agent talks to Hades over MCP on 127.0.0.1:7823. The app indexes your project's structure into the Graph, persists project memory as Asphodel, version-controlled markdown, and Charon traces every operation so nothing is hidden. Reading your project needs nothing installed in it — the optional Unity plugin is only for live-Editor actions (editing scenes and prefabs, running tests, reading the console), and it dials out to the app rather than the app reaching in.
How Hades compares
Most AI-for-Unity tooling falls into one of two camps. Action bridges let an agent execute editor actions but have no model of your project. Code-graph / RAG tools understand code but are blind to Unity's asset layer — prefabs, scenes, GUIDs, serialized references. Hades does both, and it's Unity-native.
See it in action
Open Claude Code from your Unity project directory and ask:
Tell me about this project
The agent uses the graph to give a project-specific overview — not a generic summary.
Where do we use PlayerController?
Structural search across scenes, prefabs, and scripts — not just text grep.
I want to remove OldNetworkManager. What would break?
Dependency analysis that traces references through the full project graph before you change anything.
Want proof? With and without Hades: one prompt, side by side — the same task run twice under identical conditions. Stock Claude Code misses 3 prefab variants and recommends a change that would break inheritance; Hades returns the correct impact map for 27% less cost. Includes full uncut recordings and reproduction steps.
What to trust (and what to verify)
Different answers deserve different levels of trust, and the tools do not flag this for you — there is no confidence score on a v2 result. The rubric below is yours to apply:
Hades is a navigator, not an oracle: it makes understanding your project fast and structural, and its blind spots are documented rather than signalled — so knowing them is on you and your agent, before anything destructive. See Limitations for the boundaries that are there by design, and for what the tools do and don't tell you at runtime.
Prerequisites
macOS
- Apple Silicon Mac, macOS 14+ — the embedded core is arm64-only. On an Intel Mac the app shows a clear alert and quits rather than failing silently.
Windows — beta
- Windows 10 version 1607 (build 14393) or later, 64-bit. The installer checks the build and refuses below it. There is no 32-bit build.
- x64 or ARM64. Both are shipped. The ARM64 build has never been run on ARM64 hardware — it is built and its binaries verified native, nothing more. If you run it there, an issue report is genuinely useful.
- Windows support is beta: it is at feature parity with the Mac and its suites pass, but it has had far less real-world use. See Limitations.
Both
- Claude Code — other MCP clients are untested.
- Unity 6000.0+ — only for the optional in-Editor plugin. Reading and querying your project works without it.
Installation
Step 1: Install the app
macOS
curl -fsSL https://raw.githubusercontent.com/TheArcForge/Hades/main/install.sh | bash
That downloads the release DMG, verifies its SHA-256, and copies Hades.app to /Applications. It needs no sudo, changes no system settings, and disables nothing. If you'd rather read a script before running it — a reasonable habit — the source is install.sh:
curl -fsSL -O https://raw.githubusercontent.com/TheArcForge/Hades/main/install.sh
You can also take the DMG from Releases and drag it to Applications. That works, but macOS will block it on first launch — see Signing and installation.
Windows
irm https://raw.githubusercontent.com/TheArcForge/Hades/main/install.ps1 | iex
That picks the MSI for your architecture, verifies its SHA-256, and installs per-user into %LOCALAPPDATA%\Programs\Hades. It needs no Administrator, shows no UAC prompt, and changes no system settings. The source is install.ps1 if you would rather read it first:
irm https://raw.githubusercontent.com/TheArcForge/Hades/main/install.ps1 -OutFile install.ps1
You can also take the MSI for your architecture from Releases and run it. That works, but SmartScreen will warn on a browser-downloaded file — see Signing and installation.
Then, on either platform
Launch Hades — it lives in the menu bar on macOS, the notification-area tray on Windows. Add your Unity project when it asks. On first index Hades builds the knowledge graph — a few seconds on a typical project, up to a few minutes on a very large one. After that, updates are incremental.
Windows also installs a hades command-line tool onto your PATH. It only appears in terminals you open after installing, because Windows hands each process its environment at launch.
Step 2: Claude Code plugin
/plugin marketplace add TheArcForge/hades-plugin
then /plugin install hades. Run /mcp afterwards and confirm hades reports 32 tools.
Working from a clone instead? Point Claude Code at the plugin directly — per-session, so pass it every time:
claude --plugin-dir <your-Hades-checkout>/ClaudeCodePlugin
Step 3 (optional): Unity plugin
Only needed for live-Editor actions — editing scenes and prefabs, running tests, reading the console. Hades installs it into your project's Assets/Hades from the app; you don't add a package or a git URL. Everything else works without it.
Updating
There is no automatic update check — the app will not tell you a new version exists. Watch the releases page.
Updating is re-running the command you installed with; both installers replace an existing install
in place, and neither touches your projects, graphs or authored memory. On macOS, quit Hades from
the menu bar first — install.sh refuses to replace a running app, because swapping the bundle
under a live process fails later in confusing ways. On Windows nothing needs closing; the MSI
upgrades in place.
Full detail, including what is deliberately left alone: Installing → Updating.
Uninstalling
macOS
curl -fsSL https://raw.githubusercontent.com/TheArcForge/Hades/main/uninstall.sh | bash
Removes the app, its data, the macOS sidecars, and the launch-at-login item — which dragging to
Trash leaves behind, pointing at an app that no longer exists. Add --dry-run to see exactly what
it would remove first.
Windows — Settings → Apps → Installed apps → Hades → Uninstall. That removes the app, the
Start Menu shortcut and the PATH entry. Unlike the Mac script it does not remove your data: an
MSI that deleted %LOCALAPPDATA%\Hades would be the one irreversible thing the installer could do,
so it leaves it alone. Delete that folder by hand if you want it gone.
Neither ever touches your projects' .arcforge/ directories: the graph cache and your authored
Asphodel memory live together there, and that writing is yours.
First time? Installing Hades is the step-by-step walkthrough, with verification at each step.
How it works
Claude Code connects over MCP to the Hades app on 127.0.0.1:7823 — no launcher process, no Node bridge, no cloud. The app owns the knowledge graph, project memory, and tracing, and serves every project you've added from that one endpoint. For live-Editor work, the Unity plugin in your project dials out to the app over a local socket, so the Editor is a participant rather than a dependency: if Unity isn't running, graph queries still answer. All data stays on your machine — no telemetry, no vendor lock-in. See Architecture for the full design.
Troubleshooting
Project status
Hades is 2.0.0 — the standalone app replacing the in-Editor v1.x architecture. It's been field-tested on a large production Unity project, but not yet across many projects, Unity versions, or OS versions. Static analysis has known boundaries (see Limitations). If a result looks wrong on your project, please open an issue — concrete repros on real projects are exactly how this gets solid. The tools are built to tell you when they're uncertain, so trust the confidence signals and verify before anything destructive.
Windows support is beta. The Windows shell is a view layer over the same core the Mac uses — it renders, the core decides — so the analysis you get is identical on both. What is newer is everything around that: the installer, the tray, process supervision, and the environmental hazards no CI can reach (long paths, OneDrive placeholders, antivirus locking database files). Those are named individually in Limitations. hades diagnose exports an environment report for exactly this reason — if something misbehaves on Windows, that output in an issue is worth more than a description.
Signing and installation
Hades is not code-signed on either platform. There is no Apple Developer ID certificate and no Windows code-signing certificate for this project yet; getting them is the plan, and this section disappears when it happens. On both systems the OS warning you may see is correct — nothing here has been signed by anyone — and on both, the fix is a certificate rather than a workaround.
macOS
macOS blocks unsigned apps on first launch — but only files carrying the com.apple.quarantine attribute, which is set by whatever fetched the file, not by the file itself. That single detail decides your install experience:
So install.sh is the recommended route today. It does not disable Gatekeeper, strip attributes, or ask for sudo — it simply fetches with a tool that does not mark downloads, which is the same mechanism every curl | bash developer installer relies on.
If you did get the blocked dialog, the app is fine and this is the recovery (macOS 15 removed the old right-click → Open shortcut, so this is now the only route):
- System Settings → Privacy & Security, scroll to the Security section.
- A line naming Hades appears with an Open Anyway button. Click it and authenticate.
- Open Hades again; click Open in the second dialog.
Once per installed version, not once per launch.
This is a stopgap, and it is meant to be temporary. Signing and notarizing is the real fix: it removes the prompt on every channel and lets this section be deleted. It is waiting on the Developer ID account, not on a technical decision.
Windows
The same shape, with a different mechanism. SmartScreen warns about unsigned installers — but only for files carrying a Mark-of-the-Web, the Zone.Identifier stream a browser attaches to what it downloads. Command-line downloaders don't attach it. That was measured rather than assumed:
install.ps1 is therefore the recommended route today. It does not disable SmartScreen, strip a Mark-of-the-Web, touch Defender, or ask for Administrator — it simply fetches with a tool that doesn't mark downloads.
One case this cannot help. On machines with Smart App Control enabled — Windows 11 clean installs only — unsigned code is blocked outright, with no "run anyway" override. If that is your machine, wait for a signed release rather than trying to work around it. This has not been tested on such a machine, and is recorded from documentation.
Migrating from v1.2
The app detects an existing v1.2 install (Unity package + in-Editor MCP server + Node bridge) and offers to migrate its project memory and clean up the old install.
Documentation
- Installing Hades — install, first launch, plugins, migration, known issues
- Interpreting results — an archived v1.2 doc describing the confidence signals that architecture emitted
- Limitations — the boundaries that are there by design
- Architecture — system design, data flow, component responsibilities
- Comparison — with and without Hades, one prompt, side by side
- Contributing — repository layout, running the tests, conventions
License
MIT
