Skip to content

Remove context.md and simplify prompt.txt to checkpoint prompts only #571

@gtrrz-victor

Description

@gtrrz-victor

Problem or use case

Context

Investigation revealed that context.md is dead code (written but never consumed) and prompt.txt stores all session
prompts but every consumer only uses the first one. This is unnecessary complexity and wasted storage.

Goal:

  1. Remove context.md entirely (dead code)
  2. Simplify prompt.txt to store only the first prompt (the one that triggered the checkpoint)

How prompt.txt flows today

Two independent write paths:

  1. Filesystem → shadow branches: handleLifecycleTurnEnd() (lifecycle.go:266) writes all prompts joined by
    \n\n---\n\n to .entire/metadata/{sessionID}/prompt.txt. Then copyMetadataDir() copies it to the shadow branch.
  2. Condensation → committed branch: extractSessionData() (manual_commit_condensation.go:487) extracts prompts from
    transcript. CondenseSession() passes []string to WriteCommitted() which joins them with \n\n---\n\n and writes
    prompt.txt blob in writeSessionToSubdirectory().

Changes

  1. Remove context.md generation and writing

cmd/entire/cli/strategy/manual_commit_condensation.go:

  • Remove generateContextFromPrompts() function (lines 695-716)
  • Remove data.Context = generateContextFromPrompts(data.Prompts) (line 488)
  • Remove data.Context from the struct / stop passing Context to WriteCommittedOptions

cmd/entire/cli/checkpoint/checkpoint.go:

  • Remove Context []byte from WriteCommittedOptions (line 221)
  • Remove Context string from SessionContent (line 360)
  • Remove Context string from SessionFilePaths (line 419)
  • Remove context.md from CheckpointSummary structure comment (lines 430-440)

cmd/entire/cli/checkpoint/committed.go:

  • writeSessionToSubdirectory(): Remove context.md blob creation (lines 367-379)
  • UpdateCommitted(): Remove context.md replacement (lines 1222-1233)
  • ReadSessionContent(): Remove context.md file read (lines 837-842)
  • writeStandardCheckpointEntries() comment: Remove context.md from structure doc

cmd/entire/cli/paths/paths.go:

  • Remove ContextFileName = "context.md" constant (line 24)
  1. Remove context.md consumers

cmd/entire/cli/strategy/manual_commit_logs.go:

  • Remove GetSessionContext() (line 99) — dead code, zero callers

cmd/entire/cli/strategy/common.go:

  • getSessionDescriptionFromTree() (line 1255): Remove context.md fallback (lines ~1289-1293 and ~1312 where it
    searches for ContextFileName)
  1. Scope prompt.txt to checkpoint-only prompts

Today prompt.txt stores ALL prompts from the entire session. Change it to store only the prompts from the current
checkpoint.

Two write paths need updating:

A. Condensation path (cmd/entire/cli/strategy/manual_commit_condensation.go):

  • extractSessionData() (line 487): Currently calls extractUserPrompts(agentType, fullTranscript) on the full
    transcript. Change to extract only prompts after checkpointTranscriptStart (already a parameter on line 439).
  • For JSONL agents (Claude Code): pass only lines from checkpointTranscriptStart onward to
    extractUserPromptsFromLines()
  • For JSON agents (Gemini/OpenCode): need to slice messages after the start offset
  • extractSessionDataFromLiveTranscript() (line 502): Same change — use state.CheckpointTranscriptStart to scope
    prompts

B. Filesystem path (cmd/entire/cli/lifecycle.go):

  • Line 231: analyzer.ExtractPrompts(transcriptRef, transcriptOffset) — this already uses offset, so prompts from
    lifecycle.go are already checkpoint-scoped. No change needed here.

Write path (cmd/entire/cli/checkpoint/committed.go):

  • No structural changes needed — writeSessionToSubdirectory() and UpdateCommitted() still join and write prompts
    the same way. The content is just scoped differently now.
  1. No changes to consumers

Since prompt.txt still contains prompts joined by \n\n---\n\n (just fewer of them), all consumers work as-is:

  • ExtractFirstPrompt() — still splits and takes first
  • extractLastPrompt() — still splits and takes last
  • getLastPrompt() — still reads from shadow branch
  • Rewind display — still uses ExtractFirstPrompt(content.Prompts)
  1. Update callers of WriteCommittedOptions

No changes needed — Prompts []string stays the same type, just with fewer entries.

  1. Update tests
  • cmd/entire/cli/checkpoint/checkpoint_test.go — Remove content.Context assertions, remove Context from
    WriteCommittedOptions
  • cmd/entire/cli/checkpoint/committed_update_test.go — Same
  • cmd/entire/cli/strategy/phase_postcommit_test.go — Remove content.Context references
  • cmd/entire/cli/strategy/common_test.go — Remove context.md fallback tests in getSessionDescriptionFromTree tests
  • cmd/entire/cli/strategy/session_test.go — Remove context.md references
  1. Update documentation
  • CLAUDE.md — Remove context.md from metadata structure, note prompt.txt contains checkpoint-scoped prompts
  • docs/architecture/sessions-and-checkpoints.md — Same

Backward compatibility

  • Old context.md files on entire/checkpoints/v1 are simply ignored (no reader anymore)
  • Old prompt.txt files with all-session prompts still work — consumers use ExtractFirstPrompt() /
    extractLastPrompt() which handle both formats
  • ReadSessionContent() still reads prompt.txt the same way

Verification

  1. mise run fmt && mise run lint
  2. mise run test:ci
  3. Manual: entire explain on a repo with existing checkpoints (backward compat)
  4. Manual: Create a new session, commit, verify no context.md on committed branch and prompt.txt contains only
    checkpoint-scoped prompts
  5. Manual: entire rewind to verify session labels display correctly

Desired behavior

Proposed solution

No response

Alternatives or workarounds

No response

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions