# Passalong > Hand finished work from one context to another as a "transfer guide": markdown with > frontmatter, written so an agent in a different repo, on a different machine, or in a later > session can act on it without the original conversation. A transfer has two ends. One side finishes something non-trivial and publishes what it learned; the other side picks it up, does it, and says whether it actually worked. Passalong is the CLI, MCP server and sync service for both ends. Guides are plain markdown. `passalong export` dumps every one of them. Deleting an account leaves the author with all of their content. ## If you are an agent reading a share link A share link looks like `https://passalong.dev/g//`. Append `.md` for the raw markdown, or `?view=verify` for the view that leads with what to check and folds the implementation away. 0. Check `kind` in the frontmatter first. `bug` and `transfer` ask for opposite things — see "Two kinds of guide" below. Absent means `transfer`. 1. Read the guide. `Verification` is what "done" means; `Gotchas` is what already went wrong. 2. Anything under `stack_assumptions` in the frontmatter is what the author's environment was. Adapt those to the current codebase rather than copying them. 3. Run the `Verification` steps before reporting success. 4. Report back: `passalong works ` if it holds up, `passalong broken ""` if it does not. The reason reaches the author the same day. This is the part that makes the next guide better, so do not skip it. ## Two kinds of guide `kind:` in the frontmatter says what a guide is for. The two ask for opposite behaviour, so read it before acting on anything. - `kind: transfer` (or absent) — finished work to repeat here. Follow its `Steps`. - `kind: bug` — a defect to fix where it is. It has no `Steps` and nothing in it is a procedure to apply: `Reproduce` is how to see the bug and running it produces the bug, `Verification` is the behaviour that should have happened. Fix the defect, then check `Verification` and report back. A bug report is not broken because you reproduced it. Bugs are often filed in sets. `report:` names the parent a set was filed under; `GET /v1/reports/ ` returns the rest of it. Fix only the issue you were given unless you were asked for more. ## Guide format Frontmatter fields, in order: `id`, `title`, `kind`, `created`, `author`, `source_context`, `status`, `team`, `to`, `stack_assumptions` (list), `tags` (list). Bugs also carry `report`, `area` and `severity` (`s1` blocker to `s4` cosmetic). `to:` is who is being asked, inside the `team:` it names. `@handle` asks one person and outranks everything else in their inbox; `#group` asks the people who do a thing, reaches every one of them, and the first to say they are on it takes it off the others' boards; leaving `to:` off shares with the whole team, which asks nobody in particular. Body sections, in this order — the headings are what a receiving agent keys on, so they are stable: - `## Problem` — what was actually wrong. Required. - `## Solution shape` — the approach, not a diff. - `## Decisions and rationale` — what was chosen over what, and why. - `## Steps` — what to do. Required. - `## Verification` — how to know it worked. A guide without this is flagged to the reader. - `## Gotchas` — what failed on the way. The highest-value section; record what wasted time. A bug uses `## Problem`, `## Reproduce`, `## Verification` and `## Gotchas` instead. `Reproduce` rather than `Steps` is deliberate and load-bearing: `Steps` is the heading an agent is told to execute, and steps that produce a defect are the one list that must never be run as a remedy. `status` is `draft` or `published`, and `consumed` is the author's shelf — off the board, out of the free tier's count, reversible. (`promoted` is retired: a guide carrying it keeps it and it still parses, but no write can set it.) Ids are 8 characters from a no-lookalike alphabet; they are addresses, not secrets. The key in a share link is the secret. ## Commands ```sh npm i -g passalong passalong setup # Claude Code capture skill + MCP server passalong login # optional: sync across machines ``` - `passalong share [file] [--to team[/handle]]` — publish a guide, get an id and a link - `passalong start ` — pull it and take it: one command for "I am doing this" - `passalong pull ` — fetch a guide into `./.passalong/` and print it, without answering for it - `passalong inbox` — guides handed to you that you have not pulled - `passalong board` — waiting on you, in flight, landed, worth keeping - `passalong activity [--all]` — what happened while you were away - `passalong log [repo]` — what you did, newest first, under a heading per month - `passalong list [query]` — your guides and your teams' - `passalong open [--print]` — view in the browser, or the terminal - `passalong works ` / `passalong broken ` — the verdict, after trying it - `passalong done ` — implemented on the receiving side - `passalong export [dir]` — every guide as plain markdown - `passalong team create|invite|join|use` — teams - `passalong me [--handle H]` — how teammates address you - `passalong take ` / `passalong pass ` — whether you are doing what you were handed - `passalong mcp` — run the MCP server over stdio - `passalong version` — print the installed version (also `-v`, `--version`) ## MCP tools `passalong setup` registers a stdio MCP server exposing: `publish_guide`, `file_bugs`, `start_guide`, `get_guide`, `search_guides`, `guide_template`, `set_guide_status`, `ack_guide`, `verify_guide`, `attach_screenshot`, `inbox`, `board`, `activity`, `log`. `start_guide` and `attach_screenshot` need passalong 0.3 or later; an older install exposes the rest, so fall back to `get_guide` then `ack_guide` if `start_guide` is not there. Open a guide you mean to act on with `start_guide`, not `get_guide`. Both return the same markdown; `start_guide` also says you are on it, and between handing work over and hearing it worked that is the only signal the sender gets. Follow its `Steps`, adapt anything marked as an assumption, run its `Verification`, then `verify_guide` with the result. `get_guide` is the same fetch without the answer — for reading a guide you have not committed to. Fetching is not committing, which is why they are two tools: you have to be able to read something to decide it is not yours. `ack_guide` is that answer on its own, and the way to say no. Passing must say why — an unanswered handoff looks exactly like one nobody has noticed, so the sender learns in a week rather than a minute. Taking it leaves it on your board; passing puts it back on its author's. Taking your own guide does nothing: an author is not a party to their own handoff. `log` is this user's own acts, newest first — what they published, what they took delivery of, and every verdict and ack they gave, each with a ready-made `text` line and the guide's repo. It answers "what have I been working on", and it is the opposite of `activity`, which is what other people did. It holds what was passed along and not what was worked on: work that never became a guide has no entry, so do not present it as a complete record, and do not read a quiet month as an idle one. `attach_screenshot` puts an image behind a guide. Evidence goes *in* the document: a guide travels as markdown to whoever holds its link, so a file beside it does not travel at all. The tool returns the `![](...)` line to paste into the body, and publishing claims whatever the markdown names — so attach first, publish after. Locally it takes a path on the machine. Over the hosted server it takes a file the client passes in, which today means ChatGPT on the web; the ChatGPT mobile apps send file references the server cannot download. An image the user showed you is evidence, not context. Attach it *before* filing or publishing and pass what `attach_screenshot` returns as that issue's `evidence` — describing a screenshot you were given, instead of attaching it, throws away the most useful thing in the report. A guide already filed without one is not stuck: `get_guide` it, add the markdown line to the body, and `publish_guide` the same id. Publishing claims whatever the markdown names, every time, so a re-publish picks the image up. `publish_guide` needs no id for a new guide: leave it out and one is minted and returned. To change a guide, pass the id it came back with. Inventing a fresh id to retry or to correct a guide publishes a second copy, and every copy counts against the author's synced limit. A follow-up is more context for a guide, written as a guide of its own and linked under the original. When a guide needs more context — a missing detail, a step that needed explaining, what changed since, what you found doing it — publish that context with `parent` set to the guide's id on `publish_guide`, or `passalong share --follows `. A follow-up is a whole guide, not a reply: it has its own id, verdicts and pulls. `parent` on `publish_guide` and `--follows` need passalong 0.3.1 or later. Whoever opens the original gets its follow-ups too. `get_guide` and `start_guide` return them after the guide, oldest first; read them before acting, and where one disagrees with the original, the follow-up is newer. The guide's share page lists them above the document. `file_bugs` files defects you found but are not fixing — from a test run, a QA pass, a review — as one report. Each issue becomes a guide with its own id, share link and verdict, so any of them can be handed to whoever fixes it. Send them in one call rather than one call each. Each issue takes `evidence`: the screenshot lines for that bug, which land under its Problem section. The same server is also hosted, for assistants that add remote MCP servers rather than running one: `https://passalong.dev/v1/mcp`, Streamable HTTP, authenticated with a bearer token. It carries most of these tools — everything except the ones that touch a working directory. `start_guide` is one of those, so over the hosted server take a handoff with `ack_guide` and fetch it with `get_guide`, which there returns the markdown without writing it anywhere. `attach_screenshot` is on both, shaped for where it runs: a path locally, a client-passed file over HTTP. A local server is still better where you can run one: it works offline and knows which repo you are in. Failing both, everything is plain HTTP: `GET /v1/openapi.json` describes the API for Gemini function calling or a script, and a share link's `.md` needs no account at all. ## Writing a good guide - One problem per guide. A session that solved three things is three guides. - Write `Verification` first if you can. If you cannot say how to check it, the guide is not ready. - `Gotchas` is worth more than `Steps`. Steps can be re-derived; the dead end that cost an hour cannot. - Say what the environment was rather than assuming the reader shares it. ## Links - Homepage: https://passalong.dev - Hub (your synced guides): https://passalong.dev/hub - npm: https://www.npmjs.com/package/passalong - Source: https://github.com/codellyson/passalong Guide pages are `noindex` and `/g/` is disallowed in robots.txt: a share link is for whoever holds it, not for search engines. Do not crawl share links found elsewhere.