# Session State

> Manage `.claude/STATE.md` — the single source of truth for cross-session context. Format is caveman-style: ultra-compressed, no articles, no filler, bullets only, timestamps as `HH:MM`.

- Skill: `seanx10m/session-state` (Agent Skill)
- Install (CLI): `npx skillmds@latest add seanx10m/session-state`
- Raw SKILL.md: https://api.skillmd.com/api/skills/seanx10m/session-state/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: seanx10m (https://skillmd.com/u/seanx10m)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/seanx10m/session-state

---


Manage `.claude/STATE.md` — the single source of truth for cross-session context. Format is caveman-style: ultra-compressed, no articles, no filler, bullets only, timestamps as `HH:MM`.

## STATE.md format

```
# STATE — <project> — <YYYY-MM-DD>

## NOW
<one line: what's in flight right now>

## NEXT
1. <immediate next action>
2. <following action>

## DONE
- HH:MM <what shipped> [<commit-sha if any>]
- HH:MM <decision made + why in ≤8 words>

## CONSTRAINTS
- <binding rule / hard limit discovered this session>

## FILES
- <path> — <what changed, 5 words max>

## OPEN
- <unresolved question or blocker>
```

Rules:
- No prose. No "we decided to". Just the fact.
- DONE entries: append-only, newest last.
- NEXT: overwrite each update, keep ≤3 items.
- CONSTRAINTS: permanent until explicitly removed.
- OPEN: remove when resolved.

---

## Verbs

### `update` (mid-session checkpoint)
Append to DONE what just completed. Rewrite NEXT with current top actions. Add any new CONSTRAINTS or OPEN items. Add FILES touched. Keep NOW current. Do not rewrite the whole file — surgical edits only.

### `close` (end of session)
Finalize STATE.md for handoff:
1. Move anything in-progress to DONE or NEXT (nothing ambiguous).
2. Rewrite NEXT so item 1 is the single most important action for the next session.
3. Add a `## HANDOFF` block at the bottom:
   ```
   ## HANDOFF
   - Start: cd <worktree-path> && <env cmd if needed>
   - Branch: <branch>
   - Tree: clean / uncommitted: <file> — <reason>
   - Skills: <suggest /skill-name for next session>
   ```
4. Commit outstanding work if any (conventional commit, specific files only).

### `read` (session start / orient)
Read `.claude/STATE.md`. Output a 3-bullet orient:
- **Resuming:** <NOW value>
- **First action:** <NEXT item 1>
- **Watch:** <CONSTRAINTS or OPEN items worth flagging>
Then ask: "Continue, or different focus?"

---

## File location
Always `.claude/STATE.md` in the project root (not /tmp). Create `.claude/` if it doesn't exist. If no project root is detectable, use the current working directory.

## If STATE.md doesn't exist
On `update` or `close`: create it from scratch using the format above. On `read`: say "No STATE.md found — clean session."