Quickstart

Five minutes, start to finish. You need Node 22 or newer and a git repository.

1. Run it

cd your-project
npx opencastle init

It reads the repository before asking anything: which assistants already have config, which framework and database you use, which test runner. Then it shows what it found and asks once.

  🏰 OpenCastle

  Found assistant config:
    • Claude Code (CLAUDE.md)

  Will compile for:
    → Claude Code

  Integrations detected:
    nextjs, supabase, vitest, chrome-devtools

  Set this up? [Y/n]

Answer yes. It finishes in a second or two.

Nothing you wrote is overwritten. If you already had a CLAUDE.md, your content stays exactly where it is and the generated config goes into a marked block below it:

# Acme Web

Use pnpm, never npm. Deploy via `make ship`.

---

<!-- >>> OpenCastle managed — regenerated by `opencastle sync`, edits here are lost >>> -->
...
<!-- <<< OpenCastle managed <<< -->

Everything above that marker is yours forever. Everything inside it is regenerated.

2. See where you stand

opencastle

This is the one command worth remembering. It reports what is installed, whether the generated files are still current, which assistants are configured but not being compiled, and the single next command to run:

  🏰 OpenCastle

  ! 1/1 target in sync (sources are newer)
    ✓ claude-code    up to date

  Next: opencastle sync
  generated files are older than the framework sources

3. Add your team's other assistants

The point of the tool is that one source feeds every assistant. If your team also uses Cursor and Copilot:

opencastle init --customize

Pick the extra targets. Each gets that assistant's native format — Cursor's .mdc rule files with alwaysApply, Windsurf's .md rules with a trigger enum, Copilot's .github/ layout — from the same source.

4. Keep it honest in CI

# .github/workflows/opencastle.yml
name: opencastle
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npx opencastle sync --check

sync --check compiles to a scratch directory and compares. It writes nothing, and exits non-zero when a generated file no longer matches its source — someone edited .cursor/rules/foo.mdc by hand, or upgraded without recompiling. Without this, drift is invisible: a stale rule file still loads fine.

Everyday commands

Command	What it does
opencastle	Status and the next step
opencastle sync	Recompile every target
opencastle sync --check	Fail on drift, write nothing
opencastle add <pack>	Adopt a tool and recompile
opencastle doctor	Deeper diagnostics with fixes
opencastle remove	Uninstall, keeping or deleting files

Run opencastle <command> --help for the flags.

Where things live

Path	Yours or ours
.opencastle/	Yours. Project conventions, stack notes, lessons. Never overwritten.
Everything around the managed block in CLAUDE.md etc.	Yours. Kept byte for byte.
The managed block itself	Ours. Regenerated on every sync.
.claude/, .cursor/rules/, .github/	Ours. Regenerated on every sync.

Commit all of it. Generated config is committed like a lockfile: a teammate who clones the repo gets working rules without running anything, and sync --check has something to check. Only .env and run artefacts under .opencastle/ are gitignored.

Upgrading from 0.35 or earlier

Run opencastle sync. It repairs the three things older versions recorded differently, and prints what it did:

• The .gitignore block used to hide every generated file, including the root instruction file. sync rewrites it so the compiled output can be committed.
• The manifest used to file CLAUDE.md (and the other root files) as wholly generated. Until that is repaired, remove --all had licence to delete a file you write in.
• Root files generated by an older release carry no markers. sync recognises them and replaces them with a managed block, keeping the previous contents as CLAUDE.md.opencastle-backup in case you had appended anything.

opencastle doctor reports the first two if you would rather look before acting.

To change what the assistants are told, edit .opencastle/ — not the generated files. sync --check exists to tell you when someone forgets: it reports files edited in place, files never generated, and files added by hand under a generated directory (the next sync would delete those).

Adding a tool later

opencastle add supabase
opencastle add --list      # see what's available

That updates the stored stack and recompiles, so the new integration's skills and MCP config reach every target.

Convoy (experimental)

For long multi-step work, opencastle convoy "<task>" plans it, runs it across isolated git worktrees, and resumes after an interruption. It is experimental and may change; the compiler does not depend on it.

opencastle convoy "Add user reviews to the place detail page"
opencastle convoy            # where did the last run get to?
opencastle convoy resume     # continue after an interruption