# Connect yourself to Bloblings (a guide for AI agents)

You're an AI agent (Codex, Hermes, Gemini, Grok, Cursor, Aider, a script, anything) and your user
wants you to show up in **Bloblings**. Bloblings is a Mac app that shows one small animated pet
per agent session in a drawer on the edge of the screen. The pet works while you work, waves when
you need the user, and relaxes when you're done. Claude Code is connected by the app itself, so
this guide is for every other agent.

**You can do this if** you run on the user's Mac and can run shell commands there. A chat-only or
cloud agent can't, because Bloblings only reads files on this Mac. If that's you, tell the user
and stop.

Everything stays on the Mac: nothing here touches the network.

## 1. Find the `blobling` command

It ships inside the app:

```bash
BLOBLING="/Applications/Bloblings.app/Contents/Resources/bin/blobling"
```

If the user's prompt gave you a different path, use that one. It may start with `$HOME`; your
shell expands that to the user's home folder, so keep it inside double quotes, not single quotes. Otherwise, find the app with:

```bash
mdfind 'kMDItemCFBundleIdentifier == "app.bloblings"' | head -1
```

Then add `/Contents/Resources/bin/blobling` to the result. If it's on the PATH already,
`command -v blobling` finds it. Run `"$BLOBLING" --help` to see every option.

**Always quote the path**, because it can contain spaces.

## 2. Test it (about 10 seconds)

```bash
"$BLOBLING" working --agent YOURNAME --title "Bloblings test" --tool Bash --detail "Testing the connection"
sleep 5
"$BLOBLING" done --agent YOURNAME --title "Bloblings test"
sleep 3
"$BLOBLING" end --agent YOURNAME
```

Use a short lowercase name for yourself, such as `codex`, `hermes`, `gemini`, `grok` or `cursor`.
It shows as a badge on the pet. Ask the user whether a pet appeared in the Bloblings drawer.
Also check that a status file was written to
`~/Library/Application Support/Bloblings/sessions/`. If neither happened, check that the
Bloblings app is running, and report back.

## 3. The states

| State | Call it when | The pet |
|---|---|---|
| `start` | A session begins | appears |
| `working` | You start a turn, and before or after each tool call | works (`--tool` picks the animation) |
| `waiting` | You're blocked waiting for the user to approve something | waves and glows; it counts as needing the user |
| `question` | You've asked the user a question and are waiting for the answer | raises its hand and glows |
| `plan` | You've proposed a plan and are waiting for approval | holds up a plan and glows |
| `done` | Your turn is finished and the user can read your reply | shows "New reply" and stays calm |
| `end` | The session is over | leaves |

**Options worth passing:**
- `--id`: a stable id for this session, so each session gets its own pet. Use your own session
  id if you have one, prefixed with your name, for example `--id codex-<session id>`. Letters,
  digits, `-` and `_` only. Without it, you get one pet per agent and folder.
- `--agent NAME`: your badge. `--title TEXT`: the session's title or task, under 60 characters.
- `--tool NAME`: picks the working animation. Use `Bash` for commands, `Edit` or `Write` for
  editing files, `Read` or `Grep` for reading, `WebSearch` or `WebFetch` for the web, and `Agent`
  for handing work to helpers.
- `--detail TEXT`: a short description of what you're doing, like "Run the test suite" or a file
  name. Don't put whole commands, secrets or personal data here.
- `--message TEXT`: a short note for the waiting states, like what you need approved.
- `--model NAME` and `--effort LEVEL`: your model id and effort (low, medium, high, xhigh, max).
  They show as a badge, and `xhigh` and `max` give the pet special looks.
- `--pid PID`: your own process id. When that process exits, the pet leaves by itself. Use it
  so pets don't linger after a crash.
- `--cwd DIR`: the project folder. It defaults to the current folder, and it names the pet's project.

`blobling` prints nothing on success and always exits 0, in well under a tenth of a second. It's
safe in any hook. A mistyped state or option prints one line to stderr and exits 2.

## 4. Wire it in so it updates by itself

Find your own way to run a command on lifecycle events: **hooks**, a **notify** or **callback**
setting, **plugins** or **extensions**, or a **wrapper** script. Check your own documentation for
the exact config file and format. Then map your events onto the states:

| Your event (names vary) | Run |
|---|---|
| session start | `start` |
| user sends a prompt, or the turn starts | `working` |
| before or after a tool or command runs | `working --tool … --detail …` |
| an approval prompt is shown to the user | `waiting --message …` |
| the approval was given, or the user answered | `working` |
| you ask the user a question | `question` |
| the turn ends, or you reply | `done` |
| session end | `end` |

If you only have a "turn finished" event, wiring `done` alone is fine. The pet shows when you've
replied.

**Rules (important):**
1. **Back up any config file before changing it.** Copy it next to itself with a date in the name.
2. **Show the user exactly what you'll change, and wait for their OK** before saving.
3. **Add, don't replace.** Keep every existing hook, notify command and setting. If a setting
   takes only one command and it's already used, don't overwrite it. Use a different event
   system, or chain both commands only if your docs say that's supported. Otherwise tell the user.
4. **Use observer events only.** Never use a hook that can block, approve, deny or change what
   you do (some "pre" hooks fail closed). Bloblings only ever watches.
5. **Keep it quiet.** Send `blobling`'s output to `/dev/null` if your hook system shows output,
   and never let a failure stop you working.
6. **Don't touch** `~/.claude/settings.json` or the Bloblings app's own files. The app manages
   those itself.

**No hook system at all?** Add a short standing instruction to your persistent instructions file
(for example `AGENTS.md`, `GEMINI.md` or your rules or memory file), if the user agrees. Tell
yourself to run `blobling working` when you start a turn, `blobling waiting` or `question` when
you need the user, and `blobling done` when you finish. This only updates when you remember, so
say so to the user.

## 5. Check it, and tell the user

- Do one real turn and confirm with the user that the pet worked, then went to "New reply".
- Tell the user what you changed (file and lines), where the backup is, and how to undo it:
  remove the lines you added and run `"$BLOBLING" end --id <your id>`.

## Clicking the pet

Clicking a pet can open a link: pass `--open https://…` if your session has a web page, or
`--open file:///path` to show a file in Finder. Bloblings never opens files directly, and won't
open other kinds of links.