How It Works

Xavier's architecture rests on two ideas: non-blocking agent orchestration (the Shark pattern) and compounding knowledge (the Zettelkasten vault). This page explains both.

The Shark pattern

Xavier uses the Shark pattern as its concurrency model. Three roles:

Shark (main thread)

The dispatcher. Receives commands, immediately delegates slow work. Never blocks, never implements — only orchestrates.

When you run /xavier review, the shark detects the diff, loads vault context, and spawns reviewers. It doesn't do the reviewing itself.

Remora (background workers)

One per task. Each remora gets a specific job:

• In review: one remora per reviewer persona
• In learn: one remora per directory being scanned
• In loop: one remora per task phase

Remoras run in parallel via the runtime adapter (e.g., Claude Code's Agent tool with run_in_background: true).

Pilot fish (aggregator)

Starts synthesizing results as soon as the first remora completes. No waiting for all workers to finish before processing begins.

In review, the pilot fish categorizes findings, deduplicates across reviewers, and builds the synthesized review incrementally.

Detect-and-defer

Xavier checks the SHARK_TASK_HASH environment variable on startup:

• Present → Xavier is inside an external Shark loop. It defers to the outer loop's protocol to avoid double-scheduling and poller collisions
• Absent → Xavier uses its built-in Shark execution layer

This means Xavier plays well with other Shark-based tools.

The Zettelkasten vault

Xavier's knowledge vault (~/.xavier/) is structured as a Zettelkasten — a network of atomic, interlinked notes using Obsidian-flavored Markdown.

Why Zettelkasten?

• Atomic notes — each note covers one thing (one architecture map, one review, one decision)
• Lazy loading — wikilinks are pointers, followed only when relevant. Agents don't bulk-load the entire vault
• Composable context — a review can pull in team conventions, architecture notes, and past reviews by following links
• No context pollution — only what's relevant gets loaded

Frontmatter schema

Every note has consistent YAML frontmatter for scoping and querying:

---
repo: my-app
team: platform
scope: workspace-service    # optional (monorepo package, service name)
domain: auth
type: architecture          # architecture | decision | dependency | prd | task | review
tags: [jwt, middleware]
related: [knowledge/teams/platform-conventions]
created: 2026-04-08
updated: 2026-04-08
---

Knowledge routing

• Per-repo knowledge is centralized in the vault, scoped by frontmatter — not scattered across repos
• Team knowledge is first-class under knowledge/teams/. During /xavier learn, Xavier resolves the repo's team and links conventions via wikilinks
• Agents navigate the graph lazily — they follow links only when relevant to the current task

How knowledge compounds

Every operation adds to the vault:

Over time, Xavier's suggestions get sharper because it's working with your accumulated knowledge, not starting from scratch.

Runtime adapters

Xavier separates knowledge from execution:

Portable layer (plain files)

• Vault notes, personas, config, prompt templates
• Any runtime can read these — they're just markdown

Pluggable layer (runtime-specific)

• Agent spawning, background execution, polling
• Implemented as adapters in ~/.xavier/adapters/

This is why Xavier is distributed via curl | sh rather than as a plugin — it's not tied to any single runtime.

Vault sync

The vault is a git repository backed by a private GitHub repo. Before writing, Xavier pulls from the remote first, then applies changes. Conflicts are handled like any git repository.

Your git strategy (configured during setup) controls when commits happen:

• Auto-commit — every vault write triggers a commit
• Batch-commit — commits at natural checkpoints (default)
• User-driven — never auto-commits, periodic reminders
• Batch-commit + auto-push — batch commits that also push to remote