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/              # common files (all OSes)
    files.linux/        # Linux-specific overrides
    files.macos/        # macOS-specific overrides
    files.windows/      # Windows-specific overrides

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

Per-OS file variants

Create files.<os>/ directories alongside files/ for OS-specific overlays:

pi-agent/
  files/
    settings.json       # shared config
  files.linux/
    agent.json          # Linux-specific
  files.macos/
    agent.json          # macOS-specific

On Linux, agent.json links to files.linux/agent.json. On macOS, it links to files.macos/agent.json. Files in files/ are applied first, then OS-specific variants overlay on top.

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.

IMPORTANT: Update AGENTS.md files when Sigil changes

Whenever Sigil is modified (new features, behavior changes, new commands), you MUST update the AGENTS.md documentation in BOTH locations:

Sigil repo: /home/thomasgl/programming/sigil/AGENTS.md
This dotfiles repo: /home/thomasgl/.dotfiles/AGENTS.md

Keep them in sync so agents have correct instructions regardless of which directory they're working in.

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).

3.2 KiB Raw Blame History