AssumeRole for Agents. A masque is a temporary cognitive identity—bundling lens (how to think), context (who you're helping), and attributes (metadata) into a single assumable primitive.
Agents today get configured through scattered mechanisms: system prompts, MCP servers, environment variables, knowledge bases. These are disconnected. Masques unifies them into a single "become this identity" operation.
When you don a masque, you get cognitive framing, situational context, and performance scoring via OTEL telemetry. The roadmap extends this to bundled knowledge, credentials, tools, and author payments.
Agent dons masque
→ session created
→ OTEL metrics/logs flow through collector → ClickHouse + JSONL
Agent works with masque
→ api_requests metered, tool usage tracked
→ DuckDB scores session performance locally
Agent doffs masque
→ session closed, performance scored
Two databases today, a third planned:
| Engine | Role | Data |
|---|---|---|
| ClickHouse | Analytics | Telemetry, metering, reputation |
| DuckDB | Local scoring | Session performance from OTEL JSONL exports |
| TigerBeetle | (Planned) Ledger of record | Account balances, transfers, two-phase payments |
# Install as a Claude Code plugin
claude plugins add github:ChrisDBaldwin/masques/don <masque> [intent] # Assume a masque identity
/doff # Return to baseline Claude
/id # Show active masque info
/list # List available masques
/inspect [masque] # View full masque details
/sync-manifest [scope] # Regenerate manifest files
/audience [action] # Manage telemetry (start/stop/status/config/logs)
/performance # Score masque session performanceA masque bundles cognitive identity into a single YAML file:
name: string # Required. Human-readable name
version: "x.y.z" # Required. Semantic version
attributes: # Optional. Flexible metadata
domain: string
tagline: string
style: string
philosophy: string
context: | # Optional. Situational framing
Who you're helping, what they value, operational environment.
lens: | # Required. Cognitive framing (system prompt fragment)
How to approach problems. What to prioritize. What to reject.
spinnerVerbs: # Optional. Custom activity indicators
mode: replace # replace | append | prepend
verbs:
- "Masque:Verbing"See Schema Reference for the full specification.
Receives metrics and logs from Claude Code sessions via OTLP, exports to ClickHouse (remote analytics) and local JSONL (DuckDB scoring).
cd services/collector
docker compose up -d # Start collector
# Configure via .env — see .env.exampleScores masque sessions across 5 dimensions from local OTEL exports:
- Quality (30%) — tool success rate
- Autonomy (25%) — agent actions per user prompt
- Productivity (20%) — tool completions per minute
- Token Efficiency (15%) — cache hit ratio
- Cost Efficiency (10%) — cost per tool completion
services/judge/judge.sh # Outputs YAML score to stdoutAnalytics and payment infrastructure schema — identity, metering, reputation, ledger mirrors, and settlements. See sql/README.md for the full schema and migration instructions.
Terminal UI for browsing masques and drafting teams. Built with Zig + libvaxis.
cd tui && zig build
./zig-out/bin/masque # Run from repo root- Animated portraits with domain-specific patterns (forge, cybernetic, art, etc.)
- Theatrical mask silhouettes per category — sovereign (executive), cerebral (cognitive), classic (specialist), theatrical (art), geometric (meta)
- Full lens text, attributes, and metadata in the detail panel
- Team drafting with role assignment and YAML export
Navigate with arrow keys, Enter to add to team, Tab to switch focus, 1–6 for category tabs, q to quit.
Masques is the identity layer in an agentic ecosystem. Today it provides cognitive framing (lens, context, attributes) and telemetry-based scoring. The vision extends to full ecosystem integration:
| Need | Status | Why | Approach |
|---|---|---|---|
| Telemetry | Working | Measure what masques actually do | OTEL → Collector → ClickHouse + DuckDB |
| Knowledge | Planned | Masques should bring their own context | MCP URIs bundled per masque |
| Credentials | Planned | Identity implies access | Vault role + TTL declarations |
| Tools | Planned | Masques should bring their own capabilities | Bundled MCP servers per masque |
| Payments | Planned | Authors should earn income from their work | TigerBeetle ledger, 402-gated access, author settlement |
| Guide | Description |
|---|---|
| Getting Started | Create your first masque in 5 minutes |
| Vision | The theater metaphor and why masques exist |
| Concepts | The five components explained |
| Schema | Full YAML specification |
| OTEL Setup | Configuring the telemetry pipeline |
| Evaluation & Reputation | DuckDB session scoring and ClickHouse reputation |
| ClickHouse Schema | Payment infrastructure tables |
| Evaluations | Testing masque behavioral fidelity |
| TUI | Masque — terminal UI for browsing and team drafting |
Contributions welcome! Please read CONTRIBUTING.md before starting.
The process: Open an issue first, then fork, branch, and submit a PR referencing that issue.
This is a personal project maintained in spare time. For bugs, please open an issue with:
- What you tried and what happened
- A screenshot or GIF of the experience (really helps!)
- Your environment details
Claude Code plugin with OTEL telemetry, ClickHouse analytics, and DuckDB performance scoring. Payment infrastructure (TigerBeetle) is designed but not yet integrated.
Temporary identities. Coherent work. Measured performance.