Documentation

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 cumaru CLI 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 .cumaru entry 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.md loads the framework rules.
  • Skills: .agents/skills/cumaru-* holds the guided workflows.
  • Hooks: .codex/hooks.json registers 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.md loads the framework rules.
  • Skills: .claude/skills/cumaru-* holds the guided workflows.
  • Hooks: .claude/settings.json registers 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 to cumaru map and cumaru get for 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.

Next: bootstrap your knowledge