dot-pi

dot-pi

A curated Pi package with extensions, skills, prompt shortcuts, and rules.

Install

Install Pi first:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Then install this package:

pi install git:github.com/dannote/dot-pi

For the recommended end-user setup, run the bootstrap script. Safer review-first flow:

curl -fsSLO https://raw.githubusercontent.com/dannote/dot-pi/master/install.sh
less install.sh
sh install.sh

Convenience one-liner:

curl -fsSL https://raw.githubusercontent.com/dannote/dot-pi/master/install.sh | sh

The bootstrap is a POSIX sh script for macOS, Linux, and WSL. It installs Pi if missing, installs dot-pi with pi install, offers agent-browser, and explains optional companion packages (pi-elixir, pi-subagents, pi-context, and pi-computer-use on macOS) before prompting. pi-elixir defaults to yes when Elixir or Mix is detected; other companions default to no.

Headless/non-interactive Linux needs Node.js 22.19.0+ and npm available before Pi can install. Check with node --version and npm --version; install Node 22+ with your preferred Node manager or distro setup if needed.

Use non-interactive defaults with:

curl -fsSL https://raw.githubusercontent.com/dannote/dot-pi/master/install.sh | sh -s -- --yes

Useful bootstrap options:

sh install.sh --help
sh install.sh --local              # install dot-pi into the current project
sh install.sh --with-companions    # install all optional companion packages
sh install.sh --no-agent-browser   # skip agent-browser setup
sh install.sh --dry-run            # print commands without running them
DOT_PI_REF=v0.2.1 sh install.sh    # install a specific release/tag

Project-local install for a repo/team:

pi install git:github.com/dannote/dot-pi -l

Start Pi and use pi config to review or change what is enabled:

pi config

Update Pi and installed packages later with:

pi update

If prompt shortcuts such as /ga or /wn do not appear, check that dot-pi is enabled in ~/.pi/agent/settings.json:

{
  "packages": ["git:github.com/dannote/dot-pi"]
}

Global prompt templates are discovered from ~/.pi/agent/prompts/*.md; project prompt templates are discovered from .pi/prompts/*.md after the project is trusted. For a manual checkout instead of pi install, symlink the prompt files:

mkdir -p ~/.pi/agent/prompts
ln -s /path/to/dot-pi/prompts/*.md ~/.pi/agent/prompts/

Useful companion packages, installed separately when you want them:

pi install git:github.com/injaneity/pi-computer-use@v0.2.6  # macOS computer use
pi install npm:pi-elixir                                    # Elixir/BEAM development
pi install npm:pi-subagents                                 # subagent delegation
pi install npm:pi-context                                   # context history tags/checkouts

pi-computer-use is especially useful for visible macOS apps. It adds semantic window/screenshot tools and prefers Accessibility refs over coordinates.

pi-elixir is recommended for Elixir/Phoenix work. It adds a small BEAM-native tool surface (elixir_eval, AST search/replace) so Pi can inspect and change running Mix projects through the Elixir runtime instead of shelling out for everything.

Recommended external Gmail skill/tool setup:

# Google Workspace CLI with generated agent skills
# Repo: https://github.com/googleworkspace/cli
# Note: the repo says it is not an officially supported Google product.
npm install -g @googleworkspace/cli

tmp=$(mktemp -d)
cd "$tmp"
gws generate-skills
mkdir -p ~/.pi/agent/skills
cp -R skills/gws-shared skills/gws-gmail* ~/.pi/agent/skills/

gws generate-skills creates many Workspace skills, not just Gmail. Copy only gws-shared and gws-gmail* if you want email without Drive/Calendar/Admin/etc. noise. This package's confirmation rules ask before Gmail write actions such as send, reply, forward, modify, trash, or delete.

What is enabled by default

The default install focuses on broadly useful, low-surprise tools.

Extensions

Slash command priority can be configured in ~/.pi/agent/settings.json or .pi/settings.json:

{
  "slashCommandPriority": [
    "ga",
    "gaa",
    "all",
    "wn",
    "steps",
    "big",
    "ground",
    "rtfm",
    "minimal",
    "proper",
    "verify",
    "retry",
    "stop",
    "push",
    "release",
    "quote",
    "recap",
    "oracle",
    "nobc",
    "ar"
  ]
}

Project settings append after user settings. The extension only changes autocomplete order; commands still come from normal Pi prompt/extension/skill discovery.

Action confirmations use shell-style argv parsing, not regex matching. Defaults cover recursive file deletion, suspicious world-writable modes, privileged commands, publishing/editing GitHub/GitLab issues, PRs/MRs, comments, reviews, repository/release/secret/variable mutations, mutating gh api calls, Gmail writes via gws gmail, X/Twitter mutations via bird, git pushes/risky git actions, package publishing, releases, and common deploy CLIs. Tune groups or add local rules in ~/.pi/agent/settings.json or .pi/settings.json:

{
  "confirmActionGroups": {
    "filesystem": true,
    "privilege": true,
    "github": true,
    "gitlab": true,
    "git": true,
    "gmail": true,
    "twitter": true,
    "publish": true,
    "deploy": true
  },
  "confirmCommands": [
    { "argv": ["gh", "release", "create"], "label": "Publish GitHub release" },
    { "command": "railway up", "label": "Deploy with Railway" }
  ]
}

Set a group to false to disable those built-in confirmations; custom confirmCommands still append after enabled defaults.

Workflow slash commands

These mirror repeated Pi prompts from real sessions. Keep common prompts short; use explicit prompts when extra intent matters. /steps and /big use prompt-template defaults, so /steps means 7 steps and /steps 10 means 10 steps. /recap, /quote, and /oracle are extension commands.

My usual coding flow:

1. Use /ga for plain “go ahead”.
2. Use /wn for quick orientation, /steps [N] for lists, and /big [N] for coarse work chunks.
3. Use /rtfm, /ground, /proper, or /minimal when extra intent matters.
4. Use /gaa or /all only for already agreed pending items.
5. Use /retry for tighter recovery.
6. Use /stop when the trajectory is wrong.
7. Use /push once work is coherent; use /release only for release prep.

Configure /oracle in settings:

{
  "oracle": {
    "model": "anthropic/claude-opus-4-5",
    "thinking": "high",
    "precompact": {
      "enabled": true,
      "mode": "pi",
      "keepRecentTokens": 4000,
      "minTokens": 1000,
      "reserveTokens": 12000
    },
    "context": {
      "maxTokens": 12000,
      "summary": "latest",
      "keepTailTokens": 3000,
      "keepUserTurns": 3,
      "keepAssistantTurns": 2,
      "drop": {
        "thinking": true,
        "toolResults": "all",
        "toolCalls": "names-only",
        "bashOutput": "truncate",
        "images": true,
        "customMessages": true
      }
    },
    "tools": "none",
    "confirm": true,
    "defaultIntent": "review",
    "pricing": { "inputPerMillion": 10, "outputPerMillion": 50 },
    "budget": { "targetOutputTokens": 1500, "maxTotalUsd": 1 }
  }
}

Run /oracle without args for the native intent picker and cost/context confirmation. Run /oracle <question> to skip the intent picker but still preview before sending. precompact.mode can be "pi", "custom", or "off". Custom mode uses precompact.model when set and precompact.thinking; the final one-turn context is still reduced by the context policy without deleting session history.

Skills

Optional resources

These are included in the repo but not enabled by default because they are experimental, personal, platform-specific, or require extra credentials.

Enable them by replacing the package entry in ~/.pi/agent/settings.json with an object-form package filter. Use +path to opt into resources outside the default manifest.

Optional extensions

coach.ts is the optional extension I recommend to newcomers: it explains the setup, habits, and first workflows. tutor.ts gives an in-place Dan-style workflow hint when the user is stuck or drifting. Try one from a local checkout with:

pi -e /path/to/dot-pi/extensions/coach.ts

voice-input/ uses ELEVENLABS_API_KEY and rec from sox. Optional environment variables: ELEVENLABS_LANGUAGE, ELEVENLABS_KEYTERMS (comma/newline-separated), ELEVENLABS_COMMIT_STRATEGY (manual or vad), ELEVENLABS_VAD_SILENCE_THRESHOLD_SECS, ELEVENLABS_VAD_THRESHOLD, ELEVENLABS_MIN_SPEECH_DURATION_MS, and ELEVENLABS_MIN_SILENCE_DURATION_MS.

Optional skills

Regular optional skills live under skills/. Extra/meta skills live under skills/extra/ so they do not look like core setup features.

Extra skills

Example package filter enabling only voice input, AppleScript, and the extra Mario etiquette skill:

{
  "packages": [
    {
      "source": "git:github.com/dannote/dot-pi",
      "extensions": ["+extensions/voice-input"],
      "skills": [
        "+skills/applescript",
        "+skills/session-reflect",
        "+skills/extra/dont-anger-mario"
      ],
      "prompts": ["prompts"]
    }
  ]
}

Rules

Rules are intentionally not enabled through the package. They are personal preference files. Symlink the ones you want into ~/.pi/agent/rules/:

mkdir -p ~/.pi/agent/rules
ln -s /path/to/dot-pi/rules/typescript.md ~/.pi/agent/rules/

Development

npm install
npm run format:check
npm run check
npm test

Manual workflow smoke test: docs/smoke-test.md.

Shared extension helper guide: extensions/shared/README.md.

API-backed extension guide: docs/api-backed-extensions.md.

License

MIT