iterative-works/iw-cli

Watch

Fork 0

Export Claude Code transcripts before worktree removal #80

New issue

Open

opened 2026-01-02 17:52:47 +00:00 by mprihoda · 4 comments

mprihoda commented

2026-01-02 17:52:47 +00:00

(Migrated from github.com)

Summary

When removing a worktree with iw rm, export Claude Code session transcripts to a persistent location before the worktree (and its associated sessions) become inaccessible.

Motivation

Claude Code stores session transcripts in ~/.claude/projects/{encoded-path}/ where the path is tied to the worktree directory. When we remove a worktree:

The path-based session binding breaks
Claude's retention policy is unknown - files could be purged anytime
We lose valuable context about how decisions were made

Transcripts are useful for:

Project-specific: Understanding decisions, referencing implementation details
Cross-project: Analyzing and optimizing development workflows

Proposed Solution

Storage Structure

~/transcripts/
├── {project}/
│   ├── {issue-id}/
│   │   ├── YYYY-MM-DD_session-{id}.jsonl  # raw for analysis
│   │   └── YYYY-MM-DD_session-{id}.md     # human-readable (optional)

Implementation in `iw rm`

Before removing the worktree:

Look up worktree path from server state
Encode path to find Claude's session directory:
- /home/user/project-IW-79 → -home-user-project-IW-79
- Location: ~/.claude/projects/{encoded-path}/
Copy session files to ~/transcripts/{project}/{issue-id}/
Optionally convert JSONL to Markdown for readability
Proceed with normal worktree removal

Path Encoding

Claude encodes paths by replacing / with - and prepending -:

/home/mph/Devel/projects/iw-cli-IW-79 → -home-mph-Devel-projects-iw-cli-IW-79

Configuration

Consider adding to .iw/config.conf:

transcripts {
  enabled = true
  path = "~/transcripts"
  formats = ["jsonl", "md"]  # which formats to save
}

Acceptance Criteria

iw rm exports transcripts before worktree removal
Transcripts are stored in predictable location outside project repos
Both JSONL (for analysis) and MD (for reading) formats supported
Graceful handling if no Claude sessions exist for the worktree
Configuration option to enable/disable and customize path

Notes

Third-party tool claude-conversation-extractor exists for JSONL→MD conversion, but we may want a simpler built-in solution
Consider adding iw transcripts list and iw transcripts search commands later

## Summary When removing a worktree with `iw rm`, export Claude Code session transcripts to a persistent location before the worktree (and its associated sessions) become inaccessible. ## Motivation Claude Code stores session transcripts in `~/.claude/projects/{encoded-path}/` where the path is tied to the worktree directory. When we remove a worktree: 1. The path-based session binding breaks 2. Claude's retention policy is unknown - files could be purged anytime 3. We lose valuable context about how decisions were made Transcripts are useful for: - **Project-specific:** Understanding decisions, referencing implementation details - **Cross-project:** Analyzing and optimizing development workflows ## Proposed Solution ### Storage Structure ``` ~/transcripts/ ├── {project}/ │ ├── {issue-id}/ │ │ ├── YYYY-MM-DD_session-{id}.jsonl # raw for analysis │ │ └── YYYY-MM-DD_session-{id}.md # human-readable (optional) ``` ### Implementation in `iw rm` Before removing the worktree: 1. **Look up worktree path** from server state 2. **Encode path** to find Claude's session directory: - `/home/user/project-IW-79` → `-home-user-project-IW-79` - Location: `~/.claude/projects/{encoded-path}/` 3. **Copy session files** to `~/transcripts/{project}/{issue-id}/` 4. **Optionally convert** JSONL to Markdown for readability 5. **Proceed** with normal worktree removal ### Path Encoding Claude encodes paths by replacing `/` with `-` and prepending `-`: ``` /home/mph/Devel/projects/iw-cli-IW-79 → -home-mph-Devel-projects-iw-cli-IW-79 ``` ### Configuration Consider adding to `.iw/config.conf`: ```hocon transcripts { enabled = true path = "~/transcripts" formats = ["jsonl", "md"] # which formats to save } ``` ## Acceptance Criteria - [ ] `iw rm` exports transcripts before worktree removal - [ ] Transcripts are stored in predictable location outside project repos - [ ] Both JSONL (for analysis) and MD (for reading) formats supported - [ ] Graceful handling if no Claude sessions exist for the worktree - [ ] Configuration option to enable/disable and customize path ## Notes - Third-party tool `claude-conversation-extractor` exists for JSONL→MD conversion, but we may want a simpler built-in solution - Consider adding `iw transcripts list` and `iw transcripts search` commands later

Necmttn commented

2026-06-21 09:44:27 +00:00

(Migrated from github.com)

I would export a manifest alongside the copied JSONL files.

Useful fields: original worktree path, encoded Claude project dir, session id, transcript filename, sha256, issue/worktree id, branch/head commit if known, exported_at, and destination path. Then iw rm can be retried safely and later tools can prove which raw transcript produced a markdown view.

The raw copy should happen before any conversion, so converter bugs do not lose the only source artifact.

Generated with ax.

I would export a manifest alongside the copied JSONL files. Useful fields: original worktree path, encoded Claude project dir, session id, transcript filename, sha256, issue/worktree id, branch/head commit if known, exported_at, and destination path. Then `iw rm` can be retried safely and later tools can prove which raw transcript produced a markdown view. The raw copy should happen before any conversion, so converter bugs do not lose the only source artifact. --- _Generated with [ax](https://github.com/Necmttn/ax)._

claude commented

2026-10-16 09:30:13 +00:00

Member

Intake: agent-ready
Workflow: waterfall
Reason: all gates passed
Analysis: project-management/issues/IW-80/analysis.md on branch IW-80

Intake: agent-ready Workflow: waterfall Reason: all gates passed Analysis: project-management/issues/IW-80/analysis.md on branch IW-80

claude added the

agent-ready

label

2026-10-16 09:30:14 +00:00

claude commented

2026-10-16 09:34:37 +00:00

Member

Implement: needs-human
Reason: batch-implement exit 1 — the kanon plugin does not compile against the iw-cli core of this branch, so no phase started

batch-implement.log was not written: the command failed at its scala-cli compile, before it started. The compiler output:

[error] /home/mph/.local/share/iw/plugins/kanon/lib/batch/ForgeCatchUp.scala:143:7
[error] Found:    Either[iw.core.model.TrackerError, Option[batch.ForgeState]]
[error] Required: Either[String, Option[batch.ForgeState]]
Compilation failed

The branch is current with main. fetchPullRequestForBranch on CommandEnv returns TrackerError since #778 and #780, and the installed kanon plugin still expects String. This failure is not specific to this issue: every batch-implement run on current main stops here until the plugin is updated to the new error type. When the plugin compiles, release this issue to agent-ready again.

Implement: needs-human Reason: batch-implement exit 1 — the kanon plugin does not compile against the iw-cli core of this branch, so no phase started `batch-implement.log` was not written: the command failed at its scala-cli compile, before it started. The compiler output: ``` [error] /home/mph/.local/share/iw/plugins/kanon/lib/batch/ForgeCatchUp.scala:143:7 [error] Found: Either[iw.core.model.TrackerError, Option[batch.ForgeState]] [error] Required: Either[String, Option[batch.ForgeState]] Compilation failed ``` The branch is current with `main`. `fetchPullRequestForBranch` on `CommandEnv` returns `TrackerError` since #778 and #780, and the installed kanon plugin still expects `String`. This failure is not specific to this issue: every `batch-implement` run on current `main` stops here until the plugin is updated to the new error type. When the plugin compiles, release this issue to `agent-ready` again.

claude added

needs-human

and removed

agent-ready

labels

2026-10-16 09:34:37 +00:00

claude commented

2026-10-16 17:10:29 +00:00

Member

Release: the implement loop failed this issue for a reason outside it. The kanon plugin did not compile against iw-cli main, because the tracker port now returns TrackerError (iw-cli #778). The plugin fix is dev-docs #484, and iw-cli 0.22.1 carries the core change. The issue goes back to the implement loop.

claude added

agent-ready

and removed

needs-human

labels

2026-10-16 17:10:29 +00:00