@ayhanblt/ay-pi

Features

• 🧭 Five modes. Chat, suggest, review, plan and code. Only code can edit files; the others read and answer.
• 🤖 The right model for each prompt. Put your models into three tiers. Quick questions go to your fast model, plans to your strongest one.
• 🛠️ Your own commands. Add /explain, /sec or /fix, each with its own mode, tier and note. Rename or turn off the built-in ones. All from a menu.
• 📌 Pin a mode. Press F2 to stay in review or plan for a while, without typing a command every time.
• 📋 Plan, then code. Plans are kept, refined over as many messages as you like, and implemented when you say so.
• 🧠 Or just type. With the optional Jev classifier, AY-PI reads plain prompts and picks the mode itself.
• 🧩 Plays well with others. Plannotator, goal loops, subagents and review extensions keep working; a routing scope steps aside for other plan extensions.

Works with every provider Pi supports. You choose the models, AY-PI chooses the tier.

Quick start

pi install npm:@ayhanblt/ay-pi

Then, inside Pi (1.4 or newer):

/ay-pi add low       pick a fast, cheap model
/ay-pi add medium    pick your everyday model
/ay-pi add high      pick your strongest model
/ay-pi auto          let AY-PI switch models for you

That's it. Type a command and your prompt:

/chat what does calc.js do?               → CHAT · low,  read-only
/review calc.js                           → REVIEW · medium, read-only
/plan fix add() and add a test            → PLAN · high, the plan is kept
/code                                     → CODE · medium, the plan is implemented

💡 Add Jev to skip the commands and just type.

How it works

For every prompt AY-PI picks a mode, the mode picks a tier, and the tier picks a model:

your prompt  ──▶  mode  ──▶  tier  ──▶  model

The mode comes from the first of these that applies:

1. A command you typed: /chat, /review, /plan, ... or one of your own.
2. A pinned mode, set with F2/F3.
3. A plan in progress (see Plans).
4. The classifier, if you added Jev.
5. The safe default: CHAT, medium tier, read-only.

CODE is the only mode that can edit files, and it is reached only on purpose: /code, the pinned CODE mode, an approved plan, or a classifier that is at least 80% sure you want files changed. Read-only modes block Pi's edit, write and bash tools and look around with read, grep, find and ls.

Reading the footer

AY-PI CODE (/fix) · low→medium · auto · your-everyday-model · 📋 plan waiting
      │             │            │      │                     └─ a plan is waiting (or 📝 planning)
      │             │            │      └─ the model that answered (auto mode only)
      │             │            └─ auto or manual mode
      │             └─ the tier; "low→medium" means low was empty or unusable
      └─ the mode, and the command or pin that chose it

Before a prompt, and right after you pin a mode, it reads AY-PI ready · REVIEW (pinned) · auto tier · auto.

Customize

Everything is in one menu:

/ay-pi settings

→ Commands (/chat /suggest /review /plan /code)
  Shortcuts (next mode F2, previous F3)
  Tiers (low 1, medium 1, high 1 models)
  Classifier: auto
  Scope: full
  Done

Your own commands

A command is a mode, an optional tier, and an optional note: a sentence sent along with every prompt you type after it. Some ideas:

In Commands you can:

• add a command (+ New command: name, mode, tier, note);
• rename a built-in one, for example /plan → /design when another extension owns /plan;
• change a built-in one's tier or add a note to it;
• turn off a built-in one you never use.

A note steers the model; it never unlocks tools (that is the mode's job) or picks a model (that is the tier's). Only the built-in code command implements a waiting plan, whatever you call it; /fix and other code commands leave the plan waiting. Pi registers commands when it loads, so the menu offers to reload Pi after a change.

Shortcuts

F2 pins the next mode and F3 the previous one: auto → CHAT → SUGGEST → REVIEW → PLAN → CODE → auto. While a mode is pinned, every prompt runs in it until you switch back; a command still wins for its own prompt. Without the keys: /ay-pi mode review (or chat, suggest, plan, code, auto).

Any key in Pi's syntax works (f4, ctrl+shift+m, ...), and off turns one off. On a Mac laptop press Fn with the F keys. Pi reads no Shift, Ctrl or Alt with F keys, so shift+f2 is refused.

Tiers

Each tier is a list of models; the first usable one answers and the rest are its fallbacks. If a whole tier is empty or unusable, a neighbouring tier answers (high falls back to medium before low). /ay-pi tier high pins a tier for the session; /ay-pi tier auto gives the choice back.

Auto mode (/ay-pi auto) selects the virtual model ay-pi/auto, which switches to the tier's model on each prompt. Tool follow-ups stay on the same model, so the prompt cache stays warm. Manual mode (/ay-pi manual, or any model picked with /model) keeps your model and only tells you when another tier would fit better:

AY-PI suggests the high tier (your-strongest-model) for this PLAN request.

Scope

• full (default): modes, tool scoping, instructions and plans.
• routing: only the tier and the model. Use it next to another plan extension, so that extension runs its own flow. Notes you gave your own commands are still sent.

Let Jev decide

Jev is a small, fast classification model. With it you can just type: a decision costs a fraction of a cent and adds little latency.

1. Run /login, choose TypeSafe and paste your API key (or set TYPESAFE_API_KEY).
2. /ay-pi jev shows the classifier AY-PI found.
3. Type:

Commands and pinned modes still win: they skip the classifier.

For every prompt without a command, AY-PI asks three typed questions:

• task: is this CHAT, SUGGEST, REVIEW, PLAN or CODE?
• file changes: does the user want files changed now?
• complexity: trivial, ordinary or hard? Trivial work moves one tier down, hard work one tier up.

While a plan waits, it also asks whether the message approves it; right after a plan question, whether the message answers it. The plan text itself is never sent.

CODE needs at least 80% on "file changes"; below that the turn runs as SUGGEST. A task answer under 50% is ignored and the safe default is used.

classifier is auto by default: the first available Jev model, else any other classifier Pi offers (OpenRouter, OpenCode, Cloudflare Workers AI, OpenAI, llama.cpp). Pick one with /ay-pi classifier provider/model, or turn it off with /ay-pi classifier off.

Plans

After a PLAN turn, AY-PI keeps the ## Plan section of the answer and asks:

AY-PI: the plan is ready. What next?
→ Implement it now
  Keep planning (talk it through; it is applied when you say so)
  Later (the plan waits)

• Implement it now hands the plan to the code tier, with the file tools on.
• Keep planning (📝 planning): write your changes plainly, over as many messages as you need; each one refines the plan. Say "ok, implement it" when it is final.
• Later (📋 plan waiting): talk about other things; /code implements the plan whenever you are ready.

A command still works in the middle of a plan, so /chat what are the risks? is a cheap side question that leaves the plan alone.

Works with other extensions

AY-PI stays out of other extensions' way:

• Their tools are theirs. Only Pi's own edit, write and bash are ever blocked. In full scope AY-PI adds its ay_pi_submit_plan tool and, when bash is on, Pi's read-only grep, find and ls. It never removes a tool.
• Their turns are theirs. When another extension starts a turn (a goal loop, a review, a subagent result), AY-PI only picks the model for it, on the last tier.
• Plannotator works out of the box. While its plan mode plans, your plan tier answers; once you approve in Plannotator's browser view, your code tier executes. The footer shows PLAN (Plannotator).
• Subagents started as separate Pi processes get no commands or tool scoping. If they inherit ay-pi/auto, they run on the main agent's current tier.
• Another /plan? Pi renames both (/plan:1, /plan:2) and AY-PI warns at startup. Rename AY-PI's in /ay-pi settings → Commands.

Reference

Commands

The menu writes ~/.pi/agent/ay-pi.json; you can also edit it by hand:

{
  "tiers": {
    "low": ["provider/fast-model"],
    "medium": ["provider/everyday-model", "other-provider/fallback-model"],
    "high": ["provider/strongest-model"]
  },
  "classifier": "auto",
  "scope": "full",
  "commands": {
    "plan": "design",
    "review": false,
    "explain": { "behavior": "CHAT", "tier": "low", "instructions": "Explain simply, with one short example." }
  },
  "shortcuts": { "nextMode": "f4", "previousMode": false }
}

• tiers: provider/model references, as shown in /model.
• classifier: auto, off, or a provider/model.
• scope: full or routing.
• commands: rename ("plan": "design"), turn off ("review": false), change ("code": { "tier": "high" }) or add ("explain": { ... }). Pi's own command names are refused.
• shortcuts: nextMode and previousMode, a key or false.
• A trusted project can override keys in .pi/ay-pi.json, except commands and shortcuts, so a repository cannot slip a note into your /code.

Changes to commands and shortcuts need /reload. If the file is broken, AY-PI says why at startup and runs on defaults until you fix it.

Troubleshooting

Development

npm install
npm run typecheck
npm test
npm run build        # bundles src/ into extension/ay-pi/dist

The published package lives in extension/ay-pi. See docs/architecture.md for the code layout.

License

MIT