pi-toolkit/README.md

pi-toolkit

Harness-side bring-up for the pi coding-agent.

What's here:

• pi-env.zsh — loads ~/.config/pi/.env into every shell so pi's Bedrock provider has AWS_PROFILE / AWS_REGION available.
• keybindings.json — mosh/tmux-friendly newline bindings (shift+enter, ctrl+j, alt+j).
• pi-atelier.json — Status Rail defaults for the pi-atelier extension (rail segments, context warning thresholds, sidebar tool names). Inert if that extension isn't installed.
• settings.example.json — template for ~/.pi/agent/settings.json so pi starts without having to pass --provider/--model on every invocation.
• install.sh — idempotent installer wiring these into place.

No dependency on MemPalace. For the palace memory layer see mempalace-toolkit — it installs a pi↔mempalace MCP bridge on top of this toolkit. The two repos compose but don't require each other, same pattern as opencode-toolkit ↔ mempalace.

---

Why this exists

Pi, out of the box on a fresh machine, has three friction points that this toolkit fixes:

1. No model selection without --model. Every invocation needs pi --provider ... --model ... until ~/.pi/agent/settings.json exists with defaults. The shipped settings.example.json is a working eu-west-1 Bedrock template — copy, edit for your region, done.
2. Shift+Enter (newline in the TUI) doesn't work over mosh/tmux. mosh's vt220-ish emulation strips modifier keys upstream of tmux, so pi never sees the Shift bit. The shipped keybindings.json adds ctrl+j and alt+j fallbacks that pass through as plain control/meta bytes.
3. Bedrock provider needs AWS_PROFILE and AWS_REGION in the shell environment at spawn time. The shipped pi-env.zsh sources ~/.config/pi/.env into every shell (set -a; source; set +a), so you can edit credentials in one plaintext-on-disk, encrypted-in-git-repo file.

None of this talks to MemPalace; it's all pi's own configuration surface.

---

Install

git clone ssh://git@gitea.jordbo.se:2222/joakimp/pi-toolkit.git ~/pi-toolkit
cd ~/pi-toolkit
./install.sh

Requires pi to be installed first (~/.pi/agent/ must exist). Install via:

brew install pi-coding-agent              # macOS
# or see https://github.com/earendil-works/pi for Linux
pi --help                                 # first run creates ~/.pi/agent/

What install.sh does:

Step	Action
Symlink keybindings.json	~/.pi/agent/keybindings.json → repo. Safe to symlink: pi doesn't rewrite it.
Install pi-env.zsh	cp into ~/.oh-my-zsh/custom/ if oh-my-zsh detected; otherwise print shell-specific source snippet for ~/.zshrc or ~/.bashrc. Does not auto-edit rc files.
Copy pi-atelier.json	~/.pi/agent/pi-atelier.json, only if absent. NOT symlinked: pi-atelier rewrites this path on menu saves via write-temp-then-rename, and rename(2) replaces a symlink rather than following it — so a link would silently detach. An existing file is left alone with a diff hint.
settings.example.json	Not installed. Installer warns if ~/.pi/agent/settings.json is missing and prints the cp command. NOT symlinked because pi rewrites settings.json at runtime (lastChangelogVersion bumps) and a symlink would dirty the repo.
AWS env probe	If settings.json selects amazon-bedrock, warn if AWS_PROFILE / AWS_REGION not set. Silent otherwise.

Everything is non-destructive: existing real files get backed up with a timestamp before symlinking; shell loader copy refuses to clobber local edits (prints diff hint and moves on). Re-runs are idempotent.

Uninstall

./install.sh --uninstall

Removes the keybindings and AGENTS.md symlinks, plus the shell-loader and pi-atelier.json copies — the copies only if their content still matches the repo, so local edits (including pi-atelier menu saves) survive. Your settings.json is never touched.

---

Deploying pi on a new machine

Full recipe from a clean macOS or Linux box to a working pi install. Follow in order.

0. Prerequisites

• Shell: zsh + oh-my-zsh recommended (the pi-env.zsh loader installs into ~/.oh-my-zsh/custom/). Bash or plain zsh works too — installer prints a manual source snippet.
• git, pi (installed upstream), optional: tmux ≥ 3.2 for CSI-u extended keys on non-mosh paths.
• AWS credentials reachable via AWS_PROFILE (either aws configure sso cache or static keys in ~/.aws/credentials) — only if using amazon-bedrock as pi's provider.

1. Dotfiles (if you keep one)

Your dotfiles repo should ship ~/.config/pi/.env (git-crypt encrypted, containing AWS_PROFILE and AWS_REGION). Provision it first so the loader has something to source:

git clone <your-dotfiles> ~/src/dotfiles
cd ~/src/dotfiles
git-crypt unlock <key>
# Run your dotfiles provisioner (example: myconfigs)
./provision.sh --profile <profile>

If you don't use a dotfiles repo, create the file manually after step 3 (installer will point you at the right path).

2. Install pi

brew install pi-coding-agent              # macOS
# or see https://github.com/earendil-works/pi for Linux
pi --help                                 # creates ~/.pi/agent/

3. Install this toolkit

git clone ssh://git@gitea.jordbo.se:2222/joakimp/pi-toolkit.git ~/pi-toolkit
cd ~/pi-toolkit && ./install.sh

This symlinks keybindings.json, copies pi-env.zsh, and prints the settings.json bootstrap command.

4. Bootstrap pi settings

cp ~/pi-toolkit/settings.example.json ~/.pi/agent/settings.json
$EDITOR ~/.pi/agent/settings.json

Adjust the inference-profile prefix to match your AWS region:

Region	Prefix	Example model ID
eu-west-1	eu.	eu.anthropic.claude-sonnet-5
us-east-1	us.	us.anthropic.claude-sonnet-5
non-Bedrock	(none)	anthropic:claude-sonnet-5

Run pi --list-models to confirm what your credentials can actually invoke.

5. Verify AWS env vars in your shell

If step 1 provisioned ~/.config/pi/.env and step 3 installed pi-env.zsh:

exec zsh
echo "$AWS_PROFILE  $AWS_REGION"   # should print your values

If empty, check that ~/.config/pi/.env decrypted (plain text, not binary) — git-crypt unlock in step 1 is the usual culprit.

6. First run

pi   # should start with the default model, no --model needed

7. (Optional) Add MemPalace memory

If you want pi to have persistent memory across sessions, install mempalace-toolkit:

uv tool install mempalace
git clone ssh://git@gitea.jordbo.se:2222/joakimp/mempalace-toolkit.git ~/mempalace-toolkit
cd ~/mempalace-toolkit && ./install.sh

It detects pi and symlinks a mempalace.ts extension into ~/.pi/agent/extensions/ that wires pi's MCP client to the palace.

Verification checklist

# keybindings symlinked into this repo
ls -la ~/.pi/agent/keybindings.json

# shell loader installed
ls -la ~/.oh-my-zsh/custom/pi-env.zsh

# env vars loaded in a fresh shell
zsh -ic 'echo $AWS_PROFILE $AWS_REGION'

# pi starts with its defaults
pi --version

# Re-run is idempotent
./install.sh --yes   # all rows should say "already linked/installed"

---

Settings template reference

settings.example.json:

{
  "defaultProvider": "amazon-bedrock",
  "defaultModel": "eu.anthropic.claude-opus-5",
  "enabledModels": [
    "eu.anthropic.claude-opus-5",
    "eu.anthropic.claude-sonnet-5",
    "eu.anthropic.claude-opus-4-8",
    "eu.anthropic.claude-haiku-4-5-20251001-v1:0"
  ]
}

• defaultProvider — most common values: amazon-bedrock, anthropic, openai.
• defaultModel — Bedrock IDs have region-specific prefixes (eu., us.). Bare Anthropic uses anthropic:claude-.... Run pi --list-models to see what you can actually call.
• enabledModels — optional; restricts the model picker inside pi to this subset.

pi rewrites settings.json at runtime (lastChangelogVersion bumps on upgrade), so don't symlink this file.

Keybindings reference

keybindings.json:

{
  "tui.input.newLine": ["shift+enter", "ctrl+j", "alt+j"]
}

Over direct kitty / iTerm2 / WezTerm with tmux configured for CSI-u extended keys, Shift+Enter works natively. The ctrl+j / alt+j fallbacks kick in when modifier forwarding is stripped (most commonly: mosh). Pi reads this file once at startup — restart pi after editing.

Environment file reference

~/.config/pi/.env format (plaintext on disk, chmod 600, encrypt in your dotfiles repo):

AWS_PROFILE=YourBedrockProfile
AWS_REGION=eu-west-1

Loaded by pi-env.zsh via set -a; source; set +a — plain KEY=VALUE, no export needed. Add any other pi-scoped env vars here as the surface grows.

---

Related repos

• mempalace-toolkit — MemPalace memory layer. Installs a pi↔mempalace MCP bridge on top of this toolkit. Optional.
• opencode-toolkit — sibling repo for the opencode coding-agent. Same shape (shell loader + install.sh). Independent of this repo.
• opencode-devbox — Docker containers with coding agents preinstalled. Can compose pi-toolkit and mempalace-toolkit as independent layers.
• myconfigs — dotfiles repo where ~/.config/pi/.env is tracked (git-crypt encrypted).

License

MIT — see LICENSE.