Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

SwissArmyHammer transforms AI prompt and workflow management by treating them as simple markdown files. It provides a unified, file-based approach that integrates seamlessly with your development workflow and Claude Code.

The Problem

Working with AI assistants involves repetitive prompt crafting, context loss, inconsistent results, limited automation, and poor organization of prompts scattered across different tools.

The Solution

SwissArmyHammer provides three integrated components that work together to solve these problems:

Command Line Application

A powerful CLI that executes prompts and workflows, with comprehensive diagnostics, validation, and shell completions.

MCP Server

Seamless integration with Claude Code via the Model Context Protocol, providing a comprehensive tool suite for AI-powered development.

Rust Library

A flexible library for building prompt-based applications with comprehensive APIs for custom integrations.

Core Architecture

SwissArmyHammer uses a hierarchical file system approach:

File-Based Management

  • Store prompts and workflows as markdown files with YAML front matter
  • No databases or complex configuration required
  • Everything is version-controlled and easily shared
  • Live reloading with automatic change detection

Organized Hierarchy

Clear precedence rules across three locations:

  1. Builtin - Pre-installed prompts and workflows embedded in the binary
  2. User - Personal collection in ~/.swissarmyhammer/
  3. Local - Project-specific files in ./.swissarmyhammer/

Liquid Template Engine

  • Dynamic content with variables, conditionals, and loops
  • Custom filters for domain-specific operations
  • Environment integration and system context access
  • Extensible plugin architecture

Key Features

Workflow Management

  • State-based workflow execution with Mermaid diagrams
  • Parallel and sequential action execution
  • Built-in error handling and recovery mechanisms

Development Integration

  • Code quality rules with LLM-based validation
  • Ephemeral task management with rich context
  • File operations and code analysis tools

Built-in Resources

  • 20+ production-ready prompts for common development tasks
  • Example workflows demonstrating best practices
  • Comprehensive MCP tool suite for Claude Code integration

Quick Examples

Simple Prompt

---
title: Code Review Helper
description: Assists with code review tasks
arguments:
  - name: language
    description: Programming language
    required: true
---

Review this {{language}} code for:
- Quality and style
- Potential bugs
- Performance issues
- Best practices

Basic Workflow

---
name: feature-development
description: Complete feature development process
initial_state: plan
---

### plan
Plan the feature implementation
**Next**: do

### do
Execute the implementation plan
**Description**: Work through all todos autonomously
**Next**: review

### review
Check code against rules
**Description**: Verify code meets all acceptance criteria
**Next**: complete

Command Line Usage

# Diagnose setup
sah doctor

# Test a prompt
sah prompt test code-review --var language=rust

# Run a workflow
sah flow run feature-development

# Configure Claude Code integration
claude mcp add --scope user sah sah serve

Next Steps

Installation

Install SwissArmyHammer and configure it for use with Claude Code.

Prerequisites

  • Rust 1.70+ - Required for building from source
  • Claude Code - For MCP integration (recommended)
  • Git - For issue management features

Install from HomeBrew

brew install swissarmyhammer/tap/swissarmyhammer-cli

Verify Installation

Check that everything is working:

sah --version
sah doctor

The doctor command checks your installation and configuration.

Claude Code Integration

Configure SwissArmyHammer as an MCP server for Claude Code:

# Add SwissArmyHammer as an MCP server
claude mcp add --scope user sah sah serve

# Verify the connection
claude mcp list

Once configured, SwissArmyHammer tools will be available in Claude Code automatically.

Directory Setup

SwissArmyHammer creates directories as needed, but you can set them up manually:

User Directory (Optional)

# Personal prompts and workflows
mkdir -p ~/.swissarmyhammer/prompts
mkdir -p ~/.swissarmyhammer/workflows

Project Directory (Optional)

# Project-specific prompts and workflows
mkdir -p .swissarmyhammer/prompts
mkdir -p .swissarmyhammer/workflows

Built-in prompts and workflows are embedded in the binary and available immediately.

Shell Completions (Optional)

Add shell completions for better CLI experience:

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

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

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

Configuration (Optional)

SwissArmyHammer works with sensible defaults. Optionally create ~/.swissarmyhammer/sah.toml:

[general]
auto_reload = true

[logging]
level = "info"

[mcp]
timeout_ms = 30000

Quick Test

Test your installation:

# List built-in prompts
sah prompt list

# Test a simple workflow
sah flow run hello-world

# Check everything is working
sah doctor

Common Issues

Command not found

If sah: command not found, ensure Cargo’s bin directory is in your PATH:

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Build failures

Update Rust and install dependencies:

rustup update stable
# On Ubuntu/Debian:
sudo apt-get install build-essential pkg-config libssl-dev

MCP connection issues

Verify Claude Code can find the binary:

which sah
claude mcp restart sah

Next Steps

Quick Start

Get up and running with SwissArmyHammer in 5 minutes. This guide will show you how to use full auto coding to turn specifications into working code.

Full Auto Coding

SwissArmyHammer’s most powerful feature is its ability to transform natural language specifications into complete, tested applications. Here’s how:

Step 1: Verify Installation

First, make sure SwissArmyHammer is properly installed:

sah --version
sah doctor

The doctor command will check your installation and suggest any needed fixes.

Step 2: Create a Specification

Create a markdown file describing what you want to build. You can use plain language, use cases, or code snippets:

mkdir -p specification
cat > specification/index.md << 'EOF'
# Calculator Application

Build a command-line calculator that:
- Supports basic operations: add, subtract, multiply, divide
- Has a REPL interface for interactive use
- Handles errors gracefully
- Includes comprehensive tests
- Has proper documentation
EOF

Step 3: Generate the Plan

Run the planning workflow to analyze your specification and create implementation rules and todos:

sah plan specification/index.md

This generates rules and todos in the .swissarmyhammer/ directory. Rules define acceptance criteria, and todos represent specific tasks.

Step 4: Commit the Plan

git add .swissarmyhammer/rules .swissarmyhammer/todo.yaml
git commit -m "plan: add calculator rules and todos"

Step 5: Execute the Implementation

Now let SwissArmyHammer implement your specification:

sah do

This will:

  • Work through each todo automatically
  • Write the code
  • Run tests and fix any failures
  • Commit changes as it progresses
  • Continue until all todos are complete

The implementation typically takes a few hours, but it’s faster than manual coding and produces high-quality, tested code.

Step 6: Review the Results

Once complete, you’ll have a fully working application with:

  • Complete source code
  • Passing tests
  • Documentation
  • Git history showing the implementation process

Example: Calcutron

For a complete example, check out Calcutron, a sample calculator built entirely with SwissArmyHammer:

# Clone the example
git clone git@github.com:swissarmyhammer/calcutron.git
cd calcutron

# Run the preflight check
sah doctor

# Generate the plan
sah plan specification/index.md
git add .swissarmyhammer/rules .swissarmyhammer/todo.yaml
git commit -am 'plan'

# Let it build
sah do

Manual Workflow Examples

For more targeted tasks, you can use SwissArmyHammer’s manual workflows and prompts.

Create Your First Prompt

Create a personal prompts directory and your first prompt:

# Create the directory structure
mkdir -p ~/.swissarmyhammer/prompts

# Create a simple helper prompt
cat > ~/.swissarmyhammer/prompts/task-helper.md << 'EOF'
---
title: Task Helper
description: Helps with various programming tasks
arguments:
  - name: task
    description: What you need help with
    required: true
  - name: context
    description: Additional context (optional)
    required: false
    default: "general programming"
---

I need help with: **{{task}}**

Context: {{context}}

Please provide:
1. Clear, step-by-step guidance
2. Code examples if applicable
3. Best practices to follow
4. Common pitfalls to avoid

Make your response practical and actionable.
EOF

Step 3: Test Your Prompt

Test the prompt using the CLI:

# Test with required argument
sah prompt test task-helper --var task="debugging a Rust application"

# Test with both arguments
sah prompt test task-helper \
  --var task="implementing error handling" \
  --var context="web API development"

You should see the rendered prompt with your variables substituted.

Step 4: Configure Claude Code Integration

Add SwissArmyHammer as an MCP server for Claude Code:

# Add the MCP server
claude mcp add --scope user sah sah serve

# Verify it's working
claude mcp list
claude mcp status sah

Step 5: Use in Claude Code

Now you can use your prompt directly in Claude Code. Start a conversation and use:

/task-helper task="setting up CI/CD pipeline" context="GitHub Actions for Rust project"

Claude will use your prompt template and provide structured assistance.

Step 6: Explore Built-in Prompts

SwissArmyHammer comes with 20+ built-in prompts. List them:

sah prompt list --source builtin

Try some useful ones:

# Code review helper
sah prompt test code --var task="review this function for performance issues"

# Documentation generator  
sah prompt test documentation --var task="document this API endpoint"

# Debug helper
sah prompt test debug --var error="segmentation fault in C program"

Step 7: Create a Simple Workflow

Workflows allow you to chain multiple prompts and actions. Create your first workflow:

mkdir -p ~/.swissarmyhammer/workflows

cat > ~/.swissarmyhammer/workflows/code-review.md << 'EOF'
---
name: code-review
description: Complete code review workflow
initial_state: analyze
---

## States

### analyze
Analyze the code for issues and improvements.

**Actions:**
- prompt: Use the 'code' prompt to analyze the code
- shell: Run any necessary tests

**Next**: report

### report
Generate a comprehensive review report.

**Actions:**
- prompt: Use the 'documentation' prompt to suggest documentation improvements

**Next**: complete

### complete
Review workflow completed.
EOF

Run the workflow:

sah flow run code-review

Step 8: Set Up Issue Management

SwissArmyHammer includes git-integrated issue tracking:

# Create an issue (in a git repository)
sah issue create --name "feature-auth" --content "# User Authentication

Implement JWT-based user authentication system with:
- Login/logout endpoints
- Token validation middleware
- User session management"

# List issues
sah issue list

# Work on an issue (creates/switches to branch)
sah issue work feature-auth

# Complete the issue
sah issue complete feature-auth

Step 9: Try Memoranda (Notes)

SwissArmyHammer includes a note-taking system:

# Create a memo
sah memo create --title "Project Notes" --content "# Meeting Notes

## Action Items
- [ ] Set up database schema
- [ ] Implement user API
- [ ] Write integration tests"

# List memos
sah memo list

# Search memos
sah memo search "database"

Common Patterns

Project-Specific Prompts

Create prompts specific to your project:

# In your project directory
mkdir -p .swissarmyhammer/prompts

# Create a project-specific prompt
cat > .swissarmyhammer/prompts/api-docs.md << 'EOF'
---
title: API Documentation
description: Generate API documentation for this project
arguments:
  - name: endpoint
    description: API endpoint to document
    required: true
---

Generate comprehensive API documentation for the {{endpoint}} endpoint.

Include:
- Request/response schemas
- Example requests
- Error responses
- Authentication requirements

Use our project's documentation style and format.
EOF

Template Variables

Use liquid template features for dynamic prompts:

---
title: Conditional Helper
arguments:
  - name: difficulty
    description: Task difficulty level
    required: false
    default: "medium"
---

{% if difficulty == "beginner" %}
Let's start with the basics:
{% elsif difficulty == "advanced" %}
Here's an advanced approach:
{% else %}
Here's a practical solution:
{% endif %}

[Rest of your prompt...]

Environment Integration

Use environment variables in prompts:

---
title: Project Context
---

Working on project: {{PROJECT_NAME | default: "unknown project"}}
Environment: {{NODE_ENV | default: "development"}}

[Your prompt content...]

Next Steps

Now that you have SwissArmyHammer working:

  1. Try Full Auto Coding: Create your own specification and let SwissArmyHammer build it
  2. Explore Built-in Workflows: Run sah flow list to see available workflows
  3. Create Custom Prompts: Build prompts tailored to your specific needs
  4. Integrate with Claude Code: Use SwissArmyHammer as an MCP server for enhanced AI assistance

Getting Help

  • Run sah --help for command help
  • Use sah doctor to diagnose issues
  • Visit the GitHub repository for issues and discussions