turl

turl is a Rust CLI and library for locating and reading local code-agent thread files.

Features

• Multi-agent thread resolution:
  • Amp
  • Codex
  • Claude
  • Gemini
  • Pi
  • OpenCode
• Default output is timeline markdown with user/assistant messages and compact markers.
• --raw outputs raw thread records.
• --list outputs subagent status aggregation for providers that support subagent transcripts.
  • For Pi, --list outputs session entries with leaf markers and entry URIs.
• Subagent markdown views always print full parent/subagent URIs (<provider>://<main> and <provider>://<main>/<agent>).
• Non-fatal diagnostics are kept internal; only fatal errors are printed to stderr.
• Automatically respects official environment variables and default local data roots for each supported agent.

Install

npx skills add Xuanwo/turl

Agents

Amp

• Supported URI:
  • amp://<thread_id>
• Thread id format:
  • T-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• Resolution:
  • XDG_DATA_HOME/amp/threads/<thread_id>.json
  • fallback: ~/.local/share/amp/threads/<thread_id>.json
• Example:

turl amp://T-019c0797-c402-7389-bd80-d785c98df295

Codex

• Supported URIs:
  • codex://<session_id>
  • codex://threads/<session_id>
  • codex://<main_session_id>/<agent_id>
• Subagent modes:
  • Aggregate: turl codex://<main_session_id> --list
  • Drill-down: turl codex://<main_session_id>/<agent_id>
• Resolution order:
  • SQLite thread index under CODEX_HOME (state_<version>.sqlite first, then state.sqlite) via threads(id, rollout_path, archived).
  • Filesystem fallback under sessions/ and archived_sessions/ for rollout-*.jsonl.
• Examples:

turl codex://019c871c-b1f9-7f60-9c4f-87ed09f13592
turl codex://threads/019c871c-b1f9-7f60-9c4f-87ed09f13592
turl codex://019c871c-b1f9-7f60-9c4f-87ed09f13592 --list
turl codex://019c871c-b1f9-7f60-9c4f-87ed09f13592/019c87fb-38b9-7843-92b1-832f02598495

Claude

• Supported URIs:
  • claude://<session_id>
  • claude://<main_session_id>/<agent_id>
• Subagent modes:
  • Aggregate: turl claude://<main_session_id> --list
  • Drill-down: turl claude://<main_session_id>/<agent_id>
• Example:

turl claude://2823d1df-720a-4c31-ac55-ae8ba726721f
turl claude://2823d1df-720a-4c31-ac55-ae8ba726721f --list
turl claude://2823d1df-720a-4c31-ac55-ae8ba726721f/acompact-69d537

OpenCode

• Supported URI:
  • opencode://<session_id>
• Example:

turl opencode://ses_43a90e3adffejRgrTdlJa48CtE

Gemini

• Supported URI:
  • gemini://<session_id>
• Session id format:
  • xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• Resolution:
  • GEMINI_CLI_HOME/.gemini/tmp/*/chats/session-*.json
  • fallback: ~/.gemini/tmp/*/chats/session-*.json
• Example:

turl gemini://29d207db-ca7e-40ba-87f7-e14c9de60613

Pi

• Supported URIs:
  • pi://<session_id>
  • pi://<session_id>/<entry_id>
• Session id format:
  • xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• Resolution:
  • PI_CODING_AGENT_DIR/sessions/**/*.jsonl
  • fallback: ~/.pi/agent/sessions/**/*.jsonl
• Rendering:
  • pi://<session_id> renders the latest leaf branch in the session tree.
  • pi://<session_id>/<entry_id> renders the branch ending at the specified entry id.
  • pi://<session_id> --list lists all entries and marks leaf entries that are good drill-down targets.
• Example:

turl pi://12cb4c19-2774-4de4-a0d0-9fa32fbae29f
turl pi://12cb4c19-2774-4de4-a0d0-9fa32fbae29f/d1b2c3d4
turl pi://12cb4c19-2774-4de4-a0d0-9fa32fbae29f --list