CLI Commands

All Xavier commands live under the /xavier namespace.

/xavier setup

Scaffolds the vault, runs the interactive interview, and configures Xavier for your workflow.

/xavier setup

What it does:

1. Creates ~/.xavier/ with the full directory structure
2. Initializes as a git repository
3. Creates a private GitHub repo (default name: xavier-ai)
4. Detects the active runtime and wires the adapter
5. Installs default reviewer personas (correctness, security, performance)
6. Interviews you: name, teams, preferences, review priorities, git strategy, export vault path
7. Detects existing global skills and coexists without conflict

Re-running setup: safe to run on an existing vault. Updates preferences without losing content.

/xavier review

Spawns concurrent persona-driven reviewers to analyze your code changes.

/xavier review

What it does:

1. Loads vault context (team conventions, recurring review patterns)
2. Detects the current diff via git diff
3. Spawns 3 reviewer remoras in parallel (correctness, security, performance)
4. Aggregates findings incrementally as each reviewer completes
5. Delivers a verdict: approve, request changes, or rethink
6. Stores the review note in ~/.xavier/knowledge/reviews/

Active learning: if 2+ past reviews exist for this repo, recurring patterns are injected into reviewer prompts automatically.

Persona override: place persona files in <your-repo>/.xavier/personas/ to override global personas for that repo.

Multi-model debate (optional): if the external agent CLI plus dispatch.sh/parse.sh scripts are available, review additionally dispatches to GPT and Gemini in parallel with merged findings. See Code Review → Multi-Model Debate.

/xavier add-dep

Adds a dependency-skill to the vault.

/xavier add-dep <package-name>

Example:

/xavier add-dep drizzle-orm

Creates ~/.xavier/skills/drizzle-orm/ with best practices, API patterns, and documentation links.

/xavier remove-dep

Removes a dependency-skill from the vault.

/xavier remove-dep <package-name>

/xavier deps-update

Checks lockfile versions against existing dependency-skills and regenerates stale ones.

/xavier deps-update

Run this after updating dependencies in your project.

/xavier learn

Scans the current repository and generates knowledge notes in the vault.

/xavier learn [path]

Scoped mode: [path] is optional and relative to the git root. When provided, Xavier scopes analysis to that subdirectory, derives <app-name> from its package manifest (with @org/ stripping and kebab-case, falling back to the leaf directory name), and writes notes to ~/.xavier/knowledge/repos/<monorepo>/<app>/. When omitted, behavior is unchanged (full-repo scan).

See the Scoped Mode section in the Learning guide for the full story.

What it produces:

• Architecture map (modules, responsibilities, connections)
• Decision log (inferred architectural decisions)
• Dependency graph (internal modules, external deps, entry points)
• Dependency-skills for packages you select

Ecosystem: Node.js projects only (package.json).

/xavier investigate

Hypothesis-driven bug investigation.

/xavier investigate <symptom> [--file <path>] [--test <name>]

Spawns parallel remoras across 5 fixed axes (code path, recent changes, dependency boundaries, test coverage, error patterns) plus 1–2 dynamic axes per symptom. Produces a ranked list of probable causes with evidence strength (strong/moderate/weak). Saves the diagnosis to ~/.xavier/investigations/.

Flags:

• --file <path>: anchor to a specific entry-point file. Canonicalized and required to resolve under the repo root.
• --test <name>: anchor to a failing test name.

Re-run: on a repo with existing investigations, you'll be offered "related or new?" — picking "new" appends an HHMM suffix to the filename to avoid collision.

See the Investigate guide for a walkthrough.

/xavier research

Topic-driven "teach me" skill.

/xavier research <topic> [--plan]

Decomposes the topic into 3–5 sub-questions (Foundations, Practice, State of Art + 1–2 dynamic axes + Local Context when in a git repo), spawns one remora per question, and synthesizes a digest with TL;DR + sections + sources. Saves to ~/.xavier/research/.

Flags:

• --plan: preview and edit the decomposed questions before remoras spawn.

Re-run: if a prior note exists for the topic, you're asked "update or start fresh?" — updating passes the prior note to remoras as context.

See the Research guide.

/xavier prd

Interactive PRD creation enriched with vault context.

/xavier prd

Flow:

1. Browse and select relevant vault context (past PRDs, architecture notes, team conventions)
2. Interactive interview about the problem and solution
3. User verification quiz
4. PRD written to ~/.xavier/prd/

/xavier tasks

Decomposes a PRD into phased implementation tasks.

/xavier tasks

Flow:

1. Select a PRD from ~/.xavier/prd/
2. Codebase exploration
3. Vault context loaded via PRD's wikilinks
4. Vertical slice decomposition with acceptance criteria and backpressure commands
5. Tasks written to ~/.xavier/tasks/

/xavier loop

Autonomous iteration engine for executing task phases.

Task-file mode

/xavier loop

Select a task file from ~/.xavier/tasks/. The loop executes phases in order with backpressure verification.

Freeform mode

/xavier loop "Refactor all handlers to use the new error pattern"

Accepts a plain description without requiring a formal task file.

Guardrails:

• Strict backpressure pre-flight (all checks must pass before starting)
• Automated verification after each phase
• Max iteration limits
• Completion promises

/xavier feedback

Opens a GitHub Discussion in the upstream Xavier repo with category selection. Use for product feedback and feature suggestions.

/xavier feedback

See Contributing Back in How It Works.

/xavier bug

Files a GitHub Issue with structured prompts (skill, expected, actual) and auto-appended Xavier version and OS info. Use for reproducible bugs.

/xavier bug

See Contributing Back.

/xavier export

Exports a vault note to your personal Obsidian vault.

With a path

/xavier export prd/webhook-support

Interactive

/xavier export

Browse exportable notes and select one.

Exportable directories: prd/, tasks/, knowledge/repos/, knowledge/teams/, knowledge/reviews/

Destination: <your-vault>/x-inbox/x-<filename>.md