Agent Instructions

Screenshots

When the user provides a screenshot path (e.g., /tmp/pi-clipboard-xxx.png), ALWAYS use the read tool to read the image file. Do NOT assume you can see the screenshot contents without reading it first.

Sigil usage (for agents)

This repo is managed by Sigil, a minimal symlink-based dotfile tool.

Repo layout

~/.dotfiles/
  <package>/
    config.lua
    files/
      ...

Each package has a config.lua that defines its target path per OS.

Common commands

sigil apply — apply symlinks (prompts for stale links)
sigil apply --prune — prune stale links without prompting
sigil add <path> — add a file/dir to the repo and symlink it
sigil status — show stale links
sigil unlink <spec> — restore file(s) to target and remove from repo
sigil remove <spec> — same as unlink, plus remove package/subpath from repo

Spec formats

unlink/remove accept these:

package (entire package)
package:relative/path
repo path: ~/.dotfiles/<pkg>/files/...
target path: e.g. ~/.config/<app>/...

Examples:

sigil unlink wezterm
sigil unlink wezterm:lua
sigil unlink ~/.dotfiles/wezterm/files/wezterm.lua
sigil unlink ~/.config/wezterm/wezterm.lua

Notes

If a repo file is missing, stale links should be pruned.
Prefer sigil add over manual moves into files/.

Editing dotfiles

When editing dotfiles, it is preferred to add/edit the files in this project directly, instead of going to the source. this way we can then use sigil apply --prune, and everything will be synced, even when there are new files.

pi extensions

Extensions live in pi/files/agent/extensions/.

Discovery quirk: If package.json has a pi.extensions field, pi only loads those listed extensions and skips auto-discovery of *.ts files. To enable auto-discovery (load all .ts files including symlinks), either:

Remove the extensions field entirely: "pi": {}
Or delete package.json if you don't need npm dependencies

Multi-file extensions (directories) need an index.ts entry point (or package.json with pi.extensions pointing to the entry file).

2.1 KiB Raw Blame History