Claude Code session management

Conventions for how Claude Code sessions start, stay bounded, and hand off — separate from Claude Code hooks, which cover automated quality gates rather than session lifecycle. Backed by project skills under .claude/skills/.

Why

A session is working memory and tool state, not durable knowledge. The repo — agent instructions (CLAUDE.md / AGENTS.md), docs, ADRs, code, tests — is the source of truth. Long-running sessions accumulate stale assumptions about what's already been checked or changed, especially after a task pivot or a long gap.

/orient — read-only orientation pass

Skill: .claude/skills/orient/SKILL.md

Use at the start of a session, after a long gap, or before touching code in a part of the repo you haven't worked in this session. It:

1. Reads project instruction files (and ADRs only if something looks debatable) to confirm current commands and architecture rather than assuming they match training data.
2. Runs git status --short, git branch --show-current, git log -5 --oneline to establish what's already in flight.
3. Runs typecheck and lint (read-only, no --fix / format) to confirm the tree is currently clean.
4. Reports a short summary — repo state, whether it's safe to start new work — and stops. It does not edit, format, or fix anything.

/handoff — session handoff summary

Skill: .claude/skills/handoff/SKILL.md

Use when wrapping up, switching tasks, or before compacting/starting a fresh session. It gathers git branch --show-current, git status --short, git diff --stat (and --cached if staged), git log -5 --oneline, and optionally a CI-style check script, then writes a short handoff block to chat:

## Handoff — <branch>

**Status:** <clean | N files changed>
**Diff stat:** ...
**Recent commits:** ...
**In progress:** <1-3 sentences from conversation context>
**Next steps:** <bullets>

The point is that the next session (or a different tool entirely) resumes from branch + diff + tests, not from re-reading the chat transcript.

Commands vs. skills

Two mechanisms package reusable Claude Code workflows, and they're not interchangeable:

• .claude/skills/<name>/SKILL.md — for anything with multiple steps, examples, or its own tool policy. /orient and /handoff are skills for this reason.
• .claude/commands/<name>.md — for a genuinely trivial prompt shortcut with no steps beyond "run this command and report." Example: /check runs the project's format/lint/typecheck gate and fixes any failures it surfaces.

If a command starts accumulating steps or conditional logic, move it to a skill rather than letting it grow in place — don't keep the same workflow duplicated across both.

Referencing files with @

Claude Code's @path syntax lets you cite specific files or directories in a prompt instead of describing them in prose — type @ and tab-complete a path.

Use it when asking for a change: cite the 2–3 files that actually define the task — implementation, its test, and (if the pattern matters) the relevant doc — rather than attaching the whole repo. Prefer concrete paths for the feature at hand over a full docs dump.

Agent instruction files may support a related @import syntax that eagerly loads a file into every session. Prefer naming docs to read on demand rather than importing a full docs index into every turn — most sessions only touch one or two pages.

When to start a new session vs. continue

• Continue the current session while pursuing the same goal — iterating on the same feature, fixing review feedback on the same change.
• Start fresh (or compact deliberately) when the task pivots, an unrelated part of the codebase comes into scope, or you're picking up work after a long gap. Run /handoff first if there's anything in flight worth summarizing, then /orient in the new session.

Automatic compaction safety net

/handoff and /orient are manual — they only help if someone remembers to run them before/after compacting. Compaction can also happen automatically when the context window fills up mid-task, with no chance to run /handoff first. Two hooks (see Claude Code hooks) cover that gap without requiring either skill:

• PreCompact snapshots git branch/status/diff --stat/log -5 to stdout right before compaction runs (manual or automatic), so that state survives into the compacted summary.
• SessionStart (source: compact) re-runs the same snapshot immediately after and injects it as additionalContext, so the freshly-restored summary has real repo state to be checked against rather than being trusted blindly.

These are a lighter, always-on safety net — /handoff's prose narrative of "what's in progress" and /orient's health checks are still worth running manually for anything more than raw git state.

Related

• Claude Code hooks — automated PostToolUse/Stop quality gates
• Claude Code permissions — allow/ask/deny rules
• Architecture decision records — durable "why" that survives session boundaries