offshoot
/offshoot
Use when working on a project that has an offshoot store (a .offshoot directory or OFFSHOOT_STORE) and you are about to change a SQLite database — schema migrations, bulk deletes, data experiments, or running several attempts at a fix. Teaches the fork-before-risky-work loop with the offshoot_* MCP tools.
- Author
- sricola ↗
- Repository
- offshoot ↗
- Licence
- Apache-2.0
- Last repository change
- 17.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Use when working on a project that has an offshoot store (a .offshoot directory or OFFSHOOT_STORE) and you are about to change a SQLite database — schema migrations, bulk deletes, data experiments, or running several attempts at a fix. Teaches the fork-before-risky-work loop with the offshoot_* MCP tools.
Original author description
Use when working on a project that has an offshoot store (a .offshoot directory or OFFSHOOT_STORE) and you are about to change a SQLite database — schema migrations, bulk deletes, data experiments, or running several attempts at a fix. Teaches the fork-before-risky-work loop with the offshoot_* MCP tools.
How it works
- The loop
- Rules
- Rules-file snippet for the project's AGENTS.md or CLAUDE.md
SKILL.md preview
---
name: offshoot
description: Use when working on a project that has an offshoot store (a .offshoot directory or OFFSHOOT_STORE) and you are about to change a SQLite database — schema migrations, bulk deletes, data experiments, or running several attempts at a fix. Teaches the fork-before-risky-work loop with the offshoot_* MCP tools.
---
# offshoot: branch the database before you change it
offshoot gives every attempt its own real SQLite database — a copy-on-write
fork, not a mock and not a re-seed. Every checkout is a stock `.db` file any
SQLite client opens. You have ten tools; the loop is four calls.
## The loop
1. **Orient:** `offshoot_list` — see databases, branches, checkpoints, and
which branches are protected (`main` is, by default). A human can
protect any other branch too (`offshoot protect <db>[@branch]` /
`offshoot unprotect`, CLI-only — there's no MCP tool for it, so you can
see the flag here but never change it).
2. **Fork before risk:** `offshoot_fork {database, new_branch, branch?, at?, ttl?, meta?}`
— instant, two small metadata objects, no data copy. Forks expire after
the server's default TTL (24h) unless you pass `ttl`. Then
`offshoot_checkout {database, branch: new_branch}` and point your SQL at
the returned path.
3. **Checkpoint when tests pass:** `offshoot_checkpoint {database, branch, name, meta?}`.
Name checkpoints for what they mean (`before-migration`, `migrated`).
4. **Roll back when they fail:** `offshoot_rollback {database, branch, to}`
returns the branch to a checkpoint, discarding everything since. The
branch's previous head is kept first as `<branch>-pre-rollback` — the
result's `backup` field names it — so a rollback is undone by promoting
that fork back onto the branch (`offshoot_promote {source:
"<branch>-pre-rollback", target: branch}`). Same TTL'd, one-rolling-slot
shape as promote's own safety fork below.
5. **Compare before you promote:** `offshoot_diff {database, left:
"attempt-2@done", right: "main"}` (or against a golden checkpoint) — read
the per-table added/removed/changed counts; use `table` + `full` to see
the exact rows.
6. **Promote the winner:** `offshoot_promote {database, source, target}`
repoints `target` (often `main`) at `source`'s head. Protected targets
(`main` by default) refuse; that refusal is the confirmation step, not a
bug. Do not retry with `force: true` — this server refuses force too
unless the operator started it with `offshoot mcp -allow-force`. Instead
run `offshoot_diff` to show what would change, then ask the human to
promote from the CLI (`offshoot promote <db>@<source> --onto <target>
--force`). The target's previous head is kept as `<target>-pre-promote` — the result
names it — so a promote is undone by promoting that fork back. That
safety fork always carries a TTL (24h by default) and is one rolling
slot per target, replaced by the next promote onto that target, so the
undo window closes when either happens.
7. **Clean up:** `offshoot_destroy` a failed attempt, or let its TTL expire.
`offshoot_touch {database, branch, ttl?}` keeps a fork alive if a task
runs long. A protected branch (or one under a live lease) refuses, and
`force` is refused too unless the operator started
`offshoot mcp -allow-force` — do not retry with force; ask the human, who
can destroy from the CLI. A refusal that says another checkpoint is in
progress (a lease holder starting `checkpoint:`) is the exception: that
lease ends on its own within seconds, so wait and retry the same call
rather than asking the human.
On a long-running branch where you name a checkpoint every step,
`offshoot_prune_checkpoints {database, branch, keep: 20}` (or `names`)
drops checkpoints you will not roll back to; it never touches the
branch's data, and each new checkpoint stays fast.
## Rules
- Never run a migration, `DROP`, `DELETE`, or `UPDATE` without a checkpoint
or a fork to return to. `/rewind` restores Claude's file edits only; it does
not undo what a Bash `sqlite3` command did to a database.
- Prefer forking to backing up by hand. Prefer a longer `ttl` to `ttl: "none"`.
- Read results: `structuredContent` carries `txid`, `path`, `ttl`, `backup`
for you to reuse; the text is the same information for the human.
- If a tool says a daemon session is open on a branch, close it first
(`offshoot session close`) rather than forcing. If it says the session
is closing ("closing; retry"), do not close it: wait a few seconds and
call the same tool again.
- Work in the fork's checkout path, not `main`'s, while experimenting.
## Rules-file snippet for the project's AGENTS.md or CLAUDE.md
```
Database changes: this project uses offshoot. Before any schema migration,
bulk delete, or data experiment, fork the database (offshoot_fork) and work
in the fork's checkout; checkpoint when tests pass; roll back when they
fail; promote the fork that worked. Never run destructive SQL on main's
checkout directly.
```
Docs: https://sricola.github.io/offshoot/docs/agents/ · machine-readable index:
https://sricola.github.io/offshoot/llms.txt
Versions
The database has no other skills named offshoot.
Database snapshot: 13.11.2026 · package version b172baf08505 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100mcp-server-sqlite
Use this skill when installing, configuring, and executing tools with the local SQLite file inspection and query execution SQLite MCP server. - 95expo-sqlite
Persist and query local data with expo-sqlite in Expo or React Native apps. Use for SQLite setup, SQL queries, schema migrations, transactions, SQLiteProvider, expo-sqlite/kv-store, or the localStorage polyfill. - 100database-inspector
探索 SQLite 或 PostgreSQL 数据库,执行安全只读查询,提供表列表、详细表结构(列/类型/约束/索引)、数据预览,并生成 Mermaid ER 图。当用户需要查看数据库架构、探索表关系、预览数据、执行只读查询,或提及 schema、ER 图、SQL 查询、数据预览、describe table、数据库探索等关键词时触发。 - 85SQLite
Expert guidance for SQLite database with better-sqlite3 Node.js driver including database setup, queries, transactions, migrations, performance optimization, and integration with TypeScript. Use this when working with embedded databases, better-sqlite3 driver, or SQLite operations. - 100database-schema
Implement and review Cursor BYOK SQLite schema changes. Use when adding or changing tables, columns, indexes, constraints, foreign keys, SQLx migrations, persistence mappings, or database fixtures under server. - 100sql-toolkit
Query, design, migrate, and optimize SQL databases. Use when working with SQLite, PostgreSQL, or MySQL — schema design, writing queries, creating migrations, indexing, backup/restore, and debugging slow queries. No ORMs required.