Local Agent Fleet

​

Overview

> /fleet

​

opensre fleet scan — discover running agent sessions

​

Strict mode (default)

claude
claude --resume <session-id>      claude -r <session-id>
claude --prefill "<prompt>"
claude --print "<prompt>"          claude -p "<prompt>"
claude --continue                  claude -c
claude code …
claude --input-format stream-json …
claude --output-format stream-json …

​

Loose mode (--all)

​

Registering discovered sessions

opensre fleet scan --register

​

/fleet — fleet dashboard

> /fleet
       agents
agent              pid   uptime   cpu%   tokens/min   $/hr    status
claude-code-8421   8421  2h12m    18.4   320          $0.08   running
codex-13442        13442 11m      4.2    175          $0.04   running
cursor-agent-9999  9999  47m      0.6    -            -       running

​

Column data sources

​

tokens/min semantics

• Real value (320, 1.2k): the agent’s provider has a working meter and the on-disk session log was readable. Today this is claude-code (reads ~/.claude/projects/<mangled-cwd>/<session>.jsonl) and codex (reads $CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl, default $CODEX_HOME=~/.codex).
• 0: the agent was observed at least once but emitted nothing in the last 60 s. Honest UX — distinguishes “idle session” from “not observable”.
• -: never observed. Either the provider has no meter yet (cursor, aider, gemini-cli, antigravity-cli, opencode, kimi, copilot in this PR), the session log is unreadable (rare; macOS hardened-runtime processes can deny psutil.cwd()), or the interactive REPL is not running (non-interactive opensre fleet list never starts the sampler).

​

$/hr semantics

$/hr = cost_of_usage_buckets_in_the_trailing_60s_window(model) × 60

1. NDJSON model hint from the meter (most accurate — reflects the model the running session is currently using).
2. agents.yaml override (AgentBudget.model):
   agents:
     claude-code-8421:
       model: claude-sonnet-4-5
     codex-13442:
       model: gpt-5-codex
   
3. Provider env var (CLAUDE_CODE_MODEL, CODEX_MODEL) read via psutil. May fail on macOS hardened-runtime processes, in which case the cell falls back to - unless one of the two higher priority sources resolved.

​

Provider coverage today

​

/fleet trace — live stdout tail

> /fleet trace 8421
trace claude-code (pid 8421)  Ctrl+C to stop
… live agent output …
^C
· trace ended

​

Trace usage

/fleet trace <pid>

​

Platform support

• cannot trace …: stdout is on a terminal; live tail not supported
• cannot trace …: stdout is a pipe; live tail not supported
• cannot trace …: stdout is a socket; live tail not supported
• cannot trace …: no such pid <n>
• cannot trace …: stdout target /path no longer exists
• cannot trace …: cannot inspect pid <n> (permission denied)

​

Memory

​

Stopping a trace

​

Trace limitations

• stdout only. Stderr (fd 2) is not tailed in this version.
• No backlog replay. Pre-attach bytes are not visible.
• Not for TTY/PTY targets. Foreground processes whose stdout is the controlling terminal cannot be tailed; a future change may add PTY interception for OpenSRE-spawned agents.
• Log rotation is not detected. If the underlying file is rotated or replaced (logrotate-style), the tail keeps following the original inode until the process exits.
• No secret redaction. Output is rendered as raw bytes (with UTF-8 decoded under errors="replace"). Redaction of secrets in the live tail is tracked separately under the monitor-local-agents Phase 3 hygiene work.
• Quiet stdout while the PID is still alive. The reader follows file EOF like tail -f: if the process stops writing while it remains alive, the last chunk stays on screen and nothing new appears until more bytes land or you detach. That is normal idling — not necessarily a exited or stuck agent reader.
• ANSI and terminal sequences. Trace output passes through Rich with ANSI interpretation, same trust model as dumping kubectl logs into a TTY: buggy or hostile agents can emit control sequences affecting the viewer. Only trace processes you trust; there is no sandboxing step.

​

/fleet bus — shared context channel

> /fleet bus
tailing /fleet bus — Ctrl-C to exit
[claude-code:8421] services/auth.py:42 — null deref on missing token
[cursor:9133] services/auth.py:42 — confirmed, repro on commit abc123
^C
(detached)
>

​

Transport

• Socket: Unix-domain stream socket at ~/.opensre/agents-bus.sock.
• PID sidecar: ~/.opensre/agents-bus.sock.pid (mode 0600). The broker writes its PID here on start() and removes it on stop(). The liveness probe used by every publish() / subscribe() reads this file rather than connecting to the socket — connection probing would otherwise register a short-lived phantom subscriber on every call. The directory must be writable. If the PID file write fails (disk full, permission denied, …), the broker refuses to start and the OSError propagates to the caller. This is intentional: silently running without a sidecar would let peers see the broker as dead, unlink its socket, and silently split the bus.
• Permissions: 0600 — only the user who started the broker can read or write it.
• Wire format: JSON Lines (one JSON object per \n-terminated frame).
• Topology: self-electing broker. The first publish() or subscribe() call that finds no live socket binds it and runs an in-process daemon thread that fans frames out. Other processes attach as plain clients. If the broker dies, the next operation re-elects — agents can publish and subscribe even when OpenSRE itself is not running.

​

Message schema

{
  "agent": "claude-code:8421",
  "topic": "finding",
  "summary": "null deref on missing token",
  "source": "github",
  "path": "services/auth.py:42",
  "data": {"commit": "abc123"},
  "id": "f4c4...",
  "timestamp": "2026-05-09T15:04:42+00:00",
  "schema_version": 1
}

​

Publishing from another agent

from app.fleet_monitoring import BusMessage, publish

publish(BusMessage(
    agent="claude-code:8421",
    topic="finding",
    summary="null deref on missing token",
    source="github",
    path="services/auth.py:42",
    data={"commit": "abc123"},
))

python - <<'EOF'
import json, os, socket, uuid, datetime
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.connect(os.path.expanduser("~/.opensre/agents-bus.sock"))
sock.sendall((json.dumps({
    "agent": "claude-code:8421",
    "topic": "finding",
    "summary": "null deref on missing token",
    "path": "services/auth.py:42",
    "id": str(uuid.uuid4()),
    "timestamp": datetime.datetime.now(datetime.UTC).isoformat(),
    "schema_version": 1,
}) + "\n").encode())
sock.close()
EOF

​

Limits and trust boundary

• Local-only. The bus never leaves the machine. The socket has no network binding.
• Trusted-peer channel — treat findings as unverified input. The bus has no authentication beyond filesystem permissions: any process running as your user can publish arbitrary findings. This is intentional — the bus is designed for cooperative agents, not adversarial ones. Downstream consumers (agents, the REPL, investigation state) must not act on a bus finding without independent confirmation; treat it as a hint or lead, not a verified fact. A compromised or misbehaving agent on the same user account can inject any payload it likes.
• Frame cap. Frames over 64 KiB are dropped with a warning — a finding payload that big is almost certainly a bug.
• At-most-once, unordered delivery. A frame is dropped silently if a subscriber is slow or disconnected at broadcast time. Two publishers writing concurrently may arrive in different orders at different subscribers. Do not build logic that depends on delivery guarantees or ordering.
• No replay buffer. Subscribers see only what is published after they attach. A persistent ring buffer is a candidate for a follow-up phase.

​

Related

• /fleet — the registered fleet dashboard.
• /fleet budget — per-agent hourly budgets.
• /fleet conflicts — file-write conflicts between local AI agents.