/agent-registry

name: agent-registry
description: Local Agent Registry — a standalone, dependency-free service that tracks running Claude Code (and other) agent instances. Agents self-register on startup and heartbeat while alive; the Electron overlay and Sutando dashboard read the live list. Use when you need to know which coding agents are running, where, and since when.

Agent Registry

A thin **local** service that tracks running agent instances. Claude Code instances register themselves on startup (via a SessionStart hook) and heartbeat while alive; consumers read the live list over a localhost HTTP API.

This is **not** the AG2 Workforce Hub app. It is a small local service that can *optionally* mirror its state to an AG2 hub using the hub connection layer (`ag2_workforce.hub.client`) — see "Optional: AG2 Hub mirroring" below — but the core service has zero third-party dependencies and works entirely offline.

Components

skills/agent-registry/
├── scripts/registry-service.py   # the HTTP service + SQLite store
├── scripts/registry-client.py    # CLI: register / heartbeat / deregister / list / watch
└── hooks/session-start.sh        # Claude Code SessionStart hook

• **DB:** `<workspace>/data/agent-registry.db` (SQLite, auto-created)
• **Discovery file:** `<workspace>/state/agent-registry.json` — written by the

service with the bound port so clients find it without a hardcoded port.

• **Port:** binds `127.0.0.1`, first free port from `7847` upward.

Running the service

It is **startable by Sutando** three ways, in order of preference:

1. **Auto-start (default).** Any `registry-client.py` call with `--autostart` launches the service detached if it is not already running. The SessionStart hook passes `--autostart`, so the first Claude Code session to start brings the registry up. 2. **From `startup.sh`.** For an always-on registry, add to `src/startup.sh`: `python3 skills/agent-registry/scripts/registry-service.py &` 3. **By hand:** `python3 skills/agent-registry/scripts/registry-service.py`

Registering Claude Code instances

Add the SessionStart hook to `.claude/settings.json`:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [
        { "type": "command",
          "command": "bash skills/agent-registry/hooks/session-start.sh" }
      ] }
    ]
  }
}

On session start the hook backgrounds `registry-client.py watch`, which registers the instance, heartbeats every 30s, and deregisters when the session ends. If it is killed ungracefully the entry ages out via heartbeat staleness (`> 90s` → `stale`; stopped/stale rows are pruned after 1h).

HTTP API

| Method | Path | Body | Returns | |--------|---------------|-------------------------------|--------------------------| | POST | `/register` | `{name, cwd, pid, host?, meta?}` | `{id}` | | POST | `/heartbeat` | `{id}` | `{ok, status}` | | POST | `/deregister` | `{id}` | `{ok}` | | GET | `/agents` | — | `{agents:[...], count}` | | GET | `/health` | — | `{ok, count, uptime}` |

Each agent record: `id, name, cwd, pid, host, started_at, last_heartbeat, heartbeat_age, status, meta`. `status` is `active` / `stale` / `stopped`.

CLI quick reference

C=skills/agent-registry/scripts/registry-client.py
python3 $C list                                  # show the registry
python3 $C register --name claude-code --pid $$  # register (prints id)
python3 $C heartbeat  --id <ID>
python3 $C deregister --id <ID>
python3 $C watch --name claude-code --pid <PID> --autostart   # used by the hook

Other agents (Kimi Code, etc.)

The service is agent-agnostic — `name` is free-form, so any agent registers the same way (`--name kimi-code`). What is agent-specific is the *registration trigger*: Claude Code uses a SessionStart hook; another agent needs its own equivalent (a startup hook, plugin, or a launch-command wrapper that runs `registry-client.py watch`).

Optional: AG2 Hub mirroring

To announce registry state to an AG2 hub, a future extension can open a `RemoteHubClient` (`ag2_workforce.hub.client`) and post agent join/leave events. This is deliberately *not* in the core service — it stays dependency-free and local-first. Add it as a separate module that subscribes to registry changes.