Pi Coding Agent — Cheat Sheet

Der Spickzettel zum Seminar Pi Coding Agent Praxis. Pi bewegt sich schnell — der Stand ist oben vermerkt, Quelle ist pi.dev. Verlässlich bleiben vor allem die Entscheidungen: Welche Regel gehört wohin, welche Rechte gibt man, wann lohnt welche Denkstufe.

Was Pi ist — und was bewusst fehlt

Der kleine Kern ist keine Sparversion, sondern Kontrollgewinn — „Primitives, not features”. Und „fehlt” heißt nicht „geht nicht”: vieles ist nachrüstbar.

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
cd /pfad/zum/projekt
pi                                    # interaktive Session
pi -p "Fasse dieses Repo zusammen"    # ein Durchlauf
pi @README.md "Wie laufen die Checks?"

@datei stellt Dateien als Kontext bereit, !npm run lint ruft die Shell.

Module: Pi verstehen · Installation, Modelle & Konfiguration

Einsatzszenarien und Modi

Je unbeaufsichtigter der Modus, desto enger die Umgebung — und desto wichtiger ein Prüfpunkt, der ohne Zusehen trägt.

Modul: Pi verstehen

Zugangsdaten und Denkstufen

Keys gehören nie ins Projekt-Repository — auch nicht nach .pi/. Ein häufiges Rätsel: Der Key ist gesetzt, aber auth.json gewinnt.

Niedrig starten und gezielt erhöhen, statt sich die höchste Stufe anzugewöhnen.

Welcher Kontext gehört wohin?

Je dauerhafter eine Regel gilt, desto weiter oben gehört sie hin — und Widersprüche zwischen Ebenen werden aufgelöst, nicht gestapelt.

Reserve für die Antwort: compaction.reserveTokens, Standard 16384.

Die rechte Spalte lässt sich prüfen — die linke nicht.

Module: AGENTS.md · Context Engineering · Development Workflow

Rechte und Schutzebenen

Aufsteigend vergeben — nie mit dem vollen Profil beginnen. Das ergibt zugleich die Planphase, für die Pi keinen eigenen Modus braucht:

pi --tools read,grep,find,ls \
   "Plane die Migration auf Vitest in 5 Schritten, je Schritt mit
    Nachweis. Nichts ändern."

Keine Schicht trägt allein — kombinieren.

Modul: Sicherheit & Agentenzugriff

Sessions

Erst Zweck klären, dann Werkzeug wählen. Bei Themenwechsel /new statt Nachschub in eine lange Session.

Modul: Session Management

AGENTS.md, Template, Skill oder Extension?

Ein Template je Zweck statt eines Universal-Reviews — der Ausschluss ist der Baustein, den man am ehesten vergisst.

Mehr als drei Parameter sind ein Zeichen für einen Skill.

Module: Prompt Templates · Skills entwickeln

Extensions

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("session_start", async (_e, ctx) => ctx.ui.notify("geladen", "info"));

  pi.registerTool({
    name: "greet",
    description: "Greet someone by name",
    parameters: Type.Object({ name: Type.String() }),
    async execute(id, params) {
      return { content: [{ type: "text", text: `Hello, ${params.name}!` }],
               details: {} };
    },
  });

  pi.registerCommand("hello", {
    description: "Say hello",
    handler: async (args, ctx) => ctx.ui.notify(`Hello ${args || "world"}!`),
  });

  // Guardrail: riskante Aufrufe abfangen
  pi.on("tool_call", async (event, ctx) => {
    const cmd = event.input.command ?? "";
    if (event.toolName === "bash" && /rm -rf|curl .*\| sh/.test(cmd)) {
      const ok = await ctx.ui.confirm("Riskant?", cmd);
      if (!ok) return { block: true, reason: "blockiert" };
    }
  });
}

Vor dem Installieren fremder Erweiterungen:

Module: Extensions · Packages & Erweiterungen

Typische Fallen

• Verabredungen im Chat treffen, statt sie in AGENTS.md festzuschreiben — und umgekehrt: Onboarding-Doku in AGENTS.md kopieren.
• Regeln, die man nicht prüfen kann („schreibe sauberen Code”).
• Drei Aufträge in einer Nachricht — dann priorisiert der Agent selbst.
• „Baue das Feature” ohne Abnahmekriterium — niemand kann prüfen.
• Die Ausgabe des Agenten als Beleg lesen statt als Behauptung.
• Änderungen übernehmen, ohne Tests oder Diff anzusehen.
• Bei jedem Tool-Aufruf bestätigen lassen — das liest bald niemand mehr.
• defaultProjectTrust: "always" global setzen und fremde Repos öffnen.
• Projektvertrauen vergeben, ohne .pi/ vorher gelesen zu haben.
• Netzzugriff offen lassen, obwohl die Aufgabe ihn nicht braucht.
• Erweiterungen sammeln, ohne sie zu pflegen — jede ist Code mit vollen Rechten.
• Hohe Thinking Levels für mechanische Aufgaben bezahlen.
• Skills „für später” anlegen und nie testen.
• Regeln aus AGENTS.md ins Template kopieren — zwei Wahrheiten.

Zum Seminar Pi Coding Agent Praxis