Log Conversation

---
name: log-conversation
description: "Record the current Claude Code conversation as a markdown file under $HOME/cclogs/{slug}/ for later reuse (memos, blog drafts, esa). Use when: (1) User says 'log conversation', 'record conversation', 'log-conversation', 'start logging', 'stop logging', (2) User invokes /log-conversation directly with args like -a, --all, -e, --end, or a number, (3) User wants to snapshot the chat to articlify or quote later."
argument-hint: "[N | -a | --all] [-e | --end]"
allowed-tools: Bash, Read
---

# Log Conversation

Save the current session transcript as a pair of markdown files in `$HOME/cclogs/{slug}/`
(same directory other skills use — see `logrefer`). The skill is session-scoped: state lives in
`$HOME/cclogs/{slug}/.log-conversation-state.<sessionId>.json`, so multiple concurrent sessions
do not collide.

Two files are written on each save (sharing the same timestamp base):

- `{stamp}-conversation.md` — **conversation only**: user + assistant text turns, no tool calls,

  no tool results, no thinking blocks. Optimized for human reading and reuse in articles/memos.

- `{stamp}-conversation.raw.md` — **full raw transcript**: everything in the conversation file

  plus thinking blocks, `tool_use` blocks with arguments, and `tool_result` blocks.

## Arguments ($ARGUMENTS)

Parse `$ARGUMENTS` into these flags (all optional, none required):

| Token | Meaning |
|---|---|
| `-a` / `--all` | Start a new log from the first user turn in the session |
| An integer `N` (e.g. `3`) | Start a new log from the Nth-most-recent user turn (1 = current) |
| `-e` / `--end` | Finalize: refresh the active log once more, then clear state |

If both `-a`/`N` and `-e` are given: start fresh AND finalize in a single shot (one-off save,
no persistent state).

If no args are given:

- If an active log already exists for this session → **refresh** it (overwrite with latest content).
- If no active log exists → **start** a new one from the current user turn.

## Workflow

### Step 1: Decide command and call the script

Pick the subcommand based on flags + whether state exists. Check state first:

```bash
node $HOME/.claude/skills/log-conversation/scripts/log-conversation.mjs status \
  --session "${CLAUDE_SESSION_ID}"
```

Exit code `0` = active, `1` = no active log. Then dispatch:

| Situation | Command |
|---|---|
| No args, no active state | `start` (default: from current user turn) |
| No args, active state exists | `refresh` |
| `-e` only, active state exists | `end` |
| `-e` only, no active state | `start --end` (snapshot from current turn, one-shot) |
| `-a` / `--all` | `start --all` (add `--end` if `-e` also given) |
| `N` (integer) | `start --n N` (add `--end` if `-e` also given) |

Invocation:

```bash
node $HOME/.claude/skills/log-conversation/scripts/log-conversation.mjs <cmd> \
  --session "${CLAUDE_SESSION_ID}" \
  [--n N] [--all] [--end]
```

The script prints a JSON line like:

```json
{ "action": "start",
  "logFile": "/Users/.../cclogs/slug/20260422_110000-conversation.md",
  "rawLogFile": "/Users/.../cclogs/slug/20260422_110000-conversation.raw.md",
  "startUuid": "…", "entries": 73, "ended": false }
```

`logFile` is the conversation-only `.md`; `rawLogFile` is the full transcript `.raw.md`.
Both files are rewritten on every `start` / `refresh` / `end`.

### Step 2: Report to the user

Report a short status with the absolute `logFile` path (and optionally `rawLogFile`). Mention
whether the log is now active (will be refreshed on next invocation) or finalized (state cleared).
Do not dump the file content to chat — the file is the point.

### Step 3 (optional): Open the file

If the user asks to see the log, use Read on the returned `logFile` (conversation only) or
`rawLogFile` (full transcript) path.

## Script Reference

`scripts/log-conversation.mjs` supports these subcommands (session ID via `--session` or
`$CLAUDE_SESSION_ID`):

- `start [--n N | --all] [--name NAME] [--end]` — create state, write log; `--end` deletes state after write (one-shot).
- `refresh` — rewrite the existing log from state.
- `end` — refresh + delete state.
- `status` — print active state as JSON (exit 1 if none).

The conversation log filename is `{YYYYMMDD}_{HHMMSS}-conversation[-name].md`, with the raw
counterpart `{YYYYMMDD}_{HHMMSS}-conversation[-name].raw.md` written alongside it. Once set
on `start`, the same paths are reused on every `refresh` / `end` for that session.

## Notes

- The current assistant response (the one generated by this invocation) is not yet in the transcript file when the script runs, so the final turn will be missing. The next invocation (or re-running `end`) picks it up. This is fine for typical use.
- Sidechain (subagent) turns are excluded so the log stays focused on the main conversation.
- Meta user messages (caveats, attachment markers) are kept but tagged `_(meta)_` in the log.
- State is per-session; `/clear` does not wipe state files — invoke `-e` to tidy up, or let old state files linger harmlessly in `$HOME/cclogs/{slug}/`.