slot

Parallel, isolated working environments for AI agents.

slot init                  # set up
slot create 1              # spin up a fresh sandbox
slot start 1               # open Claude Code in it
slot tree add 1 xyz        # work a second branch/PR beside the first (same sandbox)
slot start 1 --tree xyz    # open a session on that branch — its own memory
slot tree pull 1 --reset   # overwrite a branch in place; agent memory is kept
slot diff 1 my-feature     # review what the agent did
slot push 1 my-feature     # send your working branch back — to any branch name
slot teardown 1            # clean up

Each slot is a separate Docker microVM with its own clones of your projects. Agents work inside; your real code stays clean. Two modes: default (fast, for personal projects) and safe (audit log, staging buffer, scrubbed env, redacted-secrets allowlist — for production code).

Install

Published on PyPI as slot-cli (the command stays slot):

uv tool install slot-cli               # installs the `slot` command
uvx --from slot-cli slot --help        # or run it without installing
# or: pipx install slot-cli

From a local checkout instead (e.g. to try unreleased changes):

uv build && uv tool install --force ./dist/slot_cli-*.whl

Requires Python 3.11+, git, and sbx (Docker's sandbox CLI). On Linux, /dev/kvm accessible. See docs/01-getting-started/installation.md.

New here?

Read GUIDE.md — a plain-English, example-first walkthrough of every feature (including running multiple repos in one slot).

Documentation

Full docs are in docs/. Quick links:

• What is slot? — 2-minute mental model
• Your first slot — end-to-end walkthrough
• Concepts — glossary
• Default mode / Safe mode — the two workflows
• Secrets — the .agents redacted-marker rule
• Hooks — extending slot
• Integrations — wiring host services into sandboxes (Plyn walkthrough)
• Commands reference
• Why this shape — design choices
• Threat model

What's new in 0.3.4: flexible push, no-co-author commits, safe config

• Push to any branch from your working branch. slot push N <branch> sends your current work onto <branch> in the real repo even when your slot is on a differently-named branch (creating it if new). --from <ref> names the source explicitly.
• Commits carry no co-author. New slots disable the "Co-Authored-By: Claude" trailer (includeCoAuthoredBy = false in the slot's .claude-store).
• sandbox.toml is backed up before any rewrite (slot init --force) to sandbox.toml.bak, so hand edits are recoverable.

Full list in CHANGELOG.md.

What's new in 0.3.4: visibility — status, insights, memory

Reading straight off each slot's durable .claude-store on the host (no sbx exec):

• slot status [N] — the orchestrator dashboard: per-worktree branch, dirty count, ahead/behind base, sandbox state, session count, token spend, and last activity. What you want when running several agents at once.
• slot insights [N] [--by slot|day] — token spend rolled up per slot or per day; pass --rate-in/--rate-out (USD per 1M) for an estimated cost.
• slot memory show|edit|prune N — inspect, edit, or prune a slot's shared global memory layer — makes "what does this agent know?" visible.

What's new in 0.3.4: worktrees + durable memory

• slot tree — hold multiple branches/PRs in one slot at once, via git worktrees, inside a single long-lived sandbox. No more teardown→create to switch branches.
  • slot tree add N <ref> [--project P] [--name NAME] [--detach]
  • slot tree pull N [tree] [--rebase | --reset] — update a branch in place; --reset hard-overwrites it (discards local git changes) but never touches agent memory
  • slot tree ls N · slot tree rm N <name> [--force]
  • slot start N --tree NAME — open a session inside a worktree
• Durable agent memory. Each slot gets a .claude-store/ on the host-mounted workspace, and the sandbox's CLAUDE_CONFIG_DIR points at it — so session history and memory survive sbx stop/rm/rebuild, the way Plyn's data survives in its host volume.
• Two-tier memory across worktrees. Each worktree gets its own per-tree memory (keyed by folder); all sessions in the slot share one global memory layer for cross-cutting facts.
• Design: docs/worktrees-memory-plan.md.

What's new in 0.3.3

• Renamed TaskFlow to Plyn throughout the docs, integration walkthrough, and starter pack — same app, new name. Existing slot projects need no changes; only the host-side container, volume, and skill names rebrand.
• Integration doc is now docs/02-using-slot/integrations/plyn.md
• Starter pack is now plyn-starter-pack/, with setup.sh accepting env-var overrides so legacy taskflow-data volumes can be migrated in-place — see the pack README

What's new in 0.3.2

• Per-project branch in sandbox.toml — pin slots to a specific branch instead of inheriting whatever was checked out on the host
• Per-project skills = [...] in sandbox.toml — curate which ~/.claude/skills/ entries get copied into slots; omit for the current "copy everything" behaviour
• slot create prints the actual branch checked out for each cloned project — no more guessing
• Wizard input forgiveness — typing Y or N into path prompts is now detected as "yes use default" / "no skip", instead of being taken as a literal one-letter path
• Plyn integration documented — new docs/02-using-slot/integrations/plyn.md walks through the full setup, with a starter pack for one-command install
• 126 tests, up from 90

What's new in 0.3.1

• Unified [[project.secrets]] block replaces the single env = field — supports redacted env files, service account keys, certs, whatever
• Allowlist policy for safe mode: secret host filenames must contain .agents (e.g. .env.agents, .keys/sa-key.agents.json)
• Backwards compatible — old env = "..." configs still work, with a deprecation note
• 90 tests, up from 67
• Docs split into 24 focused files instead of three big ones

See docs/02-using-slot/secrets.md for the secrets story end-to-end.

Status

v0.3.1 — feature-complete for the core loop. See what we said no to for things that aren't planned.

License

MIT