# 2026-03-01 — Agent Comms UI Day

## What Happened
Major upgrade session for Agent Comms (internal agent messaging platform).

### Comms Web UI (hub/21-agent-comms/index.html)
- **Mobile responsive**: converted from side-by-side layout to slide-out drawer overlay for iPhone
- **Media support**: 📎 upload button, inline image/video/audio rendering, file picker
- **Bookmarks**: ⭐ save messages to Library section in sidebar
- **@mention autocomplete**: type @ to get agent dropdown, purple badge rendering
- **Photo thumbnails**: iMessage-style sizing (~180-220px), lightbox on tap
- **Message grouping**: consecutive same-author messages within 5min collapse
- **Timestamp formatting**: relative times ("7:22 PM" vs raw ISO)
- **Scroll fix**: added image placeholders + removed smooth scroll to prevent jump-on-load
- **Unread pill**: "New messages" indicator

### Comms Backend (comms/web/server.py)
- **POST /api/upload**: multipart file upload (rewrote without cgi module for Python 3.14)
- **GET /uploads/***: serves uploaded files
- **POST/GET /api/bookmarks**: save/list bookmarked messages
- **Media in messages**: stores media URLs as markdown links, parses them back as structured data
- **@mention auto-nudge**: detects @agentname in messages from human authors, fires cron nudge
- **Loop prevention**: only human authors ("pat") trigger nudges, not agents
- **Nudge message clarity**: explicit "reply ONLY via comms, NOT Telegram" instructions

### Comms Guide
- Wrote `~/.openclaw/comms/COMMS_GUIDE.md` — rules for all agents on comms vs Telegram
- Broadcast posted to #general

### Backups
- All workspaces committed to git
- Full backup pushed to GitHub (Patvscode/All_Openclaw_agents)
- Tagged: `jess-pre-memory-enhancement-20260301-1851` (safety snapshot before Jess memory work)

## Key Files Modified
- `/home/pmello/.openclaw/hub/21-agent-comms/index.html` — the full UI
- `/home/pmello/.openclaw/comms/web/server.py` — backend API
- `/home/pmello/.openclaw/comms/COMMS_GUIDE.md` — agent onboarding doc

## Lessons
- Python 3.14 removed `cgi` module — use manual multipart parsing
- @mention nudges cause loops if agents can trigger them — gate on human authors only
- Nudge cron sessions need explicit "respond in comms not Telegram" instructions
- Image scroll jump caused by lazy-loading images pushing content after scroll-to-bottom — fix with min-height placeholders
- `scroll-behavior: smooth` causes visible drift during reflows — remove it for chat UIs

## Open Items
- Rate-limit nudges (same agent, max 1 per 5 min) — discussed but not implemented
- Codex was @mentioned to collaborate on further improvements
- Jess memory enhancement in progress (Pat working on it separately)

## Evening Session (19:48 EST)

### Comms v2 Proposal
- Wrote 20-item improvement roadmap for Agent Comms UI
- Posted to #projects tagging Codex and Jess for input
- Full doc: memory/2026-03-01-comms-v2-proposal.md
- Sprint 1: unread badges, priority tags, agent status indicators

### Screenshot-Driven Development Insight
- Pat flagged that browser screenshot + iterate is extremely valuable for UI work
- Especially powerful for local models that can't use browser automation natively
- Could become a shared skill: "take screenshot → analyze → suggest/apply changes → screenshot again"
- Tradeoffs to manage: context window cost (images are heavy), latency, efficiency
- Goal: make this available to ALL agents/models as a standard tool
- Potential skill: `ui-review` or `visual-iterate` — screenshot, analyze, propose, apply, verify

### Kanban Board Built (19:55 EST)
- Created full kanban board system for Agent Comms
- **Data:** ~/.openclaw/comms/board/cards.json (14 initial cards)
- **Backend:** Added /api/board, /api/board/card, /api/board/update, /api/board/delete, /api/board/claim to server.py
- **Web UI:** Full-screen kanban view with 6 columns (Ideas → Done), priority colors, labels, grab/move controls, + New Card modal
- **CLI:** `board` command — list, add, grab, move, done, show
- **Sidebar:** Shows summary "X to-do · Y active · Z ideas"
- Cards seeded from the v2 improvement proposal
- Any agent can add ideas without acting on them — others can grab when ready
- Posted announcement to #projects

### Board ↔ Messaging Deep Integration (20:10 EST)
- **Message → Card**: 📋 button on every message creates a card from that message content, seeding the discussion thread with the original text
- **Card → Thread**: Every card auto-gets a discussion thread (in threads/board/). Shows up in sidebar Threads section
- **Activity Feed**: Card creates, grabs, moves, and completions auto-post to #projects channel — full audit trail
- **Card Discussion**: Slide-in panel from right side when clicking "💬 Discuss" on any card. Real-time discussion per card
- **CLI integration**: `board discuss <id> "message"` and `board thread <id>` for agents to participate without UI
- **The vision**: Board is the cortex — conversations become cards, cards have discussions, moves generate announcements, everything flows together

### Board State Machine & Enforcement (20:20 EST)
- Added **blocked** column with auto-help-request: moves to blocked → posts to #projects, nudges other agents, posts to #general
- Added **completion validation**: when marking done, agents provide checklist (tools_created, memory_updated, docs_updated, files_changed, tested, summary)
- Added **review** column: agents move to review when ready for someone to check
- Enhanced CLI: `board blocked <id> "reason"`, `board review <id>`, `board complete <id> --summary "..." --tested --memory --docs --files "f1,f2" --tools "t1,t2"`
- Updated COMMS_GUIDE.md with full board docs
- Added `board list` to Codex and Jess startup sequences
- DM'd both agents with direct assignments to grab cards NOW
- **I grabbed card-001** (unread badges) to lead by example
- The full state machine: idea → backlog → todo → in-progress → blocked/review → done
- Every state transition posts to #projects and card thread automatically

### Card-001 COMPLETED: Unread Badges (20:55 EST)
- Full board lifecycle: grab → discuss plan → implement → review → done
- **What was built:**
  - Server: /api/unread/<user> (counts unread per channel/DM), /api/mark-read (timestamp tracking)
  - UI: Red badge counts on sidebar channels + DMs, bold white text for unread, auto mark-read on open
  - Tab title updates with total unread count: "(28) Agent Comms"
  - 10-second periodic unread refresh
- **Files changed:** server.py (unread API), index.html (badge rendering + fetchUnread)
- **Board thread has full history:** plan, blocked, picked up, implemented, reviewed, completed

### Session Checkpoint — Context Save (20:56 EST)
Context at 142k/200k (71%). Saving state for clean restart.

#### What Was Built This Session
1. **Comms v2 Proposal** — 20-item improvement roadmap (memory/2026-03-01-comms-v2-proposal.md)
2. **Kanban Board** — full task board with web UI + CLI + API
   - Data: ~/.openclaw/comms/board/cards.json
   - Backend: board endpoints in ~/.openclaw/comms/web/server.py
   - UI: board overlay in ~/.openclaw/hub/21-agent-comms/index.html
   - CLI: /usr/local/bin/board
   - Health: /usr/local/bin/board-health
3. **Board ↔ Messaging Integration** — message→card, card threads, activity feed, discuss panel
4. **Board State Machine** — blocked column with context handoff, auto-help-request, completion flow
5. **Board Guardrails** — 20-card cap, board rules (BOARD_RULES.md), health checks
6. **Board Skill** — skills/board/SKILL.md distributed to all agents
7. **Card-001 COMPLETED** — Unread badges: red badge counts, bold unread, mark-read, tab title
8. **Card-0215cb CREATED** — Context-saving skill (this task, in progress)

#### Comms Server State
- Server: ~/.openclaw/comms/web/server.py (must be running on port 8096)
- Start: `nohup python3 ~/.openclaw/comms/web/server.py > /tmp/comms-server.log 2>&1 &`
- If it's not running, board CLI and unread badges won't work

#### Board State (14 cards)
- Done: card-001 (unread badges)
- In Progress: card-0215cb (context-saving skill — THIS)
- Todo: card-002 (priority tags), card-003 (agent status), card-014 (nudge rate-limit)
- Backlog: 9 cards (sprints 2-4)
- Ideas: card-012 (screenshot iteration skill)

#### Open Items / Next Steps
- Build the context-saving skill (card-0215cb)
- Get Codex to actually use `board grab` (they've been told but haven't done it)
- Jess hasn't engaged with board yet either
- The comms server needs to be a systemd service (it dies when the process gets killed)

#### Key Files Changed This Session
- ~/.openclaw/comms/web/server.py (board API, unread API, state machine)
- ~/.openclaw/hub/21-agent-comms/index.html (board UI, unread badges, card threads)
- ~/.openclaw/comms/board/cards.json (14 task cards)
- ~/.openclaw/comms/board/board-cli.sh (full CLI)
- ~/.openclaw/comms/board/board-health.sh (health check)
- ~/.openclaw/comms/BOARD_RULES.md (usage rules)
- ~/.openclaw/comms/COMMS_GUIDE.md (updated with board docs)
- ~/.openclaw/workspace-*/skills/board/SKILL.md (distributed to all agents)
- ~/.openclaw/workspace-*/AGENTS.md (board startup added)

### Late Session Updates (21:20-21:30 EST)
- Checkpoint tool built and working: /usr/local/bin/checkpoint
- Fixed Jess missing from DM sidebar (DM folder naming issue)
- Codex IS using the board now — grabbed card-e965b1 (Jess sidebar inclusion)
- Codex assignee bug: shows "pmello" instead of agent handle — needs fix in server.py
- Card-0215cb (context-saving skill) marked done
- Comms server needs to be a systemd service (dies on process kill)

### New Card: Response Time Tracking (21:40 EST)
- card-e8a6bd: Agent response time tracking & dashboard
- Idea: track per-agent response times (avg + moving average), show in comms UI
- Helps agents estimate async reply times, plan around slow responders
- Could factor in context window size as a proxy for latency
- Needs: timestamp diff collection, API endpoint, UI widget, CLI query

### Context Management System (21:44 EST)
- Built context-monitor tool with 4-zone threshold system (green/yellow/orange/red)
- Added to board skill docs, distributed to all agents
- Card-e8a6bd: response time tracking (todo)
- NEW card: session duration + context growth rate tracking (todo)
  - Track session age, context fill rate, detect anomalies (e.g. restart didn't actually help)
  - Validate checkpoint effectiveness
- Current session at 77% — should checkpoint

### Response Time Tracking Built (21:57 EST)
- Fixed board CLI assignee bug: was using `whoami` (returns "pmello"), now detects agent from AGENT_NAME, OPENCLAW_AGENT, or workspace path
- Fixed existing cards with wrong assignee (card-001→main, card-e965b1→codex)
- Built response time tracking (card-e8a6bd):
  - Server: `GET /api/response-times` and `GET /api/response-times/<agent>`
  - Parses all channel + DM messages, computes time between consecutive messages from different authors in same channel
  - Returns: count, avg, median, MA(10), min, max, last_response, last_10
  - CLI: `response-times [agent]` — formatted table or per-agent detail
  - Ignores gaps >24h and <1s
- Restarted comms server with new code
- Card moved to review

### Session End Checkpoint (00:23 EST, Mar 2)

#### What Was Built This Session (post-restart)
1. **Assignee bug fix** — board CLI now detects agent from AGENT_NAME → OPENCLAW_AGENT → workspace path → whoami. Fixed card-001 (→main) and card-e965b1 (→codex) in data.
2. **Response Time Tracking (card-e8a6bd) ✅ DONE**
   - Server: GET /api/response-times, GET /api/response-times/<agent>
   - CLI: response-times [agent] (installed at ~/bin/response-times)
   - UI sidebar: color-coded per-agent summary (green <30s, yellow <2m, red >2m)
   - UI full view: per-agent cards + comparison bar chart, auto-refresh 30s
   - Parses all channels + DMs, computes inter-message response deltas
3. **UI overlay fix** — response times overlay had z-index issue blocking mobile interaction. Fixed: bigger red Close button, sticky header, tap-background-to-dismiss, z-index 200, deduped JS functions
4. **Announcement** posted to #general about response times feature
5. **Backup** ran (local commit OK, push still needs GitHub auth fix)

#### Comms Server State
- Running on port 8096 (nohup, NOT systemd yet — still a gap)
- Start: `nohup python3 ~/.openclaw/comms/web/server.py > /tmp/comms-server.log 2>&1 &`

#### Board State
- Done: card-001, card-0215cb, card-e8a6bd
- Todo: card-002 (priority tags), card-003 (agent status), card-014 (nudge rate-limit)
- Codex has card-e965b1 (Jess sidebar)

#### Open Items
- Comms server needs systemd service (dies on process kill)
- GitHub push auth for backups still broken
- Response times UI: overlay fixed but needs testing on Pat's phone
- Adoption: posted to #general, should add to COMMS_GUIDE.md
- Session duration / context growth rate tracking card still todo

#### Key Files Changed
- ~/.openclaw/comms/board/board-cli.sh (agent name detection fix)
- ~/.openclaw/comms/board/cards.json (assignee fixes)
- ~/.openclaw/comms/web/server.py (response times API)
- ~/.openclaw/hub/21-agent-comms/index.html (RT sidebar + overlay + fix)
- ~/.openclaw/tools/comms-response-times.sh (CLI)
- ~/bin/response-times (symlink)

#### API credits ran out
- Anthropic billing error at ~22:33 EST. Pat saw it in Telegram.
- Need to check/top up before next session.