create-sessions-dir

This package is archived. Use the Sessions plugin instead:

claude plugin marketplace add vieko/sessions
claude plugin install sessions@vieko

The plugin offers the same workflow with subagents, specs, reviews, and native Claude Code integration.

---

Scaffold a Sessions Directory for working with AI coding agents.

What is this?

create-sessions-dir sets up the Sessions Directory Pattern in your project - a workflow for maintaining context across sessions with stateless AI agents like Claude Code.

Instead of relying on the agent to "remember" previous conversations, you maintain a living document that gets read at session start and updated at session end. Simple, effective, and surprisingly powerful.

Learn more: Pairing with a Partner Who Forgets Everything

Quick Start

Run this in any project directory:

npx create-sessions-dir

This creates:

• .sessions/ directory with context files
• .claude/commands/ with slash commands for Claude Code
• .claude/scripts/ with helper scripts
• Templates and workflow guide
• Optionally creates or updates CLAUDE.md to document the pattern

Then start your first session:

/start-session

What Gets Created

.sessions/
  index.md          # Your living context document
  archive/          # For completed work
  plans/            # Implementation plans
  prep/             # Pre-session context
  README.md         # Workflow guide and examples
  .gitignore        # Ignores data/, scratch/ directories
  WORKSPACE.md      # Monorepo guide (if detected)

.claude/
  commands/
    start-session.md    # /start-session command
    end-session.md      # /end-session command
    document.md         # /document <topic> command
    plan.md             # /plan command
    archive-session.md  # /archive-session command
  scripts/
    untrack-sessions.sh # Git strategy helper
  skills/
    session-context/    # Auto-reads context when relevant
    archive-session/    # Suggests archiving after PR merges

Usage

Start a Session

/start-session

Claude reads your context and asks what you want to work on. You can provide a GitHub/Linear URL and Claude will fetch details automatically.

End a Session

/end-session

Claude updates your context with session accomplishments and commits the changes.

Plan Implementation

/plan

Claude launches a planning agent to design your implementation, creating a structured plan in .sessions/plans/.

Document a Topic

/document architecture

Claude launches an exploration agent to understand the topic, then creates documentation in .sessions/docs/.

Archive Completed Work

/archive-session

Claude moves finished work to the archive to keep your context file clean.

Automatic Suggestions: After merging PRs or when you mention completion ("shipped", "done with X"), the archive-session skill prompts whether to archive - no manual tracking needed.

Change Git Strategy

/change-git-strategy

Change how .sessions/ is handled in git (hybrid, commit all, or ignore all). Useful if you want to share more/less with your team.

Skills (Passive Context)

In addition to slash commands (user-invoked), this package installs skills that Claude uses automatically when relevant.

Session Context Skill

Claude automatically reads .sessions/index.md when you ask about:

• "What's the project status?"
• "What were we working on?"
• "What decisions have we made?"
• "What's blocking us?"

No need to run /start-session for quick context questions - Claude just knows.

Archive Session Skill

Claude suggests archiving when:

• You ask to merge a PR: "merge it", "merge the PR", "ship it"
• After successfully running gh pr merge
• You mention completion: "PR merged", "shipped", "done with X"

Claude suggests but doesn't archive automatically - you stay in control.

Requirements

• Any project (works with any language/framework)
• Claude Code CLI (optional but recommended for slash commands)

Updating

Already have a Sessions Directory from v0.1 or v0.2? Just run:

npx create-sessions-dir

It will detect your existing setup and update it to v0.3.0 without touching your work. All your session notes, archive, and docs are preserved. Only the commands and structure are updated.

Interactive Setup

During installation, you'll be prompted for:

1. Git strategy - How .sessions/ should be handled in git

   • Ignore all (default) - Keep sessions completely local
   • Hybrid - Commit docs/plans, keep notes private
   • Commit all - Share everything with team

2. CLAUDE.md documentation - Document the pattern for your team

   • Creates new CLAUDE.md if none exists
   • Appends to existing CLAUDE.md if detected
   • Skips if Sessions Pattern already documented

Troubleshooting

Permission Errors with Slash Commands

If you get "This command requires approval" errors when running /end-session or other slash commands:

Cause: Mismatch between frontmatter allowed-tools and .claude/settings.json permissions. The permission system uses literal string matching, so relative vs absolute paths are treated as different patterns.

Solution:

1. Check .claude/settings.json exists at project root
2. Verify patterns use relative paths: Bash(.claude/scripts/*:*)
3. Check .claude/settings.local.json (if exists) also uses relative paths
4. Ensure patterns match between frontmatter and settings files
5. Restart Claude - quit completely and start fresh

Correct configuration example:

.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(.claude/scripts/*:*)",
      "Bash(git:*)",
      "Bash(gh:*)"
    ]
  }
}

.claude/commands/end-session.md:

---
allowed-tools: Bash(git:*), Bash(.claude/scripts/*:*)
---

Note: Both files must use the same path format (relative: .claude/scripts/* NOT absolute: /Users/you/project/.claude/scripts/*)

Updating from Older Versions

If you installed before v0.3.5 and have permission issues:

npx create-sessions-dir

This will automatically detect and fix absolute paths in your .claude/settings.json. You may need to manually update .claude/settings.local.json if it exists.

Why This Works

AI coding agents are stateless - they don't remember previous sessions. The Sessions Directory Pattern solves this by:

1. Externalizing memory - Context lives in files, not the agent's "memory"
2. Progressive documentation - You document as you build, not after
3. Continuity across sessions - Each session starts with full context
4. Proof of decisions - Everything is written down and committed

Read the full story: vieko.dev/sessions

References

The Sessions Directory Pattern is informed by research and best practices in AI agent context management:

• Effective Context Engineering for AI Agents - Anthropic's engineering guide on context engineering patterns, including structured note-taking, just-in-time context, and sub-agent architectures
• Writing a good CLAUDE.md - HumanLayer's practical guide to effective context files, including length targets, the WHY/WHAT/HOW framework, and anti-patterns to avoid

Acknowledgments

Thanks to Aman Azad for the nudge to turn the pattern into a tool.

License

MIT © Vieko Franetovic