claude-code-tools 0.2.0__py3-none-any.whl → 1.4.1__py3-none-any.whl

{claude_code_tools-0.2.0.dist-info → claude_code_tools-1.4.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

{claude_code_tools-0.2.0.dist-info → claude_code_tools-1.4.1.dist-info}/entry_points.txt

@@ -1,6 +1,7 @@
 [console_scripts]
+aichat = claude_code_tools.aichat:main
 env-safe = claude_code_tools.env_safe:main
-find-claude-session = claude_code_tools.find_claude_session:main
-find-codex-session = claude_code_tools.find_codex_session:main
+gdoc2md = claude_code_tools.gdoc2md:main
+md2gdoc = claude_code_tools.md2gdoc:main
 tmux-cli = claude_code_tools.tmux_cli_controller:main
 vault = claude_code_tools.dotenv_vault:main

docs/lmsh.md

@@ -31,18 +31,40 @@ Note: Ensure `~/.cargo/bin` is in your PATH.
 ## Usage
 
 ```bash
-lmsh                           # Interactive mode
+lmsh                           # Interactive mode (uses Claude/Haiku by default)
 lmsh "show me python files"    # Translate, edit, execute, then interactive mode
-lmsh --version                # Version info
+lmsh --agent claude            # Explicitly use Claude (default)
+lmsh --agent codex             # Use Codex instead
+lmsh --version                 # Version info
 ```
 
 ## Features
 
 - **Editable commands** - Review and modify before execution
 - **Fast startup** - Optimized Rust binary (~1ms)
-- **Claude-powered** - Leverages your existing Claude Code CLI by calling `claude -p <prompt>` in non-interactive mode
+- **Multiple AI agents** - Choose between Claude (default) or Codex for command translation
 - **Shell preservation** - Maintains your shell environment and aliases
+- **Clean output** - PTY-based execution with proper echo suppression (no garbled prompts or ANSI codes)
 
-## Note
+## Agent Selection
 
-This tool requires the Claude Code CLI (`claude` command) to be installed and configured. The translation step adds ~2-3s latency due to Claude Code CLI startup time.
+lmsh supports two AI agents for translating natural language to shell commands:
+
+### Claude (default)
+- **Model**: Haiku (fast and efficient)
+- **Command**: `claude -p "<prompt>" --model haiku`
+- **Requirement**: Claude Code CLI must be installed and configured
+- **Best for**: General shell command translation with fast response times
+
+### Codex
+- **Model**: GPT-5 (advanced reasoning)
+- **Command**: `codex exec "<prompt>"`
+- **Requirement**: Codex CLI must be installed and configured
+- **Best for**: Complex command construction requiring advanced reasoning
+
+## Requirements
+
+- At least one of the following CLI tools:
+  - **Claude Code CLI** (`claude` command) - for default Claude agent
+  - **Codex CLI** (`codex` command) - for Codex agent
+- The translation step adds ~2-3s latency due to AI model inference time

docs/local-llm-setup.md

@@ -0,0 +1,286 @@
+# Running Claude Code and Codex with Local LLMs
+
+This guide covers running **Claude Code** and **OpenAI Codex CLI** with local
+models using [llama.cpp](https://github.com/ggml-org/llama.cpp)'s server:
+
+- **Claude Code** uses the Anthropic-compatible `/v1/messages` endpoint
+- **Codex CLI** uses the OpenAI-compatible `/v1/chat/completions` endpoint
+
+## Table of Contents
+
+- [When to Use Local Models](#when-to-use-local-models)
+- [How It Works](#how-it-works)
+- [Prerequisites](#prerequisites)
+- [Shell Function for Claude Code](#shell-function-for-claude-code)
+- [Model Commands](#model-commands)
+- [Quick Reference](#quick-reference)
+- [Usage](#usage)
+- [Troubleshooting](#troubleshooting)
+- [Using Codex CLI with Local LLMs](#using-codex-cli-with-local-llms)
+
+## When to Use Local Models
+
+These local models (20B-80B parameters) aren't suited for complex coding tasks
+where frontier models excel, but they're useful for non-coding tasks like
+summarization, answering questions about your private notes, working with
+sensitive documents that can't be sent to external APIs, or high-volume tasks
+where API costs would add up.
+
+## How It Works
+
+1. **Start llama-server** with a model (see [Model Commands](#model-commands)
+   below) - this makes the model available at a local endpoint (e.g., port 8123)
+2. **Run Claude Code** pointing to that endpoint using the `cclocal` helper
+   function
+
+## Prerequisites
+
+- [llama.cpp](https://github.com/ggml-org/llama.cpp) built and `llama-server`
+  available in your PATH
+- Sufficient RAM (64GB+ recommended for 30B+ models)
+- Models will be downloaded automatically from HuggingFace on first run
+
+## Shell Function for Claude Code
+
+At its simplest, connecting Claude Code to a local model is just one line:
+
+```bash
+ANTHROPIC_BASE_URL=http://127.0.0.1:8123 claude
+```
+
+The helper function below is just a convenience wrapper for this. Add it to your
+`~/.zshrc` or `~/.bashrc`:
+
+```bash
+cclocal() {
+    local port=8123
+    if [[ "$1" =~ ^[0-9]+$ ]]; then
+        port="$1"
+        shift
+    fi
+    (
+        export ANTHROPIC_BASE_URL="http://127.0.0.1:${port}"
+        claude "$@"
+    )
+}
+```
+
+Usage:
+
+```bash
+cclocal              # Connect to localhost:8123
+cclocal 8124         # Connect to localhost:8124
+cclocal 8124 --resume abc123  # With additional claude args
+```
+
+> [!IMPORTANT]
+> Add this to your `~/.claude/settings.json` to disable telemetry:
+>
+> ```json
+> {
+>   // ... other settings ...
+>   "env": {
+>     "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
+>   }
+>   // ... other settings ...
+> }
+> ```
+>
+> Without this, Claude Code sends telemetry requests to your local server,
+> which returns 404s and retries aggressively—causing ephemeral port exhaustion
+> on macOS and system-wide network failures.
+
+## Model Commands
+
+### GPT-OSS-20B (Fast, Good Baseline)
+
+Uses the built-in preset with optimized settings:
+
+```bash
+llama-server --gpt-oss-20b-default --port 8123
+```
+
+**Performance:** ~17-38 tok/s generation on M1 Max
+
+### Qwen3-30B-A3B
+
+```bash
+llama-server -hf unsloth/Qwen3-30B-A3B-Instruct-2507-GGUF \
+  --port 8124 \
+  -c 131072 \
+  -b 32768 \
+  -ub 1024 \
+  --parallel 1 \
+  --jinja \
+  --chat-template-file ~/Git/llama.cpp/models/templates/Qwen3-Coder.jinja
+```
+
+**Performance:** ~15-27 tok/s generation on M1 Max
+
+### Qwen3-Coder-30B-A3B (Recommended)
+
+Uses the built-in preset with Q8_0 quantization (higher quality):
+
+```bash
+llama-server --fim-qwen-30b-default --port 8127
+```
+
+Downloads `ggml-org/Qwen3-Coder-30B-A3B-Instruct-Q8_0-GGUF` automatically on first
+run.
+
+### Qwen3-Next-80B-A3B (Better Long Context)
+
+Newer SOTA model. Slower generation but performance doesn't degrade as much
+with long contexts:
+
+```bash
+llama-server -hf unsloth/Qwen3-Next-80B-A3B-Instruct-GGUF:Q4_K_XL \
+  --port 8126 \
+  -c 131072 \
+  -b 32768 \
+  -ub 1024 \
+  --parallel 1 \
+  --jinja
+```
+
+**Performance:** ~5x slower generation than Qwen3-30B-A3B, but better on long
+contexts
+
+### Nemotron-3-Nano-30B-A3B (NVIDIA Reasoning Model)
+
+```bash
+llama-server -hf unsloth/Nemotron-3-Nano-30B-A3B-GGUF:Q4_K_XL \
+  --port 8125 \
+  -c 131072 \
+  -b 32768 \
+  -ub 1024 \
+  --parallel 1 \
+  --jinja \
+  --chat-template-file ~/Git/llama.cpp/models/templates/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16.jinja \
+  --temp 0.6 \
+  --top-p 0.95 \
+  --min-p 0.01
+```
+
+**Recommended settings (from NVIDIA):**
+
+- Tool calling: `temp=0.6`, `top_p=0.95`
+- Reasoning tasks: `temp=1.0`, `top_p=1.0`
+
+## Quick Reference
+
+| Model | Port | Command |
+|-------|------|---------|
+| GPT-OSS-20B | 8123 | `llama-server --gpt-oss-20b-default --port 8123|
+| Qwen3-30B-A3B | 8124 | See full command above |
+| Nemotron-3-Nano | 8125 | See full command above |
+| Qwen3-Next-80B-A3B | 8126 | See full command above |
+| Qwen3-Coder-30B | 8127 | `llama-server --fim-qwen-30b-default --port 8127 |
+
+## Usage
+
+1. Start the llama-server with your chosen model (first request will be slow
+   while model loads)
+2. In another terminal, run `cclocal <port>` to start Claude Code
+3. Use Claude Code as normal
+
+## Notes
+
+- First request is slow while the model loads into memory (~10-30 seconds
+  depending on model size)
+- Subsequent requests are fast
+- The `/v1/messages` endpoint in llama-server handles Anthropic API translation
+  automatically
+- Each model's chat template handles the model-specific prompt formatting
+
+## Troubleshooting
+
+**"failed to find a memory slot" errors:**
+
+Increase context size (`-c`) or reduce parallel slots (`--parallel 1`). Claude
+Code sends large system prompts (~20k+ tokens).
+
+**Slow generation:**
+
+- Increase batch size: `-b 32768`
+- Reduce parallel slots: `--parallel 1`
+- Check if model is fully loaded in RAM/VRAM
+
+**Model not responding correctly:**
+
+Ensure you're using the correct chat template for your model. The template
+handles formatting the Anthropic API messages into the model's expected format.
+
+---
+
+# Using Codex CLI with Local LLMs
+
+[OpenAI Codex CLI](https://github.com/openai/codex) can also use local models via
+llama-server's OpenAI-compatible `/v1/chat/completions` endpoint.
+
+## Configuration
+
+Add a local provider to `~/.codex/config.toml`:
+
+```toml
+[model_providers.llama-local]
+name = "Local LLM via llama.cpp"
+base_url = "http://localhost:8123/v1"
+wire_api = "chat"
+```
+
+For multiple ports (different models), define multiple providers:
+
+```toml
+[model_providers.llama-8123]
+name = "Local LLM port 8123"
+base_url = "http://localhost:8123/v1"
+wire_api = "chat"
+
+[model_providers.llama-8124]
+name = "Local LLM port 8124"
+base_url = "http://localhost:8124/v1"
+wire_api = "chat"
+```
+
+## Switching Models at Command Line
+
+Use the `--model` flag and `-c` (config) flag to switch models without editing
+the TOML file:
+
+```bash
+# Use GPT-OSS-20B on port 8123 (model name is immaterial)
+codex --model gpt-oss-20b -c model_provider=llama-8123
+
+# Use Qwen3-30B on port 8124 (model name is immaterial)
+codex --model qwen3-30b -c model_provider=llama-8124
+
+```
+
+You can also override nested config values with dots:
+
+```bash
+codex --model gpt-oss-20b \
+  -c model_provider=llama-local \
+  -c model_providers.llama-local.base_url="http://localhost:8124/v1"
+```
+
+## Running llama-server for Codex
+
+Use the same llama-server commands as for Claude Code.
+
+
+```bash
+# GPT-OSS-20B
+llama-server --gpt-oss-20b-default --port 8123
+
+# Qwen3-Coder-30B
+llama-server --fim-qwen-30b-default --port 8127
+```
+
+## Notes
+
+- Codex uses the `/v1/chat/completions` endpoint (OpenAI format), not
+  `/v1/messages` (Anthropic format)
+- Both endpoints are served by llama-server simultaneously
+- The same model can serve both Claude Code and Codex at the same time

docs/reddit-aichat-resume-v2.md

@@ -0,0 +1,80 @@
+# Reddit Post: aichat resume (v2)
+
+**Title:** I don't compact my Claude Code sessions. I chain them.
+
+---
+
+Compaction throws away context. I'd rather keep everything and let the 
+agent retrieve it when needed.
+
+**Core principles:**
+
+- **Lossless** — compaction summarizes and discards; I want nothing lost
+- **Searchable** — sessions must be full-text searchable, fast (Claude Code's 
+  built-in search only matches titles)
+- **Fast** — 50+ sessions in a lineage, thousands of lines each — grep doesn't 
+  scale, so I built a Tantivy-indexed Rust CLI that returns results in ms
+- **Portable** — hand off between agents: start in Claude Code, continue in 
+  Codex CLI, or vice versa
+
+**The problem with compaction:**
+
+When you hit context limits, Claude Code's default is to compact — 
+summarize and discard. But summaries lose nuance. That debugging session 
+where you finally figured out the race condition? Gone. The architectural 
+decision you made three hours ago? Flattened into a sentence.
+
+**My approach: session chaining**
+
+Instead of compacting, I chain sessions together:
+
+1. When context fills up, type `>resume`
+2. Pick a strategy (trim, smart-trim, or rollover)
+3. Start fresh — but with full lineage back to every ancestor session
+
+Nothing gets deleted. The agent traces back and pulls context on demand.
+
+**Three resume strategies:**
+
+| Strategy | What it does | When to use |
+|----------|--------------|-------------|
+| **Trim** | Truncates bloated tool outputs and early messages | Quick fix, frees 30-50% |
+| **Smart trim** | AI decides what's safe to cut | When you want surgical precision |
+| **Rollover** | Fresh session with lineage pointers | Clean slate, full history preserved |
+
+**Why Rust + Tantivy?**
+
+Session chains get long. You might have 50+ sessions in a lineage, each with 
+thousands of lines of conversation. Grepping through JSON files doesn't scale. 
+So I built `aichat-search` — a Rust CLI using Tantivy (the engine behind 
+Quickwit and other search tools). It indexes sessions on first run, then 
+returns results in milliseconds. The agent can search your entire history 
+without you waiting.
+
+**What you get:**
+
+- Fast full-text search across all sessions (Tantivy-indexed, not grep)
+- `/recover-context` command — agent pulls context from parent sessions
+- Session-searcher sub-agent — searches history without polluting your context
+- Cross-agent handoff — start in Claude Code, continue in Codex CLI, or vice versa
+
+**Quick demo:** [video in README]
+
+**Install:**
+
+```bash
+# Install the CLI tools
+uv tool install claude-code-tools
+brew install pchalasani/tap/aichat-search  # or: cargo install aichat-search
+
+# Add the plugin
+claude plugin marketplace add pchalasani/claude-code-tools
+claude plugin install "aichat@cctools-plugins"
+```
+
+Repo: https://github.com/pchalasani/claude-code-tools
+
+---
+
+Curious how others handle context limits. Do you compact and hope for the 
+best, or have you built something similar?

docs/reddit-aichat-resume.md

@@ -0,0 +1,29 @@
+# Reddit Post: aichat resume
+
+**Title:** Tool for continuing Claude Code sessions when context fills up
+
+---
+
+If you use Claude Code, you've hit this: context fills up mid-task, and your options are (a) lossy compaction that throws away information, or (b) start fresh and lose the conversation history.
+
+I built `aichat resume` to handle this. When you're running low on context:
+
+1. Type `>resume` in your session
+2. Quit Claude Code
+3. Run `aichat resume` (session ID is already in clipboard)
+4. Pick a strategy: trim large tool outputs, smart-trim with AI analysis, or rollover to fresh session
+
+The key thing: nothing gets lost. All strategies keep pointers to parent sessions, so the agent can look up prior work when needed. You get a chain of linked sessions instead of losing context.
+
+Quick demo of the `>resume` trigger: [video in README]
+
+Install:
+```
+uv tool install claude-code-tools
+claude plugin marketplace add pchalasani/claude-code-tools
+claude plugin install "aichat@cctools-plugins"
+```
+
+Repo: https://github.com/pchalasani/claude-code-tools
+
+Works with Codex too. Feedback welcome.

docs/reddit-aichat.md

@@ -0,0 +1,79 @@
+# Aichat: Session continuation without compaction, and fast full-text session search for Claude Code and Codex CLI
+
+
+
+In the [claude-code-tools](https://github.com/pchalasani/claude-code-tools) repo, I
+I've been sharing various tools I've built to improve productivity when working 
+with Claude-Code or Codex-CLI. I wanted to share `aichat` command which I use heavily to continue work **without having to compact**.
+
+Here is the thought process underlying this tool -- I think knowing the thought process and motivation helps understand what the `aichat` command-group does and why it might be useful to you. 
+
+### Compaction is lossy: clone the session and truncate long messages
+
+Session compaction is **lossy:** there are very often situations where compaction loses important details, so I wanted to find ways to continue my work without compaction. A typical scenario is this -- I am at 90% context usage, and I wish I can go on a bit longer to finish the current work-phase. So I thought,
+
+> I wish I could **truncate** some long messages (e.g. tool calls/results for file writes/reads, long assistant responses, etc) and clear out some space to continue my work.
+
+This lead to the [`aichat trim`](https://github.com/pchalasani/claude-code-tools#three-resume-strategies) utility. It provides two variants:
+
+- a "blind" [`trim`](https://github.com/pchalasani/claude-code-tools#three-resume-strategies) mode that truncates all messages longer than a threshold (default 500 chars), and optionally all-but-recent assistant messages -- all user-configurable. This can free up 40-60% context, depending on what's been going on in the session.
+
+- a [`smart-trim`](https://github.com/pchalasani/claude-code-tools#three-resume-strategies) mode that uses a headless Claude/Codex agent to determine which messages can be safely truncated in order to continue the current work. The precise truncation criteria can be customized (e.g. the user may want to continue some prior work rather than the current task).
+
+Both of these modes *clone* the current session before truncation, and inject two types of [*lineage*](https://github.com/pchalasani/claude-code-tools#lineage-nothing-is-lost):
+- *Session-lineage* is injected into the first user message: a chronological listing of sessions from which the current session was derived. This allows the (sub-) agent to extract needed context from ancestor sessions, either when prompted by the user, or on its own initiative.
+- Each truncated message also carries a pointer to the specific message index in the parent session so full details can always be looked up if needed.
+
+### A cleaner alternative: Start new session with lineage and context summary
+
+Session trimming can be a quick way to clear out context in order to continue the current task for a bit longer, but after a couple of trims, does not yield as much benefit. But the lineage-injection lead to a different idea to avoid compaction:
+
+> Create a fresh session, inject parent-session lineage into the first user message, along with instructions to extract (using sub-agents if available) context of the latest task from the parent session, or skip context extraction and leave it to the user to extract context once the session starts.
+
+This is the idea behind the [`aichat rollover`](https://github.com/pchalasani/claude-code-tools#three-resume-strategies) functionality, which is the variant I use the most frequently, and I use this instead of first trimming a session. I usually choose to skip the summarization (this is the `quick` rollover option in the TUI) so that the new session starts quickly and I can instruct Claude-Code/Codex-CLI to extract needed context (usually from the latest chat session shown in the lineage), as shown in the demo video below.
+
+### A hook to simplify continuing work from a session
+
+I wanted to make it seamless to pick any of the above three task continuation modes, when inside a Claude Code session, so I set up a `UserPromptSubmit` [hook](https://github.com/pchalasani/claude-code-tools#resume-options) (via the `aichat` plugin) that is triggered when the user types `>resume` (or `>continue` or `>handoff`). When I am close to full context usage, I type `>resume`, and the hook script copies the current session id into the clipboard and shows instructions asking the user to run `aichat resume <pasted-session-id>`; this launches a TUI that offering options to choose one of the above [session resumption modes](https://github.com/pchalasani/claude-code-tools#three-resume-strategies).
+
+**Demo video (resume/rollover flow):**
+
+https://github.com/user-attachments/assets/310dfa5b-a13b-4a2b-aef8-f73954ef8fe9
+
+### Fast full-text session search for humans/agents to find prior work context
+
+The above session resumption methods are useful to continue your work from the *current* session, but often you want to continue work that was done in an *older* Claude-Code/Codex-CLI session. This is why I added this:
+
+> Super-fast Rust/Tantivy-based [full-text search](https://github.com/pchalasani/claude-code-tools#aichat-search--find-and-select-sessions) of all sessions across Claude-Code and Codex-CLI, with a pleasant self-explanatory TUI for humans, and a CLI mode for Agents to find past work. (The Rust/Tantivy-based search and TUI was inspired by the excellent TUI in the [zippoxer/recall](https://github.com/zippoxer/recall) repo).
+
+Users can launch the search TUI using [`aichat search ...`](https://github.com/pchalasani/claude-code-tools#aichat-search--find-and-select-sessions) and (sub-) [agents can run](https://github.com/pchalasani/claude-code-tools#agent-access-to-history-the-session-searcher-sub-agent) `aichat search ... --json` and get results in JSONL format for quick analysis and filtering using `jq` which of course CLI agents are great at using. There is a corresponding *skill* called `session-search` and a *sub-agent* called `session-searcher`, both available via the `aichat` [plugin](https://github.com/pchalasani/claude-code-tools#claude-code-plugins). For example in Claude Code, users can recover context of some older work by simply saying something like:
+
+> Use your session-searcher sub-agent to recover the context of how we worked on connecting the Rust search TUI with the node-based Resume Action menus.
+
+**Demo GIF (search TUI):**
+
+![aichat search demo](https://raw.githubusercontent.com/pchalasani/claude-code-tools/main/demos/aichat-search-asciinema.gif)
+
+---
+
+**Links:**
+- GitHub repo: https://github.com/pchalasani/claude-code-tools
+
+**Install:**
+```bash
+# Step 1: Python package
+uv tool install claude-code-tools
+
+# Step 2: Rust search engine (pick one)
+brew install pchalasani/tap/aichat-search   # Homebrew
+cargo install aichat-search                  # Cargo
+# Or download binary from Releases
+
+# Step 3: Claude Code plugins (for >resume hook, session-searcher agent, etc.)
+# From terminal:
+claude plugin marketplace add pchalasani/claude-code-tools
+claude plugin install "aichat@cctools-plugins"
+# Or from within Claude Code:
+/plugin marketplace add pchalasani/claude-code-tools
+/plugin install aichat@cctools-plugins
+```

docs/rollover-details.md

@@ -0,0 +1,67 @@
+# How Rollover Works
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  ROLLOVER: Continue work in fresh context while preserving full history    │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+  ┌─────────────────────────┐
+  │  aichat resume          │  ◄── User triggers rollover of session ghi789
+  │  or aichat search       │
+  └───────────┬─────────────┘
+              │
+              ▼
+  ┌──────────────────────────────────────────────────────────────────────┐
+  │  1. TRACE LINEAGE of ghi789                                          │
+  │     Follow continue_metadata.parent_session_file pointers backwards  │
+  │                                                                      │
+  │     ghi789.jsonl ──► def456.jsonl ──► abc123.jsonl (original)        │
+  └──────────────────────────────────────────────────────────────────────┘
+              │
+              ▼
+  ┌──────────────────────────────────────────────────────────────────────┐
+  │  2. BUILD PROMPT                                                     │
+  │     • Chronological list of all ancestor session files               │
+  │     • Instructions to extract context                                │
+  │     • Optional: summary of work extracted by another agent           │
+  └──────────────────────────────────────────────────────────────────────┘
+              │
+              ▼
+  ┌──────────────────────────────────────────────────────────────────────┐
+  │  3. CREATE NEW INTERACTIVE SESSION (jkl012)                          │
+  │                                                                      │
+  │     • Work summary already present in prompt, OR                     │
+  │     • User can ask agent to recover specific parts of prior work     │
+  │       (using session-search skill or session-searcher sub-agent)     │
+  └──────────────────────────────────────────────────────────────────────┘
+              │
+              ▼
+  ┌──────────────────────────────────────────────────────────────────────┐
+  │  4. INJECT METADATA (first line of jkl012.jsonl)                     │
+  │                                                                      │
+  │     {                                                                │
+  │       "continue_metadata": {                                         │
+  │         "parent_session_file": "/path/to/ghi789.jsonl",              │
+  │         "parent_session_id": "ghi789-...",                           │
+  │         "continued_at": "2025-12-19T..."                             │
+  │       }                                                              │
+  │     }                                                                │
+  └──────────────────────────────────────────────────────────────────────┘
+              │
+              ▼
+  ┌──────────────────────────────────────────────────────────────────────┐
+  │  5. RESUME INTERACTIVELY                                             │
+  │     claude --resume jkl012  ◄── Fresh context, full history access   │
+  └──────────────────────────────────────────────────────────────────────┘
+
+
+  RESULT: Linked chain with on-demand context retrieval
+  ═══════════════════════════════════════════════════════
+
+    abc123.jsonl ◄─── def456.jsonl ◄─── ghi789.jsonl ◄─── jkl012.jsonl
+    (original)        (trimmed)         (rollover)        (NEW SESSION)
+         │                 │                 │                  │
+         └─────────────────┴─────────────────┴──────────────────┘
+         Agent can read any ancestor on demand
+         (using session-search skill or session-searcher sub-agent)
+```