Perseus

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

1. Personal install: create ~/.claude/skills/perseus/SKILL.md (and any bundled scripts) so Claude Code, Claude Desktop, and compatible agents can load it in every project.
2. Project install: commit the same folder at .claude/skills/perseus/ so teammates get the skill with the repo.
3. Restart the agent session after copying files so it re-scans the skills directory, then ask for the task in words that match the skill description.

Full install guide for Claude, Cursor, and Codex

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.