tvagent

Private Android TV dashboard service for local coding-agent activity.

tvagent runs on the Mac or workstation where Codex, Claude Code, and OpenCode are active. The Android TV app connects over Tailscale, renders the latest snapshot immediately, then stays current through Server-Sent Events.

What It Exposes

GET /health
GET /snapshot
GET /events

/snapshot returns the current dashboard state as JSON.

/events is an SSE stream. The TV opens one long-lived HTTP request and receives frames such as:

event: snapshot
event: task.started
event: task.updated
event: task.completed
event: metrics.updated
event: heartbeat

What It Scans

The service reads local files and databases only:

| Source | Local path | | --- | --- | | Codex | ~/.codex/sessions | | Claude Code | ~/.claude/projects | | OpenCode | ~/.local/share/opencode/opencode.db | | tvagent index | ~/.local/share/tvagent/tvagent.db |

Missing stores produce warnings in the snapshot instead of failing the whole dashboard.

The tvagent SQLite index is local cache state. If it is deleted, the service rebuilds it from the source logs for the configured history window.

Dashboard Shape

The TV contract is designed for a simple first screen:

• three metric cards: today tokens, today sessions, estimated today work minutes
• six task cards by default
• active tasks first, then recently completed tasks
• active means updated inside the last 15 minutes
• each task includes model and may include thinkingLevel when the source exposes reasoning effort

The defaults can be tuned with environment variables:

| Variable | Default | Notes | | --- | ---: | --- | | TVAGENT_HOST | 0.0.0.0 | Bind address. Use the Mac's Tailscale address or 0.0.0.0. | | TVAGENT_PORT | 3333 | HTTP port. | | TVAGENT_ACTIVE_WINDOW_MINUTES | 15 | Active session window. | | TVAGENT_MAX_TASKS | 6 | Number of task cards in the snapshot. | | TVAGENT_HISTORY_DAYS | 1 | Local history window scanned for dashboard state. | | TVAGENT_REFRESH_MS | 30000 | Background index refresh and snapshot broadcast cadence. | | TVAGENT_HEARTBEAT_MS | 15000 | SSE heartbeat cadence. | | TVAGENT_TIME_ZONE | local system zone | Time zone used for today tokens, sessions, and work minutes. Snapshot timestamps remain UTC. | | TVAGENT_DB_PATH | ~/.local/share/tvagent/tvagent.db | SQLite index path. Override this for local clones or tests. | | TVAGENT_INDEX_SAFETY_WINDOW_MS | 300000 | Incremental index overlap for clock and flush delays. |

Development

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm dev

Smoke the endpoints:

curl http://127.0.0.1:3333/health
curl http://127.0.0.1:3333/snapshot
curl -N http://127.0.0.1:3333/events

On Android TV, point the app at the Mac's Tailscale IP:

http://100.x.y.z:3333/snapshot
http://100.x.y.z:3333/events

Background Service

This repo does not install or write a launchd plist. To see a plist you can review and install yourself, run:

pnpm build
pnpm launchd:example

If you choose to use it, redirect the output to your own file under ~/Library/LaunchAgents/, review the paths and environment variables, then load it with launchctl. Keep the plist under your control so this repo never mutates your Mac login services automatically.