Docs

Install

Confirm what it found

It reads your repository first — which assistants already have config, which framework, database, and test runner you use — shows the plan, and asks once. Files you already wrote are never overwritten: your CLAUDE.md keeps its content and the generated config goes into a managed block below it. Prefer to choose by hand? npx opencastle init --customize.

Open your IDE

Bootstrap your project

If you have an existing codebase, run the bootstrap prompt first. It scans your project and generates tailored configuration.

Skip this step for brand-new projects — there’s nothing to detect yet.

Start building

You’re ready to go. Choose how you want to work:

Ask what needs doing

Run opencastle with no arguments. It reports which targets exist, whether the generated files are still current, which assistants are configured but not being compiled, and the one command to run next.

Recompile

opencastle sync regenerates every target from source. Your .opencastle/ customizations and anything outside a managed block are left alone.

Catch drift in CI

opencastle 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, dropped a file into a generated directory, or upgraded without recompiling. Without it, drift is invisible: a stale rule file still loads fine.

Commit the generated config, like a lockfile — that is what gives the check something to compare, and what lets a teammate clone the repo and have working rules without running anything. Only .env and run artefacts are gitignored.

# .github/workflows/opencastle.yml
- uses: actions/setup-node@v4
  with: { node-version: 22 }
- run: npx opencastle sync --check

Adopt a new tool

opencastle add supabase updates the stored stack and recompiles, so the integration's skills and MCP config reach every target. opencastle add --list shows what is available.