PRI-OM-001 · Systems referenceRev 0.37.0

800.00–1600.00

Systems reference

What each system does, how it works and what it needs.

Requirements sit beside each claim. Behavior is as of the revision in the header band. For the window as a whole, SEE 100.00.

RefSystemPart
800.00Agent setupConnect Codex, Claude Code, pi and OpenCode to a project in one step.Agent
900.00Delegation by levelRoute work to search, easy, hard and expert subagents.Agent
1000.00Agent sessionsSessions and subagents as their harness reports them.Agent
1100.00Tasks and recordsTasks and their history, shared with agents over MCP.Tasks
1200.00BriefThe whole plan, and the decisions and blockers agents are waiting on you for.You
1300.00Shared browserOne browser per project, driven by you and your agents.Agent
1400.00MeetingsDetect, record and transcribe calls on this Mac.Vault
1500.00TerminalsReal shells, one-click harnesses, restore after relaunch.Agent
1600.00Files, vault and projectsEditing, search, recovery, diagrams and the priori command.Vault
Status
SystemStatusSince
Agent terminals, files, vault and shared tasksSEE 1500.00GO0.2.0
Task records: handoffs, blockers, decisions, resultsSEE 1100.00GO0.2.0
Two or three terminal panesSEE 1500.00GO0.6.0
Command palette and Quick OpenSEE 1600.00GO0.7.0
Draft recovery and side-by-side mergeSEE 1600.00GO0.9.0
Agent workflows: sessions and subagentsSEE 1000.00GO0.9.0
Agent levels and model preferencesSEE 900.00GO0.14.0
Agent setup for Codex, Claude Code, pi and OpenCodeSEE 800.00GO0.15.0
Review comments and failure modesSEE 1200.00GO0.18.0
Shared browser and ask_user formsSEE 1300.00COND0.18.0
Harness quickstarts and terminal restoreSEE 1500.00GO0.19.0
Orchestration skills and agentsSEE 900.00GO0.19.0
Brief and Board: your plan, decisions and blockersSEE 1200.00GO0.31.0
Meetings and local transcriptionSEE 1400.00COND0.2.0
Meeting detectionSEE 1400.00COND0.19.0
Speaker labels and voice profilesSEE 1400.00COND0.23.0
Menu bar itemSEE 1400.00GO0.33.0
Project pickerSEE 1600.00GO0.33.0
Editor keys and tab orderSEE 1600.00GO0.33.0
Companion to 100.00–700.00 · GO = available · COND = extra setup required8
PRI-OM-001 · 800.00 Agent setupRev 0.37.0

800.00

Agent setup

800.01

Agent setup connects Codex, Claude Code, pi and OpenCode to a project in one step. Check the harnesses you use and choose whether they may read the linked vault. Priori writes native lifecycle hooks or a plugin, MCP configuration and the orchestration skills. There is no prompt to paste.

You Priori Project Agent Set up harnesses, vault access Hooks or plugin lifecycle events MCP servers priori, priori-browser Skills, agents priori-<level> Enrollment app data, vault scope New session loads hooks and MCP Lifecycle session, turn, subagent MCP tools tasks, workflow, vault Refresh after an update
Fig. 800.01 — What setup writes and what comes back. Installing proves the configuration; the first lifecycle event proves the connection.
800.02 Files setup writes, by harness
HarnessLifecycleMCP serversAgents and skills
Codex.codex/hooks.json.codex/config.toml.codex/agents/priori-*.toml, .agents/skills/
Claude Code.claude/settings.local.jsonLocal scope, through claude mcp.claude/agents/priori-*.md, .claude/skills/
pi.pi/extensions/priori.ts.pi/mcp.json.agents/skills/
OpenCode.opencode/plugins/priori.tsRegistered by the plugin.agents/skills/
800.03

Priori records each install in its own app data, keyed by the project’s path, with the vault access you granted. A repository’s own .priori files cannot enroll a harness or grant vault access.

800.04

When Priori updates, it refreshes the integrations it manages as each project opens, keeping their vault scope. Sessions already running keep the old hooks until you restart them.

800.05

Keep generated files out of Git, on by default, lists what setup wrote in .git/info/exclude. Priori never edits .gitignore and skips skill folders it did not create.

Since 0.15.09
PRI-OM-001 · 900.00 Delegation by levelRev 0.37.0

900.00

Delegation by level

900.01

The main session owns the outcome. It sets requirements and an acceptance check, hands bounded work to subagents at one of four levels, checks each result itself and integrates it. Completion is not acceptance.

Main session owns the outcome delegate: level, why expert xhigh architecture, risky reviews hard medium across modules, test loop easy medium bounded edit, runs tests search medium read-only lookup, cited fails its check result
Fig. 900.01 — Four levels. A result that fails its check is rerun one level up with the failure attached.
LevelUse forEffort
expertpriori-expertArchitecture, trade-offs, review of risky changes. Reasons; does not implement.xhigh
hardpriori-hardImplementation across modules with local design decisions and a test loop.medium
easypriori-easyA bounded edit or check with a clear spec. Runs the relevant tests before returning.medium
searchpriori-searchRead-only lookup. Returns cited evidence (path:line).medium
900.02

Agent levels sets a model and an effort per level for Codex and Claude Code. Effort by task type overrides it for review (high), security (max), UI (low) and API (high) work. Saving rewrites the priori-<level> agent definitions in the project; other harnesses pick their closest supported model.

900.03

Proactive delegation is on by default. Before acting, the main session states delegate or solo and why, and hands repository-wide searches, edits across modules and parallel checks to subagents without asking each time. Turn it off per project.

900.04

Agent setup installs the orchestration skills with the agents: orchestrate, swarm, verify, research, expert-review and agent-artifacts. They are a portable package; the same files work without the app.

Since 0.14.010
PRI-OM-001 · 1000.00 Agent sessionsRev 0.37.0

1000.00

Agent sessions

1000.01

Agent workflows, a tab beside Content, groups work by main session with its subagents nested beneath. Switch between a list and a delegation diagram; recent lifecycle events show each transition.

timehook eventstate 10:00 SessionStart Idle 10:00 UserPromptSubmit Running 10:01 SubagentStart subagent runs 10:01 PostToolUse 10:02 SubagentStop subagent idle 10:02 PermissionRequest Waiting 10:03 PostToolUse Running 10:04 Stop Idle 10:31 SessionEnd Completed 10:19 no event for 15 min Unknown
Fig. 1000.01 — One Claude Code session as its hooks report it. Copper marks the agent running. Silence beyond the limit reads Unknown, never Idle.
StateShown when
RunningA turn started, a tool finished or a subagent started.
WaitingThe harness asked for permission or for your input.
IdleA turn or a subagent stopped.
UnknownNo event within the freshness limit: 15 minutes for hook-based adapters, 90 seconds for pi and OpenCode.
CompletedThe session ended. This does not mean its task passed verification.
FailedThe harness reported a failed turn or session.
1000.02

Adapters record only what the harness exposes: sessions, turns, subagents, permission waits and tool completions. Priori does not read terminal text, and does not store prompts, transcripts, tool arguments or output.

1000.03

Select an agent to see its reported model, activity, sources and result. Focus terminal selects the terminal running it, or the main session’s terminal for a subagent without one.

1000.04

When Claude Code’s hooks omit the model, Priori reads at most the last 1 MiB of that session’s local transcript and keeps only the model identifier. Harnesses without an adapter can report sessions through the MCP tool report_agent.

Since 0.9.0 · native adapters since 0.15.011
PRI-OM-001 · 1100.00 Tasks and recordsRev 0.37.0

1100.00

Tasks and records

1100.01

Tasks live in the project, in .priori/tasks.json, with groups, due dates and effort. You edit them in the Brief; agents use MCP tools. Both writers share one lock and reject stale writes, and each change keeps the previous file as tasks.json.bak.

Task 0142 · Hero motion passopen Run A · Claude Code · session 14 progress Spin replaces sway assumption Motion dial stays at 1 decision Pause: text or icon? handoff scope, constraints, next You · desktop answer Text button comment index.astro:136 · label it Run B · Codex · session 15 resolved Toggle has a label result completed · 1 check passed workflow revision 9 · append-only
Fig. 1100.01 — A task’s history, grouped by run. Records are appended, never edited.
RecordHolds
HandoffAgentSummary, scope, constraints, next steps, blockers, branch, commit, changed files
ProgressAgentA progress summary, with sources
BlockerAgent; resolved by you or the agentWhat blocks the task and what is needed
DecisionAgent asks; you or the agent answerA question, its context, options with details and a recommended choice
AssumptionAgentWhat the agent proceeds on, and why
ResultAgentOutcome, changed files, checks, limitations, follow-ups
Review commentYou; the agent resolves itA file, a line and a comment
1100.02

Every record names its task, run and request, and carries the revision its writer read. Retrying the same request returns the original record. Changed content under the same request is refused, and a stale revision fails until the writer reads again.

1100.03

The main session captures tasks from what you ask for, not one per message. It reads the task list first, reuses the relevant task and updates its scope. A session that stops does not complete a task.

1100.04

Prepare to resume shows a task’s last handoff beside a read-only Git check of the repository, and copies both as a bounded brief for the next session.

Since 0.2.012
PRI-OM-001 · 1200.00 BriefRev 0.37.0

1200.00

Brief

1200.01

When an agent needs you, it records a decision request or a blocker on its task. The Brief tab, beside Content, Agent workflows and Browser, shows the project’s whole plan. Needs you lists every open ask: the one blocking the most downstream tasks comes first, then one whose agent is paused, then the oldest. Running, Ready and Blocked follow, and Done is folded away with its count. The top bar counts the open asks and opens the tab; the menu bar item counts them across your projects (SEE 1400.04).

1200.02

Any task opens in the same pane. New task and Edit open a form for the title, description, the tasks it waits on, group, due date and effort; Task groups creates, renames and removes groups. Waits on offers only tasks that do not already wait on this one, so a dependency cannot close a cycle. A save made against a task an agent changed meanwhile fails and keeps your draft. Tasks appear only in the Brief; the sidebar keeps its space for files, and the tab’s badge counts open asks.

1200.03

The Board shows the same plan as lanes by dependency depth. Unblocked holds every task with nothing unfinished upstream, and After N steps holds the tasks behind a chain of N unfinished tasks. Cards marked Next are ready: everything upstream is done, no agent is running on them and they have no open ask. V switches between Brief and Board, and each project remembers the last view. Selecting a card opens the same detail pane.

Agent Priori You Ask request_decision Brief count, ordered ask Answer actor: desktop Read answer get_decision Comment file, line, task Read task get_task_context Resolve its resolution
Fig. 1200.01 — A question and a review comment, each a round trip through the task.
1200.04

The detail pane shows the question; what it unblocks, which is the step, the tasks it waits on and the tasks waiting on it, each with its status; the context; the evidence agents reported, with their claims kept apart from the checks they ran (passed, failed or not run); and the answer.

1200.05

The answer lists the recommended option first, with its reason, then the alternatives, then Other for a written answer. Enter takes the recommendation, B, C and D pick an alternative, J and K move between asks, O opens Other, and ⌘↵ submits it. A toast offers Undo for a few seconds; there is no confirmation dialog. A blocker is Done, or Other to write what happened. An ask closes only when it is answered.

1200.06

A decision that cites the open file also appears in the editor margin, where you can answer it in place.

1200.07

Comment for agent attaches a comment to a line of a project file, for a task you choose. Comments are your instructions to the agent and do not appear in the Brief. The agent sees open comments when it reads the task and records how it addressed each one.

Brief1 open ask Needs you · 1 01 Hero motion pass Pause: text or icon? Running · 1 02 Features figures Codex · drafting Ready · 2 03 Changelog entry 04 SEO check Blocked · 2 05 Access copy waits on 01 06 Launch checklist waits on 02, 05 Done · 1 V same plan Boardby dependency depth UnblockedAfter 1 stepAfter 2 steps 01Needs you Hero motion pass decision blocks 1 02Running Features figures Codex blocks 1 03Ready Next Changelog entry nothing upstream 04Ready Next SEO check nothing upstream 05Blocked Access copy waits on 01 06Blocked Launch checklist waits on 02 +1 Done · 1 hidden lines run to the task that waits
Fig. 1200.02 — One plan, two views. The Brief answers what needs you; the Board shows what can start and what waits on what. Copper marks the task an agent is working on. V switches views.
1200.08

Failure modes. Agents log a failure that recurs, tagged with the model it was seen on. Its guidance becomes an instruction only after you approve it in Agent workflows, and goes stale when no current agent reports that model.

1200.09 Failure mode status, computed when read
StatusCondition
candidateSeen fewer than two times.
unapprovedRecurring, but you have not approved its current text.
activeRecurring and approved, and a current agent reports one of its models, or none reports a model.
staleRecurring only on models no current agent reports.
Since 0.9.0 · comments and failure modes since 0.18.0 · Queue tab since 0.30.0, renamed Brief, with the Board, in 0.31.013
PRI-OM-001 · 1300.00 Shared browserRev 0.37.0

1300.00

Shared browser

1300.01

Each open project gets its own headless browser, shown in the Browser tab beside Content. Cookies and logins stay with the project and persist across launches. Agents drive the same page you see. The page fills the pane, as in Chrome with the device toolbar off.

Chrome project profile DevTools pipe Priori DevTools on 127.0.0.1, token screen, input Browser tab you click and type CDP priori-browser Playwright MCP Agent ask_user priori browser url or project file
Fig. 1300.01 — One browser, two drivers. The dashed path shows a page, a project file or a form to you without taking focus.
Way inBehavior
Browser tabYouClick, type, scroll and paste into the page, copy from it, or open it in your default browser.
priori-browserAgentsPlaywright MCP attached to the project’s browser. Agents open their own tab before navigating.
priori browser <url|file>A terminalShows a page or a project file, such as .agent-artifacts/report.html, in the Browser tab without taking focus. https, or http on localhost.
ask_userAgents, over MCPShows an HTML form in the Browser tab and returns the submitted fields as JSON. Gives up after 10 minutes.
DevTools endpointOther clientsThe Chrome DevTools Protocol on 127.0.0.1, with a token.
1300.02

Page size. Fill sets the page to the size of the pane in CSS pixels, at your display’s pixel ratio, and follows the pane as you resize it. Device mode (⌘⇧M) picks a size instead: Responsive with drag handles, phone and tablet presets, pixel ratio, Rotate and zoom. When an agent resizes the page, the toolbar shows its size marked Set by agent and the pane leaves it alone; choose Fill to take the pane back. After you choose Fill or a size of your own, the agent’s earlier size does not return when the page navigates; a new resize from the agent switches to device mode again.

1300.03

DevTools. The DevTools button, or ⌘⌥I, opens Chrome’s own DevTools on the page in the pane, docked at the bottom or the side: Elements, Console, Network, Sources and the rest. It is the front end bundled with your installed Chrome, so it works offline and matches that version, and it inspects the same page your agents use. Copying in DevTools or in the page reaches the macOS clipboard, including Copy element and Copy as cURL. DevTools file saves, such as Export HAR, open the macOS save panel. A dropdown on a page opens a Priori menu under the field, with the native picker’s keyboard behavior; date, time and color inputs open nothing.

Fill page = pane Fill yours default, display scalefollows the pane 390 × 844 · 3× Device mode yours ⌘⇧M, a size you choosepresets, rotate, zoom Set by agent 1280×720 Set by agent agent’s browser_resizethe pane stops overridingFill takes it back choose a size agent resizes ⌘⌥I page DevTools DevTools dock bottom or right draggable divider kept per project
Fig. 1300.02 — Who owns the page size. You own Fill and device mode; an agent’s resize takes the pane until you choose Fill. DevTools docks inside the pane.
1300.04

Priori serves DevTools on a random 127.0.0.1 port and requires a token readable only by your user. It refuses requests from web origins and gives each connection its own session. HTTP sign-in prompts are cancelled, so a page fails fast instead of waiting for an answer nobody can give.

Since 0.18.0 · ask_user since 0.19.0 · fill, device mode and DevTools since 0.31.0 · page dropdowns and DevTools saves since 0.33.014
PRI-OM-001 · 1400.00 MeetingsRev 0.37.0

1400.00

Meetings

1400.01

When Zoom, Teams, Slack, FaceTime, Webex, Discord, WhatsApp, Signal, Telegram or a browser holds the microphone for 15 seconds, Priori offers to record into the current project’s vault. It learns only which processes capture audio; it does not read their audio, window titles or calendars.

Priori, on this Mac 1 Detect meeting app holds the mic 15 s 2 Record microphone and system audio 3 Stop app releases the mic for 5 s 4 Transcribe on this Mac: Parakeet or Whisper 5 Speakers You, Speaker 1, named voices 6 Vault meeting.md, transcript.md 7 Agent tasks linked to a timestamp
Fig. 1400.01 — A meeting from detection to tasks. What the agent does with the transcript depends on your harness and its model.
RefStage
1Detect Priori offers to record into the current project. Remind me in 10 min, or dismiss until the call ends.
2Record Mono 16 kHz audio into the vault’s Meetings folder. Pause, resume and take notes while it runs.
3Stop Recording follows the app that prompted it. For a call in a browser, Priori asks before stopping.
4Transcribe One meeting at a time, across all projects. No audio is uploaded.
5Speakers You is the voice the microphone carries. With Parakeet, other voices are numbered or named from voice profiles; with Whisper they read Others.
6Vault Markdown your agent can read, plus transcript.json with timings for playback.
7Agent The agent reads the transcript and creates tasks that open the recording at the moment they came from.
1400.10 Transcription engines. Download each model once from Transcription setup; Priori verifies its size and SHA-256.
EngineRuns onLanguagesDownload
ParakeetParakeet TDT 0.6B v3 with speaker diarizationApple Silicon, macOS 14 or later25 European languagesAbout 505 MB
Whisperwhisper.cpp with large-v3-turboIntel Macs, and languages Parakeet does not coverMultilingualAbout 1.6 GB, plus whisper.cpp from Homebrew
1400.02

Name a speaker once and Priori recognizes the voice in later meetings, marking each match so you can correct it. A match needs a cosine similarity of at least 0.75 and a clear lead over every other profile; otherwise the speaker stays numbered.

1400.03

Voice profiles stay in Priori’s app data on this Mac, per project unless you turn on Use in all projects. They are never uploaded, sent to agents or written to the vault.

1400.04

The Priori item in the macOS menu bar shows the count of asks waiting on you across your projects and a dot while a meeting records. Its menu records, pauses and stops a meeting; lists asks and running agents from your open and recent projects, each opening where it belongs; opens recent projects or a new window; starts a new task; pauses meeting detection for one hour; and opens settings, updates and Open at login. The pause does not survive a restart.

Since 0.2.0 · Parakeet since 0.23.0 · menu bar since 0.33.015
PRI-OM-001 · 1500.00 TerminalsRev 0.37.0

1500.00

Terminals

1500.01

Each terminal tab is a real login shell. Run claude, codex or any other CLI directly; Priori does not wrap their protocols.

Saved at quit tabclaude directory~/code/site outputlast 2,000 rows agentClaude Code a1b2c3 relaunch … saved output — restored from previous session — ❯~/code/site Resume Claude Code session claude --resume a1b2c3
Fig. 1500.01 — A terminal across a relaunch. The shell is new; its directory, output and agent session carry over.
FeatureBehavior
QuickstartsOne button per harness set up in the project starts it in a new tab, with Priori’s orchestration policy appended to its instructions. Dimmed when the command is not on PATH.
RestoreTabs reopen in their directories with up to 2,000 rows of saved output. A tab that hosted an agent offers to resume it.
PanesOne to three panes, stacked. Hidden sessions keep running when you switch tabs or projects.
Search⌘F searches scrollback and shows the match count.
File links⌘-click opens code, text and images in Priori and web pages in your browser. Right-click a link to open it in the default browser or the Priori browser. Programs and installers are only shown in Finder.
Close checksClosing a tab or quitting asks first while jobs run, including agents waiting for input.
Limits5,000 lines of scrollback per terminal. Output is flow-controlled with a 64 KiB window, so a noisy program cannot flood the app.
1500.02

Resuming runs the harness’s own command with the session ID it reported: claude --resume, codex resume, pi --session or opencode --session. Nothing runs until you click.

Since 0.2.0 · quickstarts and restore since 0.19.016
PRI-OM-001 · 1600.00 Files, vault and projectsRev 0.37.0

1600.00

Files, vault and projects

1600.01

Project files on the left open as tabs in the middle: source in a code editor, Markdown as source or rich text. The linked vault is a separate folder of Markdown notes, diagrams and meetings. Priori adds a managed vault reference to the project’s AGENTS.md, keeping your instructions, so agents know where to read.

Project folder AGENTS.mdvault reference.priori/tasks.jsontasks.priori/workflow.jsontask history.priori/agents.jsonlevels, reportssrc/ …your code AGENTS.md points here Agent task tools vault tools, if granted Linked vaultany folder *.mdnotes, wiki linksDiagrams/shared canvasesMeetings/audio, transcripts
Fig. 1600.01 — Where things live. Tasks stay with the project; notes and meetings live in the vault you link. The dashed path exists only when you grant it at setup.
FeatureBehavior
Quick Open⌘P matches paths fuzzily, recently opened files first. Type > for commands.
Search contentsLiteral search across the project, including unsaved edits. Skipped files and limits are reported.
Git statusChanged files show their Git letter; Review changes shows the diff.
External changesOpen files are checked every two seconds. Clean tabs refresh; tabs with edits offer Review and merge.
Draft recoveryUnsaved text, Markdown and diagram drafts survive a crash or quit and are offered when you reopen.
Rename, move, TrashNever overwrites. Move to Trash shows Undo for 5 seconds.
DiagramsA canvas in the vault that you and agents edit by stable node ID. It communicates; it does not execute.
ProjectsSynced folders list their child directories. Windows and projects reopen after quitting.
Editor keysCode files and the Markdown source view take VS Code’s macOS keys: multiple cursors (⌥-click, ⌘D for the next match, ⇧⌘L for all, ⌥⇧-drag for a column), moving and copying lines (⌥↑↓, ⇧⌥↑↓), ⇧⌘K to delete a line, ⌘/ to comment, find and replace (⌘F, ⌥⌘F), go to line (⌃G), folding and auto-closing brackets. Rich-text Markdown keeps one cursor.
Tab orderDrag file, terminal and browser tabs to reorder them, or move the active tab with ⌥⇧⌘[ and ⌥⇧⌘]. File and terminal tab order survives a restart; Chrome keeps no page order, so the browser’s lasts while the view stays connected.
Project pickerA new window opens on a search over recent projects, then open and synced-folder projects, with Create project, Open folder and Open Markdown file below. ⌘P with no project open shows the same list. A project open in another window is marked, and opening it brings that window forward.
priori commandOpen or create a project from a terminal; agents do the same over MCP. An open project brings its window forward. Install it from Settings → Integrations.
AppearanceSeparate light and dark schemes. Import Ghostty or iTerm2 themes.
UpdatesSigned releases install from Settings. The top bar shows when one is available.
1600.02

Agents reach the vault through MCP only when you grant it at setup. Notes are read and written with revision checks, transcripts are read-only, and audio is never exposed. Without the grant, task tools still work.