Session State
SESSION-STATE.md (project root, gitignored; schema in this skill's assets/SESSION-STATE.template.md) is the harness's live external memory — NORTH_STAR Lever 3. A model's context compresses over a long session and settled facts drift; this file is the durable copy, re-surfaced by hooks:
- SessionStart injects the whole file (Claude and Codex).
- UserPromptSubmit injects a compact digest — Constraints + Decisions + Open threads — each Claude turn.
- PreCompact checkpoints before context is compressed (Claude and Codex).
How to record (never hand-edit)
Writing via a script — not by editing the file from memory — is the point: it captures the fact even when attention is full. Resolve the writer project-first, then global install fallbacks (path layout):
PROJ="${CLAUDE_PROJECT_DIR:-.}"
# 1. Repo checkout (source of truth)
SS="$PROJ/.claude/skills/session-state/scripts/session-state.sh"
# 2. Project Codex install
[ -f "$SS" ] || SS="$PROJ/.agents/skills/session-state/scripts/session-state.sh"
# 3. Global Claude Code install
[ -f "$SS" ] || SS="$HOME/.claude/skills/session-state/scripts/session-state.sh"
# 4. Global Codex install
[ -f "$SS" ] || SS="$HOME/.agents/skills/session-state/scripts/session-state.sh"
| Type | Use for | Re-injected each turn? |
|---|
constraint | hard rules in force (e.g. "Rust only, no Python") | yes |
decision | settled choices, date-stamped (so they're not re-litigated) | yes |
infra | survey-before-act findings — what already exists, to reuse (writer emits [surveyed:name] from first token) | no |
thread | in-flight items / next steps | yes |
Claude Code — /state slash command
In Claude Code, use the /state command (.claude/commands/state.md), which invokes the writer above:
bash "$SS" init
bash "$SS" init-orchestrator # init + default orchestrator constraints (idempotent)
bash "$SS" show
bash "$SS" constraint "<entry text>"
bash "$SS" decision "<entry text>"
bash "$SS" infra "<entry text>"
bash "$SS" thread "<entry text>"
Valid types: constraint, decision, infra, thread, init, init-orchestrator, show. If the type is empty or invalid, list the valid types — do not guess. init, init-orchestrator, and show take no text; the four entry types take the text as one quoted argument.
Codex
Ask Codex to use session-state, for example: “Use session-state to record this decision: …”. The skill runs the same writer commands; no Claude slash command is installed. Codex re-injects the full state at session start and after compaction. Use Codex's native memory feature for cross-session personal memory.
Orchestrator mode: run init-orchestrator at session start so dispatch constraints re-inject every turn.
Keep entries terse. For infra, lead with the service name as the first word — e.g. "rabbitmq broker on :5552 (docker-compose) — reuse" — the writer stores [surveyed:rabbitmq] … so survey guards suppress only when a command names that exact surveyed subject.
When to reach for it (proactively)
- You just established a hard constraint, or the user gave one → record a
constraint.
- You made or were given a settled decision → record a
decision.
- You surveyed and found existing infrastructure (a running service, an existing config) → record
infra, so a later step reuses it instead of rebuilding.
- You are leaving a thread unfinished → record a
thread.
Activation (on by default)
The writer works as soon as the skill is installed. Supported hooks are registered by install.sh; Codex asks you to review and trust them with /hooks before they run. Hook JSON examples and security notes: references/hook-setup.md.
Discipline
Keep entries terse — Constraints, Decisions, and Open threads are re-injected every turn, so bloat re-creates the token tax. Prune stale lines. Do not duplicate .claude/memory/ (cross-session) or facts derivable from the repo.
Known limitations
- Existing-infra is SessionStart-only. Survey findings (
infra) are not in the per-turn digest — only Constraints, Decisions, and Open threads are. After mid-session compaction, infra coverage still depends on SessionStart injection (or recording a load-bearing finding as a constraint). The survey-before-act guard covers provisioning commands only.
- Token-cost tradeoff. Adding Decisions to the digest (#158) improves post-compaction decision coverage at the cost of a slightly larger always-on per-turn injection. Keep decision bullets terse; prune stale ones.