@pixpilot/coding-agent-sandbox weekly downloads statistics

@pixpilot/coding-agent-sandbox

Run AI coding agents — Claude Code, OpenAI Codex, GitHub Copilot CLI — inside Docker, against a dedicated Git worktree, with your centralized skills and prompts already provisioned.

The main checkout is never mounted. Each agent gets its own branch, its own worktree and its own persistent OAuth volume, so the same task can run under several agents at the same time without collisions.

Quick start

Run it with no arguments for the guided setup — it asks what to do, then for the agent, repository, task and permissions:

npx @pixpilot/coding-agent-sandbox@latest

Flags prefill the guided setup and skip their matching questions. Add -y or --yes to skip every prompt; in that non-interactive mode, --task is mandatory:

npx @pixpilot/coding-agent-sandbox@latest --agent claude --task "fix resume generation" --yes

With no --repo, the repository containing the current directory is used. With no --agent, Claude Code is used.

Guided setup

A bare invocation asks, in order:

Question	Default
What would you like to do?	Start a strict, open or no-network session — or prune unused cache volumes
Which coding agent should run this task?	Claude Code
Which model should the agent use?	Only with an initial prompt — the agents.jsonc model, or the agent's own default
How much reasoning effort should it use?	Only with an initial prompt — the model’s efforts from agents.jsonc
Main Git repository path	The repository containing the current directory
Task name	(required)
Let the agent act without approval prompts?	Yes
Enable isolated Git history and commits?	Yes

The guided setup needs a terminal. Without one, use --yes --task and any other options instead.

--prompt or --prompt-file makes the agent start working the moment it opens, leaving no chance to switch models first — so the model and effort questions appear only then, and only for whichever of --model/--effort was left off. With models configured in agents.jsonc they are pickers over those entries; otherwise the model is free text. Either can be left as the agent default.

What a session does

1. Validates the Git repository and resolves the main checkout.
2. Creates (or reuses) the branch ai/<agent>/<task>.
3. Creates (or reuses) the worktree at <repo-parent>/<repo-name>.worktrees/<task>-<agent>.
4. Refuses to start if another sandbox container is already using that worktree.
5. Builds the shared development image once, then reuses it.
6. Mounts the worktree read/write at /workspace and private session Git metadata.
7. Provisions skills, prompts, MCP servers and global rules with the bundled cross-platform synchronizer.
8. Installs project dependencies with @antfu/ni.
9. Launches the agent interactively and hands you the terminal.

On exit the container is removed. Agent commits are safely imported into that worktree's branch; uncommitted changes remain in the worktree. Nothing is merged into your main branch or deleted.

The exit summary includes short Git status and separate staged/unstaged diff statistics. Untracked files appear in status; committed changes are not included in these statistics.

Z:\github\roleclick                                        main checkout (never mounted)
Z:\github\roleclick.worktrees\fix-resume-generation-claude  -> /workspace  (read/write)
Z:\github\roleclick.worktrees\fix-resume-generation-codex   -> /workspace  (a second session)
portable configs directory                                  -> /coding-agent-sandbox/configs (read-only)

CLI options…