Install and start

1. Install pi and Phosphor

You need Node.js 22.19 or newer and a provider account or API key. Install pi in a terminal:

npm install -g @earendil-works/pi-coding-agent

Download Phosphor from the latest release. On macOS, open the DMG and drag Phosphor to Applications. On Linux, use the AppImage or the .deb. On Windows, run the x64 .exe installer.

Or, on macOS or Linux:

curl -fsSL https://github.com/agustinsacco/Phosphor/releases/latest/download/install.sh | sh

The script checks release checksums. It’s still a script piped into your shell, so read it first. Windows builds aren’t signed, so SmartScreen may warn you. Once you’ve confirmed the download came from this repo, choose More info → Run anyway.

Check: launch Phosphor. If the setup screen says pi is missing, make sure pi --version works and that its directory is on the PATH desktop apps see. Restart Phosphor after changing PATH.

2. Sign in to a provider

• ChatGPT Plus/Pro: Settings → Accounts → sign in to the ChatGPT/Codex provider. This uses pi’s built-in OAuth. You don’t need the Codex CLI.
• Claude Pro/Max: install the official Claude Code CLI and the @saccolabs/pi-claude-cli provider, then add one or more logins under Settings → Extensions → Claude Code. Step-by-step guide.
• GitHub Copilot or Kimi For Coding: use the corresponding sign-in in Settings → Accounts. Copilot Enterprise Server uses pi’s terminal login.
• API keys or custom endpoints: set them up in pi. See pi’s docs on provider auth and custom models.

If sign-in from Settings doesn’t finish, run pi in a terminal and use /login. Claude Code logins are separate from pi’s provider credentials. Phosphor doesn’t come with any model usage. Your provider’s billing and plan limits apply.

Signing in to more than one plan pays off: when one runs out, a lane can move to another and keep going. The setup we recommend.

3. Run a first task

1. Open a repo you trust. A throwaway project is a good place to start.
2. Pick a model in the composer. To use your Claude subscription, pick a model under pi-claude-cli, not one of the API-billed Anthropic entries.
3. Leave the new worktree option on to get a separate checkout, or turn it off to work in the main checkout. Git features need a Git repo.
4. Ask for something small you can check, like: “Add a test for an empty input in this parser. Run the relevant tests and show me the diff.”
5. Expand the tool calls to see the commands and their output. Open Changes to review each file. Don’t take “done” at face value: check that the tests actually ran and passed.
6. Want a write-up you can keep? Ask for it as an artifact and it opens as a versioned doc next to the chat. Use Files or Terminal to look at or run things yourself.

Check: you know which branch the session is on, you’ve read the diff, and you’ve seen the test output. For a second task, start a new lane with its own worktree. Don’t point two sessions at the same checkout. Daily work covers what comes next: reviewing, merging, and running several lanes.

Worktree safeguards · Chat and composer reference · Schedule recurring work with routines

4. Go further

Once coding works, add what you need. MCP services connect through pi itself; pi packages add web search, subagents, and computer use. Install only what you’ll use, then start a new session.

Permissions and data

Phosphor runs on your machine, but unless you use a local model, the model doesn’t. Your provider receives every prompt and tool result sent to it. Connected services have their own permissions and data policies.

Tools run with full permissions by default. There are no approval prompts unless you install a permission gate, and no sandbox around the agent. A worktree separates Git checkouts; it doesn’t limit file or network access. Packages run code inside pi’s process. Read a package’s source before installing it, and only connect services you’re comfortable handing to the agent.

HTML artifacts the model writes are isolated from the app and have no network access. That protects you from the page, not from the agent’s tools. How extensions and artifacts work.

If setup stalls

• pi missing: check the PATH desktop apps see, not just your terminal’s.
• No models: check that you’re signed in, and start a new session after changing provider config.
• Claude is unavailable: use the Claude troubleshooting checklist.
• Connector won’t authenticate: check its scopes and run Check again in MCP Connectors.

How updates work for each install type · Report a problem. Include versions and the error. Strip tokens, account IDs, private paths, and anything sensitive from logs and screenshots first.