tlive

v0.4.0

Published

a day ago

Terminal live monitoring + IM bridge for AI coding tools

0High
0Medium
0Low

str49

terminal monitoring claude-code telegram discord feishu ai-coding remote-terminal

tlive

中文文档

Terminal Live — monitor and chat with AI coding agents (Claude Code, Codex) from Telegram, Discord & Feishu.

Three features, use any combination:

| Feature | What it does | Access from | |---------|-------------|-------------| | Web Terminal | tlive <cmd> — wrap any command with a web-accessible terminal | Browser / Phone | | IM Bridge | /tlive — chat with Claude Code from your phone | Telegram / Discord / Feishu | | Hook Approval | Approve Claude Code permissions from your phone | Telegram / Discord / Feishu |

Quick Start

# 1. Install
npm install -g tlive

# 2. Configure your IM platform (interactive wizard)
tlive setup

# 3. Register hooks + Claude Code skill
tlive install skills

# 4. In Claude Code, start the bridge
/tlive

Recommended: Run /tlive setup inside Claude Code for an AI-guided setup experience that walks you through each step.

Platform setup guides: Telegram · Discord · Feishu · Full Getting Started Guide

Web Terminal

Wrap any long-running command. Access from your phone's browser.

tlive claude                  # Wrap Claude Code
tlive python train.py         # Wrap a training script
tlive npm run build           # Wrap a build

$ tlive claude --model opus

  TLive Web UI:
    Local:   http://localhost:8080?token=abc123
    Network: http://192.168.1.100:8080?token=abc123
  Session: claude (ID: a1b2c3)

Multiple sessions in one dashboard. Daemon auto-starts, auto-shuts down after 15 minutes idle.

IM Bridge

Chat with Claude Code from your phone. Start new tasks, get streaming responses with real-time tool visibility.

You (Telegram):  "Fix the login bug in auth.ts"

TLive:  ● Read(auth.ts)
        ● Grep("validateToken" in src/)
        ● Edit(auth.ts)
        ├  Applied
        ● Bash(npm test)
        ├  All 42 tests passed
        ━━━━━━━━━━━━━━━━━━
        Fixed the login bug. The token validation
        was missing the expiry check...
        📊 12.3k/8.1k tok | $0.08 | 2m 34s

Verbose levels: /verbose 0|1 — quiet (final answer only) / terminal card (tool calls + results + response).

Hook Approval

Approve Claude Code tool permissions from your phone. Never get blocked by a [y/N] prompt again.

Claude Code runs normally in your terminal (no wrapper needed)
  │
  ├── Claude wants to run a command
  │   → Hook fires → Go Core receives → Bridge sends to your phone:
  │
  │   🔒 Permission Required
  │   Tool: Bash
  │   ┌──────────────────────────┐
  │   │ rm -rf node_modules &&   │
  │   │ npm install              │
  │   └──────────────────────────┘
  │   [✅ Yes] [✅ Allow Bash(npm *)] [❌ No]
  │
  ├── You tap [Yes] → Claude Code continues
  │
  └── Walk away. Claude keeps working.
      Phone buzzes only when approval needed.

Safe by design:

Timeout defaults to deny (not allow)
Shows exact tool name and command before you approve
Hook script checks if Go Core is running — if not, passes through (zero impact on normal usage)
Works with any Claude Code session, no wrapper needed

Pause when you're at your desk:

tlive hooks pause              # Auto-allow everything
tlive hooks resume             # Back to IM approval

Supported Platforms

| | Telegram | Discord | Feishu | |---|----------|---------|--------| | IM Bridge | ✅ | ✅ | ✅ | | Hook Approval | ✅ | ✅ | ✅ | | Streaming responses | Edit-based | Edit-based | CardKit v2 | | Tool visibility | ✅ | ✅ | ✅ | | Typing indicator | ✅ | ✅ | — | | Reactions | ✅ | ✅ | ✅ | | Permission buttons | Inline keyboard | Button components | Interactive card | | Text approval (allow/deny) | ✅ | ✅ | ✅ | | Thread/Topic support | Forum topics | Auto-thread | — | | Pairing mode | ✅ | — | — | | Webhook mode | ✅ | — | WebSocket | | Content redaction | ✅ | ✅ | ✅ | | Multi-provider (Claude/Codex) | ✅ | ✅ | ✅ | | Graduated permission buttons | ✅ | ✅ | ✅ |

Commands

CLI

tlive <cmd>                # Web terminal
tlive setup                # Configure IM platforms
tlive install skills       # Register hooks + Claude Code skill
tlive start                # Start Bridge daemon
tlive stop                 # Stop daemon
tlive status               # Check status
tlive logs [N]             # Show last N lines of bridge log
tlive doctor               # Run diagnostics
tlive hooks                # Show hook status
tlive hooks pause          # Pause hooks (auto-allow)
tlive hooks resume         # Resume hooks (IM approval)

Claude Code Skill

/tlive                     # Start IM Bridge
/tlive setup               # AI-guided configuration
/tlive stop                # Stop Bridge
/tlive status              # Check status
/tlive doctor              # Diagnostics

/model <name>                  # Switch model (e.g. claude-sonnet-4-6)
/runtime claude|codex          # Switch AI provider
/settings user|full|isolated   # Claude settings scope
/perm on|off                   # Permission prompts
/effort low|medium|high|max    # Thinking depth
/stop                          # Interrupt execution
/verbose 0|1                   # Detail level
/new                           # New conversation
/sessions                      # List sessions
/session <n>                   # Switch to session
/hooks pause|resume            # Toggle hook approval
/approve <code>                # Approve Telegram pairing
/pairings                      # List pending pairings
/help                          # Show all commands

IM Commands: These slash commands also appear in Telegram's native bot menu automatically.

Configuration

Single config file ~/.tlive/config.env (created by tlive setup):

TL_PORT=8080
TL_TOKEN=auto-generated
TL_HOST=0.0.0.0
TL_PUBLIC_URL=https://example.com

TL_ENABLED_CHANNELS=telegram,discord

# Telegram
TL_TG_BOT_TOKEN=...
TL_TG_CHAT_ID=...
TL_TG_REQUIRE_MENTION=true        # @bot required in groups
TL_TG_DISABLE_LINK_PREVIEW=true   # cleaner messages

# Discord
TL_DC_BOT_TOKEN=...

# Feishu
TL_FS_APP_ID=...
TL_FS_APP_SECRET=...

# Claude Code settings scope (default: user)
# user = auth/model only · full = +CLAUDE.md/MCP/skills · isolated = none
TL_CLAUDE_SETTINGS=user

See config.env.example for all options.

Settings scope: By default, bridge only loads ~/.claude/settings.json (API key, model config). Set TL_CLAUDE_SETTINGS=user,project,local or use /settings full in chat to also load project CLAUDE.md, MCP servers, and skills.

Remote Access (frp / tunnels)

To access the web terminal from outside your LAN (e.g. via frpc, Cloudflare Tunnel, ngrok):

Forward local port 8080 (or your TL_PORT) through the tunnel
Set TL_PUBLIC_URL to your tunnel domain:
```
TL_PUBLIC_URL=https://your-domain.com
```
IM messages will use this URL for web terminal links instead of the LAN IP.

Security notes: The tunnel exposes full terminal access. Make sure:

TL_TOKEN is set (auto-generated by tlive setup) — all requests require this bearer token
IM user whitelists are configured (TL_TG_ALLOWED_USERS, TL_DC_ALLOWED_USERS, etc.)
Use HTTPS on the tunnel side (frps/Cloudflare handle this automatically)

Architecture

                    ┌──────────────────────┐
                    │   Claude Code (local) │
                    │                      │
                    │  PreToolUse Hook ────────────┐
                    │  Notification Hook ──────────┤
                    └──────────────────────┘       │
                                                   ▼
┌─ Go Core (tlive) ───────────────────────────────────────────┐
│                                                              │
│  ┌──────────┐  ┌──────────────┐  ┌────────────────────────┐│
│  │ PTY Mgr  │  │ Web UI       │  │ Hook Manager           ││
│  │ (wrap    │  │ (dashboard + │  │ (receive hooks,        ││
│  │  cmds)   │  │  xterm.js)   │  │  long-poll, resolve)   ││
│  └──────────┘  └──────────────┘  └────────────────────────┘│
│                                                              │
│  HTTP API: /api/status, /api/sessions,                       │
│            /api/hooks/permission, /api/hooks/pending          │
│  WebSocket: /ws/session/:id, /ws/status                      │
└──────────────────────────┬───────────────────────────────────┘
                           │ Bridge polls /api/hooks/pending
                           ▼
┌─ Node.js Bridge ────────────────────────────────────────────┐
│                                                              │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────┐ │
│  │Claude/Codex │  │ Telegram     │  │ Hook Poll          │ │
│  │ SDK         │  │ Discord      │  │ (forward to IM,    │ │
│  │             │  │ Feishu       │  │  resolve on click) │ │
│  └─────────────┘  └──────────────┘  └────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │  Your Phone  │
                    │  (IM app)    │
                    └──────────────┘

Development

# Go Core
cd core && go build -o tlive ./cmd/tlive/ && go test ./...

# Bridge
cd bridge && npm install && npm run build && npm test

Project Structure

tlive/
├── SKILL.md                # Claude Code / Codex skill
├── config.env.example
├── core/                   # Go → tlive binary
│   ├── cmd/tlive/          # CLI (web terminal, stop, setup, install)
│   ├── internal/
│   │   ├── daemon/         # HTTP server, sessions, hooks manager
│   │   ├── server/         # WebSocket handlers
│   │   ├── session/        # Session state + output buffer
│   │   ├── hub/            # Broadcast hub
│   │   └── pty/            # PTY (Unix + Windows ConPTY)
│   └── web/                # Embedded Web UI
├── bridge/                 # Node.js → Bridge daemon
│   └── src/
│       ├── providers/      # Claude SDK + Codex SDK providers
│       ├── messages/       # Zod schemas, canonical events, adapters
│       ├── channels/       # Telegram, Discord, Feishu adapters
│       ├── engine/         # Session state, permissions, commands, renderer
│       ├── permissions/    # Permission gateway + broker
│       ├── delivery/       # Chunking, retry, rate limiting
│       └── markdown/       # Per-platform rendering
├── scripts/
│   ├── hook-handler.sh     # PreToolUse hook → Go Core
│   ├── notify-handler.sh   # Notification hook → Go Core
│   ├── daemon.sh           # Bridge process management
│   └── statusline.sh       # Claude Code status line
├── package.json            # npm: tlive
└── docker-compose.yml

Security

Default bind 0.0.0.0 (LAN-accessible for phone QR scan)
Auto-generated bearer token
Hook timeout defaults to deny (not allow)
IM user whitelists per platform (or pairing mode for Telegram)
Bot permission probing on startup (warns about missing permissions)
Automatic redaction of API keys, tokens, passwords, and private keys in IM messages
Secret redaction in logs
chmod 600 on config.env
Environment isolation for Claude CLI subprocess

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

tlive

Quick Start

Web Terminal

IM Bridge

Hook Approval

Supported Platforms

Commands

CLI

Claude Code Skill

Configuration

Remote Access (frp / tunnels)

Architecture

Development

Project Structure

Security

License