Run
perseus <command> --helpfor full flags and options.
| Command | What it does |
|---|---|
perseus render <file> |
Resolve all directives in a source document and print rendered output. Add --output <path> to write to disk. --format json for structured output with metadata, directive details, and integrity report — consumable by agents and CI pipelines. Custom format plugins in ~/.perseus/formats/<name>.py. |
perseus scan <file> [--pii] [--json] [--report-only] |
Security build gate. Render the context (with redaction off, in-memory) and scan the resolved output for secret shapes (and, with --pii, emails/SSNs/phone numbers/Luhn-valid cards). Prints a masked report and exits non-zero on findings so CI can block a leaking context. --report-only reports without failing. |
perseus compress <file> [--output FILE] [--json] [--strip-comments] |
Render then deterministically compress the context (trim trailing whitespace, collapse blank-line runs, drop adjacent duplicate lines, optional comment strip; fenced code preserved verbatim) and report a citable token-reduction percent. Dependency-free and reproducible — a build can assert on the number. |
perseus graph <file> [--json] |
Build a static directive graph without executing directives; foundation for predictive prefetching. |
perseus prefetch <file> [--json] |
Apply configured prefetch.rules to the static graph and warm directive caches. |
perseus synthesize <question> --source FILE [--json] |
Build a cited-synthesis prompt (sources + citation scaffolding) for the host agent to answer. Perseus runs no inference of its own. |
perseus pack {validate,show} [--json] |
Inspect and validate .perseus/pack.yaml context pack manifests. |
perseus watch [--source FILE] [--output FILE] [--interval N] |
Poll context sources and refresh render outputs without platform scheduler dependencies. |
perseus validate --schema SCHEMA [payload|-] [--json] |
Validate YAML/JSON payloads against Perseus schemas; omit payload or pass - to read stdin. |
perseus checkpoint --task ... --status ... --next ... |
Write a YAML waypoint to ~/.perseus/checkpoints/. Auto-updates Mnēmē narrative. |
perseus diff [--from FILE] [--to FILE] |
Show diff between two checkpoints (default: latest two). |
perseus recover [--workspace PATH] |
Print the latest checkpoint for the workspace. |
perseus agora [--status open|in_progress|completed] |
Live task board from tasks/*.md. |
perseus suggest <prompt> |
Pythia tool oracle — ranks skills against a prompt and prints the prompt for the host agent to answer, with transparent outcome-weight hints when data exists. |
perseus memory {update,compact,show,status,query,federation} |
Mnēmē narrative project memory + cross-workspace federation. |
perseus memory index {rebuild,stats,search} |
Mnēmē v2 FTS5 vault index management. rebuild re-indexes all .md files in ~/.perseus/memory/vault/. stats shows document count and index size. search --query "..." --k 5 runs a BM25 search against the vault. |
perseus inbox {send,list,read,unread,mark-read} |
Point-to-point messages between agents. |
perseus health |
Maintenance report — stale skills, large narrative, Pythia log volume. |
perseus oracle {accept,reject,log,export,infer-labels,outcomes,drift} |
Daedalus Pythia log management, inferred labels, outcome signals, and drift checks. |
perseus init [--template name | --profile name] <workspace> |
Scaffold .perseus/context.md; profiles also write .perseus/pack.yaml. |
perseus serve [--port N] [--host H] [--generate-token] |
Read-only HTTP view of workspace state on http://127.0.0.1:7991/; optional static bearer auth via serve.auth_token. |
perseus serve --lsp --stdio|--tcp PORT [--allow-lsp-mutations] |
Run as a Language Server Protocol server for editor integration. Mutation commands are opt-in. |
perseus cron SOURCE --output FILE [--every N] [--install] |
POSIX crontab entry generator/installer for macOS, Linux, and BSD cron. |
perseus systemd SOURCE --output FILE [--interval 5m] [--install] [--enable] |
Linux-only systemd --user service + timer scaffolder. |
perseus launchd SOURCE --output FILE [--interval 300] [--label LABEL] [--force] |
macOS-only LaunchAgent plist scaffolder. |
perseus install --target {claude-code,cursor,gemini-cli,copilot} [--workspace PATH] [--dry-run] |
Install Perseus hooks into an AI assistant. |
perseus update [--apply] [--check] [--auto on|off] |
Check for and apply Perseus updates from git. |
perseus mcp {serve,config,register} |
Run Perseus as an MCP server — expose directives as tools for any MCP-compatible assistant. |
perseus doctor [--workspace PATH] [--json] |
Run readiness checks against workspace and config (10 checks: config, context file, render settings, checkpoint age, Mnēmē narrative, federation, Pythia log, serve endpoint, directive registry, version). |
perseus trust [--json] {profile,audit} |
Show effective permission profile and trust posture; audit recent access decisions. |
Agent-readable --json contracts for synthesis, oracle, memory, federation, and drift commands are documented in Agent JSON Surfaces.
pip install perseus-ctx
perseus init /workspace/myproject
perseus render /workspace/myproject/.perseus/context.md --output CLAUDE.mdSee also: Directives Reference, Quickstart, Integration Guide