Documentation > Tutorials > Session Recording & Playback

Guide ID	T-10
Audience	Developers, SysAdmins
Prerequisites	GS-3: How It Works
Time	12 minutes
Difficulty	Intermediate

Session Recording & Playback

Session recording is the observation layer that feeds all of GSD Skill Creator's learning features. When you work in Claude Code, the system records compact summaries of your activity. These observations drive skill suggestions, pattern discovery, co-activation tracking, and feedback-driven refinements. This tutorial explains what gets recorded, where data is stored, how to configure retention and feature toggles, and how to review the patterns derived from your session data.

What Gets Observed

The observation system captures four categories of session data as compact summaries. It does not store full conversation transcripts — only structured metadata about your actions:

• Commands executed — Shell commands run through Bash (git operations, build commands, test commands, deployments). Commands are classified into categories: git, build, test, install, search, file-ops, docker, and other.
• Files touched — File types, paths, and access patterns. The system records which files were read, edited, or created, enabling file-based trigger patterns for skills.
• Decisions made — Choices, preferences, and corrections. When you override a suggestion or correct output, this is recorded as high-signal feedback that can drive skill refinement.
• Skills activated — Which skills loaded during the session, when they triggered, and whether the activation was correct (continued use) or incorrect (corrected by user).

Storage Format

Session observations are stored in .planning/patterns/sessions.jsonl using an append-only JSONL format. Each line is a complete JSON object representing one session observation. The append-only design ensures safe concurrent writes — multiple processes can write to the file without corruption.

Related data files in the same directory:

• sessions.jsonl — Session observations (the primary data file)
• suggestions.json — Skill suggestions derived from session patterns
• feedback.jsonl — User corrections to skill output (drives refinement)
• agent-suggestions.json — Agent composition suggestions from co-activation patterns

Retention Configuration

Observation data is bounded to prevent unbounded growth. The default retention settings are:

Setting	Default	Description
maxAgeDays	90	Maximum age of observations in days
maxSessions	1000	Maximum number of sessions to retain

Whichever limit is reached first triggers cleanup. Older observations are removed to make room for new ones, ensuring the data stays fresh and relevant.

Feature Toggles

The integration configuration file at .planning/skill-creator.json provides per-feature toggles that control which aspects of the system are active:

{
  "features": {
    "session_observation": true,
    "skill_loading": true,
    "passive_monitoring": true,
    "dashboard_generation": false
  }
}

Feature descriptions:

• session_observation — Controls whether session activity is recorded to sessions.jsonl. Disable to stop all recording.
• skill_loading — Controls whether skills are automatically loaded into Claude Code sessions based on context matching.
• passive_monitoring — Controls background pattern detection that feeds the suggestion system.
• dashboard_generation — Controls whether planning documentation dashboards are regenerated on state changes.

All fields are validated with Zod schemas. Missing fields use sensible defaults (true for observation and loading, false for dashboard generation).

Viewing Observations

Use the suggest command to review patterns derived from session data:

skill-creator suggest

This analyzes patterns in sessions.jsonl and surfaces skill suggestions when patterns repeat 3 or more times. The interactive review workflow lets you accept, defer, or dismiss each suggestion.

To see suggestion statistics without the interactive workflow:

skill-creator suggestions

The Feedback Loop

Corrections you make during sessions are stored in .planning/patterns/feedback.jsonl. This feedback drives the refinement system:

• When you override or correct skill output, the correction is recorded
• After 3 or more corrections to the same skill, the system proposes a bounded refinement
• Refinements are limited to 20% content change with a 7-day cooldown
• All refinements require your explicit confirmation

View feedback for a specific skill:

skill-creator feedback list my-skill

Privacy Considerations

For shared repositories, add the patterns directory to .gitignore to prevent session data from being committed:

# Add to .gitignore
.planning/patterns/sessions.jsonl
.planning/patterns/feedback.jsonl

Session observations contain metadata about your coding activity, which may include file paths, command names, and workflow patterns. While no full conversation transcripts are stored, the metadata itself could be sensitive in shared environments.

You can keep smaller files tracked while excluding the larger observation data:

# Exclude large observation files, keep smaller metadata
.planning/patterns/sessions.jsonl
!.planning/patterns/suggestions.json
!.planning/patterns/agent-suggestions.json

Token Budget Configuration

The integration config also controls the token budget for skill loading:

{
  "token_budget": {
    "cumulative_char_budget": 15500,
    "profile_budgets": {
      "executor": 20000,
      "planner": 12000,
      "researcher": 8000
    }
  }
}

Different agent profiles can have different budgets. The profile name is derived by stripping the gsd- prefix — a request for profile gsd-executor looks up executor in the map. This allows execution phases to load more skills than planning phases, for example.

What's Next

• How It Works — Review the complete six-step workflow that session recording feeds
• Configuration Reference — Full documentation for all configuration options and integration settings