Skip to content

programmatic-api.md

Latest commit

 

History

History
164 lines (126 loc) · 5.12 KB

programmatic-api.md

File metadata and controls

164 lines (126 loc) · 5.12 KB

Programmatic Metadata API

opensessions exposes HTTP endpoints that let agents, scripts, and CI pipelines push custom metadata to the TUI sidebar. This is the programmatic surface — your tools can self-report status, progress, and structured logs without opensessions needing a dedicated watcher.

Endpoints

All endpoints accept POST with Content-Type: application/json on 127.0.0.1:7391.

POST /set-status

Set a status pill on a session. Shows in both the session card and the detail panel.

# Set status
curl -sS -X POST http://127.0.0.1:7391/set-status \
  -H 'content-type: application/json' \
  -d '{"session":"api","text":"Indexing","tone":"info"}'

# Clear status
curl -sS -X POST http://127.0.0.1:7391/set-status \
  -H 'content-type: application/json' \
  -d '{"session":"api","text":null}'
Field Type Required Description
session string yes Mux session name
text string | null yes Status text, or null to clear
tone string no One of neutral, info, success, warn, error

POST /set-progress

Set a progress indicator on a session. Shows as a compact summary (e.g. 3/10 or 75%).

# Set progress with current/total
curl -sS -X POST http://127.0.0.1:7391/set-progress \
  -H 'content-type: application/json' \
  -d '{"session":"api","current":3,"total":10,"label":"files"}'

# Set progress with percent
curl -sS -X POST http://127.0.0.1:7391/set-progress \
  -H 'content-type: application/json' \
  -d '{"session":"api","percent":0.75,"label":"deploying"}'

# Clear progress
curl -sS -X POST http://127.0.0.1:7391/set-progress \
  -H 'content-type: application/json' \
  -d '{"session":"api","clear":true}'
Field Type Required Description
session string yes Mux session name
current number no Current step
total number no Total steps
percent number no Progress as 0.0–1.0 (alternative to current/total)
label string no Short label shown next to the number
clear boolean no Set to true to clear progress

POST /log

Append a structured log entry to a session. Last 8 entries are visible in the detail panel.

curl -sS -X POST http://127.0.0.1:7391/log \
  -H 'content-type: application/json' \
  -d '{"session":"api","message":"Build started","source":"ci","tone":"info"}'
Field Type Required Description
session string yes Mux session name
message string yes Log message (max 500 chars, truncated)
tone string no One of neutral, info, success, warn, error
source string no Source label (e.g. ci, build, agent)

POST /clear-log

Clear all log entries for a session.

curl -sS -X POST http://127.0.0.1:7391/clear-log \
  -H 'content-type: application/json' \
  -d '{"session":"api"}'

POST /notify

Send a notification (currently appends to logs with highlighting). Same fields as /log.

curl -sS -X POST http://127.0.0.1:7391/notify \
  -H 'content-type: application/json' \
  -d '{"session":"api","message":"Deploy complete","tone":"success","source":"cd"}'

How It Renders

Session card — A compact summary line showing status text + progress:

  Indexing · 3/10 files

Detail panel — Full status, progress, and recent log entries with tone-colored icons:

ℹ Indexing
  · 3/10 files
ℹ [ci] Build started
✓ [ci] Tests passed
✗ [ci] Lint failed

Tones

Tone Icon Color
neutral · gray
info ℹ blue
success ✓ green
warn ⚠ yellow
error ✗ red

Retention

  • Status and progress are in-memory only — cleared on server restart.
  • Logs are capped at 50 entries per session (oldest are dropped).
  • Metadata for deleted sessions is auto-pruned.
  • Messages are truncated: status at 100 chars, logs at 500 chars.

Example: Build Script

#!/bin/bash
SESSION=$(tmux display-message -p '#{session_name}')
URL="http://127.0.0.1:7391"

curl -sS -X POST "$URL/set-status" \
  -H 'content-type: application/json' \
  -d "{\"session\":\"$SESSION\",\"text\":\"Building\",\"tone\":\"info\"}"

curl -sS -X POST "$URL/set-progress" \
  -H 'content-type: application/json' \
  -d "{\"session\":\"$SESSION\",\"current\":0,\"total\":3,\"label\":\"steps\"}"

npm run build 2>&1 && {
  curl -sS -X POST "$URL/log" \
    -H 'content-type: application/json' \
    -d "{\"session\":\"$SESSION\",\"message\":\"Build succeeded\",\"tone\":\"success\",\"source\":\"build\"}"
} || {
  curl -sS -X POST "$URL/log" \
    -H 'content-type: application/json' \
    -d "{\"session\":\"$SESSION\",\"message\":\"Build failed\",\"tone\":\"error\",\"source\":\"build\"}"
}

# Clear when done
curl -sS -X POST "$URL/set-status" \
  -H 'content-type: application/json' \
  -d "{\"session\":\"$SESSION\",\"text\":null}"

curl -sS -X POST "$URL/set-progress" \
  -H 'content-type: application/json' \
  -d "{\"session\":\"$SESSION\",\"clear\":true}"