Getting Started with Phantasm

macOS and Linux

brew install indefiniteloop/tap/phantasm
# or
curl -fsSL https://raw.githubusercontent.com/indefiniteloop/phantasm-dist/main/scripts/install.sh | sh
phantasm --version
phm --version

Use Homebrew if it is already part of your workflow. The shell installer remains the fallback path for Unix systems without Brew.

New to Homebrew?

Start by checking whether Homebrew is already installed.

brew --version

If that says brew: command not found, install Homebrew first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then reopen your terminal if prompted, run brew --version again, and install Phantasm with brew install indefiniteloop/tap/phantasm.

Windows

Use the published Windows release asset or run scripts/install.ps1 from the public distribution repo.

Turn it on for a project

cd /path/to/project
phantasm bootstrap
# or
phantasm init

This creates the local .phantasm/ runtime for that project. init is an alias for bootstrap.

Add agent guidance and plugin support

phantasm bootstrap --agent-guidance
phantasm bootstrap --agent-guidance --no-agent-plugin
phantasm agents --add
phantasm agents --add --agent-file AGENTS.md --agent-file CLAUDE.md

bootstrap --agent-guidance adds or refreshes a managed Phantasm instruction block and installs the bundled phantasm-memory plugin into supported local harness plugin directories. Use --no-agent-plugin when you only want the guidance block. After updating Phantasm, rerun phantasm agents --add to replace the managed block in place; you do not need to remove it first. Phantasm asks for confirmation before it writes the file, backs up existing files before changing them, and preserves text outside the managed markers.

phantasm agents-plugin
phantasm agents-plugin --target codex
phantasm agents-plugin --path ~/.codex/plugins

Use agents-plugin when you only want to install or refresh the bundled plugin.

Inspect the generated config files

After bootstrap, review .phantasm/phantasm.toml and .phantasm/clients.toml using the configuration reference. It documents every current key, default, and limitation in the shipped runtime.

Inspect the full command surface

phantasm --help
phm --help
phantasm agents --help
phantasm help bootstrap
phantasm help handle-request

phm is the shorthand alias for the same CLI. The top-level help lists commands. Command-specific help shows the available options for each workflow. Agents and wrappers can also call describe for machine-readable operation schemas and examples.

phantasm handle-request '{"operation":"describe","params":{"target":"all"}}'
phantasm handle-request '{"operation":"describe","params":{"target":"*"}}'
phantasm handle-request '{"operation":"describe","params":{"target":"ingest"}}'
printf '%s' '{"operation":"describe","params":{"target":"ingest"}}' | phantasm handle-request --stdin
phantasm handle-request --file request.json

handle-request input must be valid UTF-8. JSON strings preserve printable Unicode and accept standard \uXXXX escapes.

Every response includes notices. After a binary update, the first successful request from each client profile in a bootstrapped project includes a structured release_update notice; later calls suppress it until the installed version changes again.

After upgrading to v0.2.5, rerun any command that previously failed with no such column: quality_json. Older v1 stores repair missing quality metadata columns automatically. The current CLI surface still includes the local dashboard, init, and the bundled agent plugin installer, while the runtime discovery surface continues to include quality metadata, stale_review, duplicate_review, and Git-reviewable memory_export/memory_import workflows.

Important limitation

The current binary does not yet expose a first-class end-user MCP serve command. Today the public setup flow is bootstrap, and the advanced runtime flow is handle-request.