🎺 Overview

Pretty Session turns noisy AI coding agent logs into clean terminal output, making live streams and saved sessions easier to read, review, and debug.

❓ Motivation

I wanted a way to actually understand what my coding agents are doing while they run, especially in CI, where the default stream-json logs are noisy and painful to read.

Why? To quickly review progress, debug a run, or catch what happened at a glance.

⭐ Features

• Three ways to format agent sessions: parse a saved session, watch an active one, or stream one live.
• Multi-provider support for Claude Code, Codex, and Gemini, with a parser structure that is easy to extend.
• Cleaner terminal output for tool calls, subagents, markdown-ish text, tables, and more.

🚀 Quick Start

1. Install the CLI globally:

   npm install -g pretty-session
   # now you can use "pts" or "pretty-session" in your terminal

2. Use whichever mode matches what you are inspecting:

   Mode A: Live provider stream

   claude -p "explain this code" --print --verbose --dangerously-skip-permissions --output-format stream-json | pts parse claude
   # codex exec "explain this code" --json | pts parse codex
   # gemini -p "explain this code" --output-format stream-json | pts parse gemini

   Mode B: Saved session snapshot

   cat ~/.claude/projects/.../session.jsonl | pts parse claude
   # cat ~/.codex/sessions/.../session.jsonl | pts parse codex
   # cat ~/.gemini/tmp/.../session.jsonl | pts parse gemini

   Mode C: Follow an active session

   pts watch claude <path-or-session-id>
   # pts watch codex <path-or-session-id>
   # pts watch gemini <path-or-session-id>

🧰 Usage

# parse commands
pts parse claude
pts parse codex
pts parse gemini

# watch commands
pts watch claude <session> [--from-end] [--interval <value>]
pts watch codex <session> [--from-end] [--interval <value>]
pts watch gemini <session> [--from-end] [--interval <value>]

# completion commands
pts completion bash
pts completion fish
pts completion zsh

# other commands
pts update

| Variable | Default | Description | | -------------------------- | ------- | ------------------------------------------------ | | PTS_TOOL_RESULT_LINES | 0 | Maximum lines shown in tool result previews | | PTS_SHOW_SUBAGENT_PROMPT | true | Show subagent prompt lines under Agent tool calls |

For a better terminal experience, enable shell completion so pts <tab> can show available commands, subcommands, and flags.

Add this to your .zshrc:

eval "$(pts completion zsh)"

This enables completion for pts commands, subcommands, and flags. To get the interactive menu shown above, install zsh-autocomplete.

For other shells, generate the matching completion script:

pts completion bash
pts completion fish

🛠 Development

Install the local development command:

pnpm dev:install
ptsd --help

This creates ptsd, which runs the current workspace version without replacing your global pts command.

Add zsh completion for ptsd:

eval "$(ptsd completion zsh)"

Remove it when you are done:

pnpm dev:uninstall

📜 License

MIT