pi-cli-workspace
Pi terminal agent workspace — install, /commands, sessions, compaction, settings.json, AGENTS.md, skill discovery, precedence, session JSONL, /tree, providers/auth, models.json, credential resolution, platform setup, editor (@file, Tab, images, !bash), message queue (steering, follow-up), built-in tools (read/bash/edit/write/grep/find/ls, --tools, --no-tools), print mode (-p, piped stdin), SYSTEM.md/APPEND_SYSTEM.md, CLI flags (-c, -r, --session, --fork, --no-session), @files args, resource flags (--no-extensions, --no-skills), model shorthand (provider/id, name:thinking), all slash commands, env vars, philosophy (no MCP/sub-agents/plan-mode by design). Use for pi config, skills, sessions, compaction, providers, models, tmux, Termux, Windows, tools, modes, system prompt, message queue, or "does pi support X".
How do I install this agent skill?
npx skills add https://github.com/romiluz13/pi-agent-skills --skill pi-cli-workspaceIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a knowledge base for the Pi terminal agent workspace, grounding its instructions in the pi-mono repository. No malicious code, obfuscation, or unauthorized data access attempts were detected. A low-severity risk of indirect prompt injection is present because the skill is designed to ingest and interpret external documentation and source files from a remote repository while having access to powerful system tools.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
Pi CLI and workspace
Answer only from pi-mono/ sources listed below. If something is not in the tree, say you cannot confirm from the corpus.
Grounding (read in order)
pi-mono/packages/coding-agent/README.md— product surface, commands, customization.pi-mono/packages/coding-agent/docs/skills.md— skill locations,/skill:name, frontmatter, collisions.pi-mono/packages/coding-agent/docs/settings.md— settings locations and keys.pi-mono/AGENTS.md— maintainer rules when editing pi-mono itself.pi-mono/packages/coding-agent/docs/compaction.md— auto-compaction triggers, cut-point algorithm,reserveTokens/keepRecentTokenssettings, chained compactions, branch summarization.pi-mono/packages/coding-agent/docs/session.md— JSONL session format,~/.pi/agent/sessions/paths, entry types (message, compaction, branch_summary, custom, label),buildSessionContext()assembly.pi-mono/packages/coding-agent/docs/tree.md—/treevs/fork, branch navigation, summarization options, tree UI keybindings.pi-mono/packages/coding-agent/docs/providers.md— subscription OAuth (/login), API-key providers,auth.json, env-var credential table, cloud providers (Azure, Bedrock, Vertex).pi-mono/packages/coding-agent/docs/models.md—models.jsonfor Ollama/vLLM/LM Studio,compatflags,modelOverrides, provider-level config.pi-mono/packages/coding-agent/docs/custom-provider.md— extension-registered providers viaregisterProvider(), OAuth flows, proxy patterns.pi-mono/packages/coding-agent/docs/terminal-setup.md— Kitty keyboard protocol, Ghostty/iTerm/terminal keybinding caveats.pi-mono/packages/coding-agent/docs/tmux.md— tmuxextended-keys/csi-uso modified keys work inside pi.pi-mono/packages/coding-agent/docs/windows.md— Windows bash discovery order (shellPathsetting, Git Bash, PATH).pi-mono/packages/coding-agent/docs/termux.md— running pi on Android via Termux (install, clipboard, storage).pi-mono/packages/coding-agent/docs/shell-aliases.md— non-interactive bash andshellCommandPrefixto expand aliases from dotfiles.pi-mono/packages/coding-agent/docs/development.md— local development setup,pi-test.sh, fork/rebrand viapiConfig, test commands.- Implementation (for precedence and prompt wiring):
pi-mono/packages/coding-agent/src/core/package-manager.ts—resourcePrecedenceRankcomment block (ordering intent).pi-mono/packages/coding-agent/src/core/resource-loader.ts—reload()skill path merge (cliEnabledSkills,enabledSkills,additionalSkillPaths).pi-mono/packages/coding-agent/src/core/skills.ts—loadSkills,formatSkillsForPrompt, name collision handling.pi-mono/packages/coding-agent/src/core/system-prompt.ts— default harness text andhasReadgate for skills XML.pi-mono/packages/coding-agent/src/core/agent-session.ts—_expandSkillCommandinlines/skill:namebody.
pi-mono/packages/coding-agent/README.md§Editor —@fuzzy-search, Tab completion, Ctrl+V image paste,!/!!bash commands.pi-mono/packages/coding-agent/README.md§Message Queue — steering (Enter) vs follow-up (Alt+Enter),steeringMode/followUpMode/transportsettings.pi-mono/packages/coding-agent/README.md§Modes, §CLI Reference — interactive,-p/--print,--mode json,--mode rpc, piped stdin.pi-mono/packages/coding-agent/README.md§CLI Reference — full flag table,@files,--tools,--no-tools,--no-extensions,--no-skills,--no-prompt-templates,--no-themes, resource control.pi-mono/packages/coding-agent/README.md§Environment Variables —PI_CODING_AGENT_DIR,PI_PACKAGE_DIR,PI_SKIP_VERSION_CHECK,PI_CACHE_RETENTION,VISUAL/EDITOR.pi-mono/packages/coding-agent/README.md§Philosophy — what core intentionally omits (no MCP, no sub-agents, no permission popups, no plan mode, no built-in todos, no background bash); everything buildable via extensions.
Invariants
- Skill name collisions: first registered name wins; later paths emit collision diagnostics (
pi-mono/packages/coding-agent/src/core/skills.ts). Path order is assembled inresource-loader.tsthen fed toloadSkills. - Resource precedence rank (lower = earlier in sorted package-manager lists): project local (0), project auto (1), user local (2), user auto (3), package (4) —
pi-mono/packages/coding-agent/src/core/package-manager.ts. - Merged skill paths:
mergePaths([...cliEnabledSkills, ...enabledSkills], additionalSkillPaths)— CLI paths appear before package-manager lists; seepi-mono/packages/coding-agent/src/core/resource-loader.ts. <available_skills>is appended to the system prompt only when thereadtool is among selected tools —pi-mono/packages/coding-agent/src/core/system-prompt.ts.- Default system prompt already points models at packaged docs paths (
readmePath,docsPath, examples) —pi-mono/packages/coding-agent/src/core/system-prompt.ts. This skill adds workspace and precedence detail, not a duplicate README. - Session format version is v3 (tree-based
id/parentId);buildSessionContextassembles compaction summary + branch summary + messages after the compaction point — seepi-mono/packages/coding-agent/docs/session.md. - Compaction cut-point selection avoids splitting tool results;
firstKeptEntryIdlinks chained compactions — seepi-mono/packages/coding-agent/docs/compaction.md. - Credential resolution order:
--api-keyflag >auth.json> environment variables >models.jsoncustom keys — seepi-mono/packages/coding-agent/docs/providers.md. - SYSTEM.md / APPEND_SYSTEM.md: Replace the default system prompt with
.pi/SYSTEM.md(project) or~/.pi/agent/SYSTEM.md(global). Append without replacing viaAPPEND_SYSTEM.mdat the same locations. Context files and skills are still appended after override —pi-mono/packages/coding-agent/README.md§Context Files. - Message queue: Enter queues a steering message (delivered between tool calls); Alt+Enter queues a follow-up (delivered after the agent finishes all work). Escape aborts; Alt+Up retrieves queued messages. Settings:
steeringModeandfollowUpMode("one-at-a-time"default vs"all");transport("sse","websocket","auto") —pi-mono/packages/coding-agent/README.md§Message Queue,pi-mono/packages/coding-agent/docs/settings.md. - Built-in tools: Default four:
read,bash,edit,write. Additional available:grep,find,ls. Control via--tools <list>(e.g.,--tools read,grep,find,lsfor read-only) and--no-tools(disables all built-in; extension tools still work) —pi-mono/packages/coding-agent/README.md§Tool Options. - Editor features:
@fuzzy-searches project files; Tab completes paths; Ctrl+V pastes images (Alt+V on Windows);!commandruns and sends output to LLM;!!commandruns without sending —pi-mono/packages/coding-agent/README.md§Editor,pi-mono/packages/coding-agent/docs/keybindings.md. - Print mode:
-p/--printfor non-interactive stdout output. Reads piped stdin:cat README.md | pi -p "Summarize". Combine with--mode jsonfor JSON-line output —pi-mono/packages/coding-agent/README.md§Modes. - CLI session flags:
-c/--continue(most recent session),-r/--resume(browse/select),--session <path>(specific file or partial UUID),--fork <path>(fork from CLI),--no-session(ephemeral),--session-dir <dir>(custom storage) —pi-mono/packages/coding-agent/README.md§Session Options. - @files CLI arguments: Prefix files with
@on CLI:pi @screenshot.png "What's in this?",pi @code.ts @test.ts "Review". Included as part of the initial message —pi-mono/packages/coding-agent/README.md§File Arguments. - Resource control flags:
--no-extensions,--no-skills,--no-prompt-templates,--no-themesdisable auto-discovery.-e/--extension,--skill,--prompt-template,--themefor explicit loading. Combine--no-*with explicit flags for exact control (e.g.,--no-extensions -e ./my-ext.ts) —pi-mono/packages/coding-agent/README.md§Resource Options. - Model shorthand:
--model provider/id(e.g.,openai/gpt-4o),--model name:thinking(e.g.,sonnet:high),--models <patterns>for Ctrl+P cycling,--list-models—pi-mono/packages/coding-agent/README.md§Model Options. - Slash commands (full interactive list):
/login,/logout,/model,/scoped-models,/settings,/resume,/new,/name,/session,/tree,/fork,/compact,/copy,/export,/share,/reload,/hotkeys,/changelog,/quit. Extensions register custom commands; skills expose/skill:name; prompt templates expand via/templatename—pi-mono/packages/coding-agent/README.md§Commands. - Environment variables:
PI_CODING_AGENT_DIR(override config dir),PI_PACKAGE_DIR(override package dir),PI_SKIP_VERSION_CHECK,PI_CACHE_RETENTION(longfor extended prompt cache),VISUAL/EDITOR(external editor for Ctrl+G) —pi-mono/packages/coding-agent/README.md§Environment Variables. - Philosophy (what pi intentionally omits): No MCP (use CLI tools or extensions), no sub-agents (use tmux or extensions), no permission popups (use container or extension), no plan mode (use files or extension), no built-in to-dos, no background bash (use tmux). Everything is buildable via extensions —
pi-mono/packages/coding-agent/README.md§Philosophy.
Workflows
- Find where a skill is discovered: Walk
docs/skills.mdlocations, then cross-checkpackage-manager.tsauto-discovery andsettings.jsonskillsarrays. - Explain shadowing: Combine
resourcePrecedenceRankordering withmergePaths/loadSkills"first name wins" using file citations only. - User forced load:
/skill:nameexpansion —pi-mono/packages/coding-agent/src/core/agent-session.ts. - Debug compaction: Read
compaction.mdalgorithm; checkreserveTokens/keepRecentTokensinsettings.json; trace chained compactions viafirstKeptEntryId. - Add custom model: Follow
models.mdminimal example for Ollama/vLLM/LM Studio; checkcompatflags for non-standard OpenAI-compatible servers. - Session archaeology: Parse
.jsonlusing the switch example insession.md; navigate branches via/treepertree.md. - Configure providers: Check
providers.mdfor subscription OAuth (/login) vs API-key flow; seeauth.jsonlayout and env-var table. - Platform setup: For tmux, read
tmux.md(extended-keys); for Windows,windows.md(shellPath); for Android,termux.md; for terminal quirks,terminal-setup.md. - Shell aliases: Read
shell-aliases.mdforshellCommandPrefixto make pi's bash tool see dotfile aliases. - Develop pi from source: Read
development.mdfor clone/build/test andpi-test.shrunner. - Control tools: Use
--tools read,grep,find,lsfor read-only mode;--no-toolsto disable all built-in tools (extension tools still work). Default isread,bash,edit,write. - Non-interactive mode:
pi -p "prompt"orcat file | pi -p "Summarize"for CI/scripts. Combine with--mode jsonfor machine-readable JSON-line output. - Custom system prompt: Place
.pi/SYSTEM.mdin a project or~/.pi/agent/SYSTEM.mdglobally to replace the default prompt. UseAPPEND_SYSTEM.mdat the same locations to append without replacing.
Anti-patterns
- Do not invent MCP or sub-agent behavior as "built into core"; check
pi-mono/packages/coding-agent/README.mdphilosophy section for what core omits. - Do not claim exact merge behavior without citing
resource-loader.tsandskills.ts. - Do not describe compaction cut-point behavior from memory; cite
compaction.mdalgorithm section. - Do not guess credential resolution order; cite
providers.mdfor the exact precedence.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/romiluz13/pi-agent-skills/pi-cli-workspace">View pi-cli-workspace on skillZs</a>