Introducing a new way to review your PRs.

Read the announcement

alishahryar1 / free-claude-code

Use Claude Code, Codex, Antigravity, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

View on GitHub

28 documents · Updated Nov 20, 2026

docs / messaging-transcripts-rendering-and-voice

Transcripts, rendering, and voice

Messaging keeps conversation state across restarts, turns streaming CLI events into readable status messages, and accepts voice notes as another form of user input. It preserves the links between platform messages and conversation nodes while adapting the same transcript to Discord and Telegram display rules. See Messaging platforms, Messaging turn workflows, and Messaging conversation trees for the surrounding platform and turn model.

Session continuity

Session continuity separates two kinds of state. Conversation snapshots preserve the work tree and its platform references. A managed message log records which platform message IDs belong to the application so cleanup actions can act on owned messages without treating the whole chat as application state.

Conversation persistence

The conversation store restores typed conversation snapshots before platform traffic starts. Each snapshot is scoped to a platform chat and keeps the nodes needed to resume or reconcile queued work. The active CLI session ID is saved when the CLI reports its real ID, so later turns can reuse the correct session or fork from a reply target.

References: src/…/store.py• L19-44 src/…/store.py• L91-109 src/…/snapshot.py• L13-60 src/…/node_event_pipeline.py• L21-55

Writes are delayed and combined during normal activity. A direct write is used for authoritative clear operations. The persistence layer writes a complete JSON snapshot through a temporary file and replaces the target atomically, which reduces the chance that a process stop leaves a partial state file.

References: src/…/persistence.py• L21-31 src/…/persistence.py• L48-69 src/…/persistence.py• L130-161 src/…/store.py• L153-162

Managed message history

The managed message log is an ownership ledger, not a copy of message text. It keeps inbound and outbound IDs in chat order with a direction and kind such as prompt, voice, command, or status. Duplicate IDs are ignored, and an optional per-chat cap limits how much cleanup history is retained.

References: src/…/managed_message_log.py• L7-13 src/…/managed_message_log.py• L48-72 src/…/managed_message_log.py• L99-131 src/…/workflow.py• L622-677

Clear operations use this ledger with the conversation snapshots. They delete or forget only the messages that the application owns, while a scope clear removes the selected platform chat from both state stores and leaves other chats intact.

References: src/…/store.py• L135-158 src/…/workflow.py• L606-620 src/…/turn_intake.py• L163-195

Transcript display

A transcript is the live user-facing view of one CLI turn. The node runner receives parsed CLI events, applies them to an ordered buffer, and edits one platform status message as the turn advances. The buffer is temporary display state; the durable conversation snapshot stores node and session state rather than the complete rendered text.

References: src/…/node_runner.py• L59-73 src/…/node_runner.py• L113-169 src/…/models.py• L24-48

Event buffering

The buffer groups streamed events into readable segments. It can show thinking, answer text, tool calls, tool results, subagent activity, and errors. Start, delta, stop, and block events update open segments so partial CLI output can be displayed before the turn ends.

References: src/…/buffer.py• L30-102 src/…/segments.py• L18-24 src/…/segments.py• L26-66 src/…/segments.py• L69-119

Nested Task work is shown as a compact subagent entry instead of repeating its inner thinking and answer text in the parent view. The display still exposes the subagent description and a summary of its tool use, which keeps long delegated work readable.

References: src/…/buffer.py• L47-51 src/…/buffer.py• L138-181 src/…/subagents.py• L10-54 src/…/segments.py• L122-164

Incremental rendering

Rendering applies a platform context to each segment. The context supplies the platform’s bold, code, escaping, and Markdown functions, while segment-level tail limits prevent one long thinking block, answer, or tool result from using the whole display. The final result also carries the current status line.

References: src/…/context.py• L7-18 src/…/segments.py• L40-45 src/…/segments.py• L62-66 src/…/segments.py• L112-119

The renderer enforces a total character budget after it combines the segments and status. When the result is too long, it drops the oldest rendered parts first and marks the result as truncated. If only a small tail can fit, it keeps the end of the last part or returns the status alone.

References: src/…/renderer.py• L10-16 src/…/renderer.py• L26-63

Status message updates

The workflow creates or adopts one status message for a turn. The editor updates that message at most once per second unless a boundary such as block completion or turn completion requires an immediate refresh. It skips unchanged text and sends edits through the platform outbox, so the user sees one growing message instead of a new message for every stream event.

The main transcript path follows this sequence:

flowchart LR
    A[CLI event stream] --> B[Parsed event]
    B --> C[Transcript buffer]
    C --> D[Platform rendering profile]
    D --> E[Character budget]
    E --> F[Status message edit]
    F --> G[Platform outbox]

References: src/…/turn_intake.py• L84-105 src/…/ui_updates.py• L13-29 src/…/ui_updates.py• L48-99 src/…/outbox.py• L64-82

Markdown profiles

The rendering profile keeps transcript content platform-neutral until the last step. It selects the syntax, escaping rules, parse mode, status format, and display budget for the destination platform. Discord and Telegram therefore receive the same meaning even though their Markdown rules differ.

References: src/…/profiles.py• L29-53 src/…/workflow.py• L165-175

Discord Markdown

Discord uses standard Markdown sent as plain message content. The profile escapes characters that can change formatting, preserves common emphasis, links, lists, quotes, and code blocks, and converts tables into readable fenced text. Its transcript budget is 1,900 characters, below the transport’s 2,000-character send and edit limit.

References: src/…/discord_markdown.py• L1-36 src/…/discord_markdown.py• L55-60 src/…/discord_markdown.py• L249-307 src/…/profiles.py• L37-53 src/…/discord_io.py• L9-19

Telegram MarkdownV2

Telegram uses MarkdownV2 with an explicit parse mode. The profile escapes Telegram’s wider set of control characters, formats emphasis and code with Telegram syntax, and converts tables into fenced code blocks. If Telegram rejects a formatted message because of an entity parse error, the delivery layer retries without a parse mode so a response can still reach the user as plain text.

References: src/…/telegram_markdown.py• L1-49 src/…/telegram_markdown.py• L52-78 src/…/telegram_markdown.py• L262-320 src/…/profiles.py• L37-53 src/…/telegram_io.py• L102-125

Shared Markdown normalization

Both profiles normalize GitHub-style tables before parsing them. The normalization only changes table recognition outside fenced code, which protects literal code content while making table output more stable across the two platforms.

References: src/…/markdown_tables.py• L9-20 src/…/markdown_tables.py• L25-47 src/…/discord_markdown.py• L55-61 src/…/telegram_markdown.py• L52-58

Voice interaction

Voice input enters the same turn system as text after transcription. Platform adapters identify an audio item and supply download and reply actions to a shared voice flow. That flow owns the temporary status message, transcription work, handoff to the normal message handler, and cleanup when the work does not complete.

References: src/…/voice_flow.py• L36-58 src/…/voice_flow.py• L96-114 src/…/voice_flow.py• L144-152

Audio intake

Discord accepts an audio attachment when a message has no text. Telegram accepts a voice update. Both adapters normalize the event into a VoiceNoteRequest, which keeps platform IDs, reply context, thread context, a temporary file suffix, and platform-specific status text together.

References: src/…/discord.py• L160-184 src/…/discord_inbound.py• L23-28 src/…/discord_inbound.py• L77-112 src/…/telegram.py• L137-145 src/…/telegram_inbound.py• L76-133

The shared flow first reserves the voice message and sends a reply such as “Transcribing voice note...”. It downloads the audio to a temporary file, rejects a missing or oversized file, and removes the file after processing. A missing transcriber produces a clear disabled response instead of entering the normal turn path.

References: src/…/voice_flow.py• L24-29 src/…/voice_flow.py• L116-123 src/…/voice_flow.py• L159-208 src/…/voice_flow.py• L303-306 src/…/voice_flow.py• L381-388

Local transcription

The local transcription service turns the temporary audio file into English text through a lazily loaded Whisper pipeline. It runs the blocking model work outside the async event loop and serializes access to its owned model. Empty recognition results become a user-visible “no speech detected” value rather than an empty prompt.

References: src/…/transcription.py• L21-40 src/…/transcription.py• L42-72 src/…/transcription.py• L74-111 src/…/transcription.py• L125-132

Voice handoff

After transcription, the flow creates an ordinary IncomingMessage whose text is the transcription. It keeps the original voice message ID and the pre-sent status message ID, then hands the message to the same handler used for text turns. The normal intake path edits that status message into the turn’s first status instead of sending a second status message.

References: src/…/voice_flow.py• L205-230 src/…/models.py• L24-48 src/…/turn_intake.py• L84-105

Voice cancellation

Pending voice work has one owner per platform chat and source message. The registry also recognizes the status message as a reference to that work, so stop and clear actions can cancel a voice operation before or during handoff. Cancellation drains the owned task and returns the message IDs that should be removed, which prevents stale “transcribing” messages from remaining in the chat.

The voice path joins the transcript path only after it has produced text:

sequenceDiagram
    participant User
    participant Platform
    participant Voice as Voice flow
    participant STT as Transcription service
    participant Turns as Turn handler
    participant UI as Status message

    User->>Platform: Send voice note
    Platform->>Voice: Normalized voice request
    Voice->>UI: Send transcribing status
    Voice->>STT: Download and transcribe audio
    STT-->>Voice: Text
    Voice->>Turns: Handoff as incoming text
    Turns->>UI: Edit status with transcript progress
    Turns-->>User: Final rendered result

References: src/…/voice.py• L64-82 src/…/voice.py• L89-123 src/…/voice.py• L181-250 src/…/voice_flow.py• L125-142

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep SessionStore persistence fields aligned with snapshot loading, legacy migration, and managed-message cleanup. A field that loads but does not save can break restart behavior without an immediate error.
  • Keep the rendering profile’s parse mode and escaping functions paired. Changing one platform formatter without its RenderCtx can produce text that the platform rejects.
  • Keep the transcript character budget below the matching platform transport limit. Otherwise, a valid rendered transcript can still fail when sent or edited.
  • Keep voice status ownership linked to both the source voice ID and the generated status ID. Stop and clear flows rely on both references to remove stale work safely.
  • Keep voice handoff input compatible with IncomingMessage.status_message_id. Removing that link makes voice turns create a second status message instead of reusing the first one.
  • Keep table normalization outside fenced code blocks. Applying it to code can change user content before either Markdown profile renders it.

Important failure modes

TriggerConsequenceGuard
Session JSON is malformed or cannot be readThe process starts without the saved conversation stateSessionStore logs the load failure; restart continuity is lost until a valid snapshot is available
A newer session change supersedes a delayed writeAn older snapshot could overwrite newer stateDebounced persistence checks its generation before replacing the file
A rendered status exceeds the platform budgetThe platform may reject the edit or truncate content unexpectedlyThe renderer drops old segments and marks the display as truncated
Telegram MarkdownV2 contains an invalid entityThe formatted send or edit failsTelegram retries the operation without a parse mode
Voice transcription is unavailable, fails, or exceeds the audio size limitThe voice note cannot become a turnThe flow replies with a disabled or retry message and cleans up pending state and temporary audio
Stop or clear races with voice handoffA cancelled voice turn could continue or leave its status message behindPendingVoiceRegistry owns reservations, drains cancellation, and returns deletion IDs

Key files

FileWhy to read it
src/…/store.pyMain boundary for conversation snapshots and managed message ownership
src/…/persistence.pyPersistence timing and safe replacement behavior
src/…/managed_message_log.pyMeaning and scope of the managed message ledger
src/…/node_runner.pyConnection between one CLI turn, its transcript, and its status message
src/…/buffer.pyEvent-to-segment buffering and nested Task display behavior
src/…/renderer.pyTotal display budget and truncation policy
src/…/ui_updates.pyRate-limited incremental status edits
src/…/profiles.pyPlatform choice of Markdown rules and character budget
src/…/discord_markdown.pyDiscord output contract
src/…/telegram_markdown.pyTelegram MarkdownV2 output contract and fallback context
src/…/voice_flow.pyShared voice lifecycle from audio request to normal turn handoff
src/…/transcription.pyLocal speech-to-text boundary
src/…/voice.pyVoice ownership and cancellation contract