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:

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:

1. Choose a preset or Custom to select packs individually.
2. Confirm whether to write the CLAUDE.md activation snippet.
3. 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:

1. Adds danilods/matilha-skills to the Claude Code marketplace
2. Runs claude plugin install for each of the 8 plugins (core + 7 packs)
3. 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

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

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:

1. Read project-status.md
2. Read docs/matilha/context.md
3. 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:

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 <!-- matilha-start v1 --> and <!-- matilha-end v1 --> markers.

Try locally

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

License

MIT © Danilo de Sousa