tarek.kharsa

home / lessons / pi · tips

Tips5 min read

Pi: 20 power-user tips

Shortcuts, extensions and workflow tricks for the terminal agent harness.

by Tarek Kharsa@tarekkh1997

I studied Pi's source for eight lessons. This page recaps them, then gets practical:

The codebase

Pi

A minimal, extensible agent harness: an interactive coding agent in your terminal, plus print, JSON and RPC modes and a TypeScript SDK. It works with many model providers and is built to be bent to your workflow with extensions, skills, prompt templates and themes. Built in the open at earendil-works, mostly by Mario Zechner (who created libGDX) and Armin Ronacher (who created Flask).

The eight lessons

  1. A small, replaceable core: MCP, code mode and tool search are built-in extensions a third-party extension can replace.
  2. Entry points are cost contracts: a commit check that budgets each package entry's import graph.
  3. A fake model and an empty environment: the faux provider and env -i in test.sh.
  4. Never mutate history: sessions as an append-only JSONL tree.
  5. The lockfile is code: exact pins, three allowed install scripts, a lockfile commit gate.
  6. A tool a model can't misuse: the edit tool's matching rules and per-file queue.
  7. Who owns the scrollback: two renderers, differential rendering, counted full redraws.
  8. Measure your docs: with-docs and without-docs evals.

Reading the repo taught me how it's built. Using it taught me the tricks below. On Windows and WSL a few Alt shortcuts move; /hotkeys shows the ones active in your terminal.

20 power-user tips

Keyboard first

  1. Steer while it works. Type and press Enter to guide the next response once the current one and its tool calls finish. Alt+Enter queues a follow-up for after the whole task. Alt+↑ pulls queued messages back into the editor, and Esc stops.
  2. Write long prompts in your editor. Ctrl+G opens the prompt in $VISUAL or $EDITOR.
  3. Attach files fast. Type @ to search for a file, Tab to complete a path, or paste or drag an image in.
  4. Hide the noise. Ctrl+O expands or collapses tool output; Ctrl+T shows or hides thinking blocks.
  5. Switch brains quickly. Shift+Tab cycles the thinking level, Ctrl+L opens the model picker, and Ctrl+P cycles through the models you picked in /scoped-models.
  6. Run a command yourself. !git status runs it and sends the output to the model. !!git status runs it without sending anything.
  7. Copy the answer. Ctrl+X (or /copy) copies the last assistant message.
  8. Rebind anything. Every shortcut is a named action. Map it in ~/.pi/agent/keybindings.json, use [] to disable one, then /reload. 
    {
  "app.session.new": "ctrl+shift+n",
  "tui.altScreen.pageUp": []
}

Sessions are trees

  1. Go back without losing anything. /tree shows the whole session. Pick an earlier message of yours, edit it and resubmit: that starts a new branch, and the old one stays. When you leave a branch, Pi can summarize it into the one you enter.
  2. Know which copy you want. /fork starts a new session from an earlier message of yours; /clone copies the current branch into a new session.
  3. Label and filter the tree. In /tree, Shift+L labels a node, and Ctrl+U shows only your messages.
  4. Pick up where you left off. pi --continue resumes the latest session in this folder, pi --resume opens the picker, and /name gives a session a name you'll recognize.
  5. Compact with intent. /compact keep the API decisions and open questions tells the summary what to preserve. The original messages stay in the session file.
  6. Leave no trace. pi --no-session runs without saving a session at all.

Automation

  1. Pipe into it. git diff | pi --print "Review this change" prints the answer and exits. Piped input goes in front of your prompt.
  2. Get events, not text. pi --mode json "Inspect this repo" > events.jsonl writes every agent event as JSON lines. --mode rpc lets another program drive it over stdin.
  3. Narrow the tools. pi --tools read,grep,find,ls --print "Review this project" runs with only those tools. --tools +codemode,-write adjusts the defaults instead of replacing them. It narrows what the model is offered, not what the machine allows, so use a sandbox for untrusted work.

Make it yours

  1. Turn prompts into commands. Save ~/.pi/agent/prompts/review.md and it becomes /review. Use $1, $ARGUMENTS or ${1:-correctness} for arguments.
  2. Write skills, not giant prompts. A skill is a folder with a SKILL.md. Only its name and description sit in the prompt; the full instructions load when a task needs them.
  3. Try a package before installing it. pi -e npm:@example/pi-tools loads it for one run; pi install adds it for good. Packages run code, so read the source first.

Bonus: missing sub-agents or a plan mode? The repo has example extensions for both, or you can ask Pi to write the extension you want. That's the whole idea.

What's next

Next up: lessons from T3 Code and OpenCode. New codebases land on X first: follow @tarekkh1997, or subscribe via RSS.