Skip to content
Back to search

driftless

MarketplaceWorks with Claude CodeGitHub

Claude Code plugin that saves tokens by handing off before context rot: a goal that never drifts, a living design doc, a self-compressing logbook, and an automatic handoff into a fresh session.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 19 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Tigierre/driftless with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Tigierre/driftless'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tigierre--driftless/badge.svg)](/listings/tigierre--driftless)

HTML

<a href="/listings/tigierre--driftless"><img src="/api/listings/tigierre--driftless/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Driftless needs **Node.js 20 or later** on your PATH: every hook runs `node`, and Claude Code's native installer does not bring it.

**Claude Code** — as a plugin:

/plugin marketplace add Tigierre/driftless
/plugin install driftless@driftless

To try it on one project only, run these from that project's folder (to run it from a clone of this repository instead, give the clone's folder in place of `Tigierre/driftless`):

claude plugin marketplace add Tigierre/driftless --scope local
claude plugin install driftless@driftless --scope local

Then trust your projects folder, once

Claude Code asks "Do you trust the files in this folder?" the first time it opens a folder. A new project is a new folder, so its first fresh session would stop on that question. That is the one click Driftless cannot take for you, and it should not: trust is a security decision. No setting or flag skips it.

Outside a git repository, trust covers subfolders. So keep your projects under one folder and trust that folder once, right after installing (and set it as the plugin's **Projects folder**, `projects_root`, so new projects are created there):

cd <the folder that holds your projects>
claude          # accept "trust this folder", then exit

From then on, every project Driftless creates there opens without asking. `init` tells you when a new project is not covered yet. A project that is its own git repository is trusted at its repository root, so it asks once, the first time.

Other tools

Clone the repository (`git clone https://github.com/Tigierre/driftless.git`; Node.js 20+), then once per tool `node <clone>/scripts/driftless.mjs install <tool>`, where `<clone>` is the folder you cloned it into; `uninstall <tool>` removes exactly what `install` added. Keep the clone: the hooks run from it.

What you get depends on what the tool lets Driftless hang on to:

- **Level 1, hooks.** The tool runs Driftless when a session starts and when a turn ends. The session starts with the project's context, the size of the context is watched, the handoff is asked for by itself, and the fresh session opens by itself wherever the tool can open one. Where the hooks do not say the size of the context (Devin, Kiro), the handoff is asked for at the end of each step of the resume point instead, and the rest is the same. - **Level 2, no hooks.** The method without the automation: the agent runs two commands because `AGENTS.md` tells it to. Nothing measures the context, and you start the next session.

| Tool | Level | Install | Tried live | |---|---|---|---| | Claude Code | 1 | plugin | **yes**: on Windows, at every change | | Codex | 1 | `install codex` | no | | Cursor | 1 | `install cursor` | no | | OpenCode | 1 | `install opencode` | no (one early try, before the economic rule) | | Kilo Code | 1 | `install kilo` | no | | Amp | 1 | `install amp`, or `install amp <project folder>` | no | | Qwen Code | 1 | `install qwen` | no | | Gemini CLI | 1 | `install gemini` | no | | Copilot CLI | 1 | `install copilot` | no | | Devin | 1, no measure | `install devin` | no | | Kiro | 1, no measure | `install kiro` (CLI), `install kiro <project folder>` (IDE) | no | | Any other agent that reads `AGENTS.md` | 2 | `install generic <project folder>` | no |

"No" means written from the tool's own documentation and run in the tests on input in the documented shape, never in the tool itself. If you use one of them, see [Help wanted](#help-wanted). What each tool gets, its one-time step and its limits: [Install, tool by tool](docs/install.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 11 lines
  1. {
  2. "name": "driftless",
  3. "owner": { "name": "Driftless contributors" },
  4. "plugins": [
  5. {
  6. "name": "driftless",
  7. "source": "./",
  8. "description": "Hands off before context rot: a goal that never drifts, a living design doc, a self-compressing logbook, and an automatic handoff that resumes in a fresh session."
  9. }
  10. ]
  11. }
README.md · README · 284 lines
  1. <img src="docs/icon.svg" width="72" height="72" align="right" alt="">
  2. # Driftless
  3. [![test](https://github.com/Tigierre/driftless/actions/workflows/test.yml/badge.svg)](https://github.com/Tigierre/driftless/actions/workflows/test.yml)
  4. **Hand off before the context rots — and never drift from what you set out to do.**
  5. **Watch** the context → **hand off** when carrying it costs more than a fresh start → **write down** where things stand →
  6. **reopen** the project in a fresh session → **resume** from the resume point. By itself, then round again.
  7. **27% to 31% off the whole bill, subagents included**, replayed on the author's own month of work against carrying each
  8. piece of work in one session to the end. Every comparison, the weak ones too, is in [What it saves](#what-it-saves).
  9. For **Claude Code, Codex, Cursor, OpenCode, Kilo Code, Amp, Qwen Code, Gemini CLI, Copilot CLI, Devin and Kiro**, and, without the
  10. automation, for any agent that reads `AGENTS.md` (only Claude Code is tried live: [help wanted](#help-wanted)). Every project lives in
  11. three documents with distinct jobs, and when carrying a session's context costs more than a fresh start, Driftless
  12. distills the session into those documents and reopens the project in a fresh session by itself. No compaction, no
  13. `/clear`, nothing to type when it is time to hand off, no threshold to tune. Each tool needs one setup step, once (see
  14. [Install](#install), which also says what each tool gets).
  15. | Document | Job | Who changes it |
  16. |---|---|---|
  17. | `NORTHSTAR.md` | The goal, in your words: why, how you'll know, what you don't want | Only you |
  18. | `DESIGN.md` | Durable source of truth, by topic, kept as-is, with an index at the top | The agent, at every handoff |
  19. | `LOGBOOK.md` | Last 3 tasks in detail, older ones one line each, and the **Resume point** | The agent, while working |
  20. ## Install
  21. Driftless needs **Node.js 20 or later** on your PATH: every hook runs `node`, and Claude Code's native installer
  22. does not bring it.
  23. **Claude Code** — as a plugin:
  24. ```
  25. /plugin marketplace add Tigierre/driftless
  26. /plugin install driftless@driftless
  27. ```
  28. To try it on one project only, run these from that project's folder (to run it from a clone of this repository instead,
  29. give the clone's folder in place of `Tigierre/driftless`):
  30. ```
  31. claude plugin marketplace add Tigierre/driftless --scope local
  32. claude plugin install driftless@driftless --scope local
  33. ```
  34. ### Then trust your projects folder, once
  35. Claude Code asks "Do you trust the files in this folder?" the first time it opens a folder. A new project
  36. is a new folder, so its first fresh session would stop on that question. That is the one click Driftless
  37. cannot take for you, and it should not: trust is a security decision. No setting or flag skips it.
  38. Outside a git repository, trust covers subfolders. So keep your projects under one folder and trust that
  39. folder once, right after installing (and set it as the plugin's **Projects folder**, `projects_root`, so new projects
  40. are created there):
  41. ```
  42. cd <the folder that holds your projects>
  43. claude # accept "trust this folder", then exit
  44. ```
  45. From then on, every project Driftless creates there opens without asking. `init` tells you when a new
  46. project is not covered yet. A project that is its own git repository is trusted at its repository root,
  47. so it asks once, the first time.
  48. ### Other tools
  49. Clone the repository (`git clone https://github.com/Tigierre/driftless.git`; Node.js 20+), then once per tool `node <clone>/scripts/driftless.mjs install <tool>`, where `<clone>`
  50. is the folder you cloned it into; `uninstall <tool>` removes exactly what `install` added. Keep the clone: the hooks run from it.
  51. What you get depends on what the tool lets Driftless hang on to:
  52. - **Level 1, hooks.** The tool runs Driftless when a session starts and when a turn ends. The session starts with the
  53. project's context, the size of the context is watched, the handoff is asked for by itself, and the fresh session
  54. opens by itself wherever the tool can open one. Where the hooks do not say the size of the context (Devin, Kiro), the
  55. handoff is asked for at the end of each step of the resume point instead, and the rest is the same.
  56. - **Level 2, no hooks.** The method without the automation: the agent runs two commands because `AGENTS.md` tells it
  57. to. Nothing measures the context, and you start the next session.
  58. | Tool | Level | Install | Tried live |
  59. |---|---|---|---|
  60. | Claude Code | 1 | plugin | **yes**: on Windows, at every change |
  61. | Codex | 1 | `install codex` | no |
  62. | Cursor | 1 | `install cursor` | no |
  63. | OpenCode | 1 | `install opencode` | no (one early try, before the economic rule) |
  64. | Kilo Code | 1 | `install kilo` | no |
  65. | Amp | 1 | `install amp`, or `install amp <project folder>` | no |
  66. | Qwen Code | 1 | `install qwen` | no |
  67. | Gemini CLI | 1 | `install gemini` | no |
  68. | Copilot CLI | 1 | `install copilot` | no |
  69. | Devin | 1, no measure | `install devin` | no |
  70. | Kiro | 1, no measure | `install kiro` (CLI), `install kiro <project folder>` (IDE) | no |
  71. | Any other agent that reads `AGENTS.md` | 2 | `install generic <project folder>` | no |
  72. "No" means written from the tool's own documentation and run in the tests on input in the documented shape, never in
  73. the tool itself. If you use one of them, see [Help wanted](#help-wanted). What each tool gets, its one-time step and
  74. its limits: [Install, tool by tool](docs/install.md).
  75. ## How it works
  76. 1. **Start.** In a folder that isn't a project, Driftless asks: new project, resume one, or just work here.
  77. A new project gets its folder, the three documents and a North Star interview.
  78. 2. **Work.** Every session starts with the goal, the resume point and the design index already in
  79. context — and reads only the design sections it needs.
  80. 3. **Time to hand off.** Driftless keeps the account of what carrying the context has cost ([the rule](docs/how-it-works.md)). When
  81. it pays to start fresh, or at a cap you set, the agent is asked to run the `handoff` subagent: durable
  82. decisions go to `DESIGN.md`, the logbook is compressed, the resume point is rewritten with a course check
  83. against the North Star. In Claude Code this also happens in the middle of a long turn.
  84. 4. **Fresh session.** Driftless opens a fresh session in the project, where you were working — a new tab of
  85. the Claude Code panel in the same VS Code window, the desktop app, a new terminal window if you work in a
  86. terminal, a new session in the same window in OpenCode and Kilo Code, a new thread in Amp — whose first prompt is "resume
  87. this project from the resume point". Never a terminal you do not use: where it cannot open a session by itself,
  88. it says so and you open a new chat. The old session stops. If Claude Code says it still has background tasks
  89. or scheduled tasks, Driftless names them when it asks for the handoff and again when the session ends: they
  90. are the old session's, and will wake it.
  91. 5. **One driver.** A baton (`.driftless/baton.json`) keeps two live sessions from steering the same project. In
  92. Claude Code the project goes to the session you write in, not to the one that opened first: when the editor
  93. reopens and brings its tabs back, none of them takes the project until you send a message there. A session
  94. kept out by another takes the project by itself at your next message, once that other session has ended.
  95. A turn you did not write is not a message of yours: a background task that reports, a message from another
  96. session or a scheduled task that fires takes no project, so a chat that handed the project on does not take
  97. it back by being woken.
  98. The baton names the process of the session that holds it. In OpenCode, Kilo Code and Amp the plugin says that
  99. process at the end of every turn, so a session that took the project with `attach` (a command the model runs
  100. from a shell, which is gone at once) still holds it.
  101. **The threshold, if you want one.** By default there is nothing to tune: Driftless hands off when carrying the context
  102. has cost as much as a fresh start. To set your own limit, in `.driftless/config.json`:
  103. | Option | Example | Meaning |
  104. |---|---|---|
  105. | `token_cap` | `250000` | Hand off at this many tokens. |
  106. | `cap_percent` | `34` | Hand off at this share of the model's context window. |
  107. | both | `34` + `250000` | The lower of the two wins: the token cap is an absolute ceiling. |
  108. In Claude Code a status line shows where the session stands, so you never need `/context`:
  109. ```
  110. Driftless · ctx 142k/260k (55%) · cache 37m · saved $67.82
  111. ```
  112. In detail (the rule and its guards, mid-turn and subagent handoffs, one-shot runs, cold restarts, sessions opened
  113. outside a project, compaction): [How it works, in detail](docs/how-it-works.md).
  114. ## What it saves
  115. Read each percentage against what it compares. The "before" is **never resetting**: each piece of work carried in one session
  116. until it is done, with no handoff, no `/clear` and no compaction, on a 1M-token window (how the author works). On a 200k window
  117. native compaction would step in first, so your "before" may cost less than this one. All figures come from one machine, one
  118. person, one month, Opus 5.5, at list prices.
  119. | Against | What | Saving |
  120. |---|---|---|
  121. | never resetting | everything built today: rule, size guards, diet, command output limit (replayed on 73 pieces of work, with the handoff priced at what 17 measured handoffs cost and the re-reads after a cut output counted; the lighter start estimated, quality not measured) | **27.0% to 31.3% of the whole bill** (29.5% in the middle) |
  122. | never resetting | the rule alone, main thread (`audit --all`, run later on a larger history: 97 pieces of work) | 30.1% (95% interval 18.2% to 43.6%) |
  123. | never resetting | the rule alone, whole bill with subagents | 19.3% |
  124. | the same author's careful manual handoffs | the rule, main thread | 3.5%: the value is not having to watch a meter |
  125. | short work, under 100 requests | the rule | about 0% |
  126. Ten long pieces of work out of 73 make 85% of the saving; without them the rule saves about 10%. Your history is not the
  127. author's: `audit` replays yours (see [Ask your own history](#ask-your-own-history)).
  128. **The goal was 50% off the whole bill, subagents included, at the same model: it is not reached.** What is built today
  129. gives the 27% to 31% above; the rest of the way was studied and no lever left at the same model is worth a release.
  130. ### Ask your own history
  131. In Claude Code, ask the agent: "does Driftless pay off here?", or "on all my projects?". From a clone, in the project's
  132. folder:
  133. ```
  134. node <clone>/scripts/driftless.mjs audit # this project (Claude Code transcripts)
  135. node <clone>/scripts/driftless.mjs audit --all # every project on this machine
  136. ```
  137. `audit` replays your sessions under each policy at today's list prices and says what each would have cost, with a 95%
  138. interval. It spends no tokens and sends nothing anywhere. **On short sessions it will tell you Driftless does not save
  139. money.** In Claude Code you don't even have to ask: the saving on each project is counted as you work and said at
  140. session start. More: [Does it save you anything?](docs/savings.md)
  141. ## Stop it
  142. **Stopping for the day is not switching off.** Tell the agent you are done for now ("handoff, I'm done for today"): it runs the
  143. same handoff, the project is released, no new window opens, and Driftless is still on next time. A handoff you ask for by hand
  144. ends there unless you ask to go on in a fresh session. If Driftless asks for a handoff at a bad moment, say "not now": the
  145. request comes back once the context has grown by another 50,000 tokens (`later`), and the next session starts clean.
  146. Driftless runs no service: it lives in the agent's hooks. What it starts on its own ends by itself: the weekly replay
  147. ([Does it save you anything?](docs/savings.md)), the count of a session's saving after it ends, and, in VS Code, the
  148. headless start of the fresh session that the panel then opens. To stop it without uninstalling, tell the agent; it knows the command:
  149. | Say | What happens |
  150. |---|---|
  151. | "stop Driftless" | this project: no context, no cap, no handoff, no fresh session |
  152. | "stop Driftless everywhere" | every project, the new / resume question included |
  153. | "turn Driftless back on" (here, or everywhere) | back on |
  154. | "no Driftless status line here" | this project: no status line, from the next session (Claude Code) |
  155. It takes effect from the next answer, drops a handoff already asked for and frees the baton. From a clone, in the project's
  156. folder, the same is `node <clone>/scripts/driftless.mjs off`, `off --global`, `on [--global]`, `statusline off|on`; outside
  157. Claude Code a session that starts with Driftless off no longer knows the command, so switch it back on that way.
  158. `uninstall <tool>` removes Driftless from any other tool of the [table](#install); in Claude Code, `/plugin` disables or
  159. uninstalls it.
  160. ## Safety, in short
  161. Driftless runs as a hook of your agent, in folders you may have cloned from anyone. What it does about it, each point
  162. in full in [Safety](docs/safety.md):
  163. - **The fresh session inherits the permission mode of the session that handed off, except bypass:** nobody watches it
  164. start, so a session in bypass hands off to one in `acceptEdits`, unless you turn on the option `carry_bypass`. A
  165. project's `.driftless/config.json` can make it stricter, never looser; plan mode is never handed on.
  166. - **What a cloned folder brings in `.driftless/` is not taken for yours:** the files that say which session drives
  167. carry a seal only your machine can make.
  168. - **What it reads into the context stays inside the project:** a document that leads outside it is not read, and
  169. names from a project's files are said as plain words.
  170. - **What it writes in `.driftless/` stays out of git**, all but `config.json`.
  171. - **A folder above is your project only if it is yours** (on Windows, only if you already know it as a project).
  172. - **A file of yours stays as you made it:** never written over when it does not read, written through its link, with
  173. its permissions, and not at all for nothing.
  174. - **The skill runs only Driftless' own script without asking.**
  175. ## The diet: a smaller fixed cost at every start
  176. Before you type anything, a session already carries tool schemas, connector names, skill and agent listings: tens of
  177. thousands of tokens, most of which a given project never uses. In Claude Code, the sessions Driftless opens start
  178. without what this machine has never used, and long command output goes to a file. Nothing of yours is touched: your
  179. CLAUDE.md, memories, rules, agents and skills are never part of it unless you name them, and a hidden skill still works
  180. as `/name`. How it decides, and how to see or undo it: [The diet](docs/diet.md).
  181. ## Requirements and limits
  182. - Node.js 20+ on PATH — every hook is one script, `scripts/driftless.mjs` (OpenCode, Kilo Code and Amp run it in-process).
  183. - The fresh session opens where the session that handed off was running. From the VS Code extension (or a
  184. fork that runs it): the resume runs headless, then a link opens it in a new tab of the panel, in the same
  185. editor window (found from the session's process and the editor's own logs), with the answer already there,
  186. and goes on with the next step by itself (the panel cannot send a prompt, so Driftless' session-start hook
  187. gives that one session its first message, once); if the headless resume fails, the tab opens with the
  188. resume prompt ready to send. From the desktop app: the
  189. app. From a terminal: a new terminal window — Windows Terminal or a console on Windows, Terminal on macOS,
  190. the system terminal emulator on Linux. Anywhere else (the SDK, a CI job), no window: you resume by hand; a one-shot
  191. `claude -p` is asked for no handoff at all.
  192. `"surface"` in `.driftless/config.json` (`vscode`, `desktop`, `terminal`, `none`) overrides the choice.
  193. - To use the plugin in a second folder too, enable it in that folder's `.claude/settings.local.json`
  194. (`"enabledPlugins": { "driftless@driftless": true }`, plus the same `extraKnownMarketplaces` entry) rather
  195. than installing it again: a second `--scope local` install loads it once per session but lists it twice.
  196. - Agents ask once whether to trust a folder they have never opened. See [Then trust your projects folder, once](#then-trust-your-projects-folder-once).
  197. - Context is read from the session's own files (Claude Code, Codex, Gemini CLI), reported by the tool (OpenCode, Kilo Code, Amp, Qwen
  198. Code) or estimated from the transcript's size (Cursor, Copilot CLI); the files' formats are not documented. Devin
  199. and Kiro give nothing to measure.
  200. - The diet is for Claude Code only. The sessions Driftless opens carry it for that session only; for the ones you open by
  201. hand, the first of them in a project writes it to the project's `.claude/settings.local.json` by itself and tells you
  202. (Driftless on is the yes; `diet undo` takes it back for good). Your CLAUDE.md, memories, rules, agents and skills are never
  203. part of it unless you name them.
  204. Not the desktop app. With `diet apply`, claude.ai connectors go all together.
  205. ## Help wanted
  206. Only Claude Code is tried live. Every other row of the [table](#install) is **not tried**: built from the tool's
  207. documentation and covered by the smoke tests. Codex, Cursor, Kilo Code, Amp, Qwen Code, Gemini CLI, Copilot CLI, Devin and Kiro
  208. have never run Driftless, OpenCode only once, before the economic rule, and no real agent has ever followed the `AGENTS.md` of level 2.
  209. The author works on Claude Code only, so none of it will be tried here. If you use one of them, please try it and open
  210. an issue (**New issue → Tried on a tool** asks for all of it):
  211. - the tool and its version, and your operating system;
  212. - the output of `node <clone>/scripts/driftless.mjs status` and of `doctor <tool>`, both run in the project's folder (every tool
  213. of level 1 but Claude Code has one);
  214. - what happened at the first handoff: was it asked for by itself, did the handoff agent run, did a fresh session open, and where;
  215. - at level 2: did the agent run `begin` and `step` because `AGENTS.md` says so, or only when you told it to.
  216. "It worked" is worth as much as a bug report.
  217. ## Development
  218. ```
  219. npm test # smoke tests, each hook and command in a throwaway home; no model, no windows
  220. ```
  221. `DRIFTLESS_DRY_OPEN=1` records the fresh session in `.driftless/dry-open.json` instead of opening it.
  222. ## License
  223. MIT. Security problems: see [SECURITY.md](SECURITY.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.