log-conversation

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:

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:

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:

{ "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}/.