matilha — CLI

You lead. Agents hunt. Methodology harness CLI for AI-assisted software development.

🏠 This is the CLI twin. The official matilha entry point is danilods/matilha-skills — the Claude Code plugin ecosystem with 146 skills across 7 companion packs. This CLI is the low-friction installer and deterministic engine for power-user workflows, CI, and automation.

Fastest Start

For Claude Code users, this is the shortest path:

npm install -g matilha
matilha install --full --deep --with-claudemd

Then in Claude Code:

/reload-plugins

Open a new Claude Code prompt and start working normally. For software work, matilha-compose should route first, then hand off to the right Matilha phase or companion skill.

That installs:

matilha core methodology plugin
all 7 companion packs
the CLAUDE.md activation-priority snippet for reliable routing

If the claude CLI is not available on your PATH, Matilha automatically falls back to a paste block you can copy into Claude Code.

Codex And Cursor

Matilha can also install the same core skills and packs without Claude Code.

Codex

Install globally for Codex:

npm install -g matilha@latest
matilha install --target codex --full --scope user

This writes skills to:

~/.agents/skills/

Restart Codex or open a new session so the skill list refreshes.

For a single project instead of global/user install:

matilha install --target codex --full --scope project

That writes to:

.agents/skills/

Cursor

Run from the project root:

npm install -g matilha@latest
matilha install --target cursor --full

This writes:

.cursor/skills/
.cursor/rules/matilha.mdc

Open a new Cursor Agent chat so the rule and skills refresh.

Pick Packs For Codex Or Cursor

Use the same picker, just change the target:

matilha install --target codex
matilha install --target cursor

For Codex/Cursor, no --deep flag is needed: Matilha installs local skill files directly. --deep is only for Claude Code because it shells out to claude plugin install.

What Gets Installed

Matilha has two layers:

Layer	Installed by	What it does
npm CLI	`npm install -g matilha`	Gives you the `matilha` command: start, status, discover, spec, approve, split, merge, install/update packs
Claude Code plugins	`matilha install --deep`	Installs `matilha-skills` and companion packs inside Claude Code
Codex local skills	`matilha install --target codex`	Installs skills into `~/.agents/skills` or `.agents/skills`
Cursor project skills	`matilha install --target cursor`	Installs skills into `.cursor/skills` and writes `.cursor/rules/matilha.mdc`

Important: updating the npm CLI does not automatically update Claude Code plugins. To update both, run:

npm install -g matilha@latest
matilha install --full --deep --with-claudemd

Then reload Claude Code plugins:

/reload-plugins

Choose Packs

Interactive — pick your packs

matilha install --deep

Launches a guided picker:

Choose a preset or Custom to select packs individually.
Confirm whether to write the CLAUDE.md activation snippet.
Installs directly through claude plugin install.

Presets available: backend · ux · fullstack · security · core-only · custom

If you prefer not to run the Claude CLI, omit --deep:

matilha install

Matilha prints and copies a /plugin marketplace add + /plugin install block for you to paste into Claude Code.

Non-interactive — install everything in one shot

matilha install --full --deep --with-claudemd

What --full --deep --with-claudemd does:

Adds danilods/matilha-skills to the Claude Code marketplace
Runs claude plugin install for each of the 8 plugins (core + 7 packs)
Writes the activation-priority snippet to ./CLAUDE.md

Then in Claude Code: /reload-plugins → done.

Preset examples

matilha install --core-only --deep
matilha install --preset backend --deep --with-claudemd
matilha install --preset ux --deep --with-claudemd
matilha install --preset fullstack --deep --with-claudemd
matilha install --preset security --deep --with-claudemd

All flags

Flag	Effect
(no flags)	Interactive picker — preset or custom multiselect
`--full`	Non-interactive: core + all 7 companion packs
`--core-only`	Non-interactive: core plugin only
`--preset <name>`	Non-interactive: `backend` · `ux` · `fullstack` · `security`
`--deep`	Run `claude plugin install` directly instead of emitting a paste block (requires `claude` CLI on PATH)
`--target <name>`	`claude` (default) · `codex` · `cursor`
`--scope <name>`	For Codex/Cursor local installs: `user` or `project`
`--with-claudemd`	Also write/merge the CLAUDE.md activation-priority snippet
`--no-clipboard`	Print paste block to stdout instead of copying to clipboard

Commands

matilha --help

Matilha is state-guided. Commands remain scriptable, but interactive runs show a compact next-step recommendation so you do not have to remember the whole workflow.

matilha status
matilha status --no-guide
matilha --guide status

Command	Phase	Description
`install`	—	Install Matilha skills and optional companion packs
`start`	—	Start or refresh Matilha control files
`status`	0	Show current project phase + next action
`discover`	00→10	Map the problem space before planning or coding
`spec <slug>`	10→30	Create or continue a feature spec + implementation plan
`approve [gate]`	any	Validate and approve a phase gate
`progress`	any	Show feature artifacts + gate state
`split <slug>`	40	Split a plan into parallel worktree tasks
`merge <slug>`	40	Merge completed worktree tasks, run regression, and clean worktrees by default
`jira init`	optional	Install the local Jira skill + example JSON contract
`jira validate/preview/apply`	optional	Validate, review, then apply Jira task contracts
`jira sync`	optional	Sync Matilha completion events to Jira after preview + approval
`list`	—	List skills in the matilha registry
`pull <slug>`	—	Pull a skill or resource from the registry

Legacy aliases still work: install-plugins, init, howl, scout, plan, attest, plan-status, hunt, and gather.

Context Control

matilha start keeps provider control files intentionally small.

Instead of growing CLAUDE.md, AGENTS.md, or .cursor/rules/matilha.mdc with full methodology text, Matilha writes compact pointers and creates:

docs/matilha/context.md

Clean-session restore order:

Read project-status.md
Read docs/matilha/context.md
Open only the relevant spec, plan, wave, or skill files for the current task

This keeps Claude Code, Codex, Cursor, and other agent CLIs under their control-file limits while preserving durable context across fresh sessions.

Worktree Hygiene

matilha split <slug> creates one worktree per parallel SP. After a successful wave, matilha merge <slug> now removes completed SP worktrees and deletes merged SP branches by default.

Use this only when you want to inspect the worktrees after merge:

matilha merge <slug> --keep-worktrees

Optional Jira Flow

Jira automation is optional and contract-first. The agent turns Matilha specs, plans, waves, and SPs into a generic work item JSON contract; the CLI validates, previews, and only mutates Jira after explicit approval.

Bootstrap the local skill and example contract:

matilha jira init

This writes:

.agents/skills/matilha-jira/SKILL.md
docs/matilha/jira/tasks.example.json
docs/matilha/jira/tutorial.md

Read the tutorial first when wiring this into a real sprint:

cat docs/matilha/jira/tutorial.md

Recommended flow:

matilha jira validate docs/matilha/jira/tasks.json
matilha jira preview docs/matilha/jira/tasks.json
matilha jira apply docs/matilha/jira/tasks.json --yes

From spec/plan to tasks:

Read project-status.md plus the accepted spec and plan for <feature>.
Create docs/matilha/jira/tasks.json using schema_version 1.
Generate one generic work item per independently executable task.
If the plan contains 100 tasks, include all 100 tasks in tasks[].
Run matilha jira validate and matilha jira preview.
Do not apply until I approve the preview.

Contract shape:

{
  "schema_version": 1,
  "project_key": "MAT",
  "defaults": {
    "issue_type": "Task",
    "labels": ["matilha", "ai-assisted"],
    "story_points_field": "customfield_10016"
  },
  "tasks": [
    {
      "external_id": "feat-auth-SP1",
      "summary": "Implement login flow",
      "description_markdown": "Build login, logout, and session validation.",
      "story_points": 0.5
    }
  ]
}

For large batches, there is no special mode: every item in tasks[] is validated, previewed, and applied. If preview shows 100 task(s) ready, matilha jira apply docs/matilha/jira/tasks.json --yes attempts to create all 100 issues, preserving each external_id as Matilha traceability metadata. For readability, large previews show the full task table and omit the converted Jira payload dump; the JSON contract remains the source of truth.

For real Jira calls, set:

export JIRA_BASE_URL="https://your-domain.atlassian.net"
export JIRA_EMAIL="you@example.com"
export JIRA_API_TOKEN="..."
export JIRA_PROJECT_KEY="MAT"
export JIRA_STORY_POINTS_FIELD="customfield_10016"

Matilha converts descriptions/comments to Jira ADF, stores external_id as an issue property, keeps source.spec/source.plan/source.sp as traceability metadata, and refuses apply unless --yes is present.

Completion Hook

After matilha merge <slug> successfully merges an SP, passes regression tests, and marks it as completed, Matilha writes a local completion event:

docs/matilha/events/outbox/*.json

That hook is local and durable. It does not call Jira by itself. To update Jira comments, worklogs, story points, and Matilha issue properties, run:

matilha jira sync --preview
matilha jira sync --yes

Synced events move to:

docs/matilha/events/processed/

To enrich a completion update, the SP can add optional tracking metadata to SP-DONE.md:

tracking:
  story_points: 0.25
  worklog: "15m"
  comment_markdown: "Implemented, tested, and merged by Matilha."
  observations:
    - "No migration rollback needed."

Use matilha merge <slug> --no-events only when you intentionally want to skip local completion-event emission.

Plugin ecosystem

The CLI is one of two install surfaces. The other is the Claude Code plugin:

Surface	Install	Best for
npm CLI (`matilha`)	`npm install -g matilha`	CI, scripts, headless automation, power users
Plugin (`matilha-skills`)	`matilha install --deep` or `/matilha-install` wizard	Interactive development inside Claude Code

Both share the same methodology content from danilods/matilha-skills.

Contributing

Contributions are welcome, especially around CLI compatibility, skill quality, methodology docs, and real-world agent workflows.

Good first areas:

Improve installers for Codex, Cursor, Claude Code, Gemini CLI, and other AI coding CLIs.
Add or refine high-quality skills in the companion pack ecosystem.
Improve Matilha phase docs, gates, templates, and examples.
Report rough edges from real Claude Code, Codex, Cursor Agent, or multi-agent development sessions.
Propose methodology improvements inspired by practical AI software development patterns, including Karpathy-style workflows.

Before opening a PR:

npm install
npm run typecheck
npm test
npm run build

For skill and pack contributions, start in danilods/matilha-skills. For CLI installers, commands, packaging, and automation, use this repository.

Search terms: AI agents, agent skills, Claude Code, Claude skills, Codex skills, OpenAI Codex, Cursor Agent, Gemini CLI, Karpathy, prompt engineering, vibe coding, AI-assisted software development.

Update

npm install -g matilha@latest
matilha --version

To also update Claude Code plugins and packs:

matilha install --full --deep --with-claudemd

Then in Claude Code:

/reload-plugins

Use the interactive updater when you only want selected packs:

matilha install --deep

Uninstall

# Remove the CLI
npm uninstall -g matilha

# Remove the Claude Code plugins
claude plugin uninstall matilha --scope user
claude plugin uninstall matilha-ux-pack --scope user
claude plugin uninstall matilha-growth-pack --scope user
claude plugin uninstall matilha-harness-pack --scope user
claude plugin uninstall matilha-sysdesign-pack --scope user
claude plugin uninstall matilha-software-eng-pack --scope user
claude plugin uninstall matilha-software-arch-pack --scope user
claude plugin uninstall matilha-security-pack --scope user

Optional: remove the CLAUDE.md activation snippet — it sits between  and  markers.

Try locally

git clone https://github.com/danilods/matilha.git
cd matilha
npm install
npm run build
node dist/cli.js --help

Name		Name	Last commit message	Last commit date
docs/superpowers		docs/superpowers
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

matilha — CLI

Fastest Start

Codex And Cursor

Codex

Cursor

Pick Packs For Codex Or Cursor

What Gets Installed

Choose Packs

Interactive — pick your packs

Non-interactive — install everything in one shot

Preset examples

All flags

Commands

Context Control

Worktree Hygiene

Optional Jira Flow

Completion Hook

Plugin ecosystem

Contributing

Update

Uninstall

Try locally

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

matilha — CLI

Fastest Start

Codex And Cursor

Codex

Cursor

Pick Packs For Codex Or Cursor

What Gets Installed

Choose Packs

Interactive — pick your packs

Non-interactive — install everything in one shot

Preset examples

All flags

Commands

Context Control

Worktree Hygiene

Optional Jira Flow

Completion Hook

Plugin ecosystem

Contributing

Update

Uninstall

Try locally

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages