SwissArmyHammer

SwissArmyHammer is an integrated software development lifecycle (SDLC) platform for AI-powered coding agents. It combines skills, agents, tools, and validators into a single system that turns your AI coding assistant into a complete development team.

Instead of a loose collection of scripts and one-off instructions, SwissArmyHammer provides a structured composition of capabilities — each with a clear role — that work together to plan, implement, test, review, and ship code.

Three CLIs, One System

SwissArmyHammer ships as three complementary command-line tools:

Each tool is independently useful, but they’re designed to work together. sah provides the capabilities, avp enforces the guardrails, and mirdan lets you share and reuse everything.

How It Works

At its core, SwissArmyHammer extends AI coding agents (like Claude Code) with a composable set of SDLC primitives:

1. Skills define what to do — plan, implement, test, review, commit. Each skill is a self-contained workflow that the agent can invoke.
2. Agents (subagent modes) define how to think — a planner reasons differently than a tester. Agent modes shape the AI’s behavior for specific roles.
3. Tools provide what to work with — file operations, shell execution, code intelligence, kanban boards, git integration. These are the hands of the system.
4. Validators enforce what’s acceptable — code quality rules, security checks, test integrity. These run as hooks, catching problems before they land.

The agent orchestrates these pieces through a natural conversation interface. Say /plan and the system researches your codebase, decomposes work into kanban cards, and presents a plan. Say /implement and it picks up the next card, writes code, runs tests, and reports back. Say /review and a dedicated reviewer agent examines the changes with language-specific guidelines.

The SDLC Loop

A typical development cycle with SwissArmyHammer looks like:

/plan  →  /implement  →  /test  →  /review  →  /commit
  ↑                                                |
  └────────────────────────────────────────────────┘

Each step is a skill backed by specialized agent modes and tools. The kanban board tracks progress across steps. Validators run continuously in the background, enforcing quality at every stage.

This isn’t a rigid pipeline — you can use any skill independently, skip steps, or run them in any order. The system is designed to support how developers actually work, not to impose a process.

What Makes It Different

• Composition over configuration. Skills, agents, tools, and validators are separate, pluggable units. Mix and match what you need.
• Agent-native. Built from the ground up as an MCP server for AI coding agents, not retrofitted from human-oriented tooling.
• Quality built in. Validators run as hooks on every tool call — code quality, security, and test integrity are enforced automatically, not as an afterthought.
• Shareable. Mirdan provides a package registry so teams can publish and install skills, validators, tools, and plugins. Your team’s best practices become installable packages.
• Language-aware. Review guidelines, coverage analysis, and code intelligence adapt to the language you’re working in — Rust, TypeScript, Python, Go, and more.

The Integrated SDLC

SwissArmyHammer assembles four kinds of building blocks — skills, agents, tools, and validators — into a coherent software development lifecycle. This page explains how they fit together.

The Four Layers

┌─────────────────────────────────────────────┐
│                  Skills                      │
│   /plan  /implement  /test  /review /commit  │
│         (what to do — workflows)             │
├─────────────────────────────────────────────┤
│                  Agents                      │
│   planner  implementer  tester  reviewer     │
│         (how to think — personas)            │
├─────────────────────────────────────────────┤
│                  Tools                       │
│   files  shell  git  kanban  code-context    │
│         (what to work with — capabilities)   │
├─────────────────────────────────────────────┤
│                Validators                    │
│   code-quality  security  test-integrity     │
│         (what's acceptable — guardrails)     │
└─────────────────────────────────────────────┘

Each layer has a distinct responsibility, and the layers compose vertically. A skill like /implement activates the implementer agent mode, which uses tools (file editing, shell execution, code context) to write code, while validators (code quality, security rules) check every change as it happens.

A Concrete Example

Here’s what happens when you type /plan in your AI coding agent:

1. The plan skill activates. It defines the workflow: research the codebase, identify what needs to change, decompose work into discrete tasks.
2. The planner agent mode shapes how the AI thinks. It’s instructed to be thorough in research, conservative in scope, and to produce kanban cards as output.
3. The planner uses tools to do the work: code_context to understand the codebase structure, shell to run analysis commands, kanban to create task cards, question to ask clarifying questions.
4. Validators aren’t heavily involved during planning, but command-safety validators still ensure no destructive shell commands are run during research.

The result: a kanban board with well-scoped cards, ready for /implement to pick up.

The Development Cycle

The skills form a natural development cycle:

Plan → Implement → Test → Review → Commit

Each phase is independent — you can run /test without /plan, or /review without /implement. But when used together, they form a complete cycle where each phase’s output feeds the next.

Supporting Skills

Beyond the core cycle, additional skills handle cross-cutting concerns:

• /coverage — analyzes test coverage gaps on changed code
• /deduplicate — finds and refactors duplicate code
• /double-check — validates recent work before moving on
• /implement-all — autonomously works through the entire kanban board
• /code-context — explores codebase structure and symbol relationships
• /shell — shell command execution with history and process management
• /lsp — diagnoses and installs language servers for code intelligence

How the Pieces Connect

Skills Activate Agent Modes

When a skill runs, it typically delegates to a specialized subagent. The /implement skill spawns an implementer agent, the /review skill spawns a reviewer agent, and so on. This keeps the parent conversation clean — verbose test output, detailed code analysis, and implementation details stay inside the subagent.

Agent Modes Shape Behavior

Each agent mode is a markdown document that instructs the AI how to approach its task. The implementer follows test-driven development practices, writes minimal diffs, and reports results. The reviewer performs layered analysis (correctness, design, style) with language-specific guidelines. These aren’t just prompts — they’re behavioral contracts.

Tools Provide Capabilities

Tools are MCP (Model Context Protocol) endpoints that the agent calls to interact with the outside world. File operations, shell execution, code intelligence, kanban management — these are all tools. Skills and agents don’t hard-code tool usage; they decide which tools to use based on the task at hand.

Validators Run Continuously

Validators are Claude Code hooks that fire on every tool call. When the agent writes a file, the code-quality validator checks for cognitive complexity, magic numbers, and naming issues. When it runs a shell command, the command-safety validator ensures it’s not destructive. This happens transparently — the agent gets feedback and can self-correct before problems land.

Extensibility

Every layer is extensible:

• Skills are markdown files. Drop a new one into .claude/skills/ or install one via mirdan install.
• Agent modes are markdown files in the modes directory. Customize existing ones or create new specialized roles.
• Tools are MCP server endpoints. SwissArmyHammer’s built-in tools cover the common cases; add more via MCP server configuration.
• Validators are AVP rule sets. Add project-specific rules under .avp/validators/ or install shared ones via mirdan install.

The package manager (mirdan) ties extensibility to shareability — anything you create can be published to a registry and installed by others.

Skills

Skills are the workflows of SwissArmyHammer. Each skill defines a specific development activity — planning, implementing, testing, reviewing, committing — as a self-contained unit that the AI agent can invoke.

What a Skill Is

A skill is a markdown file with frontmatter metadata. When invoked (e.g., /plan or /implement), it expands into a full prompt that shapes the agent’s behavior for that activity. Skills typically delegate heavy work to specialized subagents, keeping the parent conversation concise.

Skills are the primary interface between you and the SDLC system. You don’t need to think about agents, tools, or validators directly — just invoke the skill and it orchestrates everything.

Built-in Skills

SwissArmyHammer ships with skills covering the core development cycle:

How Skills Work

When you type /implement, here’s what happens:

1. The skill definition is loaded and expanded into a prompt.
2. The prompt typically instructs the agent to delegate to a specialized subagent (the implementer agent mode).
3. The subagent does the work — reading code, writing files, running tests — using tools.
4. Validators check the subagent’s work as it happens.
5. The subagent reports results back to the parent conversation.

This delegation pattern keeps verbose output (test results, implementation details) contained in the subagent, while the parent conversation gets a clean summary.

Installing Skills

Beyond the built-in set, you can install additional skills from the Mirdan registry:

mirdan search "my-skill"
mirdan install my-skill

Or create your own by placing a SKILL.md file in the appropriate directory. Skills installed via Mirdan are deployed to each detected agent’s skill directory automatically.

Skill Locations

Skills are discovered from multiple locations with hierarchical precedence:

Agents

Agents are specialized behavioral modes that shape how the AI approaches a task. When a skill needs to plan, implement, test, or review, it spawns a subagent with the appropriate mode — giving it a focused persona and set of instructions for that specific role.

What an Agent Mode Is

An agent mode is a markdown document that defines a role. It tells the AI:

• What its job is (implement code, review changes, run tests)
• How to approach the work (test-driven development, layered review, minimal diffs)
• What patterns to follow (commit conventions, error handling, reporting format)
• What tools to prefer and how to use them

Agent modes aren’t just system prompts — they’re behavioral contracts that ensure consistent, high-quality output regardless of the specific task.

Built-in Agent Modes

The Subagent Pattern

Skills typically don’t do work directly in the parent conversation. Instead, they delegate to a subagent:

Parent conversation
  │
  ├─ /implement
  │    └─ spawns implementer subagent
  │         ├─ reads kanban card
  │         ├─ writes code (using file tools)
  │         ├─ runs tests (using shell tool)
  │         ├─ validators check each change
  │         └─ reports results back to parent
  │
  └─ "Implementation complete, all tests passing"

This pattern has two key benefits:

1. Context isolation. Verbose output (test results, file contents, tool calls) stays inside the subagent. The parent conversation gets a clean summary.
2. Focused behavior. Each subagent operates with instructions optimized for its specific role, without the noise of unrelated context.

How Modes Shape Behavior

Consider the difference between the implementer and reviewer modes:

The implementer is instructed to:

• Follow test-driven development (write failing test first, then make it pass)
• Make minimal changes — only what the kanban card requires
• Run tests after every change
• Report what was changed and whether tests pass

The reviewer is instructed to:

• Perform layered analysis: correctness first, then design, then style
• Apply language-specific review guidelines (Rust, TypeScript, Python, etc.)
• Capture findings as kanban cards for follow-up
• Never modify code directly — only report findings

Same tools, completely different behavior. The agent mode is what makes the difference.

Language-Specific Guidelines

Some agent modes include language-specific guidelines that activate based on the code being worked with. The reviewer, for example, loads additional guidelines for:

• Rust — ownership patterns, error handling, unsafe usage
• TypeScript/JavaScript — type safety, async patterns, React conventions
• Python — type hints, exception handling, import organization
• Go — error handling, goroutine safety, interface design
• Dart/Flutter — widget patterns, state management

These guidelines are bundled as partials within the skill definition and selected automatically based on the files being reviewed.

Tools

Tools are the capabilities that agents use to interact with the outside world. They’re exposed as MCP (Model Context Protocol) endpoints — the agent calls them like functions to read files, run commands, search code, manage tasks, and more.

What a Tool Is

A tool is an MCP endpoint with a defined schema (name, description, parameters) and an implementation. When the agent decides it needs to read a file or run a shell command, it invokes the appropriate tool. SwissArmyHammer’s MCP server (sah serve) exposes all built-in tools to the connected agent.

Tools are the lowest layer of the system. Skills and agents don’t hard-code which tools to use — they make decisions based on the task and invoke tools as needed.

Built-in Tools

File Operations

Execution

Code Intelligence

Project Management

Git

Communication

Agent Orchestration

Web

How Tools Fit In

Tools sit beneath skills and agents in the stack. Here’s the relationship:

• A skill (e.g., /test) defines the workflow.
• An agent mode (e.g., tester) shapes how the AI approaches the task.
• Tools (e.g., shell, files) are what the agent actually calls to do the work.
• Validators (e.g., command-safety) check each tool invocation before it executes.

The agent has access to all tools and chooses which to use based on context. The skill and agent mode influence these choices through their instructions, but tools themselves are general-purpose.

MCP Protocol

All tools are served via the Model Context Protocol. When you run sah serve, it starts an MCP server (stdio by default, HTTP optionally) that exposes these tools to any connected agent. Claude Code discovers them automatically via the MCP configuration created by sah init.

This means SwissArmyHammer’s tools work alongside any other MCP servers you have configured. The agent sees a unified tool palette from all sources.

Validators

Validators are the guardrails of SwissArmyHammer. They are rules-as-data quality gates — focused agents that enforce code quality, security, and test integrity. Each validator is scoped by file globs to the changed files it applies to, and the review pipeline runs the matching validators over those changes.

What a Validator Is

A validator is an AVP (Agent Validator Protocol) rule set: a collection of rules organized under a VALIDATOR.md file. Each rule is a markdown document that describes what to check and how to report violations. AVP processes these rules against the agent’s tool calls and file changes in real time.

Built-in Validators

SwissArmyHammer ships with a set of built-in validators, grouped below by the area they cover. The groups are illustrative rather than exhaustive — the authoritative list is the builtin validator tree itself, which evolves over time.

Code Quality

Enforces structural code quality rules:

• Cognitive complexity — flags overly complex functions
• Function length — catches functions that are too long
• Naming consistency — enforces naming conventions
• No commented-out code — prevents dead code from accumulating
• No hard-coded values — catches embedded credentials and config
• No magic numbers — requires named constants
• No string equality — flags fragile string comparisons
• No log truncation — ensures complete error logging
• Missing docs — flags undocumented public APIs

Security Rules

Catches security vulnerabilities:

• Input validation — ensures user input is validated at boundaries
• No secrets — prevents credentials, tokens, and keys from being committed

Command Safety

Guards against destructive shell commands:

• Safe commands — blocks rm -rf /, DROP TABLE, force pushes, and other dangerous operations

Test Integrity

Prevents test cheating:

• No test cheating — catches mocking of the thing under test, assertion-free tests, and other patterns that make tests pass without testing anything

How Validators Work

The review pipeline collects the changed files, matches each validator’s match.files globs against them, and runs the matching validators over the changes:

Changed files
    │
    ├─ Loader matches validators by file glob
    │    ├─ Code quality validator checks the changed source
    │    ├─ Security validator checks for secrets
    │    └─ Findings collected with each validator's severity
    │
    └─ Blocking findings (error severity) gate the change

Matching is on file globs only — a validator with no match.files applies to everything, and one scoped to *.rs only runs on Rust changes.

Setting Up Validators

Built-in validators are always available. Project-specific validators go in ./.validators/, and user-wide validators in $XDG_DATA_HOME/validators/ (default ~/.local/share/validators/).

Configuring the Review Tool

The review tool reads two optional keys from .sah/sah.yaml, both under a review: mapping:

Set the review model with the model use command rather than editing the file by hand:

sah model use qwen --for review

This writes review.model: qwen and leaves the global default (model:) untouched, so only the review tool switches models. Omit --for review to set the global default that every tool — including review — falls back to.

A configured .sah/sah.yaml looks like:

model: claude-code      # global default for all tools
review:
  model: qwen           # review tool overrides the global default
  concurrency: 4        # run 4 validator agents in parallel

Creating Custom Validators

A validator rule set is a directory with a VALIDATOR.md and a rules/ directory. Each rule is a markdown file describing what to check.

The VALIDATOR.md frontmatter declares:

• name — the rule set identifier (defaults to the directory name).
• description — what the rule set checks.
• match.files — file glob patterns that scope the rule set to the changed files it applies to. Supports @file_groups/... includes (e.g. @file_groups/source_code) that expand to shared pattern lists. Matching is on file globs only.
• severity — default severity for the rules (info, warn, or error).
• tags — optional labels for filtering and organization.
• probes — optional list of probe names (plain strings) the rule set requests from the probe catalog.

---
name: dead-code
description: Flags symbols with no inbound callers
match:
  files:
    - "@file_groups/source_code"
severity: error
probes:
  - callers
---

The legacy trigger key (which named a Claude Code hook event) has been removed. The loader is lenient — a leftover trigger still loads — but check validators flags it so you can remove it.

Sharing Validators

Validators can be published and installed via Mirdan:

# Create and publish
mirdan new validator my-team-rules
mirdan publish

# Install on another project
mirdan install my-team-rules

This lets teams codify their standards as installable packages — new projects get the team’s quality rules with a single command.

Validator Locations

Precedence is builtin → user → project: a project rule set overrides a user rule set of the same name, which overrides the built-in.

Closing the Write Surface

SwissArmyHammer attaches live LSP diagnostics to every file mutation, so the model sees what its edit broke on the same turn it makes the edit. That only works if the mutation actually flows through the instrumented files MCP tool (op: "edit file" / op: "write file"), which folds the diagnostics in. A mutation that goes around the tool produces no diagnostics — it is invisible to the inline fold-in.

The goal is a closed write surface: every byte written to the working tree goes through the instrumented tool, so diagnostics always ride the result. This page describes how SwissArmyHammer closes the editing half of that surface on Claude Code, the prerequisite it still depends on, and the tradeoff it accepts.

An MCP server can’t disable a host’s native tools

Claude Code ships its own native Edit and Write tools. An MCP server (which is what sah serve is) can add tools, but it cannot remove or disable the host’s built-in ones. As long as the native mutators are present and allowed, the model — tuned to reach for them — will, and those edits bypass the instrumented path.

So the editing surface is closed not from inside the server but with a host config fragment: a Claude Code settings.json change that

1. sets permissions.deny on Edit and Write, so the model is told not to use the native mutators, and
2. adds a PreToolUse hook on those same tools that, if one is attempted anyway, denies it and redirects the model to the files MCP tool’s edit/write op.

This fragment is installed for you — it is shipped through the same sah init config surface that registers the MCP server and writes the statusline, not something you hand-author. It is plain, Claude-shaped settings.json: valid on every Claude Code version, inert on agents that don’t read those keys, and a no-op on hosts that have no hook support (an unrecognized hooks block is simply ignored rather than an error).

Prerequisite: the shell must be closed first

Closing the editing tools is not enough to close the write surface. An open Bash tool can write files directly — cat > file, sed -i, tee, redirection — entirely outside any edit tool and therefore outside the diagnostics fold-in. While a general-purpose shell is available, the write surface has a hole no edit-tool deny can patch.

So shell-shorting is the prerequisite for a truly closed write surface: until the shell is constrained to a tool that cannot perform arbitrary file writes, denying the edit tools narrows the gap but does not seal it. Closing the shell is a separate initiative; this editing-surface fragment is one half of the whole.

For everything that still leaks — through the shell today, or through any future gap — the leader watcher remains the async backstop: a single leader-owned file watcher per workdir notices changes on disk and re-flows diagnostics out of band, so a bypassing write is caught eventually even though it did not ride an edit-tool result inline.

The tradeoff: latency and reliability

Routing edits through MCP is not free, and the choice is deliberate.

• Native Edit is fast and the model is tuned to it. It is an in-process tool call with no extra round-trip; the model reaches for it fluently.
• Routing through the files MCP tool adds latency — an extra hop to the server and back — and makes us own edit reliability. When the model edits through our tool, our tool’s correctness (encoding preservation, line-ending preservation, atomic replacement, exact-match semantics) is what stands between the model and a corrupted file.

That cost is worth paying only while files edit stays at least as reliable as the native tool it displaces. The whole point is to gain diagnostics on every mutation; if the instrumented path were flakier than the tool it replaces, we would be trading correctness for visibility, which is a bad trade. The bar for keeping this fragment installed is that the redirect target never regresses below the native tool’s reliability.

Installation

Install SwissArmyHammer and configure it for use with Claude Code.

Prerequisites

• Claude Code — For MCP integration (recommended)
• Git — For version control features

Install from Homebrew

brew install swissarmyhammer/tap/swissarmyhammer-cli

This installs all three CLIs: sah, avp, and mirdan.

Verify Installation

sah --version
sah doctor

The doctor command checks your installation and configuration.

Claude Code Integration

Initialize SwissArmyHammer for your project:

sah init

This does two things:

1. Registers sah as an MCP server in .mcp.json
2. Creates the project directory with skills and workflows

Verify everything:

sah doctor

Scope Options

sah init supports different scopes:

sah init user      # Install globally

Shell Completions (Optional)

# Zsh
sah completions zsh > ~/.zfunc/_sah

# Bash
sah completions bash > ~/.bash_completion.d/sah

# Fish
sah completions fish > ~/.config/fish/completions/sah.fish

Next Steps

• Quick Start — Start using the integrated SDLC

Quick Start

Get the integrated SDLC running in your project.

Setup

# Install
brew install swissarmyhammer/tap/swissarmyhammer-cli

# Initialize in your project
cd your-project
sah init        # MCP server + tools + skills

# Verify
sah doctor

The Development Cycle

Once initialized, the skills are available as slash commands in Claude Code:

1. Plan

/plan

Researches your codebase and creates kanban cards for the work ahead. The planner agent explores code structure, identifies dependencies, and decomposes the task into implementable units.

2. Implement

/implement

Picks up the next kanban card and implements it. The implementer agent writes code, runs tests, and reports results. Validators check every file write for code quality and security issues.

To work through the entire board autonomously:

/implement-all

3. Test

/test

Runs the test suite, analyzes failures, fixes issues, and reports back. The tester agent handles verbose test output so your conversation stays clean.

4. Review

/review

Performs a structured code review of your changes. The reviewer agent applies language-specific guidelines and captures findings.

5. Commit

/commit

Creates clean, well-organized git commits from your staged changes.

Other Useful Skills

/coverage          # Find untested code in your changes
/deduplicate       # Find and refactor copy-paste code
/double-check      # Verify recent work before moving on
/code-context      # Explore codebase structure
/shell             # Run shell commands with history

Installing More Skills

Browse and install community skills via Mirdan:

mirdan search "my-topic"
mirdan install some-skill

Next Steps

• The Integrated SDLC — Understand how skills, agents, tools, and validators work together
• Skills — Deep dive into the skill system
• Validators — Configure quality guardrails

Command-Line Help for swissarmyhammer

This document contains the help content for the swissarmyhammer command-line program.

Installation

brew install swissarmyhammer/tap/swissarmyhammer

Command Overview:

• swissarmyhammer↴
• swissarmyhammer serve↴
• swissarmyhammer serve http↴
• swissarmyhammer init↴
• swissarmyhammer deinit↴
• swissarmyhammer doctor↴
• swissarmyhammer completion↴
• swissarmyhammer validate↴
• swissarmyhammer model↴
• swissarmyhammer model list↴
• swissarmyhammer model show↴
• swissarmyhammer model use↴
• swissarmyhammer agent↴
• swissarmyhammer agent acp↴
• swissarmyhammer tools↴
• swissarmyhammer tools enable↴
• swissarmyhammer tools disable↴
• swissarmyhammer statusline↴
• swissarmyhammer statusline config↴

swissarmyhammer

swissarmyhammer is an MCP (Model Context Protocol) server that brings skills, workflows, and agents to AI coding tools. It supports template substitution and seamless integration with Claude Code and other ACP-compatible editors.

Global arguments can be used with any command to control output and behavior: –verbose Show detailed information and debug output –format Set output format (table, json, yaml) for commands that support it –debug Enable debug mode with comprehensive tracing –quiet Suppress all output except errors –model Override model for all use cases (runtime only, doesn’t modify config)

Main commands: serve Run as MCP server (default when invoked via stdio) init Set up sah for all detected AI coding agents (skills + MCP) doctor Diagnose configuration and setup issues agent Manage and interact with the Agent Client Protocol server model Manage and interact with models validate Validate configuration files for syntax and best practices completion Generate shell completion scripts

Example usage: swissarmyhammer serve # Run as MCP server swissarmyhammer init # Set up skills + MCP for detected agents swissarmyhammer doctor # Check configuration swissarmyhammer model list # List available models swissarmyhammer agent acp # Start the ACP server

Usage: swissarmyhammer [OPTIONS] [COMMAND]

Subcommands:

• serve — Run as MCP server (default when invoked via stdio)
• init — Set up sah for all detected AI coding agents (skills + MCP)
• deinit — Remove sah from all detected AI coding agents (skills + MCP)
• doctor — Diagnose configuration and setup issues
• completion — Generate shell completion scripts
• validate — Validate skills and workflows for syntax and best practices
• model — Manage and interact with models
• agent — Manage and interact with Agent Client Protocol server
• tools — Manage tool enable/disable state
• statusline — Render statusline from Claude Code JSON (stdin) or dump config

Options:

• -v, --verbose — Enable verbose logging

• -d, --debug — Enable debug logging

• -q, --quiet — Suppress all output except errors

• --format <FORMAT> — Global output format

  Possible values: table, json, yaml

• --model <MODEL> — Override model for all use cases (runtime only, doesn’t modify config)

swissarmyhammer serve

Run as MCP server. This is the default mode when invoked via stdio (e.g., by Claude Code). The server will:

• Expose the SwissArmyHammer tools and workflows via the MCP protocol
• Watch for file changes and reload automatically

Example: swissarmyhammer serve # Stdio mode (default) swissarmyhammer serve http # HTTP mode

Or configure in Claude Code’s MCP settings

Usage: swissarmyhammer serve [COMMAND]

Subcommands:

• http — Start HTTP MCP server

swissarmyhammer serve http

Start HTTP MCP server for web clients, debugging, and LlamaAgent integration. The server exposes MCP tools through HTTP endpoints and provides:

• RESTful MCP protocol implementation
• Health check endpoint at /health
• Support for random port allocation (use port 0)
• Graceful shutdown with Ctrl+C

Example: swissarmyhammer serve http –port 8080 –host 127.0.0.1 swissarmyhammer serve http –port 0 # Random port

Usage: swissarmyhammer serve http [OPTIONS]

Options:

• -p, --port <PORT> — Port to bind to (use 0 for random port)

  Default value: 8000

• -H, --host <HOST> — Host to bind to

  Default value: 127.0.0.1

swissarmyhammer init

Set up SwissArmyHammer for all detected AI coding agents.

This command:

1. Registers sah as an MCP server for all detected agents (Claude Code, Cursor, Windsurf, etc.)
2. Creates the .sah/ project directory
3. Installs builtin skills to the central .skills/ store with symlinks to each agent

The command is idempotent - safe to run multiple times.

Targets: project Write to project-level config files (default, shared with team via git) local Write to ~/.claude.json per-project config (personal, not committed) user Write to global config files (all projects)

Examples: sah init # Project-level setup (default) sah init user # Global setup for all projects sah init local # Personal setup, not committed to git

Usage: swissarmyhammer init [TARGET]

Arguments:

• <TARGET> — Where to install the MCP server configuration

  Default value: project

  Possible values:

  • project: Project-level configuration (committed to the repo)
  • local: Local project configuration that is not committed
  • user: User-wide (global) configuration

swissarmyhammer deinit

Remove SwissArmyHammer from all detected AI coding agents.

By default, only the MCP server entries are removed from agent config files. Use –remove-directory to also delete .sah/ and installed skills.

Examples: sah deinit # Remove from project settings sah deinit user # Remove from user settings sah deinit –remove-directory # Also remove .sah/ and skills

Usage: swissarmyhammer deinit [OPTIONS] [TARGET]

Arguments:

• <TARGET> — Where to remove the MCP server configuration from

  Default value: project

  Possible values:

  • project: Project-level configuration (committed to the repo)
  • local: Local project configuration that is not committed
  • user: User-wide (global) configuration

Options:

• --remove-directory — Also remove .sah/ project directory

swissarmyhammer doctor

Diagnose and troubleshoot your SwissArmyHammer setup in seconds.

Save hours of debugging time with comprehensive automated checks that identify configuration issues, permission problems, and integration errors before they impact your workflow.

WHAT IT CHECKS

The doctor command runs a complete health assessment of your environment: • PATH Configuration - Verifies swissarmyhammer is accessible from your shell • Claude Code Integration - Validates MCP server configuration and connectivity • Skills - Checks directories, file permissions, and YAML syntax • File Watching - Tests file system event monitoring capabilities • System Resources - Validates required dependencies and system capabilities

WHY USE DOCTOR

• Quick Diagnosis - Complete system check in seconds, not hours • Clear Reporting - Easy-to-understand pass/fail results with actionable guidance • Early Detection - Catch configuration problems before they cause failures • Setup Validation - Verify your installation is working correctly • Integration Testing - Ensure Claude Code and MCP are properly connected

UNDERSTANDING RESULTS

Exit codes indicate the severity of findings: 0 - All checks passed - System is healthy and ready 1 - Warnings found - System works but has recommendations 2 - Errors found - Critical issues preventing proper operation

COMMON WORKFLOWS

First-time setup verification: swissarmyhammer doctor

Detailed diagnostic output: swissarmyhammer doctor –verbose

After configuration changes: swissarmyhammer doctor

CI/CD health checks: swissarmyhammer doctor && echo “System ready”

EXAMPLES

Basic health check: swissarmyhammer doctor

Detailed diagnostics with fix suggestions: swissarmyhammer doctor –verbose

Quiet mode for scripting: swissarmyhammer doctor –quiet

The doctor command gives you confidence that your development environment is properly configured and ready for AI-powered workflows.

Usage: swissarmyhammer doctor

swissarmyhammer completion

Generates shell completion scripts for various shells. Supports:

• bash
• zsh
• fish
• powershell

Examples:

Bash (add to ~/.bashrc or ~/.bash_profile)

sah completion bash > ~/.local/share/bash-completion/completions/sah

Zsh (add to ~/.zshrc or a file in fpath)

sah completion zsh > ~/.zfunc/_sah

Fish

sah completion fish > ~/.config/fish/completions/sah.fish

PowerShell

sah completion powershell >> $PROFILE

Usage: swissarmyhammer completion <SHELL>

Arguments:

• <SHELL> — Shell to generate completion for

  Possible values: bash, elvish, fish, powershell, zsh

swissarmyhammer validate

Catch configuration errors before they cause failures with comprehensive validation.

The validate command ensures quality and correctness across your entire SwissArmyHammer configuration, detecting syntax errors, structural issues, and best practice violations before they impact your workflows.

Quality Assurance

Comprehensive Validation: • Skill files from all sources (builtin, user, project) • Workflow definitions from standard locations • MCP tool schemas and CLI integration (with –validate-tools) • Template syntax and variable usage • YAML frontmatter structure • Required field presence and format • Best practice compliance

Early Error Detection: • Find syntax errors before execution • Identify missing required fields • Detect template variable mismatches • Validate workflow state machine structure • Check MCP tool schema correctness • Verify CLI integration compatibility

CI/CD Integration: • Automated quality checks in build pipelines • Exit codes indicate validation results • Quiet mode for clean CI output • JSON output for tool integration • Fast execution for rapid feedback

What Gets Validated

Skill Files: • YAML frontmatter syntax correctness • Required fields: title, description • Template variable declarations match usage • Liquid template syntax validity • Parameter definitions and types • Default value correctness • Partial marker handling

Workflow Files: • State machine structure integrity • State connectivity and transitions • Action and tool references • Variable declarations and usage • Conditional logic syntax • Loop and iteration constructs • Error handling configuration

MCP Tools (with –validate-tools): • JSON schema correctness • Parameter type definitions • Required vs optional field specifications • Tool description completeness • CLI integration requirements • Documentation quality • Best practice adherence

Validation Modes

Standard validation (skills and workflows):

sah validate

Comprehensive validation (including MCP tools):

sah validate --validate-tools

CI/CD mode (errors only, no warnings):

sah validate --quiet
sah validate --validate-tools --quiet

Machine-readable output:

sah validate --format json
sah validate --validate-tools --format json

Exit Codes

• 0 - All validation passed, no errors or warnings
• 1 - Warnings found but no errors
• 2 - Errors found that require fixes

Use exit codes in scripts and CI pipelines:

sah validate || exit 1

Discovery and Sources

Skills validated from: • Built-in skills (embedded in binary) • User skills ($XDG_DATA_HOME/sah/skills) • Project skills (./.skills/)

Workflows validated from: • Built-in workflows (embedded in binary) • User workflows (~/.sah/workflows/) • Project workflows (./workflows/)

MCP tools validated from: • SwissArmyHammer tool definitions • CLI command integration points • Tool parameter schemas

Common Use Cases

Pre-commit validation:

sah validate --quiet && git commit

CI pipeline check:

sah validate --validate-tools --format json > validation-report.json

Development workflow validation:

sah validate --verbose

Quality gate in deployment:

sah validate --validate-tools --quiet || exit 1

Validation Checks

YAML Frontmatter: • Syntax correctness • Required fields present • Field types match expectations • Valid enum values

Template Syntax: • Liquid template parsing • Variable references exist • Filter syntax correctness • Control flow validity • Partial references resolve

Workflow Structure: • All states are reachable • Transitions are valid • Actions reference existing tools • Variables are declared before use • Error handlers are properly configured

MCP Tool Schemas: • JSON schema validity • Parameter type correctness • Required field specification • Tool description quality • CLI integration completeness

Best Practices: • Descriptive titles and descriptions • Proper parameter documentation • Sensible default values • Clear error messages • Consistent naming conventions

Examples

Basic validation:

sah validate

Full system validation:

sah validate --validate-tools

Quiet mode for CI:

sah validate --quiet

Detailed output:

sah --verbose validate

JSON output for tooling:

sah validate --format json | jq '.errors'

Validate after changes:

sah validate --validate-tools --verbose

Output Formats

Table format (default): • Human-readable tabular output • Color-coded error/warning levels • File paths and line numbers • Clear error descriptions

JSON format: • Machine-parseable structured output • Complete error and warning details • Suitable for CI integration • Easy tool consumption

YAML format: • Human-readable structured output • Hierarchical error organization • Good for documentation • Easy diff comparison

Troubleshooting

Validation errors in skills: • Check YAML frontmatter syntax • Verify all required fields present • Ensure template variables declared • Test Liquid template syntax

Validation errors in workflows: • Verify state machine structure • Check all state transitions • Ensure action references valid • Validate variable declarations

Validation errors in tools: • Review JSON schema correctness • Check parameter type definitions • Verify required fields specified • Ensure documentation complete

Integration with Development Workflow

Pre-commit hook:

#!/bin/bash
sah validate --quiet || {
  echo "Validation failed. Fix errors before committing."
  exit 1
}

Git hook (.git/hooks/pre-commit):

#!/bin/bash
sah validate --validate-tools --quiet

Make target:

validate:
	sah validate --validate-tools --quiet

.PHONY: validate

CI pipeline (GitHub Actions):

- name: Validate Configuration
  run: sah validate --validate-tools --format json

Benefits

Catch Errors Early: • Find problems before runtime • Prevent workflow failures • Avoid wasted execution time • Reduce debugging effort

Ensure Quality: • Enforce best practices • Maintain consistent standards • Improve documentation quality • Promote good patterns

Enable Confidence: • Deploy with certainty • Refactor safely • Share configuration reliably • Integrate automatically

Support Automation: • CI/CD quality gates • Automated testing • Pre-commit validation • Continuous quality monitoring

The validate command is your quality assurance system for SwissArmyHammer configuration, ensuring that skills, workflows, and tools are correct, complete, and ready for reliable operation.

Usage: swissarmyhammer validate [OPTIONS]

Options:

• -q, --quiet — Suppress all output except errors. In quiet mode, warnings are hidden from both output and summary

• --format <FORMAT> — Output format

  Default value: table

  Possible values: table, json, yaml

• --validate-tools — Validate MCP tool schemas for CLI compatibility

swissarmyhammer model

Manage and interact with models in the SwissArmyHammer system.

Models provide specialized AI execution environments and configurations for specific development workflows. They enable you to switch between different AI models, execution contexts, and toolchains based on your project’s needs.

MODEL DISCOVERY AND PRECEDENCE

Models are loaded from multiple sources with hierarchical precedence: • Built-in models (lowest precedence) - Embedded in the binary • Project models (medium precedence) - ./models/.yaml in your project • User models (highest precedence) - ~/.models/.yaml

Higher precedence models override lower ones by name. This allows you to customize built-in models or create project-specific variants.

BUILT-IN MODELS

The system includes these built-in models: • claude-code - Default Claude Code integration with shell execution • qwen-coder - Local Qwen3-Coder model with in-process execution

COMMANDS

The model system provides two main commands: • list - Display all available models from all sources with descriptions • use - Apply a model configuration to the current project

When you ‘use’ a model, it creates or updates .sah/sah.yaml in your project with the model’s configuration. This configures how SwissArmyHammer executes AI workflows in your project.

By default ‘use’ sets the global default model. Pass ‘–for ’ to scope the model to a single tool instead. The only supported purpose today is ‘review’: ‘sah model use –for review’ writes review.model and runs the review tool’s validator agents with that model, leaving the global default untouched. When review.model is unset, the review tool uses the global default.

COMMON WORKFLOWS

1. Explore available models: sah model list

2. Apply a model to your project: sah model use claude-code

3. Switch to a different model: sah model use qwen-coder

4. View detailed model information: sah –verbose model list

Use global arguments to control output: –verbose Show detailed information and descriptions –format FORMAT Output format: table, json, yaml –debug Enable debug mode with comprehensive tracing –quiet Suppress output except errors

Examples: sah model list # List all available models sah –verbose model list # Show detailed information and descriptions sah –format=json model list # Output as structured JSON sah model use claude-code # Apply Claude Code model to project sah model use qwen-coder # Switch to local Qwen3-Coder model sah –debug model use custom-model # Apply model with debug output

CUSTOMIZATION

Create custom models by adding .yaml files to: • ./models/ (project-specific models) • ~/.models/ (user-wide models)

Custom models can override built-in models by using the same name, or provide entirely new configurations for specialized workflows.

Usage: swissarmyhammer model [COMMAND]

Subcommands:

• list — List available models
• show — Show current model configuration
• use — Use a specific model

swissarmyhammer model list

List all available models from built-in, project, and user sources.

Models are discovered with hierarchical precedence where user models override project models, which override built-in models. This command shows all available models with their sources and descriptions.

Built-in models are embedded in the binary and provide default configurations for common workflows. Project models (./models/.yaml) allow customization for specific projects. User models (~/.models/.yaml) provide personal configurations that apply across all projects.

Output includes: • Model name and source (built-in, project, or user) • Description when available • Current model status (if one is applied to the project)

Examples: sah model list # List all models in table format sah model list –format json # Output as JSON for processing sah –verbose model list # Include detailed descriptions sah –quiet model list # Only show model names

Usage: swissarmyhammer model list [OPTIONS]

Options:

• --format <FORMAT> — Output format

  Default value: table

  Possible values: table, json, yaml

swissarmyhammer model show

Display the current model configured for this project.

Shows the model name, source, and description. If no model is explicitly configured, the default (claude-code) is used.

Examples: sah model show # Show current model sah model # Same as ‘show’ (default)

Usage: swissarmyhammer model show [OPTIONS]

Options:

• --format <FORMAT> — Output format

  Default value: table

  Possible values: table, json, yaml

swissarmyhammer model use

Apply a specific model configuration to the current project.

This command finds the specified model by name and applies its configuration to the project by creating or updating .sah/sah.yaml.

Model precedence (highest to lowest): • User models: ~/.models/.yaml • Project models: ./models/.yaml • Built-in models: embedded in the binary

By default the model is applied as the global default (top-level model:). Use --for <purpose> to scope the model to a specific tool instead; the value is written under that purpose’s mapping (e.g. --for review writes review.model:) and leaves the global default untouched.

--for review sets the model the review tool runs its validator agents with. When review.model is unset, the review tool uses the global default model.

Examples: sah model use claude-code # Apply Claude Code as the default model sah model use qwen # Apply the Qwen model as the default sah model use qwen –for review # Set the review-tool model only

Usage: swissarmyhammer model use [OPTIONS] <name>

Arguments:

• <name> — Model name to apply to the project

Options:

• --for <PURPOSE> — Purpose to scope the model to (e.g. review). Absent sets the global default model

swissarmyhammer agent

Manage and interact with Agent Client Protocol (ACP) server.

The agent command provides integration with ACP-compatible code editors, enabling local LLaMA models to be used as coding assistants in editors like Zed and JetBrains IDEs.

Subcommands: acp Start ACP server over stdio for editor integration

Examples: sah agent acp # Start ACP server (stdio) sah agent acp –config config.yaml # Start with custom config

Usage: swissarmyhammer agent [COMMAND]

Subcommands:

• acp — Start ACP server over stdio

swissarmyhammer agent acp

Start Agent Client Protocol (ACP) server for code editor integration.

The ACP server enables SwissArmyHammer to work with ACP-compatible code editors like Zed and JetBrains IDEs. The server communicates over stdin/stdout using JSON-RPC 2.0 protocol.

Features: • Local LLaMA model execution for coding assistance • Session management with conversation history • File system operations (read/write) • Terminal execution • Tool integration via MCP servers • Permission-based security model

Examples: sah agent acp # Start with default config sah agent acp –config acp.yaml # Start with custom config sah agent acp –permission-policy auto-approve-reads sah agent acp –allow-path /home/user/projects –block-path /home/user/.ssh sah agent acp –max-file-size 5242880 –terminal-buffer-size 2097152

Configuration: Options can be specified via:

1. Command-line flags (highest priority)
2. Configuration file (–config)
3. Default values (lowest priority)

Command-line flags override configuration file settings.

For editor configuration: • Zed: Add to agents section in settings • JetBrains: Install ACP plugin and configure

Usage: swissarmyhammer agent acp [OPTIONS]

Options:

• -c, --config <CONFIG> — Path to ACP configuration file (optional)
• --permission-policy <POLICY> — Permission policy: always-ask, auto-approve-reads
• --allow-path <PATH> — Allowed filesystem paths (can be specified multiple times)
• --block-path <PATH> — Blocked filesystem paths (can be specified multiple times)
• --max-file-size <BYTES> — Maximum file size for read operations in bytes
• --terminal-buffer-size <BYTES> — Terminal output buffer size in bytes
• --graceful-shutdown-timeout <SECONDS> — Graceful shutdown timeout in seconds

swissarmyhammer tools

Manage which MCP tools are enabled or disabled.

Tools are enabled by default. Disable tools you don’t need to reduce the tool surface visible to AI agents.

Examples: sah tools # List all tools with status sah tools disable # Disable all tools sah tools enable shell git # Enable specific tools sah tools disable kanban web # Disable specific tools sah tools enable # Enable all tools sah tools –global disable web # Disable web globally

Usage: swissarmyhammer tools [OPTIONS] [COMMAND]

Subcommands:

• enable — Enable tools (all if no names given)
• disable — Disable tools (all if no names given)

Options:

• --global — Write to global config (~/.sah/tools.yaml) instead of project

swissarmyhammer tools enable

Enable tools (all if no names given)

Usage: swissarmyhammer tools enable [NAMES]...

Arguments:

• <NAMES> — Tool names to enable (omit for all)

swissarmyhammer tools disable

Disable tools (all if no names given)

Usage: swissarmyhammer tools disable [NAMES]...

Arguments:

• <NAMES> — Tool names to disable (omit for all)

swissarmyhammer statusline

Render a styled statusline for Claude Code integration.

In normal mode, reads JSON from stdin and outputs styled ANSI text. Use ‘sah statusline config’ to dump the full annotated builtin config.

The statusline is configured via YAML with 3-layer stacking:

1. Builtin defaults (embedded in binary)
2. User config (~/.sah/statusline/config.yaml)
3. Project config (.sah/statusline/config.yaml)

Examples: echo ‘{“model”:{“display_name”:“Opus”}}’ | sah statusline sah statusline config > .sah/statusline/config.yaml

Usage: swissarmyhammer statusline [COMMAND]

Subcommands:

• config — Dump the full annotated builtin config to stdout

swissarmyhammer statusline config

Dump the full annotated builtin config to stdout

Usage: swissarmyhammer statusline config

Command-Line Help for mirdan

This document contains the help content for the mirdan command-line program.

Installation

brew install swissarmyhammer/tap/mirdan-cli

Command Overview:

• mirdan↴
• mirdan agents↴
• mirdan new↴
• mirdan new skill↴
• mirdan new validator↴
• mirdan new tool↴
• mirdan new plugin↴
• mirdan install↴
• mirdan uninstall↴
• mirdan list↴
• mirdan search↴
• mirdan info↴
• mirdan login↴
• mirdan logout↴
• mirdan whoami↴
• mirdan publish↴
• mirdan unpublish↴
• mirdan outdated↴
• mirdan update↴
• mirdan sync↴
• mirdan status↴
• mirdan doctor↴
• mirdan start↴
• mirdan completion↴

mirdan

Mirdan manages skills, validators, tools, and plugins across all detected AI coding agents.

Skills are deployed to each agent’s skill directory (e.g. .claude/skills/, .cursor/skills/). Validators are deployed to ./.validators/ (project) or ~/.validators/ (global). Tools are deployed to .tools/ and registered in agent MCP configs. Plugins are deployed to agent plugin directories (e.g. .claude/plugins/).

Environment variables: MIRDAN_REGISTRY_URL Override the registry URL (useful for local testing) MIRDAN_TOKEN Provide an auth token without logging in MIRDAN_CREDENTIALS_PATH Override the credentials file location MIRDAN_AGENTS_CONFIG Override the agents configuration file

Usage: mirdan [OPTIONS] <COMMAND>

Subcommands:

• agents — Detect and list installed AI coding agents
• new — Create a new package from template
• install — Install a package (type auto-detected from contents)
• uninstall — Remove an installed package
• list — List installed packages
• search — Search the registry for skills and validators
• info — Show detailed information about a package
• login — Authenticate with the registry
• logout — Log out from the registry and revoke token
• whoami — Show current authenticated user
• publish — Publish a package to the registry (type auto-detected)
• unpublish — Remove a published package version from the registry
• outdated — Check for available package updates
• update — Update installed packages to latest versions
• sync — Reconcile .skills/ with agent directories and verify lockfile
• status — Report the install-status of sah-managed components per agent and scope
• doctor — Diagnose Mirdan setup and configuration
• start — Start the Mirdan tray/accessory app
• completion — Generate shell completion scripts

Options:

• -d, --debug — Enable debug output to stderr
• -y, --yes — Skip confirmation prompts (useful for CI/CD)
• --agent <AGENT_ID> — Limit operations to a single agent (e.g. claude-code, cursor)

mirdan agents

Detect and list installed AI coding agents

Usage: mirdan agents [OPTIONS]

Options:

• --all — Show all known agents, not just detected ones
• --json — Output as JSON

mirdan new

Create a new package from template

Usage: mirdan new <COMMAND>

Subcommands:

• skill — Scaffold a new skill (agentskills.io spec)
• validator — Scaffold a new validator (AVP spec)
• tool — Scaffold a new tool (MCP server definition)
• plugin — Scaffold a new plugin (Claude Code plugin)

mirdan new skill

Scaffold a new skill (agentskills.io spec)

Usage: mirdan new skill [OPTIONS] <NAME>

Arguments:

• <NAME> — Skill name (kebab-case, 1-64 chars)

Options:

• --global — Create in agent global skill directories instead of project-level

mirdan new validator

Scaffold a new validator (AVP spec)

Usage: mirdan new validator [OPTIONS] <NAME>

Arguments:

• <NAME> — Validator name (kebab-case, 1-64 chars)

Options:

• --global — Create in ~/.validators/ instead of ./.validators/

mirdan new tool

Scaffold a new tool (MCP server definition)

Usage: mirdan new tool [OPTIONS] <NAME>

Arguments:

• <NAME> — Tool name (kebab-case, 1-64 chars)

Options:

• --global — Create in $XDG_DATA_HOME/avp/tools/ instead of current directory

mirdan new plugin

Scaffold a new plugin (Claude Code plugin)

Usage: mirdan new plugin [OPTIONS] <NAME>

Arguments:

• <NAME> — Plugin name (kebab-case, 1-64 chars)

Options:

• --global — Create in global plugin directory

mirdan install

Install a package (type auto-detected from contents)

Usage: mirdan install [OPTIONS] <PACKAGE>

Arguments:

• <PACKAGE> — Package name, name@version, ./local-path, owner/repo, or git URL

Options:

• --global — Install globally
• --git — Treat package as a git URL (clone instead of registry lookup)
• --skill <SKILL> — Install a specific package by name from a multi-package repo
• --mcp — Install as an MCP server instead of a skill/validator
• --command <COMMAND> — MCP server command (binary to run). Required when –mcp is set
• --args <ARGS> — MCP server arguments

mirdan uninstall

Remove an installed package

Usage: mirdan uninstall [OPTIONS] <NAME>

Arguments:

• <NAME> — Package name

Options:

• --global — Remove from global locations

mirdan list

List installed packages

Usage: mirdan list [OPTIONS]

Options:

• --skills — Show only skills
• --validators — Show only validators
• --tools — Show only tools
• --plugins — Show only plugins
• --json — Output as JSON

mirdan search

Search the registry for skills and validators

With a query argument, performs a single search and prints results. Without a query, enters interactive fuzzy search mode.

Usage: mirdan search [OPTIONS] [QUERY]

Arguments:

• <QUERY> — Search query (omit for interactive mode)

Options:

• --json — Output as JSON

mirdan info

Show detailed information about a package

Usage: mirdan info <NAME>

Arguments:

• <NAME> — Package name

mirdan login

Authenticate with the registry

Opens a browser for OAuth login. The registry URL can be overridden with MIRDAN_REGISTRY_URL for local testing.

Usage: mirdan login

mirdan logout

Log out from the registry and revoke token

Usage: mirdan logout

mirdan whoami

Show current authenticated user

Usage: mirdan whoami

mirdan publish

Publish a package to the registry (type auto-detected)

Auto-detects package type from directory contents: - SKILL.md present -> publishes as a skill - VALIDATOR.md + rules/ present -> publishes as a validator - TOOL.md present -> publishes as a tool - .claude-plugin/plugin.json present -> publishes as a plugin

Usage: mirdan publish [OPTIONS] [SOURCE]

Arguments:

• <SOURCE> — Path or git URL to the package directory to publish

  Default value: .

Options:

• --dry-run — Validate and show what would be published without uploading

mirdan unpublish

Remove a published package version from the registry

Usage: mirdan unpublish <NAME_VERSION>

Arguments:

• <NAME_VERSION> — Package name@version (e.g. my-skill@1.0.0)

mirdan outdated

Check for available package updates

Usage: mirdan outdated

mirdan update

Update installed packages to latest versions

Usage: mirdan update [OPTIONS] [NAME]

Arguments:

• <NAME> — Specific package to update (all if omitted)

Options:

• --global — Update global packages

mirdan sync

Reconcile .skills/ with agent directories and verify lockfile

Usage: mirdan sync [OPTIONS]

Options:

• --global — Sync global locations

mirdan status

Report the install-status of sah-managed components per agent and scope

Shows, for each detected agent and scope (project, user), whether the sah MCP server, skills, subagents, preamble, and permissions are installed.

Usage: mirdan status [OPTIONS]

Options:

• --all — Include components that do not apply to an agent at a scope
• --json — Output as JSON

mirdan doctor

Diagnose Mirdan setup and configuration

Usage: mirdan doctor [OPTIONS]

Options:

• -v, --verbose — Show detailed output including fix suggestions

mirdan start

Start the Mirdan tray/accessory app

Usage: mirdan start

mirdan completion

Generates shell completion scripts for various shells. Supports:

• bash
• zsh
• fish
• powershell

Examples:

Bash (add to ~/.bashrc or ~/.bash_profile)

mirdan completion bash > ~/.local/share/bash-completion/completions/mirdan

Zsh (add to ~/.zshrc or a file in fpath)

mirdan completion zsh > ~/.zfunc/_mirdan

Fish

mirdan completion fish > ~/.config/fish/completions/mirdan.fish

PowerShell

mirdan completion powershell >> $PROFILE

Usage: mirdan completion <SHELL>

Arguments:

• <SHELL> — Shell to generate completion for

  Possible values: bash, elvish, fish, powershell, zsh

Command-Line Help for shelltool

This document contains the help content for the shelltool command-line program.

Installation

brew install swissarmyhammer/tap/shelltool-cli

Command Overview:

• shelltool↴
• shelltool serve↴
• shelltool init↴
• shelltool deinit↴
• shelltool doctor↴
• shelltool completion↴

shelltool

shelltool - A shell that saves tokens

Replaces Bash and exec CLI tools with a persistent, searchable shell. Instead of flooding the context window with raw command output, shelltool stores everything in history — the agent runs commands, then greps the results, retrieving only the lines that matter.

Usage: shelltool [OPTIONS] <COMMAND>

Subcommands:

• serve — Run MCP server over stdio, exposing the shell tool
• init — Install shelltool MCP server into Claude Code settings
• deinit — Remove shelltool from Claude Code settings
• doctor — Diagnose shelltool configuration and setup
• completion — Generate shell completion scripts

Options:

• -d, --debug — Enable debug output to stderr

shelltool serve

Run MCP server over stdio, exposing the shell tool

Usage: shelltool serve

shelltool init

Install shelltool MCP server into Claude Code settings

Usage: shelltool init [TARGET]

Arguments:

• <TARGET> — Where to install the server configuration

  Default value: project

  Possible values:

  • project: Project-level configuration (committed to the repo)
  • local: Local project configuration that is not committed
  • user: User-wide (global) configuration

shelltool deinit

Remove shelltool from Claude Code settings

Usage: shelltool deinit [TARGET]

Arguments:

• <TARGET> — Where to remove the server configuration from

  Default value: project

  Possible values:

  • project: Project-level configuration (committed to the repo)
  • local: Local project configuration that is not committed
  • user: User-wide (global) configuration

shelltool doctor

Diagnose shelltool configuration and setup

Usage: shelltool doctor [OPTIONS]

Options:

• -v, --verbose — Show detailed output including fix suggestions

shelltool completion

Generates shell completion scripts for various shells. Supports:

• bash
• zsh
• fish
• powershell

Examples:

Bash (add to ~/.bashrc or ~/.bash_profile)

shelltool completion bash > ~/.local/share/bash-completion/completions/shelltool

Zsh (add to ~/.zshrc or a file in fpath)

shelltool completion zsh > ~/.zfunc/_shelltool

Fish

shelltool completion fish > ~/.config/fish/completions/shelltool.fish

PowerShell

shelltool completion powershell >> $PROFILE

Usage: shelltool completion <SHELL>

Arguments:

• <SHELL> — Shell to generate completion for

  Possible values: bash, elvish, fish, powershell, zsh

Command-Line Help for code-context

This document contains the help content for the code-context command-line program.

Installation

brew install swissarmyhammer/tap/code-context-cli

Command Overview:

• code-context↴
• code-context serve↴
• code-context init↴
• code-context deinit↴
• code-context doctor↴
• code-context skill↴
• code-context completion↴

code-context

code-context - Structural code intelligence for AI agents

Provides indexed code navigation, symbol lookup, call graph traversal, blast radius analysis, and semantic search. Exposes these capabilities as MCP tools for AI coding agents.

Usage: code-context [OPTIONS] <COMMAND>

Subcommands:

• serve — Run MCP server over stdio, exposing code-context tools
• init — Install code-context MCP server into Claude Code settings
• deinit — Remove code-context from Claude Code settings
• doctor — Diagnose code-context configuration and setup
• skill — Deploy code-context skill to agent .skills/ directories
• completion — Generate shell completion scripts

Options:

• -d, --debug — Enable debug output to stderr

• -j, --json — Output results as JSON (for operation commands)

• --no-progress — Disable interactive progress bars for long-running operations.

  indicatif auto-degrades to plain output on non-TTY stdout, but some environments (CI runners, recording wrappers) still benefit from a hard switch. With this flag set the dispatcher installs a no-op renderer and the tool emits no progress chrome.

code-context serve

Run MCP server over stdio, exposing code-context tools

Usage: code-context serve

code-context init

Install code-context MCP server into Claude Code settings

Usage: code-context init [TARGET]

Arguments:

• <TARGET> — Where to install the server configuration

  Default value: project

  Possible values:

  • project: Project-level configuration (committed to the repo)
  • local: Local project configuration that is not committed
  • user: User-wide (global) configuration

code-context deinit

Remove code-context from Claude Code settings

Usage: code-context deinit [TARGET]

Arguments:

• <TARGET> — Where to remove the server configuration from

  Default value: project

  Possible values:

  • project: Project-level configuration (committed to the repo)
  • local: Local project configuration that is not committed
  • user: User-wide (global) configuration

code-context doctor

Diagnose code-context configuration and setup

Usage: code-context doctor [OPTIONS]

Options:

• -v, --verbose — Show detailed output including fix suggestions

code-context skill

Deploy code-context skill to agent .skills/ directories

Usage: code-context skill

code-context completion

Generates shell completion scripts for various shells. Supports:

• bash
• zsh
• fish
• powershell

Examples:

Bash (add to ~/.bashrc or ~/.bash_profile)

code-context completion bash > ~/.local/share/bash-completion/completions/code-context

Zsh (add to ~/.zshrc or a file in fpath)

code-context completion zsh > ~/.zfunc/_code-context

Fish

code-context completion fish > ~/.config/fish/completions/code-context.fish

PowerShell

code-context completion powershell >> $PROFILE

Usage: code-context completion <SHELL>

Arguments:

• <SHELL> — Shell to generate completion for

  Possible values: bash, elvish, fish, powershell, zsh

Claude-Code Hooks (llama agent)

The llama ACP agent reads Claude Code’s .claude/settings.json hook configuration and fires hooks at the matching points in a session’s lifecycle. This lets an existing .claude/settings.json drive policy, context injection, and tool gating for the llama agent without any agent-specific format.

The wiring is hermetic to each ACP session: hooks are loaded once per session from that session’s working directory, and a session whose cwd has no .claude settings runs exactly as before, paying only one cheap settings-chain read at session start.

Events fired vs. accepted-but-never-fired

The llama agent fires the subset of Claude Code hook events that map to an ACP lifecycle seam. Every other Claude Code event kind is accepted in the settings file (so the same file works with both Claude Code and the llama agent) but never fires. Such a kind is either dropped when registrations are built or registered but never emitted — see the two categories below.

Fired

Accepted but never fired (forward-compatible)

These event kinds deserialize without error and may appear in a shared .claude/settings.json (so the same file works with both Claude Code and the llama agent), but the llama agent never fires them. There are two distinct reasons, and they behave differently at registration-build time:

Dropped at registration build (no ACP HookEventKind). Their HookEventKindConfig → HookEventKind conversion returns Err(UnsupportedEventKind), so build_registrations skips them entirely — no registration is ever created:

PermissionRequest, SubagentStart, SubagentStop, PreCompact, Setup, SessionEnd.

Registered but never emitted (no seam constructs the event). These convert to a valid HookEventKind, so registrations are built for them — but no production seam ever constructs the corresponding HookEvent (the variants exist only for tests and forward compatibility), so a matching hook never runs:

PostCompact, TeammateIdle, TaskCompleted, Elicitation, ElicitationResult, InstructionsLoaded, ConfigChange, WorktreeCreate, WorktreeRemove.

The net behavior is the same for both groups — the hook never fires — but only the first group is dropped when registrations are built.

A malformed or unknown event kind never fails the agent — it is logged and the rest of the config still loads.

Settings file locations and precedence

Hooks are read from a three-file chain, resolved relative to the session’s working directory (the ACP session cwd is the project/workspace directory — there is no ancestor walk-up). The chain, lowest precedence first:

1. User — ~/.claude/settings.json
2. Project — <cwd>/.claude/settings.json
3. Local — <cwd>/.claude/settings.local.json

Merge order is additive, not override

Claude Code runs every matching hook from every source. The loader mirrors this: for each event name, the matcher groups from all three files are concatenated in chain order (user → project → local). A PreToolUse group in the user file and a PreToolUse group in the project file both fire — there is no override.

disableAllHooks is a hard off-switch

If disableAllHooks: true appears in any applicable file, the entire merged config is dropped and the session runs with no hooks — even hooks declared in the same file or a higher-precedence file. It is a global kill switch, not a per-file opt-out.

Not supported

Only the three settings.json files above are read. The following Claude Code hook sources are not supported by the llama agent:

• Plugin hooks (hooks/hooks.json inside an installed plugin).
• Managed-policy settings (enterprise/managed managed-settings.json).
• Skill / agent frontmatter hooks.

Only the top-level hooks key of each file is read; every other key (permissions, env, statusLine, model, …) is ignored.

Handler types

A hook entry’s type selects how its decision is produced. All three Claude Code handler types are supported:

prompt and agent handlers are evaluated by the per-session llama model evaluator, so they reuse the loaded model — no separate model is configured for hooks. A prompt/agent handler returns { "ok": true } to allow or { "ok": false, "reason": "..." } to block.

Tool-name mapping divergence

This is the most important difference from Claude Code. PreToolUse / PostToolUse matchers are tested against the llama-agent tool name, the bare name the model emits — not Claude Code’s tool names.

Write matchers against the llama names, not Bash / Edit / Write:

Canonical llama-agent tool-name list

The matcher value is the bare tool name the model emitted (never a decorated display title). A matcher is regex-tested against that exact emitted name, so it matches only the name the model actually used — not every alias that resolves to the same capability. The canonical built-in names are:

• shell — execute a shell command. The model may emit either shell or terminal; both resolve to the terminal capability, but a matcher must target whichever name your model emits (shell does not also match a tool emitted as terminal).
• fs_read — read a file. The model may emit fs_read, fs/read, read_file, or read_text_file; all resolve to the read capability, but match whichever name your model emits (a fs_read matcher does not also match read_file).
• fs_write — write a file. The model may emit fs_write, fs/write, write_file, or write_text_file; all resolve to the write capability, but match whichever name your model emits.
• mcp__<server>__<tool> — any MCP tool, namespaced by its server. For example mcp__sah__kanban, mcp__sah__code_context. The <server> and <tool> segments are the MCP server name and the tool name it exposes.

A matcher is a regex (Claude Code semantics): fs_write matches exactly that tool, mcp__sah__.* matches every tool from the sah MCP server, and an omitted matcher matches every tool for that event. To match more than one alias, use an alternation — e.g. shell|terminal or fs_read|read_file.

Exit-code and JSON-stdout contract

command hooks use Claude Code’s exit-code + JSON-stdout contract verbatim.

Exit code

JSON stdout

On exit 0, stdout may be a JSON object controlling the decision. Field names are camelCase, matching Claude Code:

{
  "continue": true,
  "stopReason": "shown to the user when continue is false",
  "suppressOutput": false,
  "systemMessage": "warning shown to the user",
  "decision": "block",
  "reason": "why the action was blocked",
  "additionalContext": "text appended to the model's context",
  "hookSpecificOutput": { "hookEventName": "PreToolUse", "...": "..." }
}

• continue: false stops the turn entirely (takes precedence over everything else). At the tool seam this maps to “stop the turn without dispatching.”
• decision: "block" blocks the action; reason is the message. For Stop, decision: "block" means “do not stop” (see ACP notes).
• additionalContext is appended to what the model sees next — used by UserPromptSubmit, PostToolUse, PostToolUseFailure, and SessionStart.
• hookSpecificOutput carries the per-event fields, tagged by hookEventName:
  • PreToolUse → permissionDecision (allow / deny / ask), permissionDecisionReason, updatedInput, additionalContext.
  • PostToolUse / PostToolUseFailure / UserPromptSubmit / SessionStart / Notification → additionalContext.
  • Stop → reason.

Command hook stdin

Each command hook receives the event as JSON on stdin, including hook_event_name, the event’s fields (e.g. tool_name, tool_input, cwd, source), the session’s transcript_path (the per-session raw.jsonl, so a hook can read the transcript), and the permission_mode string.

The permission_mode is mapped from the llama agent’s coarser permission policy: AlwaysAsk → default, and AutoApproveReads / RuleBased → acceptEdits. It is informational; it does not gate firing.

ACP-specific notes

• PreToolUse blocks at the real dispatch seam. Tool hooks fire synchronously around the actual tool dispatch, so a deny (or permissionDecision: deny) genuinely prevents the tool from running. The model receives the deny reason as the tool’s result and the turn continues — matching Claude Code’s “blocked” behavior. An updatedInput rewrites the tool arguments before dispatch; additionalContext is appended to the result fed back to the model. PreToolUse fires exactly once per tool call.
• Stop ⇒ continue. A Stop hook that “blocks” (decision: block) means “don’t stop yet.” The finished turn’s response is annotated with hook_should_continue: true and hook_reason on its meta so the client can observe the request to keep going.
• Notification is the only notification-family hook. Agent message, thought, and plan notifications fire the Notification event. The notifications themselves are still broadcast to the client UI regardless of hooks; only the hook firing is gated.
• SessionStart source. new_session fires SessionStart with source startup; load_session / resume fires it with source resume. It is idempotent per session id — a resume after a load does not re-fire startup.

End-to-end behavior summary

For a session whose cwd carries a real .claude/settings.json (and/or settings.local.json), and a hermetic user-level ~/.claude/settings.json:

• SessionStart fires once on new_session.
• A UserPromptSubmit command hook exiting 2 blocks a forbidden prompt before the model is ever invoked; the reason reaches the client.
• A PreToolUse deny prevents the matched tool from dispatching; the model sees the reason as the tool result.
• PostToolUse additionalContext reaches the model after a successful call.
• A Stop hook that blocks sets hook_should_continue on the response meta.
• disableAllHooks: true disables all of the above end-to-end.
• A user-level (HOME) hook and a project hook for the same event both fire (additive precedence).