Save the working state your AI tools won't.
Website · Docs · Quickstart · npm
A Claude Code session dies mid-run — rate limit, crash, compaction, laptop sleep — or you're moving a task from Claude Code to Codex, Cursor, or ChatGPT. The code is still in git. The objective, decisions, and next steps often are not. The next session rebuilds that state from scratch.
3Notch is a local CLI and MCP server for:
- Continuation checkpoints — when Claude Code is configured, recover after rate limits, model-down failures, and compaction
- Portable packets — hand off selected work across tools, repos, and machines
- Durable inbox — async delivery between stores that share a mailbox root
No cloud service. No account. No telemetry. Records stay on disk as Markdown (and optional artifacts) under .notch/.
Every major vendor ships transcript persistence and memory files. None ship durable working state:
- Claude Code auto-saves transcripts and takes file checkpoints — but checkpoints are session-scoped undo, gone when the session ends.
- OpenAI's Agents SDK serializes
RunState— at planned human-approval pauses, not arbitrary failures. - Gemini and Grok persist conversations server-side. A transcript is a diary, not a manifest.
Recovering from a transcript means re-reading a conversation and re-interpreting what happened. The vendors' own guidance converges on the fix: combine native persistence with handoff files and checkpoint strategies. 3Notch is that layer — local, vendor-neutral, yours.
npm install -g @3notch/cli
notch onboardAgent prompt (optional):
Install @3notch/cli, run
notch onboardin this repo, and set up continuation checkpoints if I use Claude Code. Use packets for handoffs across tools or repos. Read the package README before changing MCP config.
Wrap-up: notch save. Session start: notch resume. No confirmation prompt. Codex, Grok, and Cursor should run those two commands; there is no 3Notch daemon.
notch save --summary "Auth validation done" --next-steps "Implement session store"
notch resume
notch resume --jsonClaude Code SessionStart injects the latest checkpoint body so the next agent can continue without calling get_packet after a human yes. Private packets stay hidden unless you pass --include-private. See Continuation checkpoints.
notch packet create \
--title "Auth refactor checkpoint" \
--summary "Token validation done; session store migration blocked." \
--next-steps "Implement Redis session adapter"
notch packet preview <id>
# other tool / session imports and continuesnotch packet create \
--title "Brand handoff" \
--summary "Assets and layout for the launch page." \
--file mascot.jpg:asset \
--file showcase.html:source \
--next-steps "Build the launch page from showcase.html and mascot.jpg."
notch packet pack <id>
# move <id>.notchpkt however you prefer, then:
notch packet unpack <id>.notchpktBoth sides register the same mailbox root, then pack/send and pull/ack:
notch inbox init --name review-agent --root /shared/3notch-mailbox
notch packet pack <id>
notch send <id>.notchpkt --to local:review-agent
# forward the printed delivery notice via chat, Slack, etc.
notch inbox list
notch inbox pull <delivery-id> --import
notch inbox ack <delivery-id>local: addresses are routing labels, not authenticated identity. See Durable inbox.
notch prompt --client claude-chat
# paste into the chat, copy the packet back
pbpaste | notch packet import -notch mark --summary "Keep browser auth cookie-based" --tags auth- You or an agent write selected context through the CLI or MCP tools.
- 3Notch validates, secret-scans, and stores records under
.notch/. - Preview before another agent relies on the content.
- The next session, tool, or store imports or resumes from that record.
Targeting fields (--to-agent, --to-repo) are intent metadata. Bytes move via your transport (scp, git, AirDrop, Tailscale) or the durable inbox mailbox — not a 3Notch-hosted relay.
notch onboard initialize .notch/ and MCP setup
notch save write a continuation from git snapshot + summary
notch resume print the latest continuation (no prompt)
notch packet create create a packet (--file, --ref, --next-steps)
notch packet import <path> import into .notch/inbox/
notch packet preview <id> show what an agent will read
notch packet pack / unpack .notchpkt archive round-trip
notch packet list / show list / inspect packets
notch inbox init/list/status/pull/ack durable delivery lifecycle
notch send <archive> --to <address> send a packed project handoff
notch reply <id> typed reply to a packet
notch mark self-addressed private capture
notch brief / brief create|list|show scoped task briefs
notch seed from <path> private context seeding
notch prompt --client <client> agent / web-chat instruction packs
notch scan <file-or-stdin> secret scanner
notch check structural corpus checks
notch doctor store diagnostics
notch status store summary
notch mcp serve local stdio MCP server
notch mcp serve over local stdio:
| Tools | |
|---|---|
| Read | get_brief, list_briefs, get_targeted_brief, get_packet, list_packets, resume_working_state, list_inbox, get_inbox_delivery, get_status, check_store, run_doctor |
| Write | create_brief, create_packet, save_working_state, create_mark, create_reply, create_seed_packet, import_packet, import_seed_packet, inbox_init, send_packet, pull_inbox_packet, ack_inbox_delivery |
Private records under .notch/private/ stay hidden unless the server starts with --include-private. Client setup: docs/guides/mcp-setup.md.
| Topic | Guide |
|---|---|
| Index | docs/README.md |
| Cross-repo packets | docs/guides/cross-repo-packets.md |
| Cross-tool handoff | docs/guides/cross-tool-handoff.md |
| Durable inbox | docs/guides/durable-inbox.md |
| Continuation checkpoints | docs/guides/continuation-checkpoints.md |
| MCP setup | docs/guides/mcp-setup.md |
| Privacy | docs/reference/privacy.md |
| Security | docs/reference/security-story.md |
| Releases (maintainers) | docs/guides/release.md |
Website docs mirror: https://3notch.dev/docs/.
- Local files by default — no hosted relay, account system, or telemetry
- No vector DB / native DB dependency
- No arbitrary shell execution through MCP
- You move bytes; 3Notch validates, scans, hashes, and stores them
Regression guard: tests/unit/no-deferred-commands.test.ts.
Prefer opening an issue before large features. See open issues and CONTRIBUTING.md.
git clone https://github.com/coldlogicAI/3notch.git
cd 3notch
npm install
npm run lint && npm run type-check && npm run build
npm test && npm run test:e2e
npm run release:checkSee CONTRIBUTING.md.
Architecture reference (historical but still useful): docs/archived-plans/v1/3notch-v1-technical-spec.md.
MIT © 3Notch contributors