SwissArmyHammer

The only coding assistant you'll ever need. Write specs, not code.

📚 Complete Documentation & Guides 📚

📖 Documentation

---

🎯 Why SwissArmyHammer?

Tired of babysitting AI while it codes? Want to describe what you want and come back to finished software?

SwissArmyHammer is the full-featured coding assistant that works while you sleep. Write a simple spec, kick off a workflow, and return to find your project implemented, tested, and ready to ship.

🚀 Set It and Forget It Coding

• Write a 4-sentence spec in markdown
• Run sah
• Go get coffee (or take a nap)
• Return to a fully implemented, tested CLI application

🛠️ Complete MCP Tool Suite

SwissArmyHammer IS an MCP server with 25+ professional-grade tools:

• File Operations - Read, write, edit, search across any codebase
• Git Integration - Branch management, commit workflows, PR automation
• Rules & Todos - Built-in quality checks and task management
• Web Integration - Fetch docs, search APIs, gather requirements
• Shell Execution - Safe, controlled system interaction
• Questions & Context - Elicitation-based Q&A system for capturing decisions

🧠 Agentic Intelligence

• Multi-hour autonomous execution without human intervention
• Planning and replanning as requirements evolve
• Error recovery and self-correction
• Context preservation across long-running tasks
• Tool orchestration that rivals human developers

📝 Markdown-Driven Everything

• Prompts are markdown files with Liquid templating
• Workflows are state machines defined in markdown
• Rules define code quality standards as markdown files
• Specs are simple markdown documents
• No databases, no cloud, no lock-in - just files

🏃‍♂️ Get Started in 5 Minutes

Build a weather CLI that fetches data from OpenWeatherMap - from idea to working code in minutes:

1. Installation

brew install swissarmyhammer/tap/swissarmyhammer-cli

OR

# Install SwissArmyHammer
cargo install --git https://github.com/swissarmyhammer/swissarmyhammer swissarmyhammer-cli

# Add to Claude Code as MCP server
claude mcp add --scope user sah sah serve

THEN

sah doctor

2. Create Your Project

# Set up a new project
mkdir weather-cli && cd weather-cli
git init

3. Write Your Spec (30 seconds)

Create spec.md:

# Weather CLI

Build a command-line tool that fetches current weather for any city using the OpenWeatherMap API.
The CLI should accept a city name as an argument and display temperature, humidity, and conditions in a clean format.
Include error handling for invalid cities and network issues.
Add configuration for API key via environment variable or config file.
Include basic tests and a README with usage examples.

4. Let SwissArmyHammer Build It

# Plan the implementation from your spec
sah plan spec.md

# Let SwissArmyHammer work through all todos autonomously
sah do

5. Watch the Magic ✨

SwissArmyHammer will autonomously:

• Break down your spec into rules and todos
• Initialize a Rust CLI project with proper structure
• Implement HTTP client for OpenWeatherMap API
• Add command-line argument parsing with clap
• Handle configuration and environment variables
• Write comprehensive error handling
• Create unit and integration tests
• Generate documentation and usage examples
• Work through each todo systematically until complete

No chatting. No hand-holding. No babysitting. Just working software.

---

That's the power of SwissArmyHammer - from idea to implementation while you focus on what matters.

🎯 What Makes SwissArmyHammer Different

Real Autonomy, Not Chat Theater

Other AI coding tools make you supervise every step. SwissArmyHammer works like a senior developer - give it requirements and check back when it's done.

Production-Ready from Day One

• File-based architecture - No databases, no cloud dependencies
• Git-native workflows - Branches, commits, and PRs handled automatically
• Industrial tooling - Shell execution, file operations, web integration
• Type-safe everywhere - Rust's safety guarantees throughout
• Consistent error handling - Unified Severity trait (Warning/Error/Critical) enables appropriate error handling, logging, and user notification across all 20+ error types in the codebase. See swissarmyhammer-common for details

MCP Integration Leader

SwissArmyHammer pioneered comprehensive MCP server implementation:

• 40+ professional tools available to any MCP client
• Workflow orchestration across tool boundaries
• Context preservation spanning hours of work

Markdown-Driven Development

Everything is a markdown file you can read, edit, and version control:

• Prompts with Liquid templating and variables
• Workflows as state machines with visual diagrams
• Rules for code quality standards in your repository
• Specs that become working software

Built for Scale

• Memory-efficient operation on large codebases
• Incremental processing - only analyze what changed
• Parallel execution where safe
• Resource controls prevent runaway processes

---

🎮 Build Your First Workflow

Create a fun "Daily Crypto Report" workflow that fetches live data and generates a formatted report.

SwissArmyHammer workflows aren't just for coding - you can build multi-step agents for any task using nothing but markdown files.

1. Create a Research Prompt

mkdir -p ~/.swissarmyhammer/prompts
cat > ~/.swissarmyhammer/prompts/crypto-research.md << 'EOF'
---
title: Crypto Research
description: Research cryptocurrency information
arguments:
  - name: symbol
    description: Crypto symbol (e.g. BTC, ETH)
    required: true
---

Research the cryptocurrency {{symbol}}:

1. Use web_fetch to get current price and market data from CoinGecko API: `https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd&include_24hr_change=true&include_market_cap=true` (Note: adjust coin ID based on symbol - bitcoin for BTC, ethereum for ETH, etc.)

2. Use web_search to find recent news about {{symbol}} cryptocurrency

3. Analyze the collected data and create a comprehensive research summary

4. Use files_write to save your research to ".swissarmyhammer/{{symbol}}-research.md" so it can be used for the final report

Include: current price, 24h change, market cap, recent news highlights, and key developments.
EOF

2. Create a Report Formatter Prompt

cat > ~/.swissarmyhammer/prompts/format-report.md << 'EOF'
---
title: Format Report
description: Format crypto research into a beautiful report
arguments:
  - name: symbol
    description: Crypto symbol for the report
    required: true
---

Create a beautiful daily crypto report for {{symbol}}:

1. Use files_read to retrieve the research data from ".swissarmyhammer/{{symbol}}-research.md"

2. Transform the research into a professional daily report with:
   - 📊 Executive summary
   - 💰 Key metrics table (price, change, market cap)
   - 📈 Trend analysis
   - ⚠️ Risk assessment
   - 💡 Final recommendation

3. Use professional formatting with emojis and clear sections

4. Save the final report using files_write as "daily-{{symbol}}-report.md"
EOF

3. Create the Workflow

mkdir -p ~/.swissarmyhammer/workflows
cat > ~/.swissarmyhammer/workflows/crypto-report.md << 'EOF'
---
name: crypto-report
title: Daily Crypto Report
description: Generate comprehensive cryptocurrency reports
arguments:
  - name: crypto
    description: Cryptocurrency symbol to research
    default: "BTC"
---

# Daily Crypto Report Workflow

```mermaid
stateDiagram-v2
    [*] --> Start
    Start --> ResearchCrypto
    ResearchCrypto --> FormatReport
    FormatReport --> Complete
    Complete --> [*]

Actions

• Start: Log "Starting crypto report for ${crypto}"
• ResearchCrypto: Execute prompt "crypto-research" with symbol="${crypto}"
• FormatReport: Execute prompt "format-report" with symbol="${crypto}"
• Complete: Log "Crypto report completed and saved as daily-${crypto}-report.md" EOF

### 4. Run Your Workflow
```bash
# Generate report for Bitcoin
sah crypto-report --param crypto=BTC

# Or try different cryptos
sah crypto-report --param crypto=ETH
sah crypto-report --param crypto=SOL

# Full form (also works)
sah flow crypto-report --param crypto=BTC

This workflow demonstrates SwissArmyHammer's power:

• Web integration - Fetches live API data and searches news
• Prompt orchestration - Chains research and formatting prompts
• File operations - Saves professional reports
• Memory management - Passes data between workflow states
• Parameterization - Customizable with different crypto symbols

The result: A beautiful daily crypto report with live data, news analysis, and professional formatting - all from a simple markdown workflow file.

---

Ready to automate your world? Install SwissArmyHammer and start building workflows that work while you sleep. 🚀

🔄 Workflow Execution

SwissArmyHammer provides a powerful dynamic workflow system for executing both built-in and custom workflows.

Quick Start

# List available workflows
sah flow list

# Execute a workflow (shortcut form - recommended)
sah plan ideas/feature.md

# Execute a workflow (full form)
sah flow plan ideas/feature.md

# Execute with options
sah do --quiet
sah plan spec.md --interactive --dry-run

Key Features

• Dynamic Discovery: List all available workflows with sah flow list --verbose
• Shortcuts: Each workflow gets a convenient top-level command
• Progress Tracking: MCP notifications for long-running workflows
• Parameter Support: Required parameters are positional, optional use --param
• Common Options: --interactive, --dry-run, --quiet work with all workflows

Built-in Workflows

Do: Autonomous todo execution

sah do --quiet

Plan: Generate implementation plans from specs

sah plan ideas/feature.md --interactive

Learn More

• CLI Flow Usage Guide - Complete command reference
• Flow Migration Guide - Migrating from old syntax
• MCP Flow Tool - MCP API reference

---