Getting Started

Set up Phantasm without building from source

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.

Explore a bootstrapped runtime

phantasm explorer

The Explorer is a read-only terminal UI for runtime health, records, review items, and live conflict groups. Run it from the bootstrapped project root. Use 1/2/3 to switch tabs, j/k to move, /query to search, c to clear, r to reload, and q to quit.

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 --target hermes
phantasm agents-plugin --target hermes --hermes-home /srv/hermes
phantasm agents-plugin --path ~/.codex/plugins

Use agents-plugin when you only want to install or refresh the bundled plugin. Agents can follow the complete Phantasm installation guide.

Use Phantasm as Hermes Agent memory

phantasm agents-plugin --target hermes
hermes memory setup

Select phantasm in the Hermes memory picker. The provider configuration hook writes $HERMES_HOME/phantasm.json and runs phantasm bootstrap "$HERMES_HOME", creating isolated state for the active profile under $HERMES_HOME/.phantasm/; Hermes built-in MEMORY.md and USER.md stay active. Direct YAML provider selection does not invoke this hook.

phantasm agents-plugin --target hermes --hermes-home /srv/hermes
HERMES_HOME=/srv/hermes hermes memory setup

# Or let the installer read the same environment override:
HERMES_HOME=/srv/hermes phantasm agents-plugin --target hermes
HERMES_HOME=/srv/hermes hermes memory setup

The Hermes installer writes only the provider bundle beneath <hermes-home>/plugins/memory/phantasm/ and the compatibility symlink <hermes-home>/plugins/phantasm → memory/phantasm. It never adds guidance or edits AGENTS.md, CLAUDE.md, or project files.

If setup was skipped, failed, or did not create $HERMES_HOME/.phantasm/state/store.sqlite, run phantasm bootstrap "$HERMES_HOME" for that profile home before starting Hermes. Do not run bare phantasm bootstrap from an unrelated directory expecting it to initialize Hermes.

Hermes receives up to 8,000 characters of recalled context. Context compression remains independent: configure a custom context.engine normally, because Phantasm contributes no compression prompt and never changes compressor input or output. Use hermes memory status to confirm the active provider.

Set up and verify a Hermes profile

The default Hermes profile uses ~/.hermes. Named profiles are separate homes at ~/.hermes/profiles/<name>/, so install the provider and run memory setup for every profile.

hermes profile create researcher --clone
phantasm agents-plugin --target hermes \
  --hermes-home ~/.hermes/profiles/researcher
hermes -p researcher memory setup
hermes -p researcher memory status

For a fully custom root, set the same HERMES_HOME for the installer and Hermes: HERMES_HOME=/srv/hermes-research phantasm agents-plugin --target hermes, then run HERMES_HOME=/srv/hermes-research hermes memory setup.

To prove Hermes used Phantasm, run hermes -p researcher chat and ask: “Use phantasm_remember to store ‘Hermes researcher profile verification: phantasm memory is bound.’ with subject key verification.hermes.researcher; then call phantasm_recall for ‘Hermes researcher profile verification’ and show the recalled text and record ID.” Both tool results plus hermes -p researcher memory status showing phantasm confirm the binding.

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.

v0.2.6 adds the bundled Hermes Agent memory provider, with bounded recall and compression-neutral lifecycle integration. The v0.2.5 automatic repair for older v1 stores missing quality metadata columns remains available. The current CLI surface also includes the read-only terminal Explorer, local dashboard, init, and agent plugin installer, while the runtime discovery surface includes 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.