Skip to content
Back to search

tlive

Self-hosted remote approvals + live monitoring for Claude Code / Codex — via Telegram, Feishu, or a web terminal. Any subscription or API key.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/y49--tlive/badge.svg)](/listings/y49--tlive)

HTML

<a href="/listings/y49--tlive"><img src="/api/listings/y49--tlive/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

`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 own cache (`~/.claude/plugins/cache` for Claude Code, `$CODEX_HOME/plugins/cache/tlive/tlive/local/` for Codex) — after upgrading `tlive` itself, re-run `tlive setup --hooks-only` to refresh that copy.

Ran a pre-plugin dev build that wrote hooks directly into vendor config? Remove those entries by hand once (they'd double-fire otherwise) — see the appendix in [docs/manual-hooks.md](docs/manual-hooks.md). tlive itself never edits your vendor config files.

**Old vendor versions without a plugin CLI**: `tlive setup` detects this (`claude plugin list` / `codex plugin marketplace add` failing) and prints a pointer to the manual config appendix: [docs/manual-hooks.md](docs/manual-hooks.md) — full `settings.json` hooks block and `hooks.json` you can paste in by hand.

Uninstalling (`npm uninstall -g tlive`) best-effort removes the plugin via each vendor's CLI and cleans up any leftover direct-write hooks; your `~/.tlive` config and logs are preserved. Full purge and **migrating from v0.x/v1** steps: [docs/uninstall.md](docs/uninstall.md).

**Try it from GitHub first** (no npm publish needed): `claude plugin marketplace add y49/tlive` then `claude plugin install tlive@tlive` pulls the plugin (hooks/skill/commands) straight from the repo's root `marketplace.json`. You still need the engine itself — `npm i -g tlive` — for the daemon/CLI the hooks call into.

`tlive setup` asks **which vendor(s)** to install the plugin into when it detects both `claude` and `codex` on `PATH`: `[1] Claude Code [2] Codex [3] both (default)`. Plugin registration always runs before the IM credential prompts, and the IM step is fully skippable — press Enter through it and later say "help me configure tlive" inside Claude Code or Codex — or, in Claude Code, run `/tlive:setup` — to have the AI walk you through it interactively (Codex has no slash commands; use the phrase).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 7 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "tlive",
  3. "owner": { "name": "tlive" },
  4. "plugins": [
  5. { "name": "tlive", "source": "./plugins/claude/plugins/tlive", "description": "IM approvals + web terminal for Claude Code / Codex (hooks, skill, /tlive commands)" }
  6. ]
  7. }
README.md · README · 461 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # tlive
  3. **Vendor-neutral, self-hosted remote-approval + live-monitoring for `claude` / `codex`.**
  4. Approve tool calls, watch runs, take over typing — from Telegram, Feishu, or a web terminal.
  5. [![npm version](https://img.shields.io/npm/v/tlive)](https://www.npmjs.com/package/tlive)
  6. [![CI](https://github.com/y49/tlive/actions/workflows/ci.yml/badge.svg)](https://github.com/y49/tlive/actions/workflows/ci.yml)
  7. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  8. [![LINUX DO](https://img.shields.io/badge/LINUX%20DO-Community-blue)](https://linux.do)
  9. [English](README.md) · [简体中文](README_CN.md) · [繁體中文](README_ZH_TW.md)
  10. </div>
  11. > Your `claude` / `codex` runs in your terminal as usual. tlive rides the
  12. > **open hook mechanism** both vendors support to push status (and, when you
  13. > turn it on, approval cards) to **Telegram / Feishu**, and serves a **web
  14. > dashboard + real terminal** off your own machine — watch a run, reply to
  15. > continue, send a screenshot, or take over typing, from any device. Works
  16. > **regardless of subscription or API key**; your session and data never
  17. > leave your machine.
  18. >
  19. > Out of the box tlive **watches and notifies** (`mode: notify`, the safe
  20. > default — it can never hold up a tool call). Flip on remote approval —
  21. > hold each tool call so you can Allow/Deny it from your phone — with one
  22. > command: **`tlive mode full`** (or let `tlive setup` offer it).
  23. > [!WARNING]
  24. > **v2.0 is a ground-up rewrite — breaking, with no migration.** tlive is no
  25. > longer the Agent-SDK IM *bridge* of v1.x and earlier: it no longer drives or
  26. > owns your sessions, and the old bridge model, its config schema, and its
  27. > commands (`workspace`, `/use`, chat-binding, …) are **gone and unsupported**.
  28. > Don't try to carry an old `~/.tlive` config forward — just run `tlive setup`
  29. > fresh. The final SDK-bridge release is preserved at git tag `v1.0-sdk-bridge`.
  30. **Jump to:** [Quick start](#30-seconds-to-running) · [Integration levels](#the-two-integration-levels) · [Features](#whats-in-the-box) · [Install](#install-plugins-not-config-writes) · [Codex companion](#codex-the-app-server-companion) · [Security](#security-model) · [CLI](#cli) · [Config](#config-tliveconfigjson) · [Architecture](#architecture)
  31. ## 30 seconds to running
  32. ```bash
  33. npm install -g tlive
  34. tlive setup # wizard: registers the tlive plugin with Claude Code's/
  35. # Codex's own plugin manager (hooks, skill, /tlive:*
  36. # commands), then IM credentials — or skip IM entirely
  37. # and say "help me configure tlive" inside Claude/Codex
  38. tlive start # daemon up — prints web URLs + a QR code for your phone
  39. tlive run claude # (optional) wrap the session → live web terminal + preview card
  40. ```
  41. Scan the QR once — the dashboard lists every session and streams each run.
  42. Turn on remote approval (`tlive mode full`) and, when a tool call needs
  43. approval, your IM gets a card with **Allow / Deny / Always-allow** buttons and
  44. the web card lights up red.
  45. ## The two integration levels
  46. | | hooks/companion only (`claude`/`codex` as usual) | wrapped (`tlive run claude`/`codex`) |
  47. |---|---|---|
  48. | Approval cards (IM + web) | ✅ | ✅ |
  49. | Stop-resume by IM reply | ✅ (reply window) | ✅ |
  50. | Session card on dashboard | ✅ status / last message | ✅ + live terminal preview |
  51. | Real web terminal (xterm) | — | ✅ multi-device, phone keys |
  52. | IM text injection (quote-reply → typed into the pty) | — | ✅ |
  53. | IM photo/file → agent | — | ✅ (downloaded, path injected) |
  54. | Web paste/drop upload | — | ✅ |
  55. Hooks-only always works — wrapping is pure addition. The **Approval cards**
  56. row needs remote approval on (`tlive mode full`); the default `notify` mode
  57. does everything else — live monitoring, turn-finished / waiting notifications,
  58. reply-to-continue, the web terminal — without ever holding a tool call. IM
  59. messages carry a `label · ` prefix (the session's directory) but no longer
  60. mark wrapped vs. hooks-only visually — the continue card's own "Reply to
  61. continue" line makes the distinction moot for what you actually do.
  62. ## What's in the box
  63. - **Posture — `off` / `notify` (default) / `full` / `all`.** One coarse
  64. switch that sits above every fine toggle, in escalation order (how much
  65. tlive intercepts). **`off`** makes every hook a no-op (kill switch — no
  66. gating, notifications, monitoring, or daemon autostart). **`notify`**
  67. (default) watches and notifies but the shim can never hold or block an
  68. approval — every prompt stays 100% native (your local terminal dialog, or
  69. CC's own auto-deny when headless); when a prompt is waiting at the terminal
  70. it reports **to the machine** — desktop toast + read-only dashboard card,
  71. since only whoever is sitting there can act on it. IM stays quiet about
  72. these (a phone can't reach a terminal), except once ever per chat: the
  73. first time, a card explains why and offers the one-tap switch to `full`.
  74. The desktop toast has no on/off switch of its own — use your OS's Do Not
  75. Disturb to silence it temporarily, or `tlive mode off` to stop tlive
  76. entirely. **`full`** turns on remote approval for the main session — the
  77. posture that puts approvals **on your phone**: tlive holds each tool call
  78. so you can answer it from IM / desktop / dashboard (everything the *Approvals*
  79. bullet below describes), in parallel with the terminal dialog — first
  80. answer wins. Sub-agent prompts still pass through to the terminal.
  81. **`all`** holds sub-agent approvals too — the trade is that **a held
  82. sub-agent has no terminal dialog until the window ends**, because Claude
  83. Code awaits the hook before deciding whether to build one; use it only when
  84. nobody is at the keyboard, and `tlive mode full` goes back. Flip postures
  85. live with `tlive mode off|notify|full|all` (or `/mode` from IM — a bare
  86. `/mode` replies with a card listing the ladder and marking the current
  87. rung); the shim re-reads config on the next hook, so no restart or new
  88. session is needed, and `tlive status` shows the effective mode. Remote
  89. approval is opt-in by design — a freshly-installed tool must never be able
  90. to silently hang a workflow.
  91. - **Approvals** *(remote approval — `mode: full` or `all`)* — a tool call that needs
  92. approval is held so you can answer it from IM buttons or the web card:
  93. - **Parallel, first-answer-wins** — on Claude Code the `PermissionRequest`
  94. hook fires alongside the local permission dialog; both are live, and
  95. answering at the keyboard resolves the remote card ("answered in terminal")
  96. within seconds. **Nothing is ever auto-denied** — an unanswered card just
  97. leaves the local prompt in charge.
  98. - **Grace before sending** — `approvals.approvalGraceSec` (default 10s, `0`
  99. disables) holds the card first, so answering right away means it's never
  100. sent; otherwise it stays answerable for ~24h.
  101. - **Codex** — tlive spawns/adopts a `codex app-server` companion and Codex
  102. TUIs auto-attach; the remote card and native prompt race the same way, with
  103. no window to configure (see [Security](#security-model)).
  104. - **Rendering** — diffs/commands, risky-pattern flags, secret masking.
  105. Telegram cards stay restrained (bold titles, plain-text buttons; the only
  106. emoji anywhere is `⚠️` on a risky flag / error), with expandable quotes for
  107. long diffs — use a recent Telegram app for best rendering.
  108. - **Power toggles** — **"Always allow \<tool\>"** grants a per-tool pass
  109. (in-memory, cleared on restart; on Claude Code it answers the native dialog
  110. for you remotely); `/trust on|off` pauses approvals entirely.
  111. - **Sub-agents pass through by default** — on `full`, tlive returns `{}` and
  112. lets CC handle a backgrounded/async sub-agent natively, so its terminal
  113. dialog still appears exactly as it would without tlive. **`tlive mode
  114. all`** holds sub-agent approvals too, but the trade is real: CC resolves
  115. an async agent's hook *before* it decides whether to build a dialog, so a
  116. held sub-agent has **no** terminal box until the window ends — remote
  117. becomes the only answer path. Worth it only when nobody is at the
  118. keyboard; `tlive mode full` goes back.
  119. - **Headless runs pass through too** — `claude -p` and Agent SDK hosts
  120. have no terminal dialog at all, so on `full` tlive leaves them to Claude
  121. Code: a denial under `-p`, or the SDK host's own permission callback.
  122. `tlive mode all` holds them, and a held run waits for your answer or the
  123. window.
  124. - **Answer `AskUserQuestion` from IM or the dashboard (Claude Code only)** —
  125. CC fires a `PermissionRequest` for its own question tool; tlive relays it as
  126. a single-select or multi-select card (checkboxes, a live `Submit (N)` count,
  127. `Skip`) instead of Allow/Deny, on IM and on the dashboard session card
  128. alike. A call carrying several questions is walked one at a time — the card
  129. title reads `Question 2/3`, `← Back` re-answers an earlier one, and the
  130. batch is submitted as a whole once the last question lands. The daemon owns
  131. that cursor, so answering on your phone advances the dashboard card too. The local question prompt still renders in
  132. parallel and always wins a race, so an answer given at the keyboard is
  133. never overridden — `Skip` just passes the tool through so the local prompt
  134. can be answered instead; it is not an auto-approval of anything. Codex has
  135. no equivalent concept.
  136. - **Resume** — on `Stop`, reply to the IM message (or the web reply box) and
  137. the session keeps going. The card's excerpt sits inside a collapsed
  138. expandable quote (headings, lists, tables and code all survive the
  139. conversion — nothing is cut mid-word or mid-fence); while that card is
  140. still pending, the 60-second idle "waiting for your input" notification is
  141. suppressed instead of piling a second message on top of it.
  142. - **Daemon lazy-start** — hooks-only sessions no longer need a manual
  143. `tlive start` first: on `SessionStart` (and when `tlive run` launches), the daemon is
  144. started detached (non-blocking) if it isn't already up. Disable with
  145. `daemon.autoStart: false`; `tlive start` still works and is unaffected.
  146. - **Failure alerts (Claude Code only)** — `PostToolUseFailure` (a tool call
  147. errored) and `StopFailure` (session-level error, e.g. rate-limit/billing)
  148. push a `⚠️`-prefixed IM message. Pure side-channel, never affects approval
  149. decisions; Codex has no equivalent hooks, so this only fires for Claude Code.
  150. - **In-session welcome hint (Claude Code only)** — if IM isn't configured
  151. yet, `SessionStart` injects a one-line prompt into the session context
  152. nudging you to say "help me configure tlive"; it stops appearing once IM
  153. is set up. Not injected for Codex.
  154. - **Web terminal** — `tlive run <cmd>` serves the pty at `/s/<id>`:
  155. xterm.js, multi-device with **last-input sizing** (whoever types owns the
  156. grid; everyone else sees a scaled view), screen rebuild for late joiners,
  157. soft-keyboard aware layout, view/input modes on touch, draggable key bar
  158. with Esc/Tab/⇧Tab/Ctrl-C/…, font size controls, copy-screen modal.
  159. - **Dashboard** — `/` lists sessions: status badge, "stuck Nm" staleness,
  160. last assistant message, colored approval cards, live terminal previews,
  161. per-session mute, 📎 file upload, reply box.
  162. - **Send anything to the agent** — IM quote-reply text, IM photos/files,
  163. terminal-page paste/drag-drop, dashboard 📎. All land as local paths in
  164. `~/.tlive/inbox` (auto-swept: 48 h age / 256 MB total) and are typed into
  165. the pty via bracketed paste.
  166. ## Install: plugins, not config writes
  167. `tlive setup` (and `tlive setup --hooks-only`) no longer hand-edits
  168. `~/.claude/settings.json` or `~/.codex/hooks.json` — it orchestrates each
  169. vendor's **own plugin manager**:
  170. - Claude Code: `claude plugin marketplace add <bundled dir>` then
  171. `claude plugin install tlive@tlive --scope user`.
  172. - Codex (if `codex` is on `PATH`): `codex plugin marketplace add <bundled
  173. dir>` then `codex plugin add tlive@tlive`.
  174. The Claude Code plugin bundles the 9 hook events, a `tlive` skill (usage,
  175. diagnostics, security model, under the `/tlive:*` namespace), and slash
  176. commands `/tlive:url` and `/tlive:status`. The Codex plugin ships only the
  177. skill — Codex has no hooks and needs none; its integration is the
  178. app-server companion (see below). The vendor **copies** the plugin into its
  179. own cache (`~/.claude/plugins/cache` for Claude Code,
  180. `$CODEX_HOME/plugins/cache/tlive/tlive/local/` for Codex) — after upgrading
  181. `tlive` itself, re-run `tlive setup --hooks-only` to refresh that copy.
  182. Ran a pre-plugin dev build that wrote hooks directly into vendor config?
  183. Remove those entries by hand once (they'd double-fire otherwise) — see the
  184. appendix in [docs/manual-hooks.md](docs/manual-hooks.md). tlive itself never
  185. edits your vendor config files.
  186. **Old vendor versions without a plugin CLI**: `tlive setup` detects this
  187. (`claude plugin list` / `codex plugin marketplace add` failing) and prints a
  188. pointer to the manual config appendix: [docs/manual-hooks.md](docs/manual-hooks.md)
  189. — full `settings.json` hooks block and `hooks.json` you can paste in by
  190. hand.
  191. Uninstalling (`npm uninstall -g tlive`) best-effort removes the plugin via
  192. each vendor's CLI and cleans up any leftover direct-write hooks; your
  193. `~/.tlive` config and logs are preserved. Full purge and **migrating from
  194. v0.x/v1** steps: [docs/uninstall.md](docs/uninstall.md).
  195. **Try it from GitHub first** (no npm publish needed): `claude plugin
  196. marketplace add y49/tlive` then `claude plugin install tlive@tlive` pulls
  197. the plugin (hooks/skill/commands) straight from the repo's root
  198. `marketplace.json`. You still need the engine itself — `npm i -g tlive` —
  199. for the daemon/CLI the hooks call into.
  200. `tlive setup` asks **which vendor(s)** to install the plugin into when it
  201. detects both `claude` and `codex` on `PATH`: `[1] Claude Code [2] Codex
  202. [3] both (default)`. Plugin registration always runs before the IM
  203. credential prompts, and the IM step is fully skippable — press Enter
  204. through it and later say "help me configure tlive" inside Claude Code or
  205. Codex — or, in Claude Code, run `/tlive:setup` — to have the AI walk you
  206. through it interactively (Codex has no slash commands; use the phrase).
  207. ## Codex: the app-server companion
  208. Codex has no hooks and no trust step — the entire Claude-style hooks/trust
  209. dance above doesn't apply. Instead, `tlive` attaches to a `codex
  210. app-server --listen unix://…` process: it adopts one already listening on
  211. tlive's socket path, or starts one (detached, with respawn/backoff) if none
  212. is there. Any `codex` TUI you run **auto-attaches** to that socket — this
  213. is a Codex feature, not something tlive configures per-session.
  214. Because that instance is **shared**, `tlive stop` leaves it running: it is
  215. the rendezvous point for every Codex TUI on the machine, and stopping it
  216. would leave those sessions running but invisible to tlive. The next
  217. `tlive start` adopts the same instance, so restarting tlive never drops a
  218. Codex session. (This mirrors Codex's own `codex app-server daemon`, which
  219. keeps one detached, pid-tracked app-server alive across clients. tlive
  220. doesn't delegate to it because that path requires Codex's standalone
  221. managed install and errors out for npm installs.)
  222. Over that RPC connection tlive subscribes to Codex's own thread/turn
  223. events and drives approvals through `ServerRequest`: when Codex asks for a
  224. permission decision, tlive broadcasts the same request to IM/web and to
  225. the native TUI prompt simultaneously — **first answer wins**, exactly like
  226. Claude Code's parallel channel. There is no approval window to configure:
  227. the native prompt is never blocked waiting on tlive, so there's nothing
  228. that can time out.
  229. If the companion can't be reached (Codex not installed, nothing answering
  230. on the socket, or you're on win32 where `codex app-server` isn't wired up
  231. yet), `tlive status` says so plainly, and unless Codex is simply absent
  232. tlive keeps retrying in the background — a reinstall recovers on its own and Codex just runs with its normal
  233. local approval flow — no IM/web card, no crash, no degraded behavior
  234. beyond losing the remote channel.
  235. ## Why not the official remotes?
  236. Official remotes (Claude Remote Control / Codex mobile / Channels) have
  237. structural gaps tlive fills:
  238. - **Cross-agent** — one setup for Claude Code and Codex.
  239. - **API-key users** — official remotes exclude them; tlive doesn't care.
  240. - **Self-hosted** — no vendor cloud in the path; a single token gates the web.
  241. - **Feishu** — official channels don't cover it.
  242. tlive deliberately does **not** try to be "vibe-code from your phone" — the
  243. official remotes do that better. tlive is the approval / monitoring / interject
  244. layer for sessions you already run.
  245. ## Security model
  246. - **Web**: every HTTP/WS request requires the single token
  247. (`~/.tlive/web-token`, 0600). Default bind is `0.0.0.0` so your phone can
  248. reach it on the LAN — the token is the gate. Set `web.bind: "127.0.0.1"`
  249. to go loopback-only. **Cards never carry a link to the dashboard.** The
  250. deep link that used to ship there carried the token itself — full control
  251. over every session — and sending it to IM would park that token on the
  252. messaging provider's servers permanently. Open the dashboard yourself (over
  253. your own tailscale/HTTPS reverse proxy if you need it off the LAN); IM is
  254. push, web is pull.
  255. - **IM inbound**: fail-closed. Messages/button-taps are dropped unless they
  256. come from the configured chat; add `allowedSenders` for per-user hardening
  257. in group chats.
  258. - **`/trust on` and "Always allow"** are power tools: they auto-approve.
  259. Both are in-memory and cleared on daemon restart. Prefer per-tool grants
  260. over `/trust`. Your own `permissions.deny` in Claude settings always wins —
  261. hooks cannot override it.
  262. - **Fallback is silence**: no configured chat, timeout, or a daemon that's
  263. down → the hook emits `{}` and Claude prompts in your local terminal as if
  264. tlive weren't there. On Claude Code the local dialog is live the whole
  265. time anyway (parallel channels), so "fallback" just means the remote card
  266. goes quiet.
  267. - **Codex approvals are fail-safe by construction** — the native prompt is
  268. never blocked waiting on tlive (no window, nothing to time out); if the
  269. companion is unreachable Codex just runs its own local approval flow and
  270. `tlive status` reports `codex: app-server companion unreachable —
  271. approvals local-only`. When the companion is up, the remote card and the
  272. native prompt race — first answer wins, same semantics as Claude Code's
  273. parallel channel.
  274. ## CLI
  275. ```
  276. tlive setup wizard + registers the vendor plugin(s) (idempotent); --hooks-only
  277. tlive start | stop daemon lifecycle (stop is idempotent)
  278. tlive status health, effective mode, web URLs + QR, config paths
  279. tlive logs [-f] tail the daemon log
  280. tlive run <cmd> … wrap a process: local terminal + web terminal
  281. tlive url print the dashboard URL + QR (when a full-screen app hid the run banner)
  282. tlive mode off|notify|full|all set posture (see "What's in the box"); takes effect on the next hook
  283. tlive hook <event> hook shim (called by Claude Code, not by you;
  284. Codex has no hooks — see the app-server companion)
  285. ```
  286. `setup`, `start`, `stop`, `status`, `logs`, `run`, `url`, `hook` are the
  287. frozen surface (locked by `tests/contract/`); `mode` and the runtime toggles
  288. `mute | trust | safe` (`on|off`) are additive.
  289. IM commands: `/mute on|off` (silence IM notifications), `/trust on|off` (pause
  290. approvals — auto-allow everything), `/safe on|off` (auto-allow routine ops),
  291. `/mode off|notify|full|all` (set posture; a bare `/mode` replies with the
  292. ladder), `/help`. Tapping a bare command from the client's command menu
  293. replies with on/off buttons instead of an error. Quote-reply any session
  294. message to type into that session.
  295. ## Config (`~/.tlive/config.json`)
  296. <details>
  297. <summary>Full annotated config — every field is optional; defaults shown</summary>
  298. ```jsonc
  299. {
  300. // posture: "off" | "notify" (default) | "full" | "all" (remote approval;
  301. // "all" also holds sub-agent prompts — see "What's in the box"). Also set
  302. // live with `tlive mode …` or `/mode` from IM; unset/unknown falls back to
  303. // notify.
  304. "mode": "notify",
  305. "adapters": {
  306. "telegram": { "token": "…", "chatIdAllowList": ["123"] },
  307. "feishu": { "appId": "…", "appSecret": "…", "chatId": "oc_…" }
  308. },
  309. "web": {
  310. "enabled": true, // default true
  311. "bind": "0.0.0.0", // default; use 127.0.0.1 for loopback-only
  312. "port": 7681
  313. },
  314. "daemon": {
  315. "autoStart": true // default true; false disables session-start lazy-start
  316. },
  317. "approvals": {
  318. // `holdSubagents` was removed — `tlive mode all` replaces it (upgrading
  319. // from a config with `"holdSubagents": true`: that key is now dead and
  320. // silently ignored, so switch to `tlive mode all` to keep holding
  321. // sub-agent approvals).
  322. // remote-approval window in seconds, shared by both vendors. The remote
  323. // channel runs parallel to the local prompt, so a long window costs
  324. // nothing — timing out never approves or denies anything, it only
  325. // forces you back to the keyboard.
  326. "windowSec": 86200, // default ~24h (also the max; min 60)
  327. // grace period before an approval card is sent — answering at the
  328. // keyboard within this window means it's never sent at all
  329. "approvalGraceSec": 10, // default 10s, 0 disables
  330. // how much auto-approves without a card. OMITTED (the default) = nothing:
  331. // every request CC would have asked about still gets asked. Setting this
  332. // CHANGES WHAT CC ASKS YOU — the hook only fires when a dialog was about to
  333. // appear, so an auto-allow here removes a prompt you would have seen.
  334. // omitted (default) — nothing is auto-allowed
  335. // "readonly" — also auto-allow Read/Glob/Grep
  336. // "safe" — also auto-allow routine ops (non-dangerous Bash,
  337. // edits to non-sensitive paths); dangerous ops
  338. // (rm -rf, sudo, curl|sh, sensitive-path writes…),
  339. // MCP/unknown tools, and AskUserQuestion still ask.
  340. // Cuts the card volume for autonomous / agent-driven runs. Toggle live with
  341. // /safe on|off. Never crosses the danger floor — only /trust on auto-allows
  342. // dangerous ops.
  343. // "autoApprove": "readonly",
  344. // what a HELD approval does when its window times out with nobody
  345. // answering: "defer" (default) → pass-through {} (CC-native fallback);
  346. // "deny" → deny with a "timed out" message so the turn can end and the
  347. // continuation card can redirect the agent. Never auto-allows.
  348. "timeoutAction": "defer"
  349. },
  350. "allowedSenders": [{ "channel": "telegram", "userId": "42" }] // optional
  351. }
  352. ```
  353. </details>
  354. ## Tips
  355. - **Persistent sessions**: tlive intentionally does not own sessions —
  356. `tlive run` dies with your terminal. Want detach/reattach? Combine:
  357. `tmux new -s work tlive run claude`. tmux keeps it alive; tlive keeps the
  358. web/IM layer on it.
  359. - **Scroll on phone**: view mode converts touch-drag into wheel events —
  360. full-screen TUIs (claude) scroll their transcript exactly like a desktop
  361. mouse wheel. Use `Ctrl-R` on the key bar for claude's transcript mode.
  362. - **Am I wrapped?** Wrapped processes see `TLIVE_SESSION=<id>` in their
  363. environment (like `$TMUX`); `tlive run` refuses to nest inside a wrapped
  364. session. Several wrapped sessions in the SAME directory are fine — each is
  365. its own card, and hook traffic from inside a wrapper is routed to that
  366. exact card via `TLIVE_SESSION`.
  367. - **Windows**: supported by design (named pipes, ConPTY) but less battle-tested
  368. than Linux/macOS — issues welcome.
  369. ## Architecture
  370. ```mermaid
  371. flowchart LR
  372. A["your <b>claude</b>"] -->|hooks| S["tlive hook shim"]
  373. B["your <b>codex</b>"] -->|rpc| C["app-server companion"]
  374. R["tlive run"] -->|owns pty| P["PtyBridge"]
  375. S -->|IPC| D[("daemon")]
  376. C --> D
  377. P --> D
  378. D --> IM["IM adapters<br/>Telegram · Feishu"]
  379. D --> W["web · token-gated<br/>dashboard + /s/&lt;id&gt; terminal"]
  380. ```
  381. - The **daemon** never owns sessions; it brokers approvals/resumes, fans out
  382. pty bytes, and serves the web.
  383. - The **frozen surface** (contracts locked by `tests/contract/`) is documented
  384. in [KERNEL.md](KERNEL.md).
  385. ## Upgrading from v1.0
  386. v1.0 drove sessions via the Agent SDK; v2.0 is the hook layer (see
  387. [`docs/changelog-archive.md`](docs/changelog-archive.md)). Breaking, no
  388. migration: re-run `tlive setup`. v1.0 is preserved at git tag
  389. `v1.0-sdk-bridge`.
  390. ## Development
  391. ```bash
  392. git clone https://github.com/y49/tlive
  393. cd tlive
  394. pnpm install
  395. npm run typecheck && npm test && npm run build
  396. ```
  397. ## Community
  398. tlive is shared and discussed in the [LINUX DO](https://linux.do) community —
  399. feedback and bug reports from there are welcome.
  400. ## License
  401. MIT. See [LICENSE](LICENSE). Issues and PRs welcome — [Development](#development)
  402. above has the whole setup.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.