Package Exports

matilha
matilha/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (matilha) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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-plugins --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-plugins --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-plugins --target codex --full --scope project

That writes to:

.agents/skills/

Cursor

Run from the project root:

npm install -g matilha@latest
matilha install-plugins --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-plugins --target codex
matilha install-plugins --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: init, plan, hunt, gather, install/update plugins
Claude Code plugins	`matilha install-plugins --deep`	Installs `matilha-skills` and companion packs inside Claude Code
Codex local skills	`matilha install-plugins --target codex`	Installs skills into `~/.agents/skills` or `.agents/skills`
Cursor project skills	`matilha install-plugins --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-plugins --full --deep --with-claudemd

Then reload Claude Code plugins:

/reload-plugins

Choose Packs

Interactive — pick your packs

matilha install-plugins --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-plugins

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-plugins --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-plugins --core-only --deep
matilha install-plugins --preset backend --deep --with-claudemd
matilha install-plugins --preset ux --deep --with-claudemd
matilha install-plugins --preset fullstack --deep --with-claudemd
matilha install-plugins --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

Command	Phase	Description
`install-plugins`	—	Install the matilha ecosystem (plugin + packs)
`init`	—	Bootstrap a matilha project (`project-status.md`, `docs/matilha/`)
`howl`	0	Show current project phase + next action
`scout`	00→10	Phase 00 discovery — map the problem space
`plan <slug>`	10→30	Scaffold spec + implementation plan
`attest [gate]`	any	Validate and flip a phase gate
`plan-status`	any	Show feature artifacts + gate state
`hunt <slug>`	40	Decompose plan into waves, create git worktrees
`gather <slug>`	40	Merge completed SPs, run regression, update wave status
`list`	—	List skills in the matilha registry
`pull <slug>`	—	Pull a skill or resource from the registry

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-plugins --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-plugins --full --deep --with-claudemd