Docs

Install

Needs Node.js 22.5 or newer.

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: Set this up? [Y/n]. --yes accepts without asking. Prefer to choose by hand? npx opencastle init --customize.

Root files you wrote — CLAUDE.md, .cursorrules, AGENTS.md, copilot-instructions.md — keep your content above a managed block. A file of yours inside a directory OpenCastle generates, such as .cursor/rules/ or .claude/agents/, is named by init and removed by the next sync: move it into .opencastle/ and it is compiled for every assistant. A skill another tool wrote there is kept: sync moves it into .opencastle/skills/ for you.

Open your assistant

Bootstrap an existing codebase

init has written the stack, structure, commands, routes and models into .opencastle/ from the code. Run the bootstrap-customizations prompt once to fill in what files cannot say — architecture, access rules, test conventions — listed at the end of each file. It ends by running npx opencastle sync, so every assistant gets the result.

Skip this step for brand-new projects — there’s nothing to detect yet. How each assistant runs a prompt: Prompt Templates.

Start building

Choose how you want to work:

Ask what needs doing

Run npx 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

npx opencastle sync regenerates every target from source. Your customizations in .opencastle/ are kept, and so is your content above the managed block of a root file such as CLAUDE.md. A file added by hand inside a generated directory, such as .cursor/rules/, is removed — put it in .opencastle/ and it is compiled for every assistant.

Catch drift in CI

npx 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.

Run npm i -D opencastle && npx opencastle ci once. It writes .github/workflows/opencastle.yml: checkout, install, sync --check with the OpenCastle version the project uses, and review on pull requests. On another CI, run npx opencastle sync --check with opencastle as a devDependency. See opencastle ci.

Adopt a new tool

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

Upgrade

npm i -D opencastle@latest, then npx opencastle sync: it names each file it removes and counts the ones it changes; git diff shows them all. Read the diff and commit it. Something not working? Troubleshooting.

Share it across a team

npx opencastle baseline init starts a standard every repository can extend, and npx opencastle explain shows a new teammate what their assistant is given and what they still need to set up. See OpenCastle for Teams.