Claude Code Guide

Claude Code Guide

Complete guide to Claude Code as a system-wide assistant

---

> DON'T PANIC. Transform Claude Code from "project-based coding tool" into "computer-wide intelligent assistant."

[](https://opensource.org/licenses/MIT)

Compiled from insights by Boris Cherny (creator of Claude Code), Andrej Karpathy, Anthropic Best Practices, and The Hitch-Hiker's Guide to Vibe Engineering.

---

Quick Start

# Copy the starter kit to your home directory
cp -r starter-kit ~/.claude

# Edit with your details
nano ~/.claude/CLAUDE.md

# Start Claude Code
claude

---

Table of Contents

• [Philosophy: Vibe Engineering](#vibe-engineering-philosophy)
• [Architecture Overview](#architecture-overview)
• [MCP Servers (External Tools)](#mcp-servers)
• [Commands (Slash Commands)](#commands)
• [Skills (Procedural Knowledge)](#skills)
• [Agents (Custom Personalities)](#agents)
• [The Global CLAUDE.md](#the-global-claudemd)
• [Hooks (Automation)](#hooks)
• [IDE & Terminal Hacks](#ide--terminal-hacks)
• [Boris Cherny's Patterns](#boris-chernys-patterns)
• [Setup Checklist](#setup-checklist)

---

Vibe Engineering Philosophy

DON'T PANIC

> "Vibe Engineering is the second-best way to write software in the known universe. The best way, of course, is to have someone else do it entirely while you sip Pan Galactic Gargle Blasters."

VIBE ENGINEERING (n.): The deliberate practice of building software through AI collaboration—describing intent, reviewing output, and iterating toward working systems. Distinguished from "vibe coding" by emphasizing engineering: understanding what you build, owning what you ship.

The Risk Classification System

| Level | Label | Meaning | |-------|-------|---------| | 🟢 | Mostly Harmless | If it breaks, nothing bad happens | | 🟡 | Caution Advised | Annoying but recoverable | | 🟠 | Danger | Real problems if this fails | | 🔴 | Here Be Dragons | Catastrophic consequences |

The Karpathy Spectrum

"Fully give in to the vibes" ←————————————→ "Read every line"
            ↑                                        ↑
        Prototypes                              Production

Match your scrutiny to the risk level.

The Four Honest Questions

Before shipping to production:

| Question | What It Really Asks | |----------|---------------------| | Can you debug it? | If this breaks at 3am, can you fix it? | | Can you explain it? | Could you walk someone through it? | | Can you extend it? | When requirements change, can you modify it? | | Can you own it? | Will you take responsibility in production? |

If any answer is "no" — you're not ready to ship.

The Street Rules

1. Context is currency — Specific prompts outperform vague requests
2. Verify before trust — The AI cannot test itself
3. Ship before perfect — Done beats ideal

The Towel Principle

> "A towel is about the most massively useful thing an interstellar hitchhiker can have."

In Vibe Engineering, version control is your towel.

# Before any AI session
git add -A && git commit -m "checkpoint: before AI session"

---

Architecture Overview

~/.claude/                      # Global Claude configuration
├── CLAUDE.md                   # Master instructions (loaded every session)
├── mcp.json                    # MCP server connections
├── settings.json               # Permissions, plugins
├── commands/                   # Slash commands
│   ├── dev/                    # /dev:init, /dev:test
│   └── learning/               # /learning:explain
├── skills/                     # Detailed procedures
├── agents/                     # Custom personalities
├── hooks/                      # Automation triggers
└── memory/                     # Persistent context

Key Insight: Everything in ~/.claude/ applies globally. Project-specific overrides go in .claude/ within the project.

The Counter-Intuitive Truth

Boris Cherny's setup is "surprisingly vanilla." His advice:

> "Claude Code works great out of the box. Don't over-customize initially."

---

MCP Servers

MCPs (Model Context Protocol) connect Claude to external systems. This transforms Claude from "chat assistant" to "system-wide agent."

Categories

| Category | Examples | What It Enables | |----------|----------|-----------------| | Communication | WhatsApp, Slack, Discord, Gmail | Send/receive messages | | Data | Supabase, SQLite, PostgreSQL | Database queries | | Productivity | Calendar, Todoist, Obsidian | Scheduling, tasks, notes | | Development | GitHub, Git | Repo management, PRs | | Automation | n8n, Puppeteer | Workflows, browser control | | Memory | server-memory | Persistent context |

Essential MCPs to Start

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

Pattern: If you use it daily, give Claude access to it.

See [examples/mcp-configs/](examples/mcp-configs/) for more configurations.

---

Commands

Commands are reusable prompts triggered by /command-name.

Structure

---
description: Short description shown in command list
thinking: true  # Optional: enable extended thinking
---

# Command Name

Instructions for Claude when this command is invoked.

Organization

commands/
├── dev/init.md           → /dev:init
├── dev/test.md           → /dev:test
├── learning/explain.md   → /learning:explain
└── organize.md           → /organize

See [starter-kit/commands/](starter-kit/commands/) for templates.

---

Skills

Skills are more detailed than commands — they contain step-by-step procedures.

Think of commands as "triggers" and skills as "detailed playbooks."

Structure

---
name: skill-name
description: What this skill does
---

# Skill Name

## When to Use
- Condition 1
- Condition 2

## Procedure

### Step 1: [Name]
Detailed instructions...

### Step 2: [Name]
Detailed instructions...

## Templates
Example outputs...

See [starter-kit/skills/](starter-kit/skills/) for templates.

---

Agents

Agents define specialized personas Claude can adopt.

Structure

---
name: agent-name
description: What this agent specializes in
model: sonnet
---

You are a [role] expert with deep knowledge of [domain].

## Expertise Areas
- Area 1
- Area 2

## Approach
- How to communicate
- Safety guidelines

Example Agents

| Agent | Purpose | |-------|---------| | sysadmin | Linux system administration | | code-reviewer | Code review focus | | learning-assistant | Teaching mode |

See [starter-kit/agents/](starter-kit/agents/) for templates.

---

The Global CLAUDE.md

This is loaded automatically every session.

Essential Sections

# Personal Assistant Configuration

## About Me
- Name, timezone, context

## Preferences
- Communication style
- Safety guidelines

## Environment
- Machine details
- Key directories

## Verification
- Commands to run after code changes

The Living Document

> "Anytime we see Claude do something incorrectly we add it to CLAUDE.md, so Claude knows not to do it next time." — Boris Cherny

---

Hooks

Hooks trigger actions on specific events.

Available Events

| Event | When | Use Cases | |-------|------|-----------| | SessionStart | New session | Load context | | SessionEnd | Session ends | Save transcript | | PostToolUse | After tool runs | Auto-format code | | SubagentStop | Agent completes | Verify results |

Configuration

{
  "hooks": {
    "PostToolUse": {
      "command": "bash ~/.claude/hooks/auto-format.sh",
      "timeout": 5000
    }
  }
}

See [starter-kit/hooks/](starter-kit/hooks/) for examples.

---

IDE & Terminal Hacks

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Escape | Stop Claude | | Escape twice | Jump to previous messages | | Shift+Tab twice | Enter Plan Mode | | Shift+Enter | New line without sending |

Essential CLI Flags

claude --model opus      # Heavy reasoning
claude --model haiku     # Fast, cheap
claude -c                # Continue last session
claude -p "query"        # Non-interactive
claude --max-turns 3     # Limit depth

Slash Commands

| Command | Purpose | |---------|---------| | /clear | Reset conversation (use often!) | | /compact | Reduce tokens | | /cost | Show session cost | | /permissions | Manage safe commands | | /doctor | Check installation |

Extended Thinking

| Phrase | Budget | |--------|--------| | "think" | Low | | "think hard" | Medium | | "think harder" | High | | "ultrathink" | Maximum |

Parallel Sessions

# Git worktrees for isolated branches
git worktree add ../feature-1 feature-1
cd ../feature-1 && claude

---

Boris Cherny's Patterns

The #1 Tip

> "Give Claude a way to verify its work. If Claude has that feedback loop, it will 2-3x the quality of the final result."

Add to CLAUDE.md:

## Verification
After code changes, run:
- `npm run typecheck`
- `npm run test`
- `npm run lint`

Permissions: The Safe Way

Don't: --dangerously-skip-permissions

Do: /permissions to pre-allow safe commands

The Boris Workflow

1. Start in Plan Mode (Shift+Tab twice)
2. Iterate on plan until satisfied
3. Switch to auto-accept mode
4. Claude executes (usually one-shots)
5. Verification runs automatically

Team Sharing

Share via git:

• .claude/settings.json — Permissions
• .claude/commands/ — Slash commands
• .mcp.json — MCP configs
• CLAUDE.md — Project instructions

---

Setup Checklist

Phase 1: Foundation

• [ ] Install Claude Code
• [ ] Copy starter-kit/ to ~/.claude/
• [ ] Edit CLAUDE.md with your details

Phase 2: External Connections

• [ ] Add memory MCP
• [ ] Add one communication MCP
• [ ] Test each loads

Phase 3: Personal Workflows

• [ ] Identify 2-3 frequent tasks
• [ ] Create commands for them
• [ ] Test with /command-name

Phase 4: Deeper Customization

• [ ] Skills for complex procedures
• [ ] Agents for specialty domains
• [ ] Hooks for automation
• [ ] Set up /permissions

Ongoing Evolution

• Claude makes mistake → add to CLAUDE.md
• Task repetitive → make it a command
• Command complex → promote to skill
• Need different mode → create agent

---

Key Principles

1. Start vanilla — Add complexity only when needed
2. Iterate CLAUDE.md — Add rules when Claude errs
3. Give Claude verification — 2-3x quality improvement
4. Match scrutiny to risk — 🟢 prototype freely, 🔴 production carefully
5. Git is your towel — Never vibe without it

---

Contributing

Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.

License

MIT License - see [LICENSE](LICENSE)

---

DON'T PANIC. Share and Enjoy.

---

Part of the Libre Open-Source Stack for Claude Code

This repository is part of a growing family of open-source toolkits for Claude Code.

Libre suite — comprehensive plugin bundles

• LibreUIUX-Claude-Code — UI/UX development (152 agents, 70 plugins, 76 commands, 74 skills)
• LibreArch-Claude-Code — Software architecture and system design
• LibreCopy-Claude-Code — Technical writing and documentation engineering
• LibreDevOps-Claude-Code — DevOps engineering and infrastructure automation
• LibreEmbed-Claude-Code — Embedded systems, firmware, and IoT development
• LibreFinTech-Claude-Code — Financial technology development
• LibreGEO-Claude-Code — AI-search optimization (ChatGPT, Perplexity, Gemini, Google AI Overviews)
• LibreGameDev-Claude-Code — Game development across Godot, Unity, Unreal
• LibreMLOps-Claude-Code — ML engineering and AI operations
• LibreMobileDev-Claude-Code — Mobile app development (Flutter, React Native, native iOS, native Android)
• LibreSecOps-Claude-Code — Security operations

Skills mini-repos — single CLAUDE.md drop-ins

• vibe-engineer-skills — Direct AI codegen well (hypothesis → scope → validate → reject working-but-wrong)
• markdown-discipline-skills — Strip AI-slop from markdown (no em dashes, no marketing fluff)
• shell-safety-skills — set -euo pipefail discipline + 15 failure-mode examples
• commit-standard-skills — Ormus Commit Standard v1.0 + commit-msg hook + commitlint
• unwoke-skills — Strip AI theater (ten sins to eliminate, symmetric engagement)
• python-conventions-skills — Modern Python 3.11+ (types, pathlib, async, ruff, mypy, uv)
• typescript-conventions-skills — TypeScript strict mode, discriminated unions, Result types
• hermetic-laws-skills — Seven Hermetic Principles applied to engineering
• riper-workflow-skills — Research / Innovate / Plan / Execute / Review systematic dev
• six-day-cycle-skills — Sustainable shipping cadence with mandatory rest
• token-optimization-skills — Claude Code token + context optimization
• osint-skills — OSINT research methodology (multi-wave investigative spiral)
• calcinate-skills — Stage 1 of the Magnum Opus (burn project bloat)
• claude-md-overhaul-skills — Audit CLAUDE.md and MEMORY.md against caps
• session-handoff-skills — Session handoff + pickup discipline
• naming-skills — Product naming methodology (mine the brand's vocabulary)
• magnum-opus-skills — Seven-stage alchemy applied to project transformation

Template source

• andrej-karpathy-skills — the canonical single-file CLAUDE.md pattern (fork of jiayuanjy's original)

Star the family, not just one — that's how the suite stays coherent.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: HermeticOrmus
• Source: HermeticOrmus/claude-code-guide
• License: MIT
• Homepage: https://ormus.solutions

Install and usage instructions live in the source repository linked above.