Documentation menu
On this page

5-minute quickstart

This is the shortest path from a new machine to a supervised coding run.

1. Install and onboard

pipx install skep && skep onboard

You need Python 3.12 or newer and Git. skep onboard is the guided first run: it connects a model, registers a work directory (default ~/workspace) as a project, records the sandbox backend, locks a policy baseline after you type yes, records a role, then starts skep serve and opens skep chat. A fresh home asks before every governed action until that baseline is approved. See onboarding.md for each step and its flags, and run skep onboard --check at any time to see where the setup stands.

On Debian/Ubuntu the system Python refuses bare pip install (PEP 668) — pipx is the way around it, and the PATH step is part of the install, not an optional extra:

sudo apt install pipx   # Debian/Ubuntu (Fedora: sudo dnf install pipx)
pipx ensurepath         # puts ~/.local/bin on your PATH for future sessions
source ~/.bashrc        # reload so the PATH change takes effect now
pipx install skep
skep --version          # verify it resolves

uv tool install skep works the same way. To upgrade: pipx upgrade skep (or uv tool upgrade skep), then restart skep serve.

The Linux sandbox backend needs bubblewrap; macOS ships Seatbelt:

# Fedora
sudo dnf install bubblewrap

# Ubuntu/Debian
sudo apt install bubblewrap

2. Run a task

skep run ~/workspace "add a README section for local setup" --execution-mode sandbox

Skep creates an isolated worktree, spawns the worker, streams progress, records events, captures the patch, and re-verifies the claimed result.

--execution-mode sandbox runs the worker behind the OS sandbox, and the run does not start when no backend can be applied. --execution-mode workspace has no OS sandbox: the worker still runs in a disposable worktree, through skep's capability layer, with re-verification and approval, and only skep's own worker can run that way.

The default worker is skep's own coding worker. It plans with the model the assistant is configured with (onboard step ①) and runs each step through the capability layer. With no model configured it falls back to a fixed routine that handles only a Python hello-world task, and any other run fails.

If a worker needs a gated shell command, skep can prompt inline:

approval needed: shell.run
  reason:       shell.run requires approval for command: python scripts/check.py
  [a] approve once  [b] approve + remember  [d] deny  [s] skip

Choose b when the command is normal for this kind of task. It saves the command as a grant at once (remembered: <command> → <tier>); [b] is offered only when the command can be remembered. If the resumed run then finishes successfully, Skep also saves or updates a learned template for this repo, and the next similar run can auto-match it and pre-grant the remembered permissions. skep policy grants lists what was saved; skep policy revoke removes one.

If you skip the inline prompt, use skep review <task_id> --allow-command to approve a pending shell command later.

3. Review and approve

skep status --personal
skep review <task_id>
skep review <task_id> --approve

Approval applies the patch on a branch:

skep/<task_id>

A worker can never push, and your default branch does not move. Review, merge, or discard the branch using your normal Git workflow. --pr on the approval pushes that branch and opens a pull request.

Re-verification uses the project's pinned verify command. Project setup infers one from the repository's own entry point; when it finds none, re-verification falls back to the command the worker chose and the record says so. Pin one:

skep project setup ~/workspace --verify-command "uv run pytest"

4. Pick another engine

To run Claude Code through skep, pin it as the project's engine (codex, aider and pi work the same way). An external agent's commands skip skep's capability layer, so the sandbox is its only wall: it always runs in sandbox mode, and the project must pin the command that proves its work:

skep project setup ~/workspace \
  --engine claude_code \
  --verify-command "uv run pytest"
# the sandbox masks the keychain: authenticate from the env instead
export CLAUDE_CODE_OAUTH_TOKEN=paste-it-here  # printed by: claude setup-token
skep run ~/workspace "fix the failing test" --execution-mode sandbox

The work directory from onboarding is already a project. A repository skep has not seen yet needs a strategy the first time; without one setup is refused with project setup requires a pack or strategy:

skep project setup /path/to/repo --strategy trusted_local_dev \
  --engine claude_code --verify-command "uv run pytest"

Codex authenticates from OPENAI_API_KEY, or from your ChatGPT plan login for a project that opted in with --codex-chatgpt-login (see codex-chatgpt-login.md). Without its auth variable an external engine's run is refused with NO AUTH ENV; skep doctor shows each engine's state.

The adapter expects claude on PATH. If needed:

SKEP_CLAUDE_CODE_CMD="/path/to/claude" \
skep run \
  --execution-mode sandbox \
  --env-allow SKEP_CLAUDE_CODE_CMD \
  ~/workspace \
  "add input validation"

A one-off run can pick the engine with --engine claude_code instead. A --worker-cmd or SKEP_WORKER_CMD that runs an external agent's module (python -m skep.workers.claude_code) is that engine: it runs in the sandbox whatever --execution-mode says, and needs the same auth env and pinned verify_command.

Serve UI

skep onboard starts the daemon for you. To start it yourself:

skep serve

Copy the printed access token, open http://127.0.0.1:8765, and use Settings to configure the assistant connection for the default coding worker.

From a source checkout

What contributors use. You also need uv:

curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/Anmolnoor/skep.git
cd skep
uv sync --frozen

Every command above then runs as uv run skep …:

uv run skep onboard
uv run skep run /path/to/your-repo "fix the failing test" --execution-mode sandbox
uv run skep review <task_id> --approve
uv run skep serve --host 127.0.0.1 --port 8765