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.