Provides a sandboxed, disposable bash shell with a JSON-based filesystem for rapid snapshotting, forking, and branching of agent workspaces.
- GitHub stars
- 5
- Files
- 8
- Last commit
- Nov 11, 2026
- License
- MIT
- Allowed tools
- —
What does the forkable-shell skill do?
forkable-shell provides a sandboxed, disposable bash shell with a JSON-based filesystem for rapid snapshotting, forking, and branching of agent workspaces.
Summary generated from the skill's SKILL.md.
About the forkable-shell skill
Creating sandboxed, disposable bash environments for AI agents is what forkable-shell enables. It provides a virtual filesystem stored as a single JSON file, allowing developers to snapshot, fork, and branch agent workspaces with extreme speed. Instead of waiting seconds for a container to boot, users can fork a workspace in approximately 0.24ms by simply copying the JSON file. This makes it ideal for running agent-generated shell commands without granting access to a real machine.
An agent should load this skill when it needs to experiment with multiple competing approaches by branching a single trunk into parallel workspaces. The tool relies on just-bash to provide an in-process shell without a VM or container. While it is excellent for rapid prototyping and checkpointing state, it is not intended for running real binaries like node or npm, nor is it a security boundary against human adversaries. Users must keep all important data within the /work prefix to ensure it persists through snapshots.
What an agent can do with it
- 1Parallel approach testingFork a single workspace into multiple independent branches to let an agent try different strategies simultaneously.
- 2Safe command executionRun shell commands generated by an AI in a sandboxed environment that cannot reach the host filesystem.
- 3Disposable shell for Claude CodeProvide a Claude Code subprocess with a throwaway shell environment that is isolated from the main session.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the forkable-shell skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the forkable-shell skill in Claude Code
~/.claude/skills/forkable-shell/SKILL.md
$ npx degit broomva/skills/skills/compute/forkable-shell ~/.claude/skills/forkable-shellInstall the forkable-shell skill in Claude Code (project)
.claude/skills/forkable-shell/SKILL.md
$ npx degit broomva/skills/skills/compute/forkable-shell .claude/skills/forkable-shellInstall the forkable-shell skill in Codex
~/.agents/skills/forkable-shell/SKILL.md
$ npx degit broomva/skills/skills/compute/forkable-shell ~/.agents/skills/forkable-shellInstall the forkable-shell skill in Gemini CLI
~/.gemini/skills/forkable-shell/SKILL.md
$ npx degit broomva/skills/skills/compute/forkable-shell ~/.gemini/skills/forkable-shellInstall the forkable-shell skill in Claude.ai
npx degit broomva/skills/skills/compute/forkable-shell forkable-shell && zip -r forkable-shell.zip forkable-shell # claude.ai → Customize → Skills → + → Create skill → Upload a skill → forkable-shell.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablebroomva/skills/skills/compute/forkable-shell is public and reachablegithub.com/broomva/skills/tree/HEAD/skills/compute/forkable- ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-11github.com/broomva/skills/commits ↗Pass
- No download-and-run or credential theft in scripts5 scripts read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/broomva/skills/blob/HEAD/skills/compute/forkable- ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/broomva/skills/blob/HEAD/skills/compute/forkable- ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 158 linesgithub.com/broomva/skills/blob/HEAD/skills/compute/forkable- ↗Pass
SKILL.md
View on GitHubforkable-shell
A world is one JSON file holding an entire agent workspace: the virtual filesystem plus shell state. Because a world is a single value, forking is a file copy.
Shell continuity is best-effort and self-reporting: state is replayed between calls,
and when a command exits before it can be captured, exec() says so rather than
pretending nothing changed.
world.json ──fork──> A.json (branch A works here)
└─fork──> B.json (branch B works here)
trunk is never opened, so it cannot be mutated
Setup
cd skills/compute/forkable-shell && npm install # just-bash + MCP SDK
Requires Node ≥ 20.18.1. Run it under node, not bun — see Constraints.
CLI (scripts/vbash.mjs)
node scripts/vbash.mjs init <world> [--seed <hostfile>:<guestpath>]...
node scripts/vbash.mjs fork <src> <dst>
node scripts/vbash.mjs exec <world> <command...>
node scripts/vbash.mjs cat <world> <guestpath>
node scripts/vbash.mjs info <world>
node scripts/vbash.mjs mcp-config <world> [--log <path>]
node scripts/vbash.mjs drive <world> <prompt> [--log <p>] [--model m] [--max-turns n]
Giving a Claude Code session a throwaway shell
drive runs one Claude Code turn against the world:
node scripts/vbash.mjs init /tmp/w.json --seed ./data.csv:/work/data.csv
node scripts/vbash.mjs drive /tmp/w.json "Summarise /work/data.csv into /work/out.json"
node scripts/vbash.mjs cat /tmp/w.json /work/out.json
It passes --allowed-tools mcp__vbash__vbash and denies Bash,Read,Write,Edit,Glob, Grep,WebFetch,WebSearch,Task,NotebookEdit. To wire it into a session you drive
yourself, use mcp-config and pass the file to claude --mcp-config.
What that does and does not establish. Those flags are permission allow/deny rules.
What is tested here is narrower: commands sent through the vbash MCP server cannot
reach the host filesystem. This skill does not prove that a launched Claude process
exposes only vbash — inherited settings, other configured MCP servers, and tools not
named in the deny list are outside what these tests cover. Treat drive as a
convenient default, not a proof of confinement.
The fork workflow
inita trunk and seed it with inputs.forkthe trunk once per approach you want to try.driveeach branch with a different prompt (they are independent files, so run them in parallel).- Score each branch by reading artifacts out with
cat. - Promote the winner (
cpit over your working world). The trunk is untouched, so you can re-fork and try again.
Always fork before branching. Opening a world only reads it, but every exec on the
opened world saves back to its file, so a world you run commands in is mutated; fork
never opens the source. tests/unit/world.test.mjs asserts a branch cannot change its trunk's bytes,
turn count, or file list.
Constraints worth knowing before you trust it
Measured. The first five have regression tests in this skill; the Bun, turn-budget and custom-backend notes are findings from the session that produced it, recorded here because they will bite you, and are not covered by these tests:
- Only
/workpersists. A snapshot saves the/workprefix. A write to/tmpor$HOMEsucceeds (rc 0) but lives only in the running server, so it is gone after a restart and absent from any fork. Keep everything that matters in/work. (The one item here that IS pinned by a test:tests/unit/world.test.mjs.) - Shell state does not persist by itself. just-bash resets env, cwd and functions
between
exec()calls; only the filesystem is shared.scripts/persistent-shell.mjsreplays state host-side. - A command that exits early loses its state changes. just-bash implements no
trap, soexit Nor aset -efailure abandons the script before state can be captured: the filesystem keeps the command's writes, but env and cwd stay at their previous values. This cannot be prevented, so it is reported —exec()returnsstateCaptured: false, the CLI warns on stderr, and the MCP tool appends a[warning] shell state (cwd, env) was NOT capturedline to its result. - Functions cannot be recovered from the guest.
declare -freturns a stub with the body elided, so register them host-side viaaddRc(). - Shell state must be restored paired with its filesystem. Loading state onto a fresh filesystem silently drops the cwd back to the default.
- Snapshots are prefix-scoped. An unscoped walk captures ~180 synthetic
/bin,/usr/bin,/dev,/procentries — the whole virtual distro instead of the workspace. - Bun is not supported by default. just-bash 3.4.2 throws
DefenseInDepthBox: critical patches failed: Module._resolveFilenameon the firstexec()under Bun.defenseInDepth: falsefixes the core shell but notsqlite3(a separate worker guard). Use Node. - Budget turns generously when driving. A
--max-turnscap that is too low produces an empty result that looks like a capability failure. The default here is 60. - A custom filesystem backend boots empty. just-bash seeds
/bin,/tmp,/dev,/proconly for filesystems exposing synchronousmkdirSync/writeFileSync.
Not a security boundary against humans
just-bash runs without VM isolation and is beta. Containment is verified against the
tool (tests/integration/containment.test.mjs: 8 host probes plus a positive control
proving the probe can detect a leak), and it holds for agent-generated commands. It is
not a bounty-grade jail. For arbitrary binaries or hostile input, use a real VM.
Files
| Path | Role |
|---|---|
scripts/world.mjs |
the world abstraction: open, save, exec, fork, info |
scripts/fs-snapshot.mjs |
filesystem serialize/rehydrate (dirs, symlinks, hardlink groups, modes, mtimes) |
scripts/persistent-shell.mjs |
replays env/cwd/functions across exec() calls |
scripts/vbash-server.mjs |
MCP stdio server exposing the vbash tool |
scripts/vbash.mjs |
CLI |
Tests
npm test # node --test tests/unit/*.test.mjs tests/integration/*.test.mjs
Unit tests cover snapshot fidelity (binary, UTF-8, empty dirs, symlinks, hardlink groups, file modes and mtimes, odd filenames), shell-state replay, and fork isolation — including forking onto a destination that is a hardlink to the trunk.
Integration tests are two separate suites: mcp.test.mjs drives the MCP server over
real stdio (tool listing, restart persistence, fork divergence, error reporting), and
containment.test.mjs asserts host isolation through that same server.
Symlink modes and mtimes are not restored — symlink() takes neither, and the
snapshot records them for information only. File modes and mtimes are restored.
Files in this skill
8forkable-shell skill questions
How do I install the forkable-shell skill in Claude Code?
Run npx degit broomva/skills/skills/compute/forkable-shell ~/.claude/skills/forkable-shell. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the forkable-shell skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What is a 'world' in forkable-shell?
A world is a single JSON file that holds an entire agent workspace, including the virtual filesystem and shell state.
Can I run real binaries like git or node in this shell?
No, this shell is not intended for running real binaries, long-running daemons, or listening sockets; use a real VM or Vercel Sandbox for those tasks.
How fast can I fork a workspace?
Forking is extremely fast, occurring at approximately 0.24ms per fork because it is essentially a file copy.
Does the shell state persist between commands?
By default, just-bash resets environment, current working directory, and functions between calls; only the filesystem is shared unless using a persistent-shell script.