perseus

name

perseus

description

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."

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

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

# 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

@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:

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/