agent-crystallize

Local-first checkpoints and crystals for long-running AI coding agent sessions.

Status: public seed / first npm release.

Stop compacting. Start crystallizing.

Compaction keeps the model running.
Crystallization keeps the work recoverable.

agent-crystallize writes durable Markdown artifacts that help future Codex, Claude Code, Cursor, or other coding-agent sessions resume from the actual work state: current focus, decisions, evidence, open loops, changed files, and next actions. When turn order matters, it can also include a bounded Continuity Tail: redacted recent messages used only for nuance recovery, not as promoted durable knowledge.

It is the first open-source slice of Agent Context Crystallization: the practice of turning long-running agent work into durable, provenance-backed checkpoints, evidence, open loops, and resume state.

The Problem

Long-running coding-agent sessions now span hours, many files, multiple tools, and multiple compactions.

Compaction is necessary, but it is lossy. It can keep the chat alive while flattening the work:

• the next session remembers the gist but loses the why;
• decisions survive as vague summaries without evidence;
• failed paths and edge cases disappear;
• open loops turn into generic TODOs;
• each agent spends tokens reloading context that should have been saved.

The model survives, but the work does not.

The Workflow

Create frequent checkpoints while the work is active:

agent-crystallize checkpoint \
  --body "Finished auth refactor. Tests pass. Need OAuth replay check next."

Before compaction, handoff, or session end, create a fuller session crystal:

agent-crystallize now \
  --project my-product \
  --budget standard \
  --body "Ready to compact. Preserve latest state, open loops, and next action."

If you have been checkpointing throughout the task, roll those checkpoints into the session crystal:

agent-crystallize now \
  --from-checkpoints latest \
  --body "What changed since the latest checkpoint, current open loops, and next action." \
  --agent-body codex \
  --harness codex-cli \
  --session-id "$CODEX_THREAD_ID" \
  --transcript-uri "$HOME/.codex/sessions/2026/06/28/rollout-example.jsonl" \
  --topic "parser" \
  --relation "depends_on:git commit abc123" \
  --decision "Keep the parser local-first for this release." \
  --finding "Replay tests are the highest-risk remaining check." \
  --open-loop "Run duplicate-row replay test before handoff." \
  --test "npm test passed." \
  --next-action "Run replay test and update this crystal." \
  --memory-candidate "Strict replay checks should be captured before handoff."

Validate local crystals before relying on them for handoff:

agent-crystallize validate

Default output:

.agent-crystals/
  checkpoints/
  sessions/

Five-Minute Useful Path

Install the package, set up a thin protocol pointer, and activate the current repo:

npm install -g @stewie-sh/agent-crystallize

agent-crystallize setup --codex --skills
agent-crystallize init
agent-crystallize doctor

Then create a first checkpoint:

agent-crystallize checkpoint \
  --body "Finished the launch-readiness pass. Build passes. Need public scan next." \
  --topic "launch-readiness" \
  --decision "Keep generated dogfood artifacts local unless they are sanitized examples." \
  --test "npm run check passed." \
  --next-action "Run npm pack --dry-run and scan tracked files before release."

Before ending the session, roll the recent checkpoints into a session crystal:

agent-crystallize now \
  --from-checkpoints latest \
  --body "Ready to hand off. Preserve current focus, decisions, verification, open loops, and next action." \
  --topic "agent-context-crystallization"

Then validate what you plan to rely on:

agent-crystallize validate

Generated .agent-crystals/ files are local work artifacts by default. This repo keeps them ignored so private dogfood traces do not become public accidentally. Public dogfood material should be represented as sanitized Markdown under examples/.

Skill Support

agent-crystallize includes a public agent-context-crystallizer skill using the Agent Skills / SKILL.md folder format. The skill is a thin wrapper around the CLI; the CLI remains the source of truth for artifact generation and validation.

Current support matrix:

| Harness | Status | Setup | | --- | --- | --- | | Codex | first-class install path, setup smoke-tested | agent-crystallize setup --codex --skills | | Claude Code | first-class install path, setup smoke-tested | agent-crystallize setup --claude --skills | | Other Agent Skills-compatible harnesses | portable/manual install | copy skills/agent-context-crystallizer into the harness skill directory |

For manual installs, make sure the agent-crystallize binary is available on the agent's PATH. The skill follows the open Agent Skills shape, but each harness chooses its own discovery directories, trust flow, tool permissions, and hook behavior. Treat untested harnesses as compatible-in-format, not guaranteed end-to-end support.

Why Local First

The first version is intentionally boring infrastructure:

• no account;
• no login;
• no runtime network dependency;
• no hosted database;
• no server setup;
• inspectable Markdown files in your repo.

You can commit .agent-crystals/, ignore it, archive it, or import it into a memory system later. The local artifact is the portable source of continuity.

Install

Install globally with npm:

npm install -g @stewie-sh/agent-crystallize
agent-crystallize --help

For local development from a checkout:

npm install
npm run build
node dist/index.js --help

What It Captures

• current focus;
• checkpoint trail for session crystals;
• topics and lightweight relation hints for later indexing;
• safe session provenance such as agent body, harness, session id, transcript pointer, and source references when supplied;
• git commit, branch, status, diff stat, and changed files;
• detected instruction files such as AGENTS.md and CLAUDE.md;
• decision, finding, open-loop, and next-action sections;
• a resume prompt for the next agent/session.

agent-crystallize validate checks generated artifacts for required sections, missing header fields, TODO-only current focus, and TODO-heavy quality warnings.

Git is the provenance backbone. Crystals are the work-memory layer.

Git commits show what changed. Crystals preserve why it mattered, what remains open, and how to resume.

What It Does Not Capture

agent-crystallize does not preserve hidden chain-of-thought. It preserves durable work context: evidence, decisions, findings, open loops, and resume state.

It is not a hosted memory service, transcript database, or AI chat product. The default CLI writes local files only.

Commands

agent-crystallize setup [options]
agent-crystallize init [options]
agent-crystallize doctor [options]
agent-crystallize checkpoint [options] [summary]
agent-crystallize now [options] [summary]
agent-crystallize validate [options]
agent-crystallize manifest [options]
agent-crystallize hook [options]

Setup options:

--dry-run                 Show planned setup actions without writing
--force                   Replace existing protocol file when it differs
--all                     Configure all supported global harness pointers
--codex                   Add/update ~/.codex/AGENTS.md managed pointer
--claude                  Add/update ~/.claude/CLAUDE.md managed pointer
--skills                  Install public agent-context-crystallizer skill files for selected harnesses
--hooks                   Report hook setup docs; v0 does not mutate hook config
--protocol <path>         Protocol path; default ~/.agents/context-persistence-protocol.md

Init options:

--repo <path>             Repo to activate; default cwd
--project <slug>          Project/product slug; default repo basename
--dry-run                 Show planned init actions without writing
--no-checkpoint           Do not create an activation checkpoint
--no-agents-md            Do not create/update repo AGENTS.md pointer
--hooks                   Report hook setup docs; v0 does not mutate hook config
--mind                    Mark intent to connect an external memory layer later

Doctor options:

--repo <path>             Repo to inspect; default cwd
--codex                   Check ~/.codex/AGENTS.md managed pointer
--claude                  Check ~/.claude/CLAUDE.md managed pointer
--hooks                   Check common hook config locations and print trust/verification reminders

Crystal/checkpoint options:

--repo <path>              Repo to crystallize; default cwd
--out-dir <path>           Output dir relative to repo
--title <title>            Artifact title
--scope <scope>            repo|project|product|cross-project|user|system
--project <slug>           Project/product slug; default repo basename
--budget <mode>            fast|standard|deep
--surface <name>           codex|claude-code|cursor|cli|hook
--body <text>              Current focus body
--stdin                    Read body from stdin
--topic <name>             Add a topic label; repeatable
--tag <name>               Alias for --topic; repeatable
--relation <type:target>   Add a lightweight relation hint; repeatable
--agent-body <name>        Agent/body name, for example codex or claude-code
--harness <name>           Harness/runtime name
--harness-version <value>  Harness/runtime version
--session-id <id>          Session id from the active agent harness
--thread-id <id>           Thread id from the active agent harness
--run-id <id>              Run id from the active agent harness
--conversation-id <id>     Conversation id from the active agent harness
--task-id <id>             Task id from the active agent harness
--transcript-uri <uri>     Transcript/source URI or local path pointer
--source-ref <ref>         Source pointer such as file:line or transcript range; repeatable
--model <name>             Model name if safe and useful to record
--provenance <key=value>   Extra safe provenance field; repeatable
--continuity-tail <entry>  Add bounded raw continuity entry, e.g. "user: latest correction"; repeatable
--continuity-tail-max-chars <n>  Max rendered continuity-tail content budget; default 12000
--decision <text>          Add a decision bullet; repeatable
--finding <text>           Add a finding bullet; repeatable
--open-loop <text>         Add an open-loop bullet; repeatable
--test <text>              Add a test/verification bullet; repeatable
--next-action <text>       Add a next-action item; repeatable
--evidence <text>          Add an evidence pointer; repeatable
--memory-candidate <text>  Add a memory-candidate bullet; repeatable
--from-checkpoints latest  For 'now': include recent checkpoints as provenance anchors
--checkpoint-dir <path>    Checkpoint dir relative to repo; default .agent-crystals/checkpoints

Validate options:

--repo <path>              Repo to validate; default cwd
--crystals-dir <path>      Crystals dir relative to repo; default .agent-crystals
--files <path>             Validate only this Markdown crystal; repeatable
--fail-on-warnings         Exit non-zero when warnings are present

Manifest options:

--repo <path>              Repo to index; default cwd
--crystals-dir <path>      Crystals dir relative to repo; default .agent-crystals
--include-superseded       Include superseded artifacts in JSON output
--write                    Write .agent-crystals/manifest.json

Hook options:

--repo <path>                    Repo for local hook artifacts; default cwd or hook stdin cwd
--harness <name>                 codex|claude-code|hook; default hook stdin harness or hook
--event <name>                   SessionStart|UserPromptSubmit|PostToolUse|PostToolBatch|PreCompact|PostCompact|Stop
--state-dir <path>               User-level hook state dir; default ~/.agent-crystallize/hooks
--stop-checkpoint-ms <ms>        Stop cadence threshold; default 1500000
--dedupe-window-ms <ms>          SessionStart/PostCompact dedupe window; default 600000
--max-pointers <count>           SessionStart local artifact pointers; default 3
--strict-precompact              Exit non-zero if PreCompact checkpoint fails
--include-transcript-uri         Include transcript_path from hook stdin when supplied
--no-continuity-tail             Do not include hook-provided continuity_tail/messages arrays
--continuity-tail-max-chars <n>  Max rendered continuity-tail content budget; default 12000

Hook compaction behavior:

• PreCompact writes a local checkpoint before lossy compaction.
• PostCompact prints a compact-resume bootstrap even when it skips a duplicate checkpoint because a recent PreCompact checkpoint already exists.
• UserPromptSubmit prints one post-compact fallback bootstrap if the harness did not surface the compact-resume context before the next prompt.

Hook activation is harness-specific. For Codex, open /hooks after installing or changing hook definitions, then review and trust the changed hooks. Codex may skip new or changed hooks until this trust step is done. For Claude Code, use /hooks and the debug log/transcript view to confirm hooks are visible and firing. If a hook command depends on NVM or shell-managed binaries, prefer an absolute command path or wrapper script because hook processes may not inherit your interactive shell PATH. The generated setup/init instruction pointers also include a soft reminder to run agent-crystallize doctor --hooks and check the host /hooks view when continuity feels broken.

Read body text from stdin:

cat handoff.md | agent-crystallize checkpoint --stdin

Examples

• Basic checkpoint
• Compaction recovery flow
• Strict crystal example
• Sanitized session crystal fixture
• Agent Context Crystallization manifesto
• Hook automation guide

Read In This Order

1. STATUS.md
2. docs/quickstart.md
3. docs/crystal-format.md
4. docs/manifesto.md
5. docs/hooks.md
6. ROADMAP.md
7. examples/
8. CONTRIBUTING.md
9. SECURITY.md
10. LICENSING.md

Relationship To Stewie

agent-crystallize is part of the Stewie open-core ecosystem.

• agent-crystallize: local-first checkpoints and crystals for agent work.
• PBC: open format for product behavior truth.
• Other tools can import or build on local crystals when that is useful, but this package stays local-file-only by default.

Created and maintained by Vinh Nguyen / MrWarPro, founder of Stewie.

License

Apache-2.0. See LICENSING.md for the repo license mapping.