| name | manage-favorites |
| description | Add, remove, or list commands in the pi-phone-3gs favorites rail. Use when the user asks to add a skill, prompt, slash command, action key, raw input, or anything else to their phone favorites, or to remove or clear favorites. |
Manage pi-phone-3gs Favorites Rail
What is the favorites rail?
The pi-phone-3gs extension shows a horizontally-scrollable strip of tap buttons at the bottom of the screen. Each button can do one of four things when tapped: send a slash command, perform a shell action, send raw terminal bytes, or send an editor-aware key sequence. This strip is populated from a user-owned JSON file. You can add, remove, or reorder entries by editing that file, then reloading the config — no restart required.
Favorites file location
~/.pi/agent/pi-phone-3gs/phone-shell.favorites.json
Confirm the exact path at any time with /phone-shell paths — look for the favorites: line.
File schema
The file is a JSON array of objects. Each object is one rail button with exactly one of command, action, or data:
[
{ "label": "NEW", "command": "/new", "palette": "warning" },
{ "label": "ESC", "action": "sendEscape", "palette": "warning" },
{ "label": "^C", "data": "\u0003", "palette": "warning" },
{ "label": "/", "action": "openSlash" },
{ "label": "↑", "action": "arrowUp" },
{ "label": "↵", "action": "sendEnter" },
{ "label": "CMPT", "command": "/compact", "palette": "warning" },
{ "label": "RLPH", "command": "/skill:ralph-wiggum" },
{ "label": "CI", "command": "/skill:ci-fix-watch" },
{ "label": "LTCH", "command": "/skill:latchkey" }
]
Fields
| Field | Required | Description |
|---|
label | yes | Short text shown on the button. Keep to 6 characters or fewer — longer labels still work but may feel cramped. Uppercase looks best. Unicode arrows/symbols are fine. |
command | one of command/action/data | Full slash command sent when tapped. Must start with /. Any valid Pi command works. |
action | one of command/action/data | A named shell action. See the action reference below. |
data | one of command/action/data | Raw terminal bytes to inject, e.g. "\u0003" for ctrl+c, "\u001b[A" for arrow up. |
kind | no | Only used with data. "input" (default) sends raw bytes; "editorKey" sends bytes through the editor layer with optional clear/setText. |
clearFirst | no | (editorKey only) Clear the editor before sending data. |
setText | no | (editorKey only) Set editor text before sending data. |
palette | no | "accent" (default, teal), "warning" (amber), or "muted" (dim). Use "warning" for destructive or session-changing buttons. |
Action reference
These are the valid action values and what they do:
Keys & input:
| Action | What it does |
|---|
sendEscape | Sends Escape (or aborts if agent is running) |
sendInterrupt | Sends ctrl+c (interrupt) |
sendEnter | Sends Enter/Return |
sendFollowUp | Sends the follow-up key (option+enter) |
openSlash | Clears the editor and types / |
arrowLeft | Sends ← |
arrowUp | Sends ↑ |
arrowDown | Sends ↓ |
arrowRight | Sends → |
Scroll & navigation:
| Action | What it does |
|---|
scrollTop | Scrolls the viewport to the top |
pageUp | Scrolls the viewport up one page |
pageDown | Scrolls the viewport down one page |
scrollBottom | Scrolls the viewport to the bottom |
Toggles & menus:
| Action | What it does |
|---|
toggleUtilities | Opens/closes the utility overlay |
toggleViewMenu | Opens/closes the view menu |
toggleSkillsMenu | Opens/closes the skills menu |
toggleBottomBar | Shows/hides the favorites rail itself |
toggleEditorPosition | Switches editor between top and bottom |
toggleNavPad | Shows/hides the arrow/nav key pad |
toggleViewportJumpButtons | Shows/hides viewport jump buttons |
toggleTopEditorSendButton | Shows/hides the top editor send button |
toggleTopEditorStashButton | Shows/hides the top editor stash button |
Other:
| Action | What it does |
|---|
selectModel | Opens the model selection overlay |
cycleThinkingLevel | Cycles through thinking levels |
stashEditor | Stashes the current editor content |
Common raw data values
For buttons using data instead of action:
| Label | data | What it sends |
|---|
^C | "\u0003" | ctrl+c (interrupt) |
Tab | "\t" | Tab |
BS | "\u007f" | Backspace |
↑ | "\u001b[A" | Arrow up (raw) |
↓ | "\u001b[B" | Arrow down (raw) |
← | "\u001b[D" | Arrow left (raw) |
→ | "\u001b[C" | Arrow right (raw) |
Prefer action over data when an action exists — actions have built-in smart behavior (e.g. sendEscape aborts when agent is running). Use data only when no action covers what you need.
Deriving a short label
When the user doesn't specify a label, derive one:
- Strip the leading
/
- Strip the
skill: prefix if present
- Take the first 4–5 meaningful characters, uppercase
- For keys and arrows, use the natural symbol:
ESC, /, ↑, ↓, ←, →, ↵, ^C
- Avoid generic abbreviations — prefer something recognizable
Examples:
/skill:ralph-wiggum → RLPH or RALPH/skill:ci-fix-watch → CI/skill:latchkey → LTCH/compact → CMPT/new → NEW/resume → RSME/skill:gamenative-discord-research → GN-D or DISC- action
sendEscape → ESC
- action
openSlash → /
- action
sendEnter → ↵
- action
arrowUp → ↑
- action
sendInterrupt → ^C
What commands can be added
Anything that works as a slash command in Pi:
- Built-ins:
/new, /compact, /reload, /resume, /tree
- Model switching:
/model <provider/id> — e.g. /model zai/glm-5.1, /model github-copilot/claude-sonnet-4.6
- Skills:
/skill:<name> — use pi.getCommands() or look at installed packages
- Prompt templates:
/<template-name>
- Extension commands: e.g.
/phone-shell, /touch
Plus any action or raw key as described above.
Interpreting natural language requests
When the user asks to add something to favorites in casual language, map it to the right type:
| User says | Add this |
|---|
| "add escape" / "the escape key" | { "label": "ESC", "action": "sendEscape", "palette": "warning" } |
| "add a slash key" / "the slash button" | { "label": "/", "action": "openSlash" } |
| "add enter" / "return key" | { "label": "↵", "action": "sendEnter" } |
| "add the arrow keys" / "arrow buttons" | Add all four: ↑↓←→ as arrowUp, arrowDown, arrowLeft, arrowRight |
| "add ctrl+c" / "interrupt" | { "label": "^C", "action": "sendInterrupt", "palette": "warning" } or { "label": "^C", "data": "\u0003", "palette": "warning" } |
| "add compact" | { "label": "CMPT", "command": "/compact", "palette": "warning" } |
| "add [any slash command]" | { "label": "<derived>", "command": "/<the-command>" } |
| "add [skill name] skill" | { "label": "<derived>", "command": "/skill:<name>" } |
| "add scroll to top" / "scroll top" | { "label": "TOP", "action": "scrollTop" } |
| "add page down" | { "label": "PG↓", "action": "pageDown" } |
| "add model picker" / "model selector" | { "label": "MODEL", "action": "selectModel" } |
| "add a tab key" | { "label": "TAB", "data": "\t" } |
When in doubt, prefer action over data, and command for anything that's a slash command.
Workflow
Add one or more favorites
- Read the current file (if it doesn't exist, start with
[])
- Append the new entry or entries
- Write the updated array back to the file
- Run
/phone-shell reload-config — the rail updates immediately, no restart needed
- Confirm to the user what was added
Remove a favorite
- Read the current file
- Filter out entries where
label, command, or action matches what the user asked to remove
- Write the updated array back
- Run
/phone-shell reload-config
Reorder favorites
- Read the current file
- Re-sort or move entries as requested
- Write back and reload
Clear all favorites
- Write
[] to the file
- Run
/phone-shell reload-config
List current favorites
- Read the file
- Format as a readable list showing label, type (command/action/data), and value — no reload needed
Getting a favorites template
Run /phone-shell favorites-template to paste a starter template into the editor. The user can edit it directly and save it to the favorites path.
Example exchanges
User: "add the latchkey skill to my favorites"
→ Append { "label": "LTCH", "command": "/skill:latchkey" }, write, reload.
User: "add escape and the arrow keys to favorites"
→ Append 5 entries: ESC (sendEscape, warning), ↑ (arrowUp), ↓ (arrowDown), ← (arrowLeft), → (arrowRight), write, reload.
User: "add compact to favorites with a warning color"
→ Append { "label": "CMPT", "command": "/compact", "palette": "warning" }, write, reload.
User: "remove ralph from my favorites"
→ Filter out entries where command is /skill:ralph-wiggum (or matches "ralph"), write, reload.
User: "what's in my favorites?"
→ Read file, list each entry with its label, type, and value.
User: "clear my favorites"
→ Write [], reload.
