Satchery

Docs

Using Satchery

Everything runs on your machine. There is no account and nothing is uploaded. You need Node.js 20 or newer.

Install

Run it without installing:

$ npx satchery

With no arguments it walks you through a move: it finds agents on this machine and in this project, asks where to send one, shows the plan and waits for your yes.

CLI

What a move does

  1. Read. The source adapter reads the agent. Source files are opened read-only.
  2. Pack. Everything goes into an in-memory satchel. Secrets are replaced by {{secret:NAME}} references.
  3. Plan. The destination adapter lists every file it would create or update, with a level per category. This is what plan prints.
  4. Back up. Each file the move will touch is copied to ~/.satchery/backups/<id>/.
  5. Write. Each file is written to a temporary file and renamed into place, then read back and compared.
  6. Receipt. A JSON receipt in ~/.satchery/receipts/ records every file with its hash.

Conflict modes: merge (default) keeps what is already at the destination and adds what is missing; copy creates a separate agent next to the existing one; replace overwrites, only after showing exactly what it touches and asking.

Routines always arrive paused. Permission rules can be narrowed on the way but never widened, unless you pass --allow-wider and confirm. A file you edited after Satchery wrote it is not overwritten silently.

Receipts and restore

Every move leaves a receipt. List them, then put a move back:

$ satchery receipts
$ satchery restore <receipt-id>

MCP server

Satchery also runs as an MCP server over stdio, so an agent can plan its own move. It is read-only unless you start it with --allow-write.

Format

Satchels are plain folders: a satchel.json manifest plus Markdown, packed as a tar.gz .satchel with sha256 checksums. Full spec on Satchel Format. Check a file in the browser with the inspector.

Limits

  • Hosted apps (ChatGPT, claude.ai, Gemini and others) and agent frameworks are write-only: Satchery writes a kit folder with numbered steps and paste-ready files, because those apps have no local files to write into.
  • Some local layouts are not documented by their makers. Where Satchery had to assume a layout, the platforms page says what was assumed.
  • Secret values are never carried. You reconnect them at the destination.
  • Routines are never scheduled or run for you. They arrive paused, with steps to turn them on.
  • Model settings do not carry across providers; where they cannot be set, a step is written instead.
  • Adapters are tested against fixtures written from each tool's documented file layout, not against live installs. Tests run on macOS; Windows is not tested yet.

What is not audited

Satchery has a test suite but has had no audit, certification or security review. Secret detection is pattern-based and can miss a value in an unusual format, and a .satchel is checksummed, not encrypted or signed. Read the plan before you confirm a move, keep your own backups of anything you cannot lose, and report problems on @satcherypro.