# Agent Habitat

A live desk for the coding agents I run in tmux on my Mac. A small service finds every Claude Code, Codex and OpenCode window by itself and shows each one as a row: what it is doing now, the task it last reported, and whether it has gone quiet. Agents report through hooks and a one-line command, and nothing ever reads their screens or prompts. The Fedora screen shows the desk over the tailnet.

**Status:** Private · Agents · 2026

- **Local checkout:** `/Users/simon/Developer/agent-habitat` (branch `main`, last commit dd79af7, 2026-10-31 — Record existing Habitat dashboard before live feed)
- **Uncommitted changes:** 11 file(s) at brief generation time
- **Repository:** https://github.com/ShimonNavon/agent-habitat
- **On another machine:** `git clone https://github.com/ShimonNavon/agent-habitat` — the paths below are Simon's Mac
- **Live:** http://100.125.119.73:8765/
- **Where it runs:** Python 3 on the Mac. SQLite at ~/.local/share/agent-habitat/events.db, backups in ~/.local/share/agent-habitat/backups
- **Note:** Private, tailnet only; no public URL.

## Stack

Python 3 standard library (http.server, sqlite3), tmux and ps observation, macOS launchd user agents, Single-file HTML desk

## Start here

- `board.py` — HTTP server: / (desk), /api/feed, POST /api/event, /health, /legacy; client, Host and Origin gate
- `live_store.py` — Finds agent panes, derives run identity from pane and process start, SQLite event store and feed merge
- `live.html` — The live desk page (inline CSS/JS)
- `hooks/` — emit (hook adapter), report (agent-report), install.py for Claude Code, Codex and OpenCode
- `setup_service.py` — Installs the launchd service and nightly backup job
- `backup_db.py` — SQLite online backup, keeps 7 daily copies
- `habitat` — CLI: up, board, status, doctor, log

## Commands

- **Health:** `curl -s http://127.0.0.1:8765/health`
- **Feed:** `curl -s http://127.0.0.1:8765/api/feed`
- **Report a task:** `python3 hooks/report "what I am doing"  (--done RESULT, --state STATE, --show)`
- **Install or refresh the service:** `python3 setup_service.py --install`
- **Install hooks (Simon runs it):** `python3 hooks/install.py install   # undo: python3 hooks/install.py uninstall`
- **Tests:** `python3 -m unittest test_live_feed.py && python3 -m unittest hooks/test_hooks.py`
- **Show on Fedora:** `habitat board`

## Deploy and where it runs

- Mac launchd user agent com.simon.agent-habitat: board.py on 0.0.0.0:8765, KeepAlive; accepts loopback and Tailscale 100.64.0.0/10 clients only
- Tailnet URL http://100.125.119.73:8765/ (the Mac); no public tunnel
- com.simon.agent-habitat.backup runs nightly at 03:15

## Current state

Live Desk running on the Mac since 2026-10-31 16:44 (launchd). Hooks are built and tested, not installed yet: Simon runs hooks/install.py install. Docs being finished; repo changes not yet committed.

## Watch out

- Must run on the Mac beside the tmux server it watches; Fedora only displays it.
- No caller authentication. The server derives the run from tmux and process start and refuses clients off loopback and the tailnet, but any allowed client can report for any live pane.
- Hooks set state and activity only; only an explicit report sets the task or result.
- Agents in auto mode are blocked from installing hooks into agent settings, so Simon runs install.py.
- Hermes windows are not detected yet: its launcher runs python3 -I -c with no script path.
- Codex asks to trust new hooks once in /hooks; OpenCode reports only after a restart.

## Tags

tmux, Live status, Agent hooks, SQLite, launchd, Tailscale

---

Brief generated 2026-11-08 from `~/Developer/my-projects/context/`. Canonical URL: https://projects.navonsimon.com/context/agent-habitat.md
