CLI Reference

contxt sessions

View session history, inspect logged events, and resume working context after an AI context compaction.

Subcommands

Command	Description
contxt sessions	List recent sessions with event counts and duration
contxt sessions show <session-id>	Show all logged events for a specific session
contxt sessions resume	Print the latest session snapshot — use after context compaction to restore working state

Example output

$ contxt sessions

Recent sessions — my-app

  sess_abc123   payment-integration     47 events   2h 12m   ended 3h ago  ◆ snapshot
  sess_def456   auth-refactor           23 events   58m      ended 1d ago
  sess_ghi789   onboarding-flow         61 events   3h 41m   ended 3d ago  ◆ snapshot

$ contxt sessions show sess_abc123

Events — payment-integration (sess_abc123)

  14:02  decision_made    Chose Stripe over Braintree for webhook reliability
  14:18  file_edited      src/api/webhooks/stripe.ts
  14:35  error_hit        Webhook signature verification failing in test env
  14:52  task_completed   Stripe webhook handler implemented and tested
  15:10  file_edited      src/lib/stripe.ts, src/api/webhooks/stripe.ts
  ...

$ contxt sessions resume

Resume snapshot for session: payment-integration

  Goal     Implement Stripe payment webhooks
  Completed
    - Stripe webhook handler (src/api/webhooks/stripe.ts)
    - Signature verification middleware
  In progress
    - Retry logic for failed webhook deliveries
  Blockers
    - Test environment Stripe CLI setup
  Next steps
    - Wire up retry queue
    - Write integration tests

Session events

During a session, your AI agent silently logs notable events using the contxt_session_event MCP tool. Four event types are tracked:

Type	When it fires
decision_made	An architectural or design decision is made
file_edited	A file is written or significantly modified
task_completed	A discrete task or sub-task is finished
error_hit	An error is encountered that is not immediately resolved

Rolling snapshots and compaction survival

Every 10 events, Contxt automatically builds a compact “resume snapshot” — a structured summary of goals, completed work, in-progress tasks, blockers, and next steps. This snapshot is stored in the session entry’s metadata so it survives context window compression.

When your AI editor compacts the context (Claude Code’s automatic compaction, Gemini’s rolling window, etc.), the history is lost — but the snapshot is not. Your CLAUDE.md (and equivalent files for other platforms) instructs the AI to call contxt_session_resume immediately after loading, restoring full working context in a single tool call.

# After your AI context was compacted — get back up to speed
$ contxt sessions resume

You can also paste the resume output directly into a new chat to restore context manually, or run contxt sessions show <id> to see the full event log for deeper investigation.

Relation to `contxt session`

contxt session (singular) manages session lifecycle — start, end, current. contxt sessions (plural) is the history viewer. Use both together: start a session at the beginning of a coding task, let events be auto-logged, and use contxt sessions resume whenever you need to restore context.