conversation-compiler

Files (2)

• SKILL.md
• VCC.py · scripts/

SKILL.md (first lines)

# VCC — View-oriented Conversation Compiler

Compile Claude Code JSONL logs into adaptive views for reading, searching, and context recovery.

## Usage

```bash
python "path/to/VCC.py" <input.jsonl ...> [options]
```

| Option | Description |
|--------|-------------|
| `-o <dir>` | Output directory (default: same as input) |
| `-t <N>` | Token truncation limit (default 128) |
| `-tu <N>` | User message token limit (default 256) |
| `--grep <pattern>` | Regex search pattern (Python `re` — use `a|b`, NOT `a\|b`) |

This tool also supports multi-file processing:

```bash
cd "/path/to/target/folder" && python "path/to/VCC.py" *.jsonl --grep "keyword"
```

## Output Files

| File | When | Description |
|------|------|-------------|
| `.txt` | Always | Full transcript, lossless |
| `.min.txt` | Always | Brief overview |
| `.view.txt` | `--grep` only | Search-focused view |
| stdout | `--grep` only | Search results with block-level line range references |

## Rules

- **Forward slashes only in bash commands.** Backslashes in double quotes are escape characters — `\U`, `\l`, `\.` get silently mangled. Use `"C:/Users/..."` not `"C:\Users\..."`. This applies to ALL bash commands (not just this skill), on ALL platforms (Windows and Linux alike).
- Do NOT use `-o` unless the user explicitly requests an output directory. By default, compiled files are written next to the input JSONL — this is the intended behavior.
- Do NOT clean up compiled output files after use. Leave them in place unless the user explicitly asks to clean up.

## Workflow

**1. Compile**

```bash
python "path/to/VCC.py" "path/to/conversation.jsonl"
```

Produces `.txt` + `.min.txt` next to the input file. Long conversations are automatically split into numbered chunks. The console output lists every produced file with line/word counts — read it to understand the conversation's size and structure before proceeding:

```
conversation_1.txt  (2808 lines, 34545 words)
conversation_2.txt  (9622 lines, 116015 words)
conversation_3.txt  (3242 lines, 37946 words)
conversation_1.min.txt  (101 lines, 1572 words)
conversation_2.min.txt  (811 lines, 9504 words)
conversation_3.min.txt  (205 lines, 3340 words)
```

Chunks are numbered chronologically — higher numbers are more recent. (During `/recall`, the last chunk is the current conversation; the second-to-last is likely where the previous session's context ends.) Use this to gauge how many chunks exist and how large each is, so you can target your `.min.txt` reads and `--grep` searches to the right chunks.

**2. Read `.min.txt`**

The `.min.txt` is a scannable outline: user/assistant text is kept (truncated), tool calls collapse to one-line summaries with line references back to `.txt`.

```
[user]

Take a look!

[assistant]

Let me take a look.

* Read "code.py" (a_1.txt:19-21,24-34)
```

Each `*` line shows the tool name, key parameter, and two `.txt` line ranges: the call (19-21) and the result (24-34). Read these ranges in `.txt` for full details.

**3. Search with `--grep`**

Always use `--grep`, never system grep nor your embedded Grep tool. This script's `--grep` returns important block-level line RANGES that no other grep tools can provide. The output paths are relative to CWD, so `cd` close to the target first to keep outputs short and save tokens.

```bash
cd "/path/to/target/folder" && python "path/to/VCC.py" "path/to/conversation.jsonl" --grep "keyword"
```

Stdout example (`#` prefix = shortened filename)：

```
(#752a87.txt:L67-L81) [assistant]      →  .txt lines 67-81
  77: one matched line ...             →  .txt line 77
```

Optionally read `.view.txt` for focused search view.

**4. Jump to `.txt`**

All line references point to `.txt`. Read the referenced range for full context. Remember to read a bit more lines before and after the referenced range to get more context.

# SKILLs

## /readchat — Read a specific conversation log

**Trigger**: The user wants to read a specific JSONL conversation log.

**Action**: Follow the Workflow above with the user-specified filenames or requests.

## /searchchat — Search across conversation logs

**Trigger**: The user wants to search across conversation logs in `~/.claude/projects/`.

**Action**:

1. `ls ~/.claude/projects/` — browse project directories, narrow the search area.
2. `cd ~/.claude/projects/<project> && python "absolute/path/to/VCC.py" *.jsonl --grep "keyword"` — search top-level conversations first.
3. If no results: `cd ~/.claude/projects/<project> && python "absolute/path/to/VCC.py" **/*.jsonl --grep "keyword"` — expand to subagents.

**Critical**: Always `cd` into the target directory first, then use VCC globs — a single `cd && python VCC.py <glob> --grep` is the correct pattern. Without `cd`, grep output contains full absolute paths instead of short relative paths, wasting tokens. All content search on JSONL must use VCC's `--grep`, never system grep or the embedded Grep tool — VCC's `--grep` returns block-level line ranges with role tags that no other grep can provide.

## /recall — Recover context from a previous conversation

From zbzq8ztx22-star/VCC, Apache-2.0.