Configuration

Configure Phantom with config files, hooks, templates, and environment variables.

Phantom can be configured via YAML config files, environment variables, and command-line flags. This page covers all configuration options.

Config File

The main configuration file is located at ~/.phantom/config.yaml. You can create it with:

phantom init

Default Configuration

# Phantom Configuration
# Generated by: phantom init

# Base directory for all Phantom data
data_dir: ~/.phantom

# Overlay settings
overlays:
  # Directory where overlays are stored
  dir: ~/.phantom/overlays

  # Directory where overlays are mounted
  mount_dir: ~/.phantom/mnt

  # Default timeout for agent runs
  default_timeout: 30m

  # Maximum number of parallel overlays
  max_parallel: 5

# Git settings
git:
  # Auto-commit after agent finishes
  auto_commit: true

  # Default branch prefix
  branch_prefix: phantom/

  # Push on apply
  push_on_apply: false

# Hooks (global)
hooks:
  on_success: []
  on_failure: []
  on_complete: []

# Logging
logging:
  # Log level: debug, info, warn, error
  level: info

  # Log file location
  file: ~/.phantom/phantom.log

# Agent defaults
agents:
  # Default agent command
  default: claude --print

  # Timeout for individual agents
  timeout: 30m

Configuration Locations

Phantom looks for configuration in the following order (later files override earlier):

/etc/phantom/config.yaml - System-wide config
~/.phantom/config.yaml - User config (default)
./.phantom.yaml - Project-specific config
--config flag - Explicitly specified config

Environment Variables

All configuration options can be set via environment variables with the PHANTOM_ prefix:

# Set data directory
export PHANTOM_DATA_DIR=~/.phantom

# Set default timeout
export PHANTOM_OVERLAYS_DEFAULT_TIMEOUT=1h

# Set log level
export PHANTOM_LOGGING_LEVEL=debug

# Disable auto-commit
export PHANTOM_GIT_AUTO_COMMIT=false

Environment Variable Reference

Environment Variable	Config Path	Default
`PHANTOM_DATA_DIR`	`data_dir`	`~/.phantom`
`PHANTOM_OVERLAYS_DIR`	`overlays.dir`	`~/.phantom/overlays`
`PHANTOM_OVERLAYS_MOUNT_DIR`	`overlays.mount_dir`	`~/.phantom/mnt`
`PHANTOM_OVERLAYS_DEFAULT_TIMEOUT`	`overlays.default_timeout`	`30m`
`PHANTOM_OVERLAYS_MAX_PARALLEL`	`overlays.max_parallel`	`5`
`PHANTOM_GIT_AUTO_COMMIT`	`git.auto_commit`	`true`
`PHANTOM_GIT_BRANCH_PREFIX`	`git.branch_prefix`	`phantom/`
`PHANTOM_GIT_PUSH_ON_APPLY`	`git.push_on_apply`	`false`
`PHANTOM_LOGGING_LEVEL`	`logging.level`	`info`
`PHANTOM_LOGGING_FILE`	`logging.file`	`~/.phantom/phantom.log`
`PHANTOM_AGENTS_DEFAULT`	`agents.default`	`claude --print`
`PHANTOM_AGENTS_TIMEOUT`	`agents.timeout`	`30m`

Hooks

Hooks are commands that run at specific points in the overlay lifecycle.

Hook Types

Type	When it runs
`on_success`	After agent completes successfully
`on_failure`	After agent fails
`on_complete`	After agent finishes (success or failure)

Configuring Hooks

In config file:

hooks:
  on_success:
    - command: npm test
      timeout: 5m
    - command: npm run lint
      timeout: 2m
  on_failure:
    - command: 'notify-send "Phantom" "Agent failed"'
  on_complete:
    - command: ./scripts/cleanup.sh

Via CLI:

# Add a hook
phantom hook add my-overlay --type on_success --command "npm test"

# List hooks
phantom hook list my-overlay

# Remove a hook
phantom hook remove my-overlay --index 0

Hook Context

Hooks receive environment variables with context about the overlay:

Variable	Description
`PHANTOM_OVERLAY_NAME`	Name of the overlay
`PHANTOM_OVERLAY_PATH`	Path to overlay mount point
`PHANTOM_BASE_PATH`	Path to base directory
`PHANTOM_AGENT_COMMAND`	The agent command that ran
`PHANTOM_AGENT_EXIT_CODE`	Exit code of the agent
`PHANTOM_TASK`	Task description

Hook Examples

Run tests on success:

hooks:
  on_success:
    - command: npm test
      timeout: 10m

Notify on failure:

hooks:
  on_failure:
    - command: 'curl -X POST $SLACK_WEBHOOK -d "{\"text\": \"Phantom task failed: $PHANTOM_OVERLAY_NAME\"}"'

Cleanup temp files:

hooks:
  on_complete:
    - command: rm -rf /tmp/phantom-*

Templates

Templates are reusable configurations for common workflows.

Creating Templates

# Generate an agents template
phantom template agents > agents.yaml

# Generate a chain template
phantom template chain > chain.yaml

# Generate a hooks template
phantom template hooks > hooks.yaml

Agents Template

# agents.yaml - Configuration for parallel agents
agents:
  - name: feature
    command: claude --print
    task: "Implement the feature"
    timeout: 30m
    hooks:
      on_success:
        - npm test

  - name: tests
    command: aider
    task: "Add tests for the feature"
    timeout: 20m

  - name: docs
    command: gemini
    task: "Update documentation"
    timeout: 15m

Chain Template

# chain.yaml - Configuration for sequential chain
steps:
  - name: implement
    command: claude --print
    task: "Implement the feature"

  - name: test
    command: aider
    task: "Add comprehensive tests"

  - name: review
    command: claude --print
    task: "Review code for issues and improvements"

Project Configuration

Create a .phantom.yaml file in your project root for project-specific settings:

# .phantom.yaml - Project-specific Phantom configuration

# Project-specific hooks
hooks:
  on_success:
    - command: npm run test:unit
    - command: npm run lint

# Default agents for this project
agents:
  default: claude --print --model claude-3-opus

# Project-specific timeouts
overlays:
  default_timeout: 45m

# Exclude patterns (not monitored by watch)
exclude:
  - node_modules/**
  - dist/**
  - .git/**

Advanced Configuration

Custom Mount Options

overlays:
  # Linux overlayfs options
  overlayfs_options:
    - index=off
    - metacopy=on

  # FUSE options (macOS/fuse-overlayfs)
  fuse_options:
    - allow_other
    - uid=1000
    - gid=1000

Resource Limits

# Resource limits for agents
agents:
  # Maximum memory (0 = unlimited)
  max_memory: 2GB

  # Maximum CPU percentage
  max_cpu: 80

  # Maximum file descriptors
  max_fds: 1024

Security Settings

security:
  # Allowed agent commands (empty = all allowed)
  allowed_agents:
    - claude
    - aider
    - gemini

  # Sandbox agent processes
  sandbox: true

  # Network access for agents
  network: true

Config Commands

# View current configuration
phantom config

# Get a specific value
phantom config get overlays.default_timeout

# Set a value
phantom config set git.auto_commit false

# Open config in editor
phantom config edit

# Show config file path
phantom config path

Configuration Best Practices

Use project config for team settings - Commit .phantom.yaml to version control
Use user config for personal preferences - Timeouts, log levels
Use hooks for quality gates - Run tests, linters before applying
Set appropriate timeouts - Prevent runaway agents
Use templates - Standardize workflows across your team