Why

First, this repo is for my own reference. You are welcome to ride along.

For each new project, I copy stuff from here to the project. I avoid global skills/AGENTS.md/etc, everything is per-project.

AGENTS.md

Combine the agents.md/AGENTS*.md files as you need them. As few or as many as you want.

cd agents.md && cat AGENTS.md AGENTS-svelte.md AGENTS-lovely-docs.md > /path/to/new/project/AGENTS.md

Then edit the new AGENTS.md, and optionally feed the edits back here if they are good.

Pi

Packages to install:

• pi install -l npm:@xl0/pi-lovely-dev-tools — /tool and /show-sysprompt commands.
• pi install -l npm:@xl0/pi-lovely-comment — /comment GUI-editor draft workflow.
• pi install -l npm:@xl0/pi-lovely-rename — automatic and manual session naming.
• pi install -l npm:@xl0/pi-ide-integration — IDE selection/@mention integration.
• pi install -l npm:@xl0/pi-lovely-web — web_search/web_fetch/web_image.
• pi install -l git:git@github.com:xl0/pi-agent-notebook-extension — .ipynb read/edit tools + VSCode/Jupyter execution.

Sandbox with bwrap (Linux only)

scripts/run-pi-sandboxed.sh provides a simple bubblewrap (https://github.com/containers/bubblewrap)

It mounts / read-only, keeps ~/.pi, Claude's config directory, ~/.bun, ~/.npm, ~/.cache, conda/mamba dirs, VS Code user-data dirs, ~/node_modules, and XDG_RUNTIME_DIR writable by default, mounts NVIDIA device nodes when present, and runs pi inside the sandbox. Very easy, reasonably secure. Escape is not impossible, but it protects against lots of oopsies.

Copy it somewhere in your $PATH: cp scripts/run-pi-sandboxed.sh ~/.local/bin/

Usage: scripts/run-pi-sandboxed.sh [--no-ssh] [--no-runtime] [--ro-runtime] [--ro-bun] [--ro-npm] [--ro-cache] [--ro-conda] [--ro-vscode] [--ro-node-modules] [--no-cuda] [--writable PATH ...] [PI_ARG ...]
       scripts/run-pi-sandboxed.sh [--no-ssh] [--no-runtime] [--ro-runtime] [--ro-bun] [--ro-npm] [--ro-cache] [--ro-conda] [--ro-vscode] [--ro-node-modules] [--no-cuda] [--writable PATH ...] [-- COMMAND [ARG ...]]

Runs `pi` in bubblewrap by default.
Use `-- COMMAND ...` to run something other than `pi`.

Bubblewrap setup:
- host / mounted read-only
- current repo mounted read-write
- repo .pi/sandbox/tmp mounted at /tmp
- repo .pi/sandbox/var-tmp mounted at /var/tmp
- network allowed by default
- ~/.pi mounted read-write by default
- CLAUDE_CONFIG_DIR mounted read-write (~/.claude by default)
- ~/.bun mounted read-write by default
- ~/.npm mounted read-write by default
- ~/.cache mounted read-write by default
- conda/mamba dirs mounted read-write by default
- VS Code user-data dirs mounted read-write by default if present
- ~/.config/matplotlib hidden behind an empty writable tmpfs
- ~/node_modules mounted read-write by default if present
- XDG runtime dir mounted read-write by default
- NVIDIA device nodes mounted by default if present, so CUDA/nvidia-smi can work

Options:
  --no-ssh           hide ~/.ssh with an empty tmpfs
  --no-runtime       hide XDG_RUNTIME_DIR (/run/user/<uid>) with an empty tmpfs
                     default: mount XDG_RUNTIME_DIR read-write if present
  --ro-runtime       keep XDG_RUNTIME_DIR read-only
  --ro-bun           keep ~/.bun read-only; default: mount ~/.bun read-write if HOME exists
  --ro-npm           keep ~/.npm read-only; default: mount ~/.npm read-write if HOME exists
  --ro-cache         keep ~/.cache read-only; default: mount ~/.cache read-write if HOME exists
  --ro-conda         keep conda/mamba dirs read-only; default: mount ~/.conda,
                     ~/.mamba, detected roots, and configured env/pkg dirs read-write
  --ro-vscode        keep VS Code user-data dirs read-only; default: mount existing dirs read-write
  --ro-node-modules  keep ~/node_modules read-only; default: mount read-write if present
  --no-cuda          do not mount NVIDIA device nodes into the sandbox
  --writable PATH    extra host path to mount read-write
  --help             show this help

Examples:
  scripts/run-pi-sandboxed.sh
  scripts/run-pi-sandboxed.sh --no-ssh
  scripts/run-pi-sandboxed.sh --model gpt-5
  scripts/run-pi-sandboxed.sh "prompt here"
  scripts/run-pi-sandboxed.sh --no-runtime -- pi
  scripts/run-pi-sandboxed.sh --ro-runtime
  scripts/run-pi-sandboxed.sh --ro-bun
  scripts/run-pi-sandboxed.sh --ro-npm
  scripts/run-pi-sandboxed.sh --ro-cache
  scripts/run-pi-sandboxed.sh --ro-conda
  scripts/run-pi-sandboxed.sh --ro-vscode
  scripts/run-pi-sandboxed.sh --ro-node-modules
  scripts/run-pi-sandboxed.sh --no-cuda
  scripts/run-pi-sandboxed.sh -- bash -lc 'uname -a'

Claude Code

scripts/run-claude-sandboxed.sh is the Claude Code equivalent of the Pi sandbox helper. It runs claude by default, stores sandbox temporary files under the repository's .claude/sandbox/ directory, and keeps CLAUDE_CONFIG_DIR writable (~/.claude by default). Claude is run with that variable set explicitly so its state file, lock, and atomic-update temporary files all live in the writable directory. The legacy ~/.claude.json is imported on first run, and ~/.pi is also mounted read-write. The script supports the same sandbox options and -- COMMAND ... escape hatch as run-pi-sandboxed.sh. For implicit Claude invocations, it enables --dangerously-skip-permissions because filesystem access is constrained by bubblewrap.

Copy it somewhere in your $PATH:

cp scripts/run-claude-sandboxed.sh ~/.local/bin/

Run scripts/run-claude-sandboxed.sh --help for full usage.