agent-registry

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).