How Uniloom installs into an agent
Pressing Connect in Connect → Agents installs Uniloom into that agent's config folder, once. The agent then reaches Uniloom's memory and tools, and Uniloom captures its sessions. The dialog's last line names the file Uniloom writes into.
What it writes#
Uniloom goes in one of two ways, never both:
- A plugin, for Claude Code, Codex, Gemini (as an extension) and Cursor. The plugin carries Uniloom's hooks and four commands, and the agent's own uninstall removes it. The plugin needs Node 24 or newer.
- Hooks in the agent's config, for the other agents that take hooks, and for the four above when the plugin cannot run. These config files apply to every project on the computer. Codex takes no config hooks: without its plugin it keeps only Uniloom's MCP server.
Every agent also gets one uniloom entry in its MCP config, which starts Uniloom's MCP server inside the app. Each session starts its own copy, so Uniloom's tools work whether or not the Uniloom window is open.
Each time Uniloom starts, it checks every connected agent and puts back what is missing, so Uniloom is installed exactly one way. Only Disconnect keeps it off. Uniloom installs no plugin while it runs from the disk image; it waits until Uniloom is in Applications.
What you see in a Claude Code session#
Claude Code prints one line when Uniloom loads or saves memory, at most once per session each:
| When | What prints |
|---|---|
| The session starts | Uniloom · <branch> · 5 memories, 1 parked branch, 3 sessions |
| The session saves memory | Uniloom · saved 3 memories from this session, and a notification |
| The session did work but saved nothing | Uniloom · this session did real work but saved nothing yet. |
| You made a plan | Uniloom · you made a plan. The agent then asks whether to save it |
Other agents get the same reminders in the form each one reads.
Four commands#
The plugin adds these to the agent's / menu:
| Command | What it does |
|---|---|
/uniloom:brief | What Uniloom knows about this project, in a few lines |
/uniloom:recall <what> | Search your memory |
/uniloom:remember <fact> | Save one memory, in your words |
/uniloom:open | Open this project in Uniloom |
What Disconnect puts back#
Before its first write, Uniloom keeps what each file held. On Disconnect, a file only Uniloom changed goes back to exactly that, and a file Uniloom created is removed. If you or the agent edited the file since, only Uniloom's parts are removed.
If Disconnect fails, it says which part did not come out. For a stuck plugin it gives the command to run, such as codex plugin remove uniloom@uniloom.
Check that it works#
An agent whose hooks do not run looks like an agent nobody used. To check, run this in Terminal:
"$HOME/Library/Application Support/dev.uniloom.app/hooks/uniloom-hook" doctorIt prints one line per agent:
| Line | Means |
|---|---|
3 hook(s) OK · last session <when> | Working |
1 BROKEN of 3 | A hook cannot run. The lines under it say why and name the file |
3 hook(s) OK · no session recorded yet | Uniloom's part is sound. The agent was not used since, its hooks wait for your approval, or it cannot sign in |
Two common causes of silence:
- Codex runs no plugin hook until you trust it. Until then
codex plugin listsaysinstalled, enabledwhile nothing runs. - Gemini cannot sign in with a personal Google account. Use an API key or a Gemini Code Assist licence.
The dialog also shows what the agent's last session ran: this Uniloom and when, or another Uniloom install, named, behind an amber dot.
Last updated