Phantom

Phantom runs all engineering and manages resources.

Phantom is the open-source engineering agent workbench from AshlrAI. An agent installs one command, calls the CLI with --json, or connects the MCP gateway. A person uses the same tools to chat with a signed-in coding agent, or to hand the fleet a result and review the record.

Agents start here. Humans can use the same commands.

Agent index ·
Full agent reference ·
Onboarding ·
User guide ·
GitHub

Quickstart

One install. Node.js 22.15.0 or newer. phm and ashlr are the same program.

node --version
npm install -g @ashlr/phantom
phm --version
phm docs --agent --json

This source tree targets version 3.29.16; check canonical release availability and exact matching assets before installation.
Install the promoted npm latest release, or pin a published version from
GitHub releases.
The source tree is not proof that npm has that version yet.

Open the console when a person wants the app. It listens on 127.0.0.1 only and prints a read token and a mutation token. Neither token is written to disk.

phm verse --no-open --json

The page is http://127.0.0.1:7777/verse/. Paste the read token once. The page asks for the mutation token the first time you change something. Do not paste either token into a PR, issue, or chat log.

New here? phm.dev/connect is the guided onboarding path. The first-run guide covers the same ground in this repository.

Commands that print JSON

Run these after install. They read local state. They do not start a fleet or spend credits.

phm docs --agent --json
phm mcp list --json
phm mcp doctor --json
phm wire status --json
phm authority status --json

phm docs --agent --json is the command list for the binary you installed. Prefer it over a copied example when the two differ. phm mcp doctor exits 1 when a required server is down. That is a health result. phm authority status --json reports the grant. Autonomy ships dormant. A status command does not turn it on.

MCP gateway

The gateway server key is ashlr-hub. The process is ashlr with args mcp. phm wire backs up the editor file, then writes that entry. It is safe to run again.

phm wire claude --json
phm wire cursor --json
phm wire codex --json
phm wire status --json

Claude Code reads ~/.claude.json. Cursor reads ~/.cursor/mcp.json. Paste this under mcpServers if you would rather not run phm wire. Claude's entry also sets type and env. Cursor's entry is the two fields below.

{
  "mcpServers": {
    "ashlr-hub": {
      "command": "ashlr",
      "args": ["mcp"]
    }
  }
}

Codex stores servers in ~/.codex/config.toml. Do not hand-edit that file. phm wire codex runs codex mcp add ashlr-hub -- ashlr mcp after a backup. The codex program must be on PATH.

Restart the editor after the file changes. Registration does not prove the server started. Check with phm wire status --json and phm mcp doctor --json.

The read-only fleet server is a second entry. It does not launch work or merge.

{
  "mcpServers": {
    "phantom-fleet": {
      "command": "phm",
      "args": ["mcp", "fleet"]
    }
  }
}

Details: self-hosting and fleet MCP.

Compiled 3.24.3 browser UI with labeled Demo accounts. No provider ran and no fleet was active. The screenshot shows the browser UI, not the native app window.

Features

	CLI for agents. phm docs --agent --json lists commands. Add --json on commands that offer it.
	One MCP gateway. Claude, Cursor, and Codex use ashlr-hub.
	Your accounts. Claude Code, Codex, Grok, Devin, API credits, and tool-capable local models. Phantom does not ask for or store the vendor credential.
	A record you can review. Chats, diffs, checkpoints, and fleet runs stay in the console. A finished run is not proof the outcome shipped.

Work with me is the chat. Work for me is the fleet. Saving a fleet outcome does not start work and does not widen permission. The fleet runs only in enrolled repositories under a signed grant. Autonomy ships dormant and is macOS-only.

Compare

No scores. This is what the install changes.

A connected account is not permission to spend credits. Check readiness before you delegate. Resource evidence says what each reading means.

How work moves

flowchart LR
  Agent[Agent or engineer] --> CLI[phm --json or MCP ashlr-hub]
  CLI --> Chat[Work with me]
  CLI --> Fleet[Work for me]
  Chat --> Accounts[Signed-in CLIs and local models]
  Fleet --> Grant[Signed macOS grant]
  Grant --> Accounts
  Accounts --> Evidence[Diffs, JSON, and recorded runs]
  Evidence --> Review[Human review or an admitted merge check]

Independent ready tasks can use more than one admitted resource. Slots, quotas, budget reserves, and the signed grant limit how much runs at once. Open Resources in the console to see chat readiness and fleet readiness separately. Unknown stays unknown.

FAQ

Does Phantom store my API keys?
No. Each vendor CLI signs itself in. Phantom does not ask for or store that credential.

What Node version do I need?
22.15.0 or newer. node --version must print that before npm install -g @ashlr/phantom.

What is the difference between phm and ashlr?
They are the same program. phm is the primary name. Scripts that call ashlr keep working. The separate Phantom Secrets command is phantom.

Is autonomy already running?
No. It ships dormant and is macOS-only. It starts after you install the custody helper, sign a Touch ID grant, and start the resident daemon. phm authority status --json reads the state. It does not turn autonomy on.

Does a zero exit code mean the task shipped?
No. Read the JSON. A health command can exit 0 when work is held. A recorded run is not a merge, a release, or proof the outcome was delivered.

Where is the long agent page?
docs/llms.txt is the short index. docs/llms-full.txt is the copy-paste reference.

Star Phantom

If this workbench is useful, star ashlrai/phantom. A star helps the next engineer or agent find it. This page does not print a star count. GitHub has the live number.

The desktop app (macOS)

The desktop app is a native window around the same console. It bundles the CLI, so the app itself does not need a separate Node.js install.

Download the signed arm64 archive and paired update manifest from GitHub releases. Match the archive to the installed CLI version. The app is locally signed, not Apple notarized, so macOS may ask for Open Anyway on first launch. Steps: desktop installation guide.

phm verse

Closing the window hides it. Quit stops the server. Building from source is in Releasing locally.

The CLI

The console also runs from the CLI on macOS, Linux, and Windows. You need Node.js 22.15 or newer and Git.

npm install -g @ashlr/phantom
phm --version
phm verse

phm verse serves http://127.0.0.1:7777/verse/. The package exports @ashlr/phantom, @ashlr/phantom/core, @ashlr/phantom/types, @ashlr/phantom/plugin, and @ashlr/phantom/universe.

Optional cloud handoff, off unless you launch it:

phm cloud launch "<task>" --repo owner/name
phm devin connect
phm devin launch "<task>"

Cloud lanes do not merge by themselves. See Cloud and Devin.

Inspect autonomy without turning it on:

phm authority setup --dry-run --json
phm authority status --json

Commissioning steps: Autonomy setup.

The Phantom ecosystem

Phantom is the workbench. These projects stay useful on their own. The ecosystem page charts a dated GitHub star history for six repositories. The chart adds the six totals. It is not a count of unique people. Each repo has its own install and its own live star count.

The ecosystem map is a planning snapshot, not a claim that every integration is live.

Documentation

Working on this repository

Agents that change this repo follow AGENTS.md. Humans follow CONTRIBUTING.md.

For agents working in this checkout, .mcp.json declares phantom-secrets, locus, lexicon, stack, ashlr. These companion servers are separate from Phantom's aggregation gateway (phm mcp). Registration and discovery do not establish authorization or live readiness. See the agent toolchain.

License

MIT. See LICENSE.