Hacksmith

From browsing to building. One command.

Hacksmith accelerates engineering productivity by automating complex setup and integration tasks through guided workflows called blueprints. Teams standardize implementation processes and cut onboarding time by up to 80%.

Introduction

Teams use blueprints—structured workflow definitions—to guide users through multi‑step processes like setting up payment systems or configuring development environments. Hacksmith eliminates the gap between reading docs and shipping code.

Core Concepts

• Blueprint: Defines a guided workflow for multi-step engineering tasks.
• Workflow: Executes the blueprint interactively, adapting based on input and state.
• Templates: Parameterize code/config outputs for different environments and stacks.
• Sessions: Track progress and resume safely across runs and projects.

Installation and Setup

Install Hacksmith and verify it works.

# Option 1: Binary installer (recommended)
curl -fsSL https://raw.githubusercontent.com/saif-shines/hacksmith/main/scripts/install.sh | bash

# Option 2: npm (requires Node.js >=18)
npm install -g hacksmith

# Verify
hacksmith --version

When installed via npm, Hacksmith requires Node.js 18 or later. Binaries work on macOS, Linux, and Windows.

Basic Usage

Start Hacksmith in interactive mode (no args) or run a blueprint directly.

# Interactive mode
hacksmith

# Load a local blueprint
hacksmith plan --blueprint ./path/to/blueprint.toml

# Load from GitHub (shorthand, auto-adds --execute unless provided)
hacksmith saif-shines/hacksmith-blueprints

# Configure AI assistant and analyze tech stack
hacksmith preferences setup

# Check session status
hacksmith session status

Use Cases

Integrate Payment Processing

Add Stripe payments with a guided flow.

hacksmith plan --blueprint ./stripe-integration.toml

Onboard New Team Members

Standardize new-hire setup across tools, repos, and permissions.

hacksmith plan --blueprint ./team-onboarding.toml

Set Up Development Environments

Create consistent local dev setups with required SDKs and configs.

hacksmith plan --blueprint ./dev-environment.toml

Implement Authentication Systems

Guide secure auth flows (e.g., Auth0, Firebase) tailored to your stack.

hacksmith plan --blueprint ./auth-implementation.toml

Architecture Overview

User Input → Command Layer → Engine Layer → Service Layer → System Output

Blueprints define the workflow logic in TOML format. The engine interprets these definitions at runtime, adapting execution based on user responses and system state.

Project-Aware Storage

Hacksmith uses project-aware storage to keep data organized and avoid cross-project leakage:

• Project-local storage (.hacksmith/): variables, tech stack, session state
• System-level storage (~/.hacksmith/): AI agent preferences, backups, global settings

Session Management

Sessions save your progress and support resuming interrupted workflows:

• Automatic project detection (git/package files)
• Progress tracking (current step, captured variables)
• Resume prompts on restart
• Automatic data backups after success

Best Practices

• Design clear steps with rationale and validation.
• Favor adaptable prompts that work across stacks and frameworks.
• Use conditional steps for optional or gated flows.
• Mark secrets as sensitive; never print or store them in plaintext.

Troubleshooting

Installation

• If hacksmith: command not found, ensure the install directory is on your PATH or restart your terminal.
• For npm installs, ensure Node.js >=18.

Blueprint execution

• If a blueprint fails with “template not found”, verify the file path and referenced templates.

Glossary

• Blueprint: TOML file defining steps, variables, and outputs.
• Template: Reusable configuration blocks within blueprints.
• Workflow: Runtime execution of a blueprint.
• Step: Individual action in a workflow (input, navigate, info, etc.).
• Engine: Processor that interprets blueprints and executes steps.

Next Steps

• Read the Blueprint Spec at https://thehacksmith.dev/get-started/author-blueprint
• Follow Blueprint Best Practices at https://thehacksmith.dev/get-started/blueprint-best-practices
• See the Command Reference at https://thehacksmith.dev/handbooks/commands