tlive

tlive

Vendor-neutral, self-hosted remote-approval + live-monitoring for claude / codex. Approve tool calls, watch runs, take over typing — from Telegram, Feishu, or a web terminal.

English · 简体中文

Your claude / codex runs in your terminal as usual. tlive rides the open hook mechanism both vendors support to push status (and, when you turn it on, approval cards) to Telegram / Feishu, and serves a web dashboard + real terminal off your own machine — watch a run, reply to continue, send a screenshot, or take over typing, from any device. Works regardless of subscription or API key; your session and data never leave your machine.

Out of the box tlive watches and notifies (mode: notify, the safe default — it can never hold up a tool call). Flip on remote approval — hold each tool call so you can Allow/Deny it from your phone — with one command: tlive mode full (or let tlive setup offer it).

[!WARNING] v2.0 is a ground-up rewrite — breaking, with no migration. tlive is no longer the Agent-SDK IM bridge of v1.x and earlier: it no longer drives or owns your sessions, and the old bridge model, its config schema, and its commands (workspace, /use, chat-binding, …) are gone and unsupported. Don't try to carry an old ~/.tlive config forward — just run tlive setup fresh. The final SDK-bridge release is preserved at git tag v1.0-sdk-bridge.

Jump to: Quick start · Integration levels · Features · Install · Codex companion · Security · CLI · Config · Architecture

30 seconds to running

npm install -g tlive

tlive setup        # wizard: registers the tlive plugin with Claude Code's/
                    # Codex's own plugin manager (hooks, skill, /tlive:*
                    # commands), then IM credentials — or skip IM entirely
                    # and say "help me configure tlive" inside Claude/Codex
tlive start        # daemon up — prints web URLs + a QR code for your phone

tlive run claude   # (optional) wrap the session → live web terminal + preview card

Scan the QR once — the dashboard lists every session and streams each run. Turn on remote approval (tlive mode full) and, when a tool call needs approval, your IM gets a card with Allow / Deny / Always-allow buttons and the web card lights up red.

The two integration levels

	hooks/companion only (claude/codex as usual)	wrapped (tlive run claude/codex)
Approval cards (IM + web)	✅	✅
Stop-resume by IM reply	✅ (reply window)	✅
Session card on dashboard	✅ status / last message	✅ + live terminal preview
Real web terminal (xterm)	—	✅ multi-device, phone keys
IM text injection (quote-reply → typed into the pty)	—	✅
IM photo/file → agent	—	✅ (downloaded, path injected)
Web paste/drop upload	—	✅

Hooks-only always works — wrapping is pure addition. The Approval cards row needs remote approval on (tlive mode full); the default notify mode does everything else — live monitoring, turn-finished / waiting notifications, reply-to-continue, the web terminal — without ever holding a tool call. IM messages carry a label · prefix (the session's directory) but no longer mark wrapped vs. hooks-only visually — the continue card's own "Reply to continue" line makes the distinction moot for what you actually do.

What's in the box

• Posture — off / notify (default) / full / all. One coarse switch that sits above every fine toggle, in escalation order (how much tlive intercepts). off makes every hook a no-op (kill switch — no gating, notifications, monitoring, or daemon autostart). notify (default) watches and notifies but the shim can never hold or block an approval — every prompt stays 100% native (your local terminal dialog, or CC's own auto-deny when headless); when a prompt is waiting at the terminal it reports to the machine — desktop toast + read-only dashboard card, since only whoever is sitting there can act on it. IM stays quiet about these (a phone can't reach a terminal), except once ever per chat: the first time, a card explains why and offers the one-tap switch to full. The desktop toast has no on/off switch of its own — use your OS's Do Not Disturb to silence it temporarily, or tlive mode off to stop tlive entirely. full turns on remote approval for the main session — the posture that puts approvals on your phone: tlive holds each tool call so you can answer it from IM / desktop / dashboard (everything the Approvals bullet below describes), in parallel with the terminal dialog — first answer wins. Sub-agent prompts still pass through to the terminal. all holds sub-agent approvals too — the trade is that a held sub-agent has no terminal dialog until the window ends, because Claude Code awaits the hook before deciding whether to build one; use it only when nobody is at the keyboard, and tlive mode full goes back. Flip postures live with tlive mode off|notify|full|all (or /mode from IM — a bare /mode replies with a card listing the ladder and marking the current rung); the shim re-reads config on the next hook, so no restart or new session is needed, and tlive status shows the effective mode. Remote approval is opt-in by design — a freshly-installed tool must never be able to silently hang a workflow.
• Approvals (remote approval — mode: full or all) — a tool call that needs approval is held so you can answer it from IM buttons or the web card:
  • Parallel, first-answer-wins — on Claude Code the PermissionRequest hook fires alongside the local permission dialog; both are live, and answering at the keyboard resolves the remote card ("answered in terminal") within seconds. Nothing is ever auto-denied — an unanswered card just leaves the local prompt in charge.
  • Grace before sending — approvals.approvalGraceSec (default 10s, 0 disables) holds the card first, so answering right away means it's never sent; otherwise it stays answerable for ~24h.
  • Codex — tlive spawns/adopts a codex app-server companion and Codex TUIs auto-attach; the remote card and native prompt race the same way, with no window to configure (see Security).
  • Rendering — diffs/commands, risky-pattern flags, secret masking. Telegram cards stay restrained (bold titles, plain-text buttons; the only emoji anywhere is ⚠️ on a risky flag / error), with expandable quotes for long diffs — use a recent Telegram app for best rendering.
  • Power toggles — "Always allow <tool>" grants a per-tool pass (in-memory, cleared on restart; on Claude Code it answers the native dialog for you remotely); /trust on|off pauses approvals entirely.
  • Sub-agents pass through by default — on full, tlive returns {} and lets CC handle a backgrounded/async sub-agent natively, so its terminal dialog still appears exactly as it would without tlive. tlive mode all holds sub-agent approvals too, but the trade is real: CC resolves an async agent's hook before it decides whether to build a dialog, so a held sub-agent has no terminal box until the window ends — remote becomes the only answer path. Worth it only when nobody is at the keyboard; tlive mode full goes back.
• Answer AskUserQuestion from IM or the dashboard (Claude Code only) — CC fires a PermissionRequest for its own question tool; tlive relays it as a single-select or multi-select card (checkboxes, a live Submit (N) count, Skip) instead of Allow/Deny, on IM and on the dashboard session card alike. A call carrying several questions is walked one at a time — the card title reads Question 2/3, ← Back re-answers an earlier one, and the batch is submitted as a whole once the last question lands. The daemon owns that cursor, so answering on your phone advances the dashboard card too. The local question prompt still renders in parallel and always wins a race, so an answer given at the keyboard is never overridden — Skip just passes the tool through so the local prompt can be answered instead; it is not an auto-approval of anything. Codex has no equivalent concept.
• Resume — on Stop, reply to the IM message (or the web reply box) and the session keeps going. The card's excerpt sits inside a collapsed expandable quote (headings, lists, tables and code all survive the conversion — nothing is cut mid-word or mid-fence); while that card is still pending, the 60-second idle "waiting for your input" notification is suppressed instead of piling a second message on top of it.
• Daemon lazy-start — hooks-only sessions no longer need a manual tlive start first: on SessionStart (and when tlive run launches), the daemon is started detached (non-blocking) if it isn't already up. Disable with daemon.autoStart: false; tlive start still works and is unaffected.
• Failure alerts (Claude Code only) — PostToolUseFailure (a tool call errored) and StopFailure (session-level error, e.g. rate-limit/billing) push a ⚠️-prefixed IM message. Pure side-channel, never affects approval decisions; Codex has no equivalent hooks, so this only fires for Claude Code.
• In-session welcome hint (Claude Code only) — if IM isn't configured yet, SessionStart injects a one-line prompt into the session context nudging you to say "help me configure tlive"; it stops appearing once IM is set up. Not injected for Codex.
• Web terminal — tlive run <cmd> serves the pty at /s/<id>: xterm.js, multi-device with last-input sizing (whoever types owns the grid; everyone else sees a scaled view), screen rebuild for late joiners, soft-keyboard aware layout, view/input modes on touch, draggable key bar with Esc/Tab/⇧Tab/Ctrl-C/…, font size controls, copy-screen modal.
• Dashboard — / lists sessions: status badge, "stuck Nm" staleness, last assistant message, colored approval cards, live terminal previews, per-session mute, 📎 file upload, reply box.
• Send anything to the agent — IM quote-reply text, IM photos/files, terminal-page paste/drag-drop, dashboard 📎. All land as local paths in ~/.tlive/inbox (auto-swept: 48 h age / 256 MB total) and are typed into the pty via bracketed paste.

Install: plugins, not config writes

tlive setup (and tlive setup --hooks-only) no longer hand-edits ~/.claude/settings.json or ~/.codex/hooks.json — it orchestrates each vendor's own plugin manager:

• Claude Code: claude plugin marketplace add <bundled dir> then claude plugin install tlive@tlive --scope user.
• Codex (if codex is on PATH): codex plugin marketplace add <bundled dir> then codex plugin add tlive@tlive.

The Claude Code plugin bundles the 9 hook events, a tlive skill (usage, diagnostics, security model, under the /tlive:* namespace), and slash commands /tlive:url and /tlive:status. The Codex plugin ships only the skill — Codex has no hooks and needs none; its integration is the app-server companion (see below). The vendor copies the plugin into its