phi

Phi is a planning-first, agent-native orchestration layer for software work in Claude Code and Codex-style agents. It creates recoverable run artifacts under .phi/runs/<run-id>/, separates planning from implementation, and routes work through validation, audit, fix-loop, and final-summary stages.

Install in a project

From the root of the project where you want to use Phi:

npx @mhdsemps_/phi@latest

This installs or updates:

• AGENTS.phi.md — Codex-facing adapter instructions
• .claude/commands/phi.md — Claude Code /phi command dispatcher
• .phi/config.md — points adapters at the project-local Phi skill
• .phi/.gitignore — keeps run history and installer metadata out of commits
• .phi/skill/ — the Phi orchestration skill, roles, references, and templates

The installer is non-destructive for run history: it never deletes, renames, or rewrites .phi/runs/.

Update an existing project

Run the same command again whenever you want the latest adapter and skill files:

npx @mhdsemps_/phi@latest update

Active projects keep their existing .phi/runs/ history. Managed adapter and skill files are updated in place. If a managed file has local changes, the installer creates a timestamped .bak-... backup before replacing it unless you pass --force.

Check an installation with:

npx @mhdsemps_/phi@latest check

Preview changes without writing files:

npx @mhdsemps_/phi@latest update --dry-run

Usage guide

Claude Code

After installation, run Phi from Claude Code with:

/phi <your request>

Examples:

/phi add password reset with tests
/phi refactor the billing webhook safely
/phi continue

Phi will bootstrap a run under .phi/runs/<run-id>/, write original-request.md and _state.json, then follow the project-local skill at .phi/skill/.

Codex-style agents

Tell the agent to use Phi, for example:

Use phi to plan and implement CSV export for invoices.

The Codex adapter instructions live in AGENTS.phi.md. If your project already has an AGENTS.md, add a short reference to AGENTS.phi.md so the agent knows to load it.

Continue or recover a run

Phi stores durable state in .phi/runs/<run-id>/_state.json.

Use:

/phi continue

or name a run id explicitly:

/phi continue 2026-05-18-141500

The adapter resumes from _state.json; it should not continue from chat history alone.

CLI reference

npx @mhdsemps_/phi@latest [install]
npx @mhdsemps_/phi@latest update
npx @mhdsemps_/phi@latest check

Options:

• --cwd <path> — install/check a different project directory
• --dry-run — show planned changes without writing files
• --force — overwrite changed managed files without backups
• --help — show CLI help
• --version — show package version

What Phi writes during runs

Runtime artifacts are written only under:

.phi/runs/<run-id>/

Common artifacts include:

• original-request.md
• _state.json
• plan.md
• implementation-report.md
• test-gap-report.md
• validation-report.md
• audit-report.md
• fix-loop-01.md, fix-loop-02.md, ...
• final-summary.md
• error.md or pause-summary.md when stopped

Safety notes

• The npm installer does not publish, commit, push, deploy, or mutate remote services.
• The installer preserves .phi/runs/ so active users can update adapters without losing run history.
• Phi run orchestration is agent-native; this package installs instructions and skill files, not a standalone task runner.

License

MIT