Mantra 文档

English

简体中文

English

简体中文

Appearance

Session Live Streaming ​

Mantra v0.10.0 introduces Session Live Streaming, letting you watch new messages appear in real-time — open an in-progress AI coding session and watch it like a livestream, no manual refresh needed.

What is Session Live Streaming? ​

Traditionally, Mantra reviewed completed session records. Now, when your AI tool (Claude Code, Cursor, Gemini CLI, Codex) is actively working, you can open Mantra simultaneously and watch each new message appear in the narrative panel in real-time.

This is especially useful for:

  • Monitoring long-running AI tasks on a second monitor
  • Staying informed about what the AI is doing without switching windows
  • Verifying the AI is progressing in the expected direction

Supported Data Sources ​

AI ToolWatching MechanismNotes
Claude CodeJSONL file monitoringIncremental reads, only processes new content
CodexJSONL file monitoringIncremental reads, only processes new content
CursorSQLite periodic pollingRead-only polling, no interference with Cursor
Gemini CLIJSON file monitoringFull re-parse with diff comparison against last state

Core Features ​

Live Message Rendering ​

New messages appear in the narrative panel with a fade-in animation:

  • Auto-scroll: If you're at the bottom, the panel automatically follows new messages
  • Floating button: When you scroll up to review history, a "N new messages" floating button appears at the bottom — click to jump back to the latest

Live Status Indicator ​

A status indicator appears next to the session title showing the current watch state:

StateMeaning
🟢 LiveActively watching, connection healthy
⏸ StoppedWatching stopped, click to reconnect
🔄 ReconnectingConnection interrupted, auto-recovering

Automatic Error Recovery ​

Live watching supports intelligent auto-recovery:

  • Exponential backoff: Automatically retries up to 3 times on connection loss, with increasing intervals
  • Manual reconnect button: Available when automatic recovery fails
  • Idle detection: Automatically lowers polling frequency when a session appears to have ended, reducing resource usage

How to Use ​

Open a Live Session ​

  1. Start your AI tool and begin a coding task
  2. Find the corresponding project in Mantra's project list
  3. Click the project — Mantra automatically detects and enables live watching
  4. A 🟢 Live indicator appears next to the session title, confirming live updates are active

Auto-Detection

Mantra automatically determines whether a session is in progress. If the session file has recent writes, live watching activates automatically.

Track New Messages ​

Once live watching is enabled, Mantra handles:

  • Normal appends: Each AI response appears automatically
  • Tool calls: Tool call requests and results display in real-time
  • Error handling: If the AI tool outputs unparseable content, Mantra skips it and continues watching

Live Updates for Remote Sessions ​

If you've connected to a remote server via Remote SSH Access, live streaming is also supported for remote sessions:

  • Claude Code / Codex: Stream-reads the tail of remote JSONL files via SSH (equivalent to tail -f)
  • Cursor: Executes database queries remotely via SSH
  • Gemini CLI: Polls remote JSON file changes via SSH
  • SSH Reconnection: After reconnecting, resumes from the last read offset — no messages are missed

FAQ ​

Why don't I see the Live status indicator?

Possible reasons:

  1. Session already finished: If the AI tool has ended this session, Mantra won't activate live watching
  2. Imported historical session: Sessions manually imported from the import wizard don't support live updates
  3. File permissions: Mantra needs read access to the log file; check file permissions

Solution: Start a new task in your AI tool, then refresh Mantra's project list.

Does live streaming affect performance?

The impact is minimal. Mantra's live watching is specifically optimized:

  • JSONL watching: Only reads incremental content, never re-parses existing data
  • SQLite polling: Read-only queries, no writes to Cursor's database
  • Idle frequency reduction: Automatically checks less frequently when sessions end
  • Connection reuse: Remote SSH live watching reuses existing connections, no extra connections
Does live watching stop automatically?

Yes. Mantra automatically pauses or stops watching when:

  • The AI tool session ends normally (file stops updating for a period)
  • You switch to another session or close the project
  • The app enters background mode (frequency is reduced, not fully stopped)

You can also manually click the stop button next to the status indicator at any time.

How do I tell live messages apart from history?

Live new messages appear with a fade-in animation, briefly visually distinct from existing history. After the animation ends, they look identical to historical messages, maintaining interface consistency.

Next Steps ​