Metadata-Version: 2.4
Name: slot-cli
Version: 0.3.4
Summary: Isolated Docker sandboxes for Claude Code, with a hook-based plugin system
Project-URL: Homepage, https://github.com/snehangsude/slot
Project-URL: Issues, https://github.com/snehangsude/slot/issues
Author: Snehangsu
License: MIT
License-File: LICENSE
Keywords: agents,ai-coding,claude-code,docker,sandbox
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Software Distribution
Requires-Python: >=3.11
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# slot

Parallel, isolated working environments for AI agents.

```bash
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`):

```bash
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):

```bash
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](docs/01-getting-started/installation.md).

## New here?

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

## Documentation

Full docs are in [`docs/`](docs/README.md). Quick links:

- [What is slot?](docs/01-getting-started/what-is-slot.md) — 2-minute
  mental model
- [Your first slot](docs/01-getting-started/first-slot.md) — end-to-end
  walkthrough
- [Concepts](docs/01-getting-started/concepts.md) — glossary
- [Default mode](docs/02-using-slot/default-mode.md) /
  [Safe mode](docs/02-using-slot/safe-mode.md) — the two workflows
- [Secrets](docs/02-using-slot/secrets.md) — the `.agents` redacted-marker rule
- [Hooks](docs/02-using-slot/hooks.md) — extending slot
- [Integrations](docs/02-using-slot/integrations/README.md) — wiring
  host services into sandboxes ([Plyn walkthrough](docs/02-using-slot/integrations/plyn.md))
- [Commands reference](docs/03-reference/commands.md)
- [Why this shape](docs/04-design/why-this-shape.md) — design choices
- [Threat model](docs/06-security/threat-model.md)

## 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](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`](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`](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`](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](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](docs/04-design/what-we-said-no-to.md) for things
that aren't planned.

## License

[MIT](LICENSE)
