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:
- Keep
SessionEnd as the main execution point for archive/delete of the current session.
- Use the hook payload's
transcript_path directly for archive/trash/purge operations.
- 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)
- Treat any session index as optional and rebuildable, mainly for review/discovery acceleration rather than as the main state source.
- 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.
Problem
The current
plugins/sessionimplementation keeps a separatesession-index.jsonstate 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:
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:
SessionEndas the main execution point for archive/delete of the current session.transcript_pathdirectly for archive/trash/purge operations.session-index.jsondependency with a much smaller pending-action store only when needed for user-triggered deferred actions, e.g.session_id -> pending-archivesession_id -> pending-delete(mode=trash|purge)This would reduce duplicated state while keeping the current slash-command UX.
Alternatives Considered
Keep the current full index/state-machine design
Hooks only, no skill support
Filesystem-only with no cached index at all
Additional Context
This is mainly about aligning the plugin with Claude Code's built-in session/transcript model:
SessionStart/SessionEndalready provide lifecycle hooks.A likely end state is:
This should make the plugin easier to reason about and more robust.