Perseus
Use when you need live project state (git branch, service health checks, recent sessions, task board, env vars, agent inbox) injected into context BEFORE the AI reads it. Perseus is a compile-before-context engine — it runs directives like @query, @services, @waypoint, @agora and hands the assistant a fully-resolved markdown briefing. Use for: deterministic session starts, multi-agent coordination, workspace audits, and anywhere you want "all the facts first."
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Perseus when an AI agent needs a reusable SKILL.md workflow for this job: Use when you need live project state (git branch, service health checks, recent sessions, task board, env vars, agent inbox) injected into context BEFORE the AI reads it. Perseus is a compile-before-context engine — it runs directives like @query, @services, @waypoint, @agora and hands the assistant a fully-resolved markdown briefing. Use for: deterministic session starts, multi-agent coordination, workspace audits, and anywhere you want "all the facts first."
When not to use it
Skip Perseus when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/perseus # Save SKILL.md to ~/.claude/skills/perseus/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/perseus/SKILL.md. For a shared project, commit the folder at .claude/skills/perseus/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Perseus skill for this task: Use Perseus when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
73/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 83/100
- Practical detail
- 74/100
- Source evidence
- 54/100
- Source signals
- 70/100
Model compatibility evidence
- claudeinferred
The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- chatgptinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- geminiinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- copilotinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- llamainferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- perplexityinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- mistralinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- grokinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Perseus — Live Context Engine for AI Assistants
Perseus pre-resolves your entire workspace state — git, services, memory, team coordination — into a single markdown document every assistant reads at session start. Deterministic. Cacheable. Assistant-agnostic.
## Quick Start
```bash pip install perseus-ctx # or: uv tool install perseus-ctx perseus init # scaffold .perseus/context.md perseus render --format agents-md # render to AGENTS.md ```
## Installation as a Claude Code Skill
```bash # Install Perseus uv tool install perseus-ctx
# Set up Claude Code hooks — auto-injects Perseus context every session cd your-project perseus install --target claude-code
# Render your first briefing perseus render .perseus/context.md --format claude-md ```
This drops `SessionStart` + `UserPromptSubmit` hooks into `.claude/settings.json`. Every Claude Code session now starts with Perseus-resolved context injected automatically.
## Core Directives
Write a `.perseus/context.md` file with `@perseus` as the first line, then use any of these 22 directives:
| Directive | What it does | |-----------|-------------| | `@query "command"` | Run a shell command and embed stdout | | `@services` | Health-check listed services (HTTP, TCP, etc.) | | `@read path=file` | Embed file contents | | `@env VAR` | Embed environment variable | | `@waypoint` | Latest session checkpoint (crash recovery) | | `@agora` | Task board from `tasks/*.md` | | `@inbox` | Inter-agent messages | | `@memory` | Narrative project memory (federated across workspaces) | | `@skills` | List available agent skills | | `@session` | Recent session digests | | `@health` | Context maintenance report | | `@date` | Current date/time | | `@include path=file` | Include and render another file | | `@if / @else / @endif` | Conditional blocks | | `@cache ttl=N` | Cache directive output for N seconds | | `@cache session` | In-memory cache (session lifetime) | | `@constraint` | Constraint block for validation | | `@validate schema=` | Validate a rendered block | | `@tree` | Tree view of directory | | `@list` | List directory or structured data |
## Example .perseus/context.md
```markdown @perseus v1.0.6
# Project Context
## Git @query git branch --show-current @query git log --oneline -5
## Services @services
## Session State @waypoint @session count=3
## Team Coordination @agora @inbox unread=true ```
## Multi-Agent Coordination
Perseus's strongest differentiator is multi-agent shared state. With `@agora` (task board), `@inbox` (inter-agent messaging), and `@memory federation`, every agent in your swarm reads the same resolved context at session start. The filesystem-based coordination protocol handles 150+ concurrent writers with zero collisions.
## MCP Server Mode
Perseus also runs as an MCP server, exposing all directives as native MCP tools:
```bash perseus mcp serve --workspace /path/to/project ```
Any MCP-compatible assistant (Claude Desktop, Cursor, Continue) can call `perseus_query`, `perseus_services`, `perseus_memory`, etc. as tools.
## Tips
- **Deterministic sessions**: Run `perseus render` before starting work. Your AI assistant gets the same briefing every time. - **CI integration**: `perseus render --format agents-md -o AGENTS.md` in your CI pipeline. Every PR gets Perseus-resolved context. - **PR descriptions**: Render the snapshot as HTML comments in PR descriptions. Reviewers (human and AI) see the same briefing. - **Trust boundaries**: Perseus supports schemas, path guards, and redaction policies. By default, dangerous operations are restricted.
## Resources
- **Homepage**: https://github.com/Perseus-Computing-LLC/perseus - **Docs**: https://github.com/Perseus-Computing-LLC/perseus/blob/main/docs/index.md - **PyPI**: https://pypi.org/project/perseus-ctx/
Intended uses
- Use Perseus when this documented workflow matches the task.
Implementation notes
- Deterministic sessions: Run perseus render before starting work. Your
- CI integration: perseus render --format agents-md -o AGENTS.md in your
- PR descriptions: Render the snapshot as HTML comments in PR descriptions.
- Trust boundaries: Perseus supports schemas, path guards, and redaction
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.