Active Claude sessions ticker: cross-host session metadata surface #41

New issue

Closed

opened 2026-05-23 20:55:26 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-05-23 20:55:26 +00:00

Owner

Originally filed by @coilysiren on 2026-05-14T02:19:57Z - https://github.com/coilysiren/repo-recall/issues/127

Motivation

Kai is scoping a personal Pulse-style dashboard (inspired by danielmiessler/Personal_AI_Infrastructure). One desired panel is a live ticker of Claude Code sessions running across Mac, Windows, and kai-server, with click-through to the transcript. The dashboard is phone-first over Tailscale.

Rather than build session tracking inside the new dashboard, repo-recall should own the surface. The dashboard reads from repo-recall. This keeps session state in the tool that already knows about repo-scoped agent activity, and gives every future consumer (CLI, dashboard, future automations) one source of truth.

Proposed surface

A repo-recall subcommand or HTTP endpoint that returns active session metadata. JSON twin per kai-tech-prefs (human-readable default, --json for machine consumers, same fields both ways).

Per-session fields, at minimum:

host - mac, windows, kai-server, etc.
repo - repo name if the cwd resolves to one
cwd - absolute path on the originating host
started_at - ISO 8601
last_activity_at - ISO 8601, updated by heartbeat
transcript_path - absolute path on the originating host
session_id - stable id for click-through

Shape sketch, not final:

repo-recall sessions list - human table
repo-recall sessions list --json - array of the above
GET /sessions on the repo-recall HTTP surface, same JSON

Cross-host data path

Open question. How does kai-server learn about a session running on the Mac?

Strawman: each Claude session writes a heartbeat file on its origin host at ~/.repo-recall/sessions/<host>/<session_id>.json, refreshed every N seconds while the session is active. Aggregation options:

Shared filesystem reachable over Tailscale. Each host writes to ~/.repo-recall/sessions/<host>/ locally, and repo-recall sessions list on kai-server reads a Tailscale-mounted union of the three host dirs. Simple, no daemon, but needs a sync mechanism (rsync cron, or a mount).
Push to a central kai-server endpoint. Each host POSTs heartbeats to repo-recall on kai-server. Authoritative, no sync needed, but adds a network dependency to session startup.
Pull from each host. kai-server polls each host's ~/.repo-recall/sessions/ over Tailscale SSH. Read-only, no writes from non-server hosts, but adds latency.

Preference probably option 2 (push) for freshness and to avoid filesystem coupling, but worth pricing out all three.

The session-write side likely hooks into the Claude Code session lifecycle. A SessionStart hook to register, a periodic heartbeat (timer or PostToolUse hook), Stop or SessionEnd to deregister.

Stop condition

Stale heartbeat files get reaped. Default idle timeout in the 2 to 5 minute range, configurable. A session whose heartbeat is older than the timeout is filtered from the active list and either deleted or moved to a sessions/archive/ dir for later inspection.

Out of scope

Dashboard rendering. That lives in the Pulse-style dashboard project and consumes this surface.
Transcript pretty-printing or remote transcript fetch. Click-through can resolve locally on each host for now.
Auth model for the HTTP endpoint beyond what repo-recall already does. Trust the Tailscale boundary.

_Originally filed by @coilysiren on 2026-05-14T02:19:57Z - [https://github.com/coilysiren/repo-recall/issues/127](https://github.com/coilysiren/repo-recall/issues/127)_ ## Motivation Kai is scoping a personal Pulse-style dashboard (inspired by `danielmiessler/Personal_AI_Infrastructure`). One desired panel is a live ticker of Claude Code sessions running across Mac, Windows, and kai-server, with click-through to the transcript. The dashboard is phone-first over Tailscale. Rather than build session tracking inside the new dashboard, repo-recall should own the surface. The dashboard reads from repo-recall. This keeps session state in the tool that already knows about repo-scoped agent activity, and gives every future consumer (CLI, dashboard, future automations) one source of truth. ## Proposed surface A repo-recall subcommand or HTTP endpoint that returns active session metadata. JSON twin per `kai-tech-prefs` (human-readable default, `--json` for machine consumers, same fields both ways). Per-session fields, at minimum: - `host` - mac, windows, kai-server, etc. - `repo` - repo name if the cwd resolves to one - `cwd` - absolute path on the originating host - `started_at` - ISO 8601 - `last_activity_at` - ISO 8601, updated by heartbeat - `transcript_path` - absolute path on the originating host - `session_id` - stable id for click-through Shape sketch, not final: `repo-recall sessions list` - human table `repo-recall sessions list --json` - array of the above `GET /sessions` on the repo-recall HTTP surface, same JSON ## Cross-host data path Open question. How does kai-server learn about a session running on the Mac? Strawman: each Claude session writes a heartbeat file on its origin host at `~/.repo-recall/sessions/<host>/<session_id>.json`, refreshed every N seconds while the session is active. Aggregation options: 1. Shared filesystem reachable over Tailscale. Each host writes to `~/.repo-recall/sessions/<host>/` locally, and `repo-recall sessions list` on kai-server reads a Tailscale-mounted union of the three host dirs. Simple, no daemon, but needs a sync mechanism (rsync cron, or a mount). 2. Push to a central kai-server endpoint. Each host POSTs heartbeats to repo-recall on kai-server. Authoritative, no sync needed, but adds a network dependency to session startup. 3. Pull from each host. kai-server polls each host's `~/.repo-recall/sessions/` over Tailscale SSH. Read-only, no writes from non-server hosts, but adds latency. Preference probably option 2 (push) for freshness and to avoid filesystem coupling, but worth pricing out all three. The session-write side likely hooks into the Claude Code session lifecycle. A `SessionStart` hook to register, a periodic heartbeat (timer or `PostToolUse` hook), `Stop` or `SessionEnd` to deregister. ## Stop condition Stale heartbeat files get reaped. Default idle timeout in the 2 to 5 minute range, configurable. A session whose heartbeat is older than the timeout is filtered from the active list and either deleted or moved to a `sessions/archive/` dir for later inspection. ## Out of scope - Dashboard rendering. That lives in the Pulse-style dashboard project and consumes this surface. - Transcript pretty-printing or remote transcript fetch. Click-through can resolve locally on each host for now. - Auth model for the HTTP endpoint beyond what repo-recall already does. Trust the Tailscale boundary.

coilysiren referenced this issue

2026-05-23 20:55:28 +00:00

recall_action_required: define an ordering contract #60

coilysiren commented

2026-05-30 05:43:58 +00:00

Author

Owner

Iceboxed in the 2026-05-29 backlog burn-down: Cross-host ticker for speculative Pulse-style dashboard. Reopen anytime if it becomes real.

coilysiren closed this issue

2026-05-30 05:43:58 +00:00

coilysiren added the

label