Getting started

Excalibur Core is the AI coding agent for product engineers. Most agents write code; Excalibur knows the whole product cycle — discover, build, verify, ship — on any model, in any terminal, local-first. It's zero-config: install it, run it, start building.

Prerequisites

• Node.js ≥ 22 and a package manager (npm, pnpm or yarn).
• A git repository — Excalibur works inside any repo and isolates its work in branches.
• An API key for one model provider — or run a local model with Ollama, free and offline. You paste the key during setup; Excalibur saves it to a private local file (~/.config/excalibur/secrets.env, owner-only 0600) and loads it automatically. Your committed config never contains the key — only the name of the env var that holds it.

1. Install

npm install -g @excalibur-oss/excalibur

One global, self-contained package — no peer resolution. Verify it's on your PATH:

excalibur --version
excalibur doctor      # checks Node, git, provider config and PATH

2. Run it

Just run excalibur in your repo. There's no setup step to remember — on the first run Excalibur onboards you: detects your stack, connects a model, writes a minimal .excalibur/, and drops you into the m-shell — its conversational surface.

cd your-repo
excalibur

3. Build something

Describe what you want in plain language. Excalibur routes intent to the right workflow, shows the plan, and works in the open with a live TUI.

In the shell, or as a command

Everything the shell does is also a one-shot command — for scripts, hooks and CI. Two ways to do the same thing:

# from your normal shell (programmatic):
excalibur run "add pagination to the orders endpoint"   # L3 — build in a branch
excalibur review                                         # L0 — read & critique
excalibur patch "fix the timezone bug in invoices"       # L2 — a reviewable patch
excalibur ask "how does the retry logic work?"           # L1 — just answer
excalibur discovery "should we add SSO reminders?"       # decide before building

Inside the m-shell, the same actions are natural language or /commands:

See Autonomy levels for what L0–L4 mean, and the full command reference.

Optional: set up up front

You don't need this — but to scaffold config explicitly (handy for teams or CI), run init:

To switch or add model providers later, run excalibur models setup. Full matrix in Models & providers.

Where work lands

Every run is recorded locally — nothing is hidden:

.excalibur/runs/<run-id>/
├── run.json        # workflow, autonomy, model, tokens, cost, timing
├── events.jsonl    # the full, replayable event stream
├── diff.patch      # the accumulated change
└── summary.md      # what happened and why

That immutable, append-only event stream is the single source of truth — the same data renders the live run, the replay, the web dashboard and the audit trail, byte-identical. It powers the time machine: excalibur rewind <run-id> (or /rewind in the shell) scrubs a run step by step and forks a new run from any point. Nothing good is thrown away.

Safe from the first command

The standard-safe preset is active immediately: writes, applies and branches ask for approval; push and network are disabled; .env files, keys and other sensitive paths are blocked. Full model in Safety.

Handy commands

excalibur status      # repo config, provider, safety preset
excalibur logs        # recent runs
excalibur serve       # open the local web dashboard (kanban, runs, cost, live orchestration)
excalibur doctor      # diagnose setup problems
excalibur workflows list
excalibur models list

Troubleshooting

Next steps

• The m-shell — the conversational surface in depth.
• Missions — give a goal, get the whole cycle planned and driven for you.
• Command reference — every slash command and CLI command.
• Dashboard — the local web board: kanban, runs, cost, live orchestration.
• Workflows — the 14 built-in recipes.