// DRY for agentic dev
Your coding playbook, synced to every agent, project, and teammate.
Claude Code, Cursor, and Codex build your way: the skills you use, the order you work in, the rules you hold. Set it once; it holds everywhere and sharpens as you work.
npx @snuffle/cli setupEvery agent works its own way until you teach it yours. So you teach Claude Code, then Cursor, then the next repo, then a teammate's machine. Four copies of how you build, each drifting a little further, quietly going stale.
snuffle makes them one playbook: captured as you work, read by every agent on your machine, carried into every project, synced to your team. Everyone's agents build the same way.
// every agent, the same routine
One playbook, and every agent set up to use it.
snuffle installs the same operating skills into each agent and wires it to your playbook, so every agent knows your routine and pulls the rules a task needs before it edits.
snuffle claude|cursor|codex initWires the snuffle MCP server into each agent: .mcp.json, .cursor/mcp.json, ~/.codex/config.toml. Your agent starts snuffle when it needs it: nothing for you to run.
11 snuffle-* operating skillsInstalled in each agent's own format: Claude skills, Cursor rules, Codex prompts. Every agent learns the same routine in the shape it reads.
context_for_file <path>Before your agent edits a file, it pulls the rules, specs, and skills that govern it, over MCP. The same lookup is snuffle why on the CLI.
snuffle pack "<task>"Assemble the working set for a task: ranked, graph-expanded, packed to a token budget, with citations.
// the playbook improves as you work
Nobody maintains a playbook by hand. This one is tended while you build.
Capture lands the moment a decision is made. Gaps show up on demand. Drift is caught on sync. What proves out gets promoted.
snuffle nudgeA heads-up to record a decision while it's fresh, right before you push. Advisory: it never blocks.
snuffle coverageFind code that changed with no decision recorded, and the areas no decision covers.
snuffle backfillSeed the decision log from the git history you already have. You review and commit. It never commits for you.
snuffle syncOverrides are tracked against the canon they diverged from. Sync clears the redundant ones and escalates real changes to you.
snuffle doctorHealth checks for the playbook. It flags the reusable skills and rules living in only one project, and suggests what to promote.
snuffle promote <ref>Promote a skill to user scope and it follows you into every project, reused by reference, never copied.
how it works
the whole flow, as you would run it, from your machine to your whole team. every step traces to a real command in the shipped cli.
// set up, once
one npx command puts snuffle on your machine and indexes the skills and mcp servers you already use.
set up snuffle on your machine
shippedone command finds the skills, subagents, and mcp servers you already use across your agent config, then imports them at your user scope. it asks before writing; --apply (or -y) skips the prompts for CI.
→ your global skills + mcp servers imported at user scope, ready to drop into any repo. no account, no cloud. --apply/-y runs it headless in CI.
~ %
// in a project
onboard a repo, wire every agent to it, and carry your playbook into the next project without copy-paste.
onboard a project
shippedsnuffle discovers what is already here, lists it, and (in a terminal) lets you edit the selection before it imports a thing. secret-bearing files are skipped, never copied into canon.
→ your existing docs become your playbook (secrets skipped, never leaked) and your agent reads them over MCP. press e to deselect anything before it imports: you choose exactly what gets indexed.
~/your-project %
wire a second agent; get the same behavior
shippedone command connects another agent to the same store and installs the same operating skills in its own format. nothing is migrated, nothing copied: both agents resolve the same playbook.
→ a second agent that behaves like the first: same skills, same rules, same order of work, in its own format. no re-teaching.
~/your-project %
ask snuffle, and let it tidy up
shippedask questions on the cli and get answers from your own playbook; doctor checks its health and flags reusable skills + rules worth lifting to user scope.
→ answers from your own playbook without leaving the terminal, and a doctor that flags the reusable skills + rules living only in this project, so the right knowledge can be lifted to the right level.
~/your-project %
carry it into the next project
shippedonboard the same way; anything already covered by your user scope is reused by reference, not copied. lift a project resource up the chain with snuffle promote.
→ a second repo where every agent builds like in the first, minus the copy-paste: whatever your user scope already covers is reused by reference, and snuffle promote lifts a reusable resource up so every project inherits it.
~/your-project %
// with your team
a team is a signing key you pin and a shared store, not a service to run. invite with an allow-list; a teammate joins your approval queue; you approve.
create a team, invite a teammate
shippeda team is your device's signing key, pinned as the owner, plus a shared store. there is no service to run. create it, then mint a signed invite that names who may join, or open it to anyone.
→ a signed invite only your pinned owner key could mint, carrying the emails you allow (or open to anyone). the private key never leaves your keychain.
~/your-project %
a teammate joins, you approve
shippedfrom their own machine, the invitee verifies the code against your pinned owner key, then drops a signed request (their public key, never their secret) into the shared store. nobody is admitted until you approve it; membership is owner-signed, so holding the shared store credential is not enough to become a member.
→ the joiner sees exactly which team and owner before anything is contacted, then only queues. you confer membership with one owner-signed approval, so a leaked shared-store credential cannot mint a member or forge a contribution.
~/your-project %
everyone syncs the same canon
shippedpush your team canon and it is signed on the way out; pull verifies every file against the approved member set before it touches your repo, and the secret scan runs both directions.
→ team canon carries a signature out and is checked against the owner-approved member set on the way in: an unsigned or unknown-signer file is rejected before it lands, and the secret scan runs both ways. and when one repo needs a different take on a team skill, a project-scope copy overrides it for that repo alone; team rules and hooks stay enforced for everyone.
~/your-project %
// leaving clean
detach a team, project, or device and keep a readable markdown folder behind.
detach and offboard
shippedleave a team, a project, or a device without losing a thing: only derived state and creds go, your markdown stays.
→ a graceful offboard that leaves a readable markdown folder behind. nothing held hostage, and an honest reminder that cutting off access means the owner rotating the shared store credential.
~/your-project %
// what you get
- ++your playbook as plain markdown under .snuffle/, versioned in your git history. delete snuffle and you keep a folder you can read.
- ++every agent works the same way: Claude Code, Cursor, and Codex read one resolved playbook over MCP, each wired in its own format; your agent starts snuffle on demand.
- ++the right knowledge at the right level: project knowledge stays local, reusable knowledge lifts to user scope, team knowledge syncs to everyone.
- ++the playbook improves as you work: capture on the spot, coverage for the gaps, drift caught on sync, promote what proves out.
- ++fail-closed everywhere: every resource is secret-scanned before it is imported, served, or synced.
capture ++ share ++ reuse
Everyone builds the same way.
Your skills and rules follow you across every project, and sync to your team's shared store. Set how you build once, and it holds everywhere instead of drifting repo by repo and person by person.
Capture as you work.
snuffle tells your agent what to write down. New skills and your decisions land in the project as plain markdown, the moment you make them.
Workflows hold your order of work.
A workflow is ordered phases: the skills and rules each phase uses, with soft or hard gates between them. Your agent records one with record_workflow and runs it the same way next time.
Share with your team.
Mint a signed invite that names who can join, or open it to anyone, verified against your team's owner key. A teammate joins into your approval queue; once you approve, canon syncs both ways through a store you own: signed on push, verified on pull.
Ask in plain language.
Any MCP-capable agent asks and gets the right skills, rules, and docs back, with citations. Search covers this project, your user scope, and your joined teams. The default runs free and offline; a learned embedder is opt-in via snuffle embed setup.
A decision rides with every change.
The why behind it (when, who, the trade-offs) lands as a durable record. Your agent nudges you to write it as you work, and the forge blocks a merge that arrives without one. The reasoning holds for any agent or teammate, not on trust.
Secret-safe by default.
Every resource is scanned before it reaches an agent. A detected secret blocks the serve and tells you to redact and rotate. Reference, not value.
Respected everywhere. Overridden on purpose.
User, project, and team layers compose into one resolved playbook. Skills and workflows can be overridden where it matters: for one project, or for one person at user scope. Team rules and hooks stay enforced, so a local scope can't silently shadow a team mandate. Personal preference stays personal; team mandates hold for everyone.
It's all plain markdown in your repo. Delete snuffle and you keep a folder you can read. No lock-in.
// works with
your playbook, served over MCP · runs on macOS & Linux
// faq
the basics
- What is snuffle?
- Your coding playbook, served to every coding agent. Skills, rules, workflows, and the decisions behind them live as plain markdown in your repo and reach Claude Code, Cursor, Codex, and any MCP-capable agent over MCP. One way of working, followed everywhere.
- Who is it for?
- Developers working with coding agents (Claude Code, Cursor, Codex) who are tired of re-teaching each one the same things, and teams who want everyone's agents building the same way instead of drifting repo by repo and person by person.
- What lives in a snuffle playbook?
- Plain-markdown resources: skills (how to do a thing), workflows (ordered phases with gates), rules (constraints your agent must follow), decisions (the why behind a choice, with trade-offs), and docs you import. All in a .snuffle/ folder in your repo.
- Isn't this just a wiki, or a big CLAUDE.md?
- No. A wiki is for humans to read; a CLAUDE.md is one flat file. A playbook is structured and scoped: served to agents over MCP, composed across user/project/team layers, and governed. It can import your existing CLAUDE.md, rules, and docs as a starting point.
- How does this relate to context engineering?
- snuffle sits before context engineering, not inside it. Context engineering decides what goes into the context window; snuffle is where that comes from: your team's accumulated know-how, captured as you work. You can only put in what got written down.
the playbook
- Will every agent follow my workflow?
- Yes. A workflow is a first-class resource: ordered phases, the skills and rules each phase needs, gates between them. Every agent gets the same operating skills and reads the same resolved playbook over MCP, so Claude Code, Cursor, and Codex run it the same way.
- Can I override the playbook for one project, or for one person?
- Yes, for the personal kinds. Skills, workflows, commands, and notes resolve user over project over team: your user scope follows you into every project, and a project overrides exactly what it needs. Team rules and hooks resolve team-first by design, so a local scope never quietly displaces a team mandate.
- Can I give one agent its own rules, say a variant just for an agent named hermes?
- No, not today. Scopes are user, project, and team; there is no per-agent scope. Every agent reads the same resolved playbook, adapted only in format, never in content. If a person needs their own way of working, that is the user scope.
- Do remote or cloud agents run it?
- Not yet as a feature. Your agent runs snuffle locally, so today it covers any MCP-capable agent on your machine. The playbook is plain markdown in your repo, so it goes wherever the repo goes, and CI or headless automation supplies the signing key through an environment variable instead of the keychain.
- Does the playbook improve over time?
- Yes. snuffle nudges your agent to record skills and decisions the moment they're made. snuffle coverage finds code that changed with no decision recorded. Overrides are tracked against the canon they diverged from: sync clears the redundant ones and escalates real changes to you. snuffle promote lifts what proved out so every project inherits it.
- Can it find what we never wrote down?
- No. It can't recover unwritten reasoning, but snuffle coverage shows where it's missing: code that changed with no decision recorded, and the areas none covers, so you can backfill it.
- We have years of history and no decision log. Start from zero?
- No. snuffle backfill reads your git history and proposes decision stubs for the changes that look architectural. You review the ones that matter and commit them. snuffle never commits for you.
how it works
- How does my agent use it?
- Over MCP. Your agent starts snuffle on demand and queries your playbook in plain language: searching, fetching resources, and recording new skills and decisions as you work. Claude Code, Cursor, and Codex today, and any MCP-capable agent can read it, since it's all served over MCP.
- Does my agent read files, or query MCP?
- Both, by role. Your playbook is plain markdown on disk in .snuffle/, versioned in git, so it's always readable. MCP is how your agent pulls the right slice at the right moment: it searches the playbook, fetches the rules and skills that govern the file it's editing, and records new ones, resolved across your user, project, and team scopes. So the files are the source; MCP is the lookup-and-record layer over them. Moving the playbook between machines is git and your team store, not MCP.
- Do I have to write everything down by hand?
- No. snuffle nudges your agent to capture skills and decisions the moment you make them, landing as markdown in the repo. You can also run snuffle import to pull in your existing docs, ADRs, and rules.
- What are scopes?
- Three layers that compose into one resolved playbook: user (follows you across every project), project (lives in this repo), and team (synced to everyone). You override exactly what a project needs; everything else is inherited, so the right knowledge lives at the right level.
- What's a decision, and what's the gate?
- A decision is a durable record of why you chose something: when, who, the trade-offs. The gate can block a merge that changes governed canon without recording one, so the reasoning travels with the code instead of living in someone's head.
local-first, data & lock-in
- Is it local-first?
- Yes. v1 runs entirely on your machine: snuffle init scaffolds a .snuffle/ folder, a local server reads it, your agent queries it. No account, no cloud required.
- Where does my data live?
- In your repo. Your playbook is plain markdown in .snuffle/, versioned in your git history. The derived search index is rebuildable and gitignored.
- Is there lock-in?
- No. It's all plain markdown in your repo. Nothing is held hostage, nothing needs snuffle to make sense.
- Is my code sent anywhere?
- No. Everything is local by default. Team sharing is opt-in and syncs only the .snuffle/team canon you choose, to a store you own: never your source code.
agents & platforms
- Which agents does it work with?
- Claude Code, Cursor, and Codex: snuffle wires its MCP server into each (.mcp.json, .cursor/mcp.json, and ~/.codex/config.toml) and installs the same operating skills in each one's own format. Any MCP-capable agent can read it, since it's all served over MCP.
- Can different agents share the same knowledge?
- Yes. That's the point. One markdown source, served to every MCP-capable agent, so Claude, Cursor, and Codex all build from the same playbook instead of each drifting on its own.
- Which platforms does it run on?
- macOS and Linux. Your device signing key is held in the OS keychain (macOS Keychain or Linux secret-tool), so Windows isn't supported yet.
teams
- How does team sharing work?
- There's no server. Coordination happens through a shared store you own (an S3-style bucket), and only public keys and signed records ever pass through it. The owner creates a team (pinning their signing key), then mints a signed invite. A teammate joins from their own machine by writing a signed request into the store: their public key, never their secret. The owner approves it with one command, recording an owner-signed membership. After that, canon syncs both ways, and every pull is verified against the approved member set. Trust is the owner's signature: no broker, no OAuth, no signup.
- If there's no backend, how does a teammate on another machine get approved?
- No live server. Asymmetric crypto and a shared bucket do it. Your private key never leaves your machine; only your public key travels. The joiner drops a signed request into the store; the owner approves with one command, writing an owner-signed membership that both machines verify. It's asynchronous: the owner approves whenever they next touch the store.
- Who runs the shared store?
- You do. It's a bucket you own (Scaleway / any S3-compatible store), or even a shared folder; snuffle never operates a service for you. Its credential is handed to the team out-of-band; the invite itself carries no credential.
- What stops someone who has the bucket from joining or tampering?
- Signatures. Membership only counts if it's signed by the team's owner key, and team canon is verified against the approved members on pull, so a bucket credential alone can't mint a member or inject content. It can still read and delete bytes, so cutting someone off means revoking the credential itself, not just denying them: rotating the shared one, or, if you've opted into per-user credentials, disabling just that member.
- How do I remove someone from a team?
- snuffle team revoke <email> drops them from the signed member set, and team revoke-invite kills an outstanding invite. Cutting off access to the bytes depends on how the store is credentialed: with one shared credential you rotate it (there's a team rotate-credential checklist). If you've opted into per-user credentials, snuffle team revoke-credential <email> disables just that member (team revoke chains it automatically), so nobody else has to rotate anything.
- Can I limit what a teammate is able to change?
- By default every approved member can push signed canon. For teams that want tighter control, per-user credentials are an opt-in tier: each member gets a scoped credential that can only write to their own inbox, and the owner promotes verified contributions into the shared canon. A member proposes changes but can't overwrite anyone else's work, and you can revoke one member without disturbing the rest. It runs on scoped cloud credentials you operate (S3/IAM), so it's a deliberate add-on; the default team model still needs no server.
- Does team canon sync automatically, and can I see its history?
- Both, opt-in. snuffle sync runs one pass on demand; snuffle sync --watch runs it as a background daemon (re-syncing when your canon changes or on an interval), so everyone's agents stay current without remembering to sync. And snuffle sync --git-snapshot records each verified sync as a commit in a local git repo, giving you a git log / diff audit trail of the team's canon. Both are additive: the plain one-shot sync is unchanged.
- Does my signing key ever leave my machine?
- No. It's generated and held in your OS keychain; only the public half is ever shared. For CI or headless automation you can supply it through an environment variable instead of the keychain.
security
- Will it leak my secrets?
- No. Every resource is scanned before it's served, imported, or synced, in or out. A detected secret blocks the operation and tells you to redact and rotate. Reference, not value.
- Can a teammate or attacker inject content into my repo?
- No. Team canon is signed on push and verified on pull against the owner-approved member set; unsigned or unknown-signer files are rejected before they touch your repo, and the secret scan runs on the way in too. A stranger holding the bucket can't quietly poison your canon.
availability
- When can I use it?
- Soon. It's in private dogfooding now. Say hi and we'll tell you when it opens.
- What will it cost? Is it open source?
- Free. Always. snuffle is open source, and it runs entirely on your own machine and a store you own, so there's nothing to meter. Say hi if you'd like to follow along or contribute.