Quickstart.

Install the CLI, initialize a store, then pick the flow that matches where your source and destination live. Each flow runs in under a minute once 3Notch is installed.

Install once

$ npm install -g @3notch/cli
$ notch onboard

notch onboard initializes .notch/ in your current project and offers to wire any MCP-capable clients it detects. Re-run any time with --yes to accept defaults non-interactively.

1 · Bundle files for another tool

When one tool has files the next tool needs, create a packet that carries both intent and bytes:

$ notch packet create \
  --title "Brand handoff" \
  --summary "Brand handoff for the launch page." \
  --to-agent codex \
  --to-repo ../brand-site \
  --file mascot.jpg:asset \
  --file showcase.html:source \
  --next-steps "Build apps/brand-site/ using showcase.html as the layout and mascot.jpg in the hero."

The packet lands as a folder in .notch/outbox/ with packet.md, manifest.json, and copied bytes under artifacts/. The destination imports the folder:

$ notch packet import ../source/.notch/outbox/<packet-folder>/packet.md
$ notch packet preview <packet-id>

MCP clients use the same model through create_packet with files, refs, and nextSteps.

2 · Same store, two tools

For one project used from both Claude Code and Claude Desktop, point both clients at the same .notch/ store:

$ notch onboard --yes --mcp claude-code
$ notch onboard --yes --mcp claude-desktop

Both clients now read and write the same store. When one creates a packet, the other can list and read it immediately — no transfer step.

3 · Cross-repo on one machine

$ notch packet create --title "Auth handoff" --summary "Auth context for the API repo." \
  --to-agent codex --to-repo ../api --ref src/auth.ts
$ notch packet import ../source/.notch/outbox/<packet-file-or-folder>/packet.md

Use --ref when both repos share the same workspace path. Use --file when the destination needs the bytes copied in.

4 · Cross-machine

Pack the folder into a deterministic .notchpkt archive, move it via scp / iCloud / Tailscale / email / git, unpack on the other side:

$ notch packet pack <packet-id>
# move <packet-id>.notchpkt to the destination machine
$ notch packet unpack <packet-id>.notchpkt

The archive is a gzipped tar with deterministic entry ordering. Hashes are re-verified at unpack against the manifest before anything lands in the inbox.

5 · Browser-only chats (fallback)

Claude.ai and other web chats can't reach local MCP yet. The fallback is clipboard-mediated:

$ notch prompt --client claude-chat
# paste the prompt into the chat, ask for a packet, copy the result
$ pbpaste | notch packet import -

This is an escape hatch, not a peer of the MCP-native paths. The structurally honest replacement is custom connectors and remote MCP — see the Where We Want Help section.

6 · Personal capture

When you just want to remember something for yourself:

$ notch mark --summary "Decided to keep browser auth cookie-based" --tags auth

Marks live under .notch/marks/. They're self-addressed packets — no recipient required.

How the handoff model works

The loop is explicit and reviewable:

1. A user asks an AI client or CLI session to package selected context.
2. The client supplies a summary, source links, exclusions, recipient metadata, and next steps through CLI or MCP.
3. 3Notch validates the record, scans it for secrets, and writes a Markdown packet under .notch/outbox/ or .notch/private/.
4. The user previews the packet before another tool or repo relies on it.
5. Another repo can import the packet, or another tool can read it directly when both clients share the same store.

Targeting fields (--to-agent, --to-person, --to-repo) answer "who is this packet for?" They are routing and review metadata. They are not identity, authentication, or delivery controls — your existing transport (scp, rsync, iCloud, Tailscale, email, git) moves the bytes.