Perseus
Live Context Engine for Professional Developers v1.0.6 · MIT

Your AI assistant opens cold.
Perseus makes sure it already knows what’s running.

A live context engine for AI coding assistants. Perseus resolves your environment before the context window opens — directives like @query "git log -5" are rendered to facts at build time, so the assistant reads a document that was already true. Works with any tool that reads a file.

Works with any assistant that reads a file — Claude Code, Cursor, Codex, Rovo Dev, Hermes, or your own. No plugin. No SDK. Drop a rendered markdown file where your assistant already looks.

pip install perseus-ctx
github★ cipassing pypiv1.0.6 licenseMIT
Perseus with the Head of Medusa, bronze sculpture by Benvenuto Cellini, 1545–1554, Loggia dei Lanzi, Florence
Plate I
Perseus with the Head of Medusa
Cellini, 1545 · Bronze · Loggia dei Lanzi
I  —  The Mirror

Don’t meet the Gorgon’s gaze. Reflect it.

Without Stale facts. Wasted turns.

The assistant guesses.

# session opens, CLAUDE.md last edited 11 days ago
you   deploy the api service to staging.
ai   running `make deploy-staging`...
ai   Makefile target removed in #482. Let me check
         the current scripts.
ai   Which branch are you on? Is the helm chart
         still at v0.3? What’s the staging cluster name?
# 4 orientation turns. 11k tokens. 0 progress.

Sessions start cold. Tooling drifts. Docs lie politely. Every conversation pays an orientation tax before the real work begins — and the assistant is staring straight at the Gorgon.

With Resolved at render time.

The assistant already knows.

# CLAUDE.md rendered 38s ago by `perseus render`
you   deploy the api service to staging.
ai   You’re on feat/billing-v2, helm chart
         v0.4.1, staging = eu-west-2/stg-a.
ai   Running `./scripts/deploy.sh staging api`.
ai   ✓ Image pushed. ✓ Helm upgrade applied.
# 1 turn. The branch, chart version, cluster: all true.

Perseus renders directives to live facts before the assistant reads the file. No guessing, no probing, no trusting yesterday’s notes. The mirror, polished.

Watch it happen — cold-start eliminated
Perseus demo: without Perseus (cold start, 36 discovery calls) vs with Perseus (install, render, 0 discovery calls, warm cache 0.28s)
II  —  The Render

A document that was already true.

Source01
# .perseus/context.md ## Project This is @query "jq -r .name package.json". ## Current state Branch: @query "git branch --show-current" @cache ttl=300 @query "git log --oneline -5" ## Dependencies @read pyproject.toml
Directives. Authored once.
Perseus render02
$ perseus render \ .perseus/context.md \ --output CLAUDE.md resolve query → 3 directives (1 cached) resolve read → 1 directive ✓ 4 directives in 31ms ✓ wrote CLAUDE.md (3.2 KB)
Parallel. Cached. Idempotent.
Output → Assistant03
# CLAUDE.md ## Project This is perseus-ctx. ## Current state Branch: feat/billing-v2 a3f1b9c fix: drift on tag walk 8c2e4d7 feat: add @file lines= d019f80 bench: 1M directive run …
Plain markdown. No directives left.

The principle The assistant never sees a directive. It sees a document that was already true.

III  —  The Triad

Three tools. One mirror.

The Renderer

The polished shield.

Resolves @query, @read, @waypoint, @services and friends before the assistant sees them. The output is plain markdown. No directives left for the model to chase. --tier 1|2|3 for progressive context disclosure.

perseus render .perseus/context.md
Session Waypoints

Pick up where the thread snapped.

Write a checkpoint at any natural pause; perseus recover finds the right one for your workspace; perseus diff shows what changed between two pauses. Continuity, without re-orientation.

perseus checkpoint --task ... --next ...
Pythia · Tool Oracle

Ranked paths, with a reason.

Given a task and the current environment, Pythia surfaces the highest-utility skill or tool and tells you why. No extra model required. The loop closes inside the same context window.

perseus suggest "deploy the staging container"
The wider constellation
Mnēmē
@memory
Narrative project memory. Federates across workspaces to build a coherent, long-term understanding of your work.
Daedalus
@drift
Self-rating oracle. Detects when recommendations drift from reality, preventing implementation of flawed suggestions.
Agora
@agora
Live task board rendered from tasks/, ensuring the AI and team share a single source of truth for work.
Hermes
@inbox
Point-to-point messages between agents for coordination and handoff on complex tasks.
Tiered Context
--tier 1|2|3
Progressive disclosure. The agent is the RAG — only core context injected, rest pulled on demand.
Graeae
perseus serve —lsp
LSP server & VSCode extension. Hover-preview directives.
·  —  The Blueprint

How the pieces fit together.

Click to expand
A diagram showing how Perseus directive sources flow through the render engine into output files consumed by AI assistants, with subsystems and integrations branching off. DIRECTIVE SOURCES .perseus/context.md @query · @read · @cache @memory · @drift · @skills · @services @agora · @inbox · @checkpoint authored once triggers on push / schedule perseus render Resolve shell · HTTP Cache TTL-aware Compile markdown resolves directives against live environment RESOLVED CONTEXT (plain markdown) CLAUDE.md Claude Code AGENTS.md Codex · Rovo .cursorrules Cursor .hermes.md Hermes CONTEXT Your own read by any assistant that opens a file at session start SUBSYSTEMS & INTEGRATIONS checkpoint · recover · diff session waypoints Agora task board Inbox messages Pythia · @drift tool oracle LSP · VSCode · MCP editor + registry GitHub Action — renders on push, commits resolved context Directives authored once. Context resolved on every render. The assistant opens a file that was already true.

One file · one render · every assistant reads the same live truth

IV  —  The Arsenal

Every tool. One engine.

Core directives — resolved at render time
@query
Shell execution
Runs a command and captures output. Cached with @cache ttl=N. The workhorse directive.
@read
File inclusion
Inlines file content with optional line ranges. Context-overflow guarded.
@services
Health checks
HTTP, Docker, or command-based service discovery. Parallel checks, configurable timeouts.
@waypoint
Session checkpoint
Inserts the latest checkpoint summary. TTL-aware. Restores continuity across sessions.
@memory
Mnēmē narrative
Project memory federated across workspaces. Auto-distills checkpoints into a rolling narrative.
@agora
Task board
Live task board from tasks/*.md. Single source of truth for AI and team.
@drift
Daedalus oracle
Self-rating. Detects when recommendations diverge from reality. Prevents flawed execution.
@inbox
Hermes messages
Point-to-point agent messages for coordination and handoff on complex multi-agent tasks.
@agent
Subprocess agent
Executes a local agent subprocess. Gated behind allow_agent_shell for safety.
@synthesize
Cited synthesis
LLM-powered summarization with provenance claims. Every assertion traces back to a source.
@include
Nested render
Includes and resolves another context file. Enables composable, modular context packs.
@prompt
System prompt
Injects a system-level prompt block consumed by the assistant at session start.
CLI — one binary, every verb
perseus init
Scaffold a workspace
Creates .perseus/context.md + pack.yaml. Profile-aware: --profile hermes, codex, claude-code, cursor.
perseus quickstart
Zero to warm in one command
Detects your assistant, scaffolds, renders, and prints next steps. The fastest path from nothing to live context.
perseus render
Resolve and output
Resolves all directives in parallel. Outputs plain markdown. --tier 1|2|3 for progressive disclosure.
perseus checkpoint
Save session state
Write a waypoint at any natural pause. recover finds the right one; diff compares two.
perseus suggest
Pythia tool oracle
Ranks the highest-utility tool or skill for a task. No extra model. Closes the loop in-context.
perseus doctor
Readiness check
Verifies config, permissions, cache health, and output freshness. One command to know you're solid.
perseus watch
Auto-refresh daemon
Polls for source changes, re-renders on drift. Works anywhere — no crontab or systemd needed.
perseus cron
Scheduled render
Installs a crontab entry. --every 30 minutes. Traditional, battle-tested.
perseus systemd
User unit timer
Installs and enables a systemd timer. --interval 5m. Native Linux scheduling.
perseus mcp serve
MCP server
Exposes 24 tools over stdio or SSE (port 8420). Listed on the MCP Registry. Works with any MCP client.
perseus serve --lsp
Graeae LSP
Language server with hover-preview for directives. Auto-renders on save. VSCode extension included.
perseus memory
Mnēmē management
Update, show, or compact project memory narratives across workspaces.
MCP server — 24 tools, one endpoint

Listed on the official MCP Registry as io.github.tcconnally/perseus. Every directive is a live tool: perseus_query, perseus_services, perseus_memory, perseus_agora, perseus_skills, perseus_inbox, perseus_drift, perseus_agent, and 16 more. Works with Claude Desktop, Claude Code, Cursor, Codex, Hermes Agent, Rovo Dev, and any MCP-compatible assistant.

perseus mcp serve  — that's it. Tools resolve live at invocation time. No stale cache.

V  —  The Receipts

Numbers from the bench, not the pitch deck.

Concurrent writers
120agents

30 developers × 4 agents each. 150 concurrent checkpoint writes in 9.7s on local NVMe with atomic O_CREAT | O_EXCL locking. Writes hit the task board (tasks/*.md) with zero failures, zero collisions — protocol tested across edge cases: crash recovery, stale claims, TTL expiry.

0 failures 0 collisions 9.7s wall edge cases
Perseus v1.0.6 — Performance Benchmarks: 450× speedup, 1,190× cache, 301× vs LLM, 94% compression, 0 failures, 813 tests

450× cold→warm · 1,190× cache punch · 301× vs LLM · 94% token compression · 0 failures at 150 concurrent · 813 tests all green · full benchmark suite ↗

VI  —  The Compatible

Resolves to a file. Yours, already.

CLAUDE.md
Claude Code
.cursorrules
Cursor
AGENTS.md
Codex · Rovo Dev
.hermes.md
Hermes
CONTEXT.md
Your own

Perseus outputs plain markdown. Point the output at whatever file your assistant opens at session start — no plugin, no SDK, no migration. The next session opens warm.

VII  —  The Adapters

Four ways to own session-start.

VS Code · Cursor
editor extension · LSP server
Source · editors/vscode ↗

Auto-renders .perseus/context.md on save. Status bar indicator. Hover-preview for any directive. Auto-detects the target assistant file. Install from source; Marketplace publishing pending.

$ git clone https://github.com/tcconnally/perseus.git && cp -r perseus/editors/vscode ~/.vscode/extensions/tcconnally.perseus-vscode
Claude Code Hook
session-start trigger · one curl

Runs perseus render automatically before every Claude Code session. The assistant opens already briefed — no orientation phase, ever.

$ perseus install --target claude-code
GitHub Action
push & schedule · commits back
Released · tcconnally/perseus-action ↗ @v1

Renders on every push and on a schedule. Commits the resolved context back to the repo so every teammate gets pre-warmed context without installing anything locally.

# .github/workflows/ uses: tcconnally/perseus-action@v1
MCP Server
directive tools · on the registry
Listed · io.github.tcconnally/perseus ↗

Exposes 24 Perseus directives as MCP tools for any MCP-compatible assistant. Bearer-token authentication on SSE transport, platform-portable timeouts, and SSRF-hardened foreign resolver. Listed on the official MCP Registry.

$ perseus mcp serve
VIII  —  The Start

Thirty seconds from cold to warm.

One command. Or hand the guide to your AI.

perseus quickstart detects your assistant, scaffolds a workspace, and renders live context in a single command. Or give your AI our LLM-tuned setup guide and say “set up Perseus for me.” Your assistant opens its next session already briefed.

01 $ pip install perseus-ctx
or ~ uv tool install perseus-ctx
02 $ perseus quickstart
or ~ perseus init --profile hermes /workspace/myproject
03 $ perseus doctor
⌘
LLM-Tuned Guides — Perseus ships with documentation written for AI assistants to read and execute. Drop SETUP-GUIDE.md or SKILL.md into any AI coding assistant and say “set up Perseus for this workspace.” Config, auto-refresh, permissions, MCP wiring, troubleshooting — the guide covers it all. Your AI reads it, then types the commands. You watch.

After setup → perseus doctor verifies everything is wired correctly.