Guide 1 of 3
Set up your project
Add a .cumaru/ tree to your repository and connect your coding agent to it. At the end,
every new agent session loads the framework rules on its own.
Before you start
- The
cumaruCLI is installed. If not, install it first. - cURL is on your
PATH. Install reads the domain from GitHub. - You are at the project root, and the project has no
.cumaruentry yet. Commit or stash your work first, so you can review the changes.
1. Choose a domain
A domain sets the folders, roles, and skills that Cumaru installs. You must choose one. Without --domain, the CLI installs base, the minimal kernel, not sdlc-light.
cumaru help domains lists the current domains. Source: Available domains.
2. Choose your agent and install
Pick the agent you use in this project. The command installs the domain and that agent's integration in one step.
Codex
cumaru install agent codex --domain <domain> Choose a domain in step 1. Replace <domain> if you copy by hand.
This writes three parts of the integration:
- Instructions:
AGENTS.mdloads the framework rules. - Skills:
.agents/skills/cumaru-*holds the guided workflows. - Hooks:
.codex/hooks.jsonregisters the session, prompt, and read hooks.
Claude
cumaru install agent claude --domain <domain> Choose a domain in step 1. Replace <domain> if you copy by hand.
This writes three parts of the integration:
- Instructions:
CLAUDE.mdloads the framework rules. - Skills:
.claude/skills/cumaru-*holds the guided workflows. - Hooks:
.claude/settings.jsonregisters the session, prompt, and read hooks.
What the integration does
- At session start, the agent receives the framework rules and the top of your knowledge tree.
- Before each prompt, the agent gets a short reminder of the active disciplines.
- When the agent tries to read a
.cumaru/Markdown file with a shell command, it is pointed tocumaru mapandcumaru getfor guided reads.
Install merges these entries into existing files. It keeps your own instructions, settings, and other hooks.
Already have .cumaru/?
Do not run install again; it refuses an existing tree. To add or refresh an agent, preview the change, then apply it:
cumaru update agent codex cumaru update agent codex --apply Other agents
Cumaru also supports OpenCode and a generic none adapter. See the agent adapters reference.
3. Reopen your agent
Close the agent session and start a new one in the project root. A running session does not load new instructions or hooks. Your client may ask you to trust the project or approve the hooks.
4. Check your setup
Run doctor. It validates the tree and the instructions:
cumaru doctor Doctor does not check skills or hooks. Confirm the hook file contains the Cumaru entries:
grep -n 'cumaru hooks' .codex/hooks.json Then ask the new agent session what it loaded:
Which Cumaru files and disciplines did you load at the start of this session? List them, then run `cumaru tree . --rows` and show the root candidates. The answer should name .cumaru/index.md, domain.md, and the disciplines.
Sources: Project installation, Agent adapters, Update. The agent check prompt is guidance from this site, not a CLI feature.