Context Closeout

Context Closeout is a portable session-handoff skill for Claude Code and Codex. It saves verified work state, artifacts, decisions, blockers, and an exact continuation point so a fresh AI context can resume without reconstructing the previous session.

The skill activates when you explicitly end a context with language such as:

Done, save and close.

Wrap this up and save my place.

Close out this context.

It does not activate merely because the word “done” appears in an ordinary request.

What it solves

• Prevents one session from overwriting another with atomic, collision-safe path reservation.
• Separates local, committed, pushed, deployed, and user-verified states.
• Creates a durable project handoff only when meaningful work remains.
• Creates a concise receipt for every requested closeout.
• Records the exact first action for a new context.
• Keeps external writes, deployments, messages, and commits outside closeout authority.
• Uses one identical skill source across Claude Code and Codex.

Requirements

• Python 3.10 or newer for the installer and helper scripts.
• Claude Code, Codex, or both.
• A project directory where the AI runtime is allowed to write local Markdown files.

The skill itself has no Python package dependencies.

Install in a project

Download or clone this repository, then point the installer at the project that should receive the skill:

cd context-closeout

python3 scripts/install.py install \
  --runtime both \
  --scope project \
  --project /path/to/your/project

Project installation writes:

/path/to/your/project/.claude/skills/context-closeout/
/path/to/your/project/.agents/skills/context-closeout/

Use --runtime claude or --runtime codex to install only one adapter.

Install for your user account

python3 scripts/install.py install --runtime both --scope user

User installation writes to ~/.claude/skills/context-closeout/ and ~/.codex/skills/context-closeout/.

The installer upgrades its own unmodified installations automatically. It refuses to overwrite an unmanaged or locally modified skill. --force moves that directory to a timestamped backup under .context-closeout-backups/, outside runtime skill-discovery directories, so replacement remains recoverable without loading duplicate skills.

Verify the installation

python3 scripts/doctor.py --runtime both --scope project --project /path/to/your/project

The doctor checks that each installed copy is managed by this repository and byte-for-byte current with the source skill. It also validates .context-closeout.json when the project has one.

Use it

Work normally. When the current AI context should end, say something like:

Done, save and close.

By default, the skill creates:

.context/
├── handoffs/
│   └── YYYY-MM-DD-HHMMSS-scope-topic.md
└── sessions/
    └── YYYY-MM-DD-HHMMSS-scope-topic.md

The handoff is the detailed resume artifact. The session receipt is a compact index and review record. Fully completed work receives a receipt but does not get a pointless handoff.

Find the latest handoff deterministically:

python3 /path/to/installed/context-closeout/scripts/latest.py \
  --root /path/to/your/project \
  --kind handoff

Add --scope my-project when several workstreams share the same repository.

The closeout skill reserves receipt and handoff paths with exclusive file creation before it writes either artifact. Parallel contexts closing in the same second therefore receive distinct numeric suffixes instead of racing to overwrite the same filename.

Configuration

Configuration is optional. Copy the example to the target project root:

cp examples/context-closeout.json /path/to/your/project/.context-closeout.json

{
  "timezone": "local",
  "receipts_directory": ".context/sessions",
  "handoffs_directory": ".context/handoffs",
  "decision_log": null
}

• timezone controls how the agent labels closeout timestamps. local uses the machine’s zone.
• receipts_directory and handoffs_directory must stay inside the project root.
• decision_log may point to an existing project decision log. The skill never creates one merely because the setting is present.

Safety model

A closeout request authorizes only local persistence needed to preserve the session. It does not authorize:

• commits or pushes;
• deployments;
• email, chat, issue, or task-system writes;
• purchases or paid API calls;
• deletion of project work.

The skill ignores unrelated dirty-worktree changes and never turns an assumption into a completion claim.

Receipts and handoffs may describe sensitive work. The skill explicitly redacts credentials, tokens, cookies, personal data, and raw sensitive tool output, but you should still review .context/ before committing it. Add .context/ to your project’s .gitignore when handoffs should remain local; commit it only when the repository’s collaborators are intended readers.

Uninstall

python3 scripts/install.py uninstall \
  --runtime both \
  --scope project \
  --project /path/to/your/project

Uninstall is recoverable: the installed directory is moved under .context-closeout-backups/, outside runtime skill discovery. If the installed skill was edited after installation, uninstall refuses unless you pass --force.

Development

Run the complete standard-library test suite:

python3 -m unittest discover -s tests -v

Contributions should preserve the core invariants: explicit closeout intent, truthful state, atomically collision-safe artifacts, exact continuation instructions, no automatic external writes, and identical behavior across runtime adapters.

License

MIT. See LICENSE.