Quick Start Guide¶

Get up and running with Samuel (Artificial Intelligence Coding Framework) in under a minute.

60-Second Setup¶

# 1. Install the CLI
brew tap ar4mirez/tap && brew install samuel

# 2. Initialize your project
cd your-project
samuel init

# 3. Done! Start coding with AI guardrails

# 1. Install via curl
curl -sSL https://raw.githubusercontent.com/ar4mirez/samuel/main/install.sh | sh

# 2. Initialize your project
cd your-project
samuel init

# 1. Install via Go
go install github.com/ar4mirez/samuel/cmd/samuel@latest

# 2. Initialize your project
cd your-project
samuel init

# 1. Copy to your project
cp -r /path/to/samuel/{CLAUDE.md,.claude} ./

# 2. (Optional) For cross-tool compatibility
ln -s CLAUDE.md AGENTS.md

The system works immediately:

• AI loads CLAUDE.md automatically (500 lines of guardrails + operations)
• Language guides auto-load based on file extensions
• 14 CLI commands for component management
• Progressive - starts minimal, grows with your project
• Cross-tool: Works with any AI assistant via AGENTS.md

Discover Components Before Installing¶

One of Samuel's best features is component discovery. Before installing anything, explore what's available:

Search for Components¶

# Find anything matching "react"
samuel search react

# Search only frameworks
samuel search --type fw api

# Fuzzy matching - finds "python" even with typos
samuel search pythn

Preview Before Installing¶

# See component details
samuel info framework react

# Preview the actual content (first 20 lines)
samuel info lang typescript --preview 20

# See what's related
samuel info fw nextjs  # Shows: Related to typescript, react

Add What You Need¶

# Add a framework
samuel add framework react

# Add a language guide
samuel add language typescript

# Add a workflow
samuel add workflow code-review

# Use short aliases
samuel add fw react
samuel add lang ts
samuel add wf security-audit

Check What's Installed¶

# List installed components
samuel list

# See what's available (not installed)
samuel list --available

# Filter by type
samuel list --type frameworks

Choose Your Path¶

Path 1: New Project with CLI¶

# Create and initialize a new project
mkdir my-project && cd my-project
samuel init

# Or initialize with specific components
samuel init --languages typescript,python --frameworks react

The CLI will:

1. Create CLAUDE.md with all guardrails
2. Create .claude/ directory structure
3. Let you select languages, frameworks, workflows interactively
4. Set up cross-tool compatibility (AGENTS.md symlink)

Path 2: Existing Project¶

cd existing-project
samuel init

AI will:

1. Detect existing files (won't overwrite without --force)
2. Create Samuel structure
3. Let you select relevant components

Or use the workflow for deep analysis:

@.claude/skills/initialize-project/SKILL.md

"This is an existing project - analyze the codebase"

Path 3: Jump Right In¶

Just start coding. AI follows guardrails automatically.

"Fix the login button alignment"

"Add user profile editing"

"Build real-time chat with WebSockets"

CLI Command Reference¶

Here are the most useful commands to get started:

Type aliases: language (lang, l), framework (fw, f), workflow (wf, w)

Full CLI Reference

Verify Installation¶

After setup, verify everything is working:

# Check installation health
samuel doctor

# See what's installed
samuel list

# Check for updates
samuel version --check

Expected output from samuel doctor:

Samuel Health Check
==================

[OK] CLAUDE.md exists
[OK] .claude/ directory exists
[OK] Configuration valid
[OK] 3 languages installed
[OK] 2 frameworks installed
[OK] All workflows available

Status: Healthy

What Happens Next?¶

Once initialized, the system is ready. Here's what to expect:

Automatic Loading¶

When you start working with an AI assistant:

1. CLAUDE.md loads automatically - 500 lines of guardrails and operations
2. Language guides auto-load - Based on file extensions you're working with
3. Guardrails are enforced - Code quality, security, testing standards

Progressive Growth¶

The .claude/ directory grows with your project:

Next Steps¶