Skip to content

[Feature] Simplify session archive/delete around Claude Code transcripts #25

@codeasier

Description

@codeasier

Problem

The current plugins/session implementation keeps a separate session-index.json state machine for archive/delete/review flows, even though Claude Code already provides the key session facts through its own transcript management and hook payloads (session_id, transcript_path, cwd).

This creates extra complexity for archive/delete behavior:

  • a second source of truth for session lifecycle state
  • stale-session reconciliation logic
  • lock management and corruption handling for the index
  • more edge cases where plugin state can drift from the real transcript filesystem state

For archive/delete specifically, most of the behavior is fundamentally file operations on the transcript path that Claude Code already gives us at SessionEnd.

Proposed Solution

Refactor the session plugin so that archive/delete are implemented as filesystem-first, hook-first operations, with Claude Code transcript paths as the primary source of truth.

Suggested direction:

  1. Keep SessionEnd as the main execution point for archive/delete of the current session.
  2. Use the hook payload's transcript_path directly for archive/trash/purge operations.
  3. Replace the full lifecycle session-index.json dependency with a much smaller pending-action store only when needed for user-triggered deferred actions, e.g.
    • session_id -> pending-archive
    • session_id -> pending-delete(mode=trash|purge)
  4. Treat any session index as optional and rebuildable, mainly for review/discovery acceleration rather than as the main state source.
  5. For historical session operations, prefer locating transcripts from Claude Code's project transcript tree first, with optional indexing as a cache.

This would reduce duplicated state while keeping the current slash-command UX.

Alternatives Considered

  • Keep the current full index/state-machine design

    • Pros: one place to look up metadata and pending state.
    • Cons: more moving parts than archive/delete seem to require; state drift remains possible.
  • Hooks only, no skill support

    • Pros: simplest implementation.
    • Cons: loses useful interactive flows like marking the current session for archive/delete or canceling a pending action.
  • Filesystem-only with no cached index at all

    • Pros: minimal state.
    • Cons: historical review and lookup may become slower or less ergonomic across many projects.

Additional Context

This is mainly about aligning the plugin with Claude Code's built-in session/transcript model:

  • SessionStart / SessionEnd already provide lifecycle hooks.
  • Claude Code already owns transcript creation and session identity.
  • Archive/delete appear to need only lightweight deferred intent, not a full second lifecycle database.

A likely end state is:

  • archive/delete -> hook-first + transcript-path-first
  • optional pending actions -> tiny state file
  • review/search -> optional rebuildable index/cache

This should make the plugin easier to reason about and more robust.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions