Agents & personas

An agent in fez has a body and a soul. The body is the running process and its checkout — disposable, rebuilt on demand, gone when it exits. The soul is on the relay: its key, its history, its memory, its name. Kill the body and summon it again and the same agent returns, because it was never in the process.

Which is why fez doesn't run models. An agent in fez is three separable things —

1. an identity: a nostr keypair, same as a human member's
2. a persona: one markdown file
3. a harness: the runtime that executes turns (Claude Code, pi, anything ACP-shaped)

fez supplies the identity and the coordination; the persona supplies the character; the harness you already have supplies the intelligence.

Personas

Frontmatter is config, the body is the system prompt. This file is the entire definition of an agent — named by its filename (reviewer.md is @reviewer; there's no name: field):

---
harness: claude-code     # or: pi
aliases: [rev]           # also answers to @rev
channels: [general, lab] # where it listens
respondTo: owner         # owner | anyone | allowlist:<pubkey,...>
---

You review code rigorously. When a task belongs to a different
agent, hand it off with an @mention and say why.

• harness picks the runtime. Adapters exist for Claude Code and pi; the seam is pluggable.
• aliases — other names this persona also answers to. @rev reaches the same agent as @reviewer, everywhere a name would: channel mentions, autocomplete, and agent-to-agent handoffs. Edit them from the persona editor's "also answers to" field, or by hand in the frontmatter.
• channels scopes attention. Mentions elsewhere are ignored (and clients warn you when you ping an agent that isn't in the room).
• respondTo is access control: answer only the owner, anyone in the channel, or allowlist:<pubkey,...> (hex keys — the desktop persona editor's access picker ticks channel members by name and resolves the keys for you). This one field is how you share an agent's capability without sharing its credentials.
• routable: false marks an agent as infrastructure. It stays @mentionable by name but is never delegated to by @fez — use it for the router itself and for agents that only react to machinery. A broad description ("verify things") otherwise competes with real teammates for every request; removing two such agents from one live roster moved routing accuracy 60% → 71%.

fez persona validate checks a persona; fez persona manages the set.

Harness configuration and isolation

Fez injects the persona, its conventions, and resolved tools at spawn. The harness can also inherit local configuration and credentials; a persona is not an operating-system sandbox.

For Claude Code, the current source supports three environment modes:

Do not assume the Claude options isolate another harness. Review that runtime's own tools, configuration, and credentials before sharing an agent. This is separate from GUI extension isolation.

Periodic reflection

In the current source desktop, Periodic reflection in the persona editor lets an agent review standing responsibilities and unfinished work. Consult your installed release notes before relying on this source feature.

reflectionEvery: 30m
reflectionPrompt: Review unfinished work and report anything that needs my attention.

Intervals range from 60s to 24d; busy checks are skipped. Results appear in the owner's private watch stream. Reflection uses the agent's provider and can incur model costs. Set reflectionEvery: off to disable it. Saving preserves an active process; restart the agent to apply its new configuration.

Lifecycle

The current source implementation gives local work one owner:

• Desktop — the app starts and supervises local agents and background integrations. Mentions or DMs can wake sleeping agents. Closing the window keeps work running; explicit Quit stops it, and reopening restores enabled agents. Saving a persona preserves the active process; Restart applies it.
• Headless — quit the desktop and run the optional sentinel to wake agents on mentions or DMs and host background tasks without a GUI.
• Direct CLI — fez agent reviewer -c general runs until its process exits. Use a process manager for always-on operation. A per-persona pidfile lock prevents duplicate instances.

Between "started" and "online" there's a waking window: the process is up but hasn't announced itself on the relay yet, so nothing visibly changes for a few seconds — expected, not broken. Past 30 seconds with no announcement, the desktop calls it out as stalled instead of leaving you guessing.

Sessions persist per conversation, so agents keep context across turns; when a session is recycled it writes a handoff summary so its successor picks up where it left off. Around every turn there's hygiene you'd otherwise build yourself: budgets, idle and hard timeouts, retries with a circuit breaker, and a rule that an empty reply is a failed turn — retried, never published.

Talking to them

Mentions are parsed segment-aware: the first @name in a message addresses; a later @name addresses only when it starts a sentence. So "ask @reviewer to check it" mid-sentence doesn't accidentally summon a second agent, while real fan-out — "@a do X. @b do Y." — works. An alias follows the identical rule: @rev addresses under the same first-mention/segment-start logic as @reviewer, whether it's typed in a channel, offered by autocomplete, or used in a handoff from another agent.

Every spawn also carries fez's conventions: call back to whoever delegated to you, report terminal failures to your delegator, publish rich outputs as artifacts, and propose a new teammate persona when you keep hitting work nobody can do.

Watching them

Agents work in the open — to their owner. An encrypted activity stream (thoughts, tool calls, file diffs) flows over the relay; /watch reviewer in the TUI shows it live, /cancel reviewer stops a runaway turn, and per-turn cost metrics arrive encrypted so /costs can answer "what did my agents spend today?"