Wiring Perseus

July 16, 2026 · View on GitHub

Perseus resolves your project state before the AI assistant sees it. This guide covers every way to wire Perseus into your workflow so context stays live-loaded — no stale files, no "discover what's running" preambles.

Quick Reference

Pattern	Command	Refresh
One-shot render	`perseus render .perseus/context.md --output .hermes.md`	Manual
Watch	`perseus watch`	Auto on file change
Systemd timer	`perseus systemd create … --install --enable`	Every N minutes
Cron	`perseus cron create … --install`	Every N minutes
MCP server	`perseus mcp serve`	Live on tool call
Editor hook	`perseus install --target claude-code`	Before session start

1. MCP Server — Live Tools at Invocation Time

Every MCP tool resolves live workspace state when called — no stale cache, no pre-computed snapshots.

stdio (Claude Desktop, Claude Code, Cursor, Codex)

perseus mcp serve

Add to your assistant's MCP config:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "perseus": {
      "command": "perseus",
      "args": ["mcp", "serve"]
    }
  }
}

Claude Code or Cursor (.mcp.json in your project root):

{
  "mcpServers": {
    "perseus": {
      "command": "perseus",
      "args": ["mcp", "serve"]
    }
  }
}

Print the exact config:

perseus mcp config

SSE (remote agents, multi-machine)

perseus mcp serve --transport sse --port 8420

Then point remote assistants at http://<host>:8420/sse.

Available MCP Tools

After wiring, the assistant gets these tools:

Tool	Resolves
`perseus_render_source`	Full context rendering with all directives
`perseus_memory_search`	Mnēmē vault (FTS5 semantic search)
`perseus_memory_narrative`	Project narrative
`perseus_health_report`	Maintenance suggestions
`perseus_oracle_suggest`	Pythia tool/skill recommendations
`perseus_synthesize`	Cited synthesis claims across sources
`perseus_read_file`	File contents with size guards
`perseus_list_directory`	Directory listing
`perseus_run_query`	Shell command execution (gated)
… and 12+ more	Check `perseus mcp register` for the full registry

2. Editor Hooks — Context Before Every Session

perseus install injects Perseus context rendering into your AI assistant's startup hook, so every new session starts with live context.

# Claude Code
perseus install --target claude-code

# Cursor
perseus install --target cursor

# GitHub Copilot
perseus install --target copilot

# Gemini CLI
perseus install --target gemini-cli

What it does:

Creates .perseus/context.md (if missing)
Writes a hook that runs perseus render before each assistant session
The hook produces .hermes.md / CLAUDE.md / AGENTS.md / .cursorrules depending on the target

Dry run — see what files would be written without writing them:

perseus install --target claude-code --dry-run

3. Live Auto-Refresh — Continuous Context Updates

Watch (poll-based, zero config)

Watches source files for changes and re-renders on every save. Ideal for development.

# Start watching — re-renders .hermes.md whenever .perseus/context.md changes
perseus watch

# Custom source/output
perseus watch --source .perseus/context.md --output CLAUDE.md

# Custom interval
perseus watch --interval 10

Runs in the foreground. For background operation, use systemd or cron.

systemd Timer (Linux, background)

# Create, install, and enable a systemd timer for every-5-minute refresh
perseus systemd create .perseus/context.md --output .hermes.md --interval 5m --install --enable

This creates:

~/.config/systemd/user/perseus-render-context.service — the render job
~/.config/systemd/user/perseus-render-context.timer — the timer

# Check status
systemctl --user status perseus-render-context.timer

# Manual trigger
systemctl --user start perseus-render-context.service

# Remove
perseus systemd uninstall .perseus/context.md

Cron (macOS / Linux)

# Install a crontab entry
perseus cron create .perseus/context.md --output .hermes.md --every 5 --install

# Remove
perseus cron uninstall .perseus/context.md

4. Context Packs — Multiple Outputs, One Source

A context pack defines multiple render targets from a single context source, each formatted for a different assistant.

# Create a pack for Hermes Agent
perseus init --profile hermes --workspace /path/to/project

This creates .perseus/pack.yaml:

version: 1
assistant: hermes
label: Hermes Agent
source: .perseus/context.md
output: .hermes.md
trust_profile: balanced

Once configured, perseus watch auto-detects the pack and renders all targets.

Supported profiles:

perseus init --list-profiles

Profile	Output	For
`hermes`	`.hermes.md`	Hermes Agent
`claude-code`	`CLAUDE.md`	Claude Code
`codex`	`AGENTS.md`	OpenAI Codex
`cursor`	`.cursorrules`	Cursor IDE
`rovodev`	`AGENTS.md`	Atlassian Rovo Dev
`generic`	`live-context.md`	Any assistant / stdin flow

Validate:

perseus pack validate

Show summary:

perseus pack show

5. LLM Backend — Pythia & Synthesis

Pythia (task suggestions) and Synthesis (cited claims) need an LLM. Quick setup:

# Interactive (recommended)
perseus quickstart

# Non-interactive with auto-detection
perseus quickstart --non-interactive

# Verify
perseus llm ping

See QUICKSTART.md for Gemini free tier, Groq, and llama.cpp setup details.

6. Full Workflow — End-to-End Example

Here's the complete wiring for a project where you use Claude Code and want live context auto-refreshing every 5 minutes:

# 1. One-command bootstrap
perseus quickstart

# 2. Wire Claude Code
perseus install --target claude-code

# 3. Set up auto-refresh (Linux)
perseus systemd create .perseus/context.md \
  --output CLAUDE.md \
  --interval 5m \
  --install --enable

# 4. Verify everything
perseus doctor
perseus llm ping
perseus pack validate

# 5. Start coding — Claude Code gets fresh context every session

For macOS:

# Replace step 3 with:
perseus watch &  # background, or
perseus launchd create .perseus/context.md \
  --output CLAUDE.md \
  --interval 300

7. Trust & Security

Perseus defaults to the balanced permission profile, which keeps shell execution disabled. Review and adjust:

# See what's in effect
perseus trust

# See audit log
perseus trust audit --tail 20

# Switch to power-user (enables shell)
# Add to .perseus/config.yaml:
#   render:
#     allow_query_shell: true
#     allow_agent_shell: true
#     allow_services_command: true
#   trust:
#     allow_query_shell: true
#
# Also set in your environment:
#   export PERSEUS_ALLOW_DANGEROUS=1

8. Verification

# Full health check
perseus doctor

# LLM reachability
perseus llm ping

# Directive coverage in your context
perseus render .perseus/context.md --explain

# Permission posture
perseus trust

9. Savings Wire — Metering Spend and Provable Savings into Plutus

Perseus observes; it never brokers your LLM calls. The plutus: config block (default off) lets a deployment record real usage, and the counterfactual it replaced, into a Plutus ledger whose totals a customer can re-derive by raw SQL.

# .perseus/config.yaml
plutus:
  enabled: true
  db_path: ~/.plutus/perseus-ledger.db   # or endpoint: https://plutus.example
  org: my-org
  workspace: prod-agent

Three levels of wiring, from zero-code to billing-grade:

Spend only. After each provider call, hand the SDK response to the meter: perseus.meter_response(cfg, response). Tokens and cost land in the ledger, tagged workspace and task_type.
Provable savings on real calls (billing-grade). If you know what the call would have cost without Perseus, attach the counterfactual to the same event: perseus.meter_response(cfg, response, baseline_input_tokens=N) where N is the token count of the context you would have sent (for example, the full-context prompt a Vault recall replaced). Plutus prices the counterfactual from its published table, floors the actual at list price, and hash-chains both, so the per-event saving is reconstructable and tamper-evident (plutus #134). Requires plutus-agent > 1.0.1; an older plutus-agent still meters spend and drops the baseline with one warning.
Zero-code reduction estimates. plutus.meter_memory_posture: true records one estimate-arm event per render: the memory block Perseus actually injected versus the dump the legacy always posture would have injected. These land in a dedicated workspace (plutus.estimates_workspace, default perseus-render-estimates) and are labeled estimate-exact (tiktoken installed) or estimate-heuristic, so estimated context sizes never contaminate provider-billed spend. Costs one vault call per render. There is also a direct helper for custom wiring: perseus.meter_context_reduction(cfg, actual_text=..., baseline_text=...).

Estimates are for visibility; bills come from level 2. Never quote an estimate-arm figure as a measured saving.