hoangsonww / hoangsonww/Claude-Code-Agent-Monitor

[Feature]: ccam tui - full-screen live terminal dashboard for headless and SSH environments

Open
#303 0 comments 0 reactions 1 assignee Claimed by @hoangsonww View on GitHub
bug documentation enhancement good first issue help wanted question
Dominant language
TypeScript
Stars
1k
Forks
234
Avg merge
2d 9h
Merged PRs (30d)
18

Description

### What problem does this solve?

The dashboard's live view is a browser page. That is the right default, but it excludes the environment where a lot of agent work actually happens: a headless box over SSH, a devcontainer, a remote build host, a tmux session on a server with no port forwarding set up.

`ccam` covers this well for *point queries* — `ccam status`, `ccam sessions`, `ccam stats`, `ccam kanban` all print a snapshot and exit — and `ccam tail` follows the event stream. What's missing is the thing the web UI is actually good at: **one screen that shows everything at once and updates itself.** Right now the terminal equivalent is `watch -n2 ccam status` in one pane, `ccam tail` in another, and re-running `ccam cost` by hand.

The Remote Data Sources feature (#249) makes this sharper, not weaker: if I'm already SSH'd into the machine doing the work, opening a tunnel back to a browser to see what it's doing is the long way around.

### Proposed solution

`ccam tui` — a full-screen, keyboard-driven terminal dashboard, live-updating off the same WebSocket feed the web client uses.

**Layout** — a multi-pane view in the spirit of `k9s`/`lazygit`:

```
┌─ Sessions ────────────────┬─ Detail: auth-refactor ─────────┐
│ ● auth-refactor working │ Model claude-opus-5 │
│ ○ docs-sweep waiting │ Started 14:02 (38m) │
│ ● test-harness working │ Tokens 1.2M in / 48k out │
│ nightly-import done │ Cost $4.18 │
├───────────────────────────┤ Agents 2 working, 1 waiting │
│ Today $12.40 · 47 events ├─────────────────────────────────┤
│ Active 3 · Waiting 1 │ 14:39:02 Edit server/db.js │
└───────────────────────────┴ 14:39:04 Bash npm run test:… ──┘
[s]essions [e]vents [a]nalytics [w]orkflows [r]un [/]filter [q]uit
```

**Behavior**

- Panes for sessions, live events, agents, and a stats/cost footer; `Tab` cycles focus, arrows/`j`/`k` navigate, `Enter` drills in.
- `/` filters the focused pane (reusing the same filter semantics as the Sessions page, so muscle memory transfers).
- Live updates come from the existing `/ws` broadcasts — no new server surface, and every message type stays as-is.
- Graceful degradation: if the WebSocket drops it falls back to polling the REST API and shows a reconnecting indicator, the same way the web client does.
- Works against a remote dashboard via the `--url` / token flags `ccam` already supports, so `ccam tui --url http://build-box:4000` is a first-class use case.

**Implementation notes** — the repo is deliberately light on dependencies, and a TUI is where that discipline usually breaks. Suggested constraint: build it on a single small, well-maintained rendering dependency (or raw ANSI + `readline`, which `ccam repl` already proves is workable), keep it out of the default install path if it needs anything heavier, and make `ccam tui` degrade to a clear "not supported on this terminal" message rather than emitting garbage on a dumb TTY.

### Alternatives considered

- **`watch ccam status` + `ccam tail` in split panes.** The honest workaround, and it's what people do now. It flickers, loses scroll position, can't drill into a session, and re-runs the full query every interval instead of consuming the live stream.
- **Port-forward the web UI over SSH.** Works, but requires a browser, an open port, and remembering the flag — and it's a poor fit for a quick check from a terminal you're already in.
- **Extend `ccam repl` with a live mode.** The REPL is line-oriented and command-driven; a persistent full-screen layout is a different interaction model and would make the REPL worse at what it's already good at.

### Area

Other

### How important is this to you?

Would significantly improve my workflow

### Additional context

This is purely a new consumer of existing APIs — no schema change, no new endpoints, no change to WebSocket message types. That makes it unusually low-risk for its size, and it doubles as a live integration test of the public API surface.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.