Install and verify Pi (@earendil-works/pi-coding-agent, command pi). It is a minimalist terminal coding assistant that runs an AI agent locally, managing credentials, execution history, and parallel collaboration for multiple AI CLIs. It is not Qwen/DeepCode or any other tool of the same name.
Customer-readable description
What this skill can do
| What the customer wants | What the skill will do | What the customer can see |
|---|---|---|
| Install Pi | Verify the project identity, Node.js, and npm, then install the upstream package | Version, source, installation, and configuration directories |
| Check or update | Compare versions from official npm metadata; after explicit authorization, update along pi update --self Update |
Updatable status or "updated" |
| Configure model/provider | Check ~/.pi/agent/settings.json 's provider/model settings, protect credentials |
Configuration location and next steps for local secure configuration |
| Command unavailable | Check PATH, the npm global directory, and commands of the same name | Blocking causes and fixes |
How the customer uses it
- The customer says "install Pi"; the Agent first confirms the target is
@earendil-works/pi-coding-agent, and the customer does not need to operate a terminal. - The Agent performs read-only checks of
pi, Node.js, npm, the actual package source, and the version, then presents the plan. - An installation request only authorizes installing a missing CLI; existing versions are not updated by default. An ambiguous "update" only shows the version; only an explicit "update to the latest" executes it.
- When running requires model credentials, the customer creates or manages the key themselves on the corresponding Provider platform (such as DeepSeek); the key must not be sent into the chat. The Agent only guides protected local input or uses the customer's existing secure credential injection.
- After completion, verify the version and help command; if credentials are not configured, truthfully write "installed, awaiting local configuration" instead of falsely reporting that it is running normally.
Initial configuration and real verification
~/.pi/agentis only the default data directory (sessions, skills, extensions, git, npm packages); you must check both the directory and~/.pi/agent/settings.json. The existence of the directory does not mean the provider is configured.- On first launch,
piinitializes some local runtime state, but does not generate thesettings.json。 - Pi's model/provider configuration is in
~/.pi/agent/settings.json(such asdefaultProvider、defaultModel、theme),does not contain the key; Provider credentials go through environment variables (such asDEEPSEEK_API_KEY) orpi auth。 - After the customer creates an API key on the Provider platform, configure it in the shell environment (such as
~/.zshrc) orpi auth, and do not send the key to the Agent. - The Agent rechecks
config_status、config_file_status, then performs side-effect-free verification; only if the actual request succeeds is the running status written as "normal".
Dependencies and installation
| Dependency | Type | How to handle if missing |
|---|---|---|
| Node.js and npm | Hard dependency | Call soia-env-node-install to install a compatible stable version; do not force-install with an old Node |
| Network diagnostics | Optional prerequisite | Called when npm or GitHub is unreachable soia-env-network-diagnose |
| Provider credentials (such as DeepSeek API key) | Runtime dependency | Customer local security configuration, not sent to chat or logs |
| Other CLIs such as Qwen/DeepCode | Non-dependency | Same name but not the target of this skill, mixing installations is prohibited |
For identity, package name, and configuration facts, see official-sources.md。
Standard process
- Execute
python3 scripts/inspect_cli.py --json, read-only detection ofpi, version, path, npm source,~/.pi/agentdirectory, and the actual existence status ofsettings.json. - Read the actual
node --versionand npm global package source; if Node.js is below the required version, report the blocker first and do not run the installation package. - Execute
python3 scripts/check_latest.py --json, read the latest version of@earendil-works/pi-coding-agentfrom official npm metadata. - If the command is provided by another package, write "Blocked: same-name command source mismatch" and do not overwrite. If the upstream package is installed and working normally, write "Installed" and do not update by default.
- When not installed, the Agent executes
npm install -g @earendil-works/pi-coding-agent; if the npm global directory requires administrator privileges, first provide a user-level alternative and confirm, do not default tosudo。 - Only when explicitly updating to the latest, execute
pi update --self(ornpm install -g @earendil-works/pi-coding-agent@latest). Record the old version and npm prefix, do not switch to a Git repository development installation. - Verify
--versionand--helpat the same absolute path. When the customer requests installation/configuration and the configuration is missing, the Agent prompts to configure provider credentials; when credentials are already securely configured, perform a side-effect-free verification; otherwise write "Unverified" for the running status. - Recheck the version and directory, use
scripts/render_status.pyto output one line of customer status.
Credential configuration boundaries
~/.pi/agent/settings.jsonOnly stores non-secret configuration (provider/model/theme); the API key is not written to this file.- Prefer environment variables or local secure credential solutions such as
pi auth; if product capabilities force the use of a credential file, explain the risks first, restrict it to the user configuration directory, and set it to be readable only by the current user. - The customer does not provide keys in chat. The Agent does not read key contents, only verifies the result category of "whether it exists/whether it can authenticate".
- In-project
.pi/settings.jsonmay enter Git; any key written to project configuration is always rejected.
Customer status list (mandatory)
The reply must begin with the following ten-column table, outputting only one row Pi:
| Skill | Current status | Current version | Latest version | Running status | Installation method | Installation directory | Configuration file directory | Update time | Processing result |
|---|---|---|---|---|---|---|---|---|---|
| Pi | <Installed/Not installed/Blocked> | <version or not obtained> | <version or not obtained> | <Normal/Abnormal/Unverified> | <npm global installation/not obtained> | <directory or not obtained> | <directory or not obtained> | <Installed/Already latest/Updatable, not executed/Waiting to confirm whether to update to latest/Updated/Waiting for local configuration/Blocked: reason> |
- When the user asks only about Pi, do not add Node.js, npm, or other skill lines; Node.js is compressed in only when blocking
处理结果。 更新时间generated after final verification; directories use~relative paths to avoid usernames.- When already updated,
当前状态still writes “installed”. When the source does not match, do not write “installed” based solely on the command name. - If the latest version cannot be obtained, write “not obtained”; do not guess.
config_status=未创建orconfig_file_status=未创建, the handling result must state “awaiting first-time configuration” and provide the Provider credential configuration entry point; do not report only a default directory.
Intermediate states of installation and update
Generate a random run_idduring actual installation or update, and at each actual stage immediately call scripts/record_install_progress.pyto synchronously display check, plan, awaiting confirmation, install/update, verification, and terminal state. Read-only checks do not create state.
| Stage | Current status | Update time | Handling result |
|---|---|---|---|
| <check/plan/awaiting confirmation/install or update/verification/complete or failed> | <in progress/awaiting/completed/failed/blocked> | <redacted result> |
The update execution and verification stages must carry the customer's explicit latest-version authorization marker. Records save only fixed result codes and times, not npm output body, API key, account, full command text, or private paths.
Permissions and rollback
- Prefer a user-level npm prefix; do not use
sudoby default. Confirm first before modifying PATH/profile, overwriting a same-named command, or system-wide installation. - Before updating, record the old version and package identity; on failure, keep the old installation and do not automatically uninstall, downgrade, or delete configuration.
- Installation must not rewrite the project
package.jsonor lockfile.
Private information and intermediate data
- Keep API keys in a customer-approved local secure location; SOIA configuration, audit state, and receipts do not store secrets.
- Non-secret settings may remain in
~/.pi/agent/settings.json; project configuration stores only committable non-secret settings. - Machine change stage records are written to user-private state; version checks are stateless by default.
- Do not record tokens, keys, accounts, prompts, code content, response bodies, or customer-private absolute paths.
Logs and completion receipt
The final receipt contains the fixed ten-column table, package identity, whether Node.js is satisfied, verification items, and whether the customer still needs to configure credentials on this machine. Normal dependencies are not expanded into extra lines.
Forward testing
Use a temporary fake pi to cover missing, normal, wrong package source, and version anomalies; mock the npm latest version; verify the Node.js gate, ten-column list, path redaction, no update by default, and the explicit authorization gate.
Install the entire domain (Claude Code and Codex share the same domain plugin):
claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-env@soia
Install only this one skill:
npx skills add soia-team/soia-open-env-skills -g -a '*' -s soia-env-pi-cli-install -y
WorkBuddy 's loading unit is a role-based expert rather than a plugin,npx skills add -a '*' cannot cover it and it needs to be installed separately, see docs/install/workbuddy.md。