Claude Code Workshop (2026 Q2)
An org-driven tutorial of the CLI, slash commands, and runtime surface

This file is both documentation and apparatus. Read it top-to-bottom the first time. After that, use it three ways:

1. Run blocks in place. Every sh / bash block can be executed with C-c C-c inside Emacs org-mode. Most are defensive (:eval no-export) so they don't run during batch HTML export. Remove the guard locally when you want to run them.
2. Tangle configs out. Blocks with :tangle <path> write config files when you invoke C-c C-v t. The appendix includes a starter settings.json, a hook script, an agent definition, and a SKILL.md.
3. Walk the exercises. Each session ends with an exercise. Do them.

One invariant across the whole workshop: you do not need to understand Claude Code's internals to drive it well; you need to understand its surface — the CLI, the slash commands, the hook lifecycle, and where each one writes state.

Before anything else, establish a known-good baseline.

claude --version

claude doctor

claude doctor spawns stdio MCP servers from .mcp.json as part of its health check. Run it in a directory you trust.

# Where does Claude keep its state?
ls ~/.claude/ 2>/dev/null
ls ~/.claude/projects/ 2>/dev/null | head -5

The per-project directory is derived from the absolute path: ~/.claude/projects/-home-you-ghq-github-com-you-repo. That directory holds sessions (as JSONL), memory (memory/), and auto-memory index.

Read this before Session 1. Each point anchors later sessions.

Three ways to start Claude:

# 1) Interactive session -- the default
claude

# 2) One-shot, no TTY
claude -p "list the files in this directory and group by extension"

# 3) Continue the most recent session in this directory
claude -c

The first difference that matters: -p skips the workspace-trust dialog. Only use -p in a directory you trust. It is the correct mode for scripts, CI, and pipes.

-p has the richest flag surface. Key combinations:

# Structured output with schema validation
claude -p "extract the TLDs from https://wal.sh" \
  --json-schema '{"type":"object","properties":{"tlds":{"type":"array","items":{"type":"string"}}},"required":["tlds"]}' \
  --output-format json

# Streaming JSON -- one message per line
claude -p "count to five slowly" --output-format stream-json --include-partial-messages

# Hard budget cap -- stops before burning through $
claude -p "refactor all Python files in src/" --max-budget-usd 2.00

# Input from stdin in stream-json format -- for long-running pipelines
cat requests.jsonl | claude -p --input-format stream-json --output-format stream-json

--no-session-persistence is the right call when -p is part of a pipeline and you don't want thousands of session files accumulating.

--fallback-model only works with -p and only triggers on overload of the primary model:

claude -p "do the thing" --model opus --fallback-model sonnet

In an interactive session, type / and a picker appears. The full list is in Appendix B. Here are the groups you'll touch most often in the first week, with the reason each one exists.

Claude Code reads several files as context automatically:

• ~/.claude/CLAUDE.md — user-global preferences.
• <project>/CLAUDE.md — project instructions.
• ~/.claude/projects/<slug>/memory/*.md — per-project auto-memory (facts, feedback, references; indexed via MEMORY.md).
• Plus whatever tools pull in (file reads, grep, URL fetches).

Key CLI knobs:

# Make another directory readable without prompting (multi-dir projects)
claude --add-dir ../shared-libs ../docs

# Override CLAUDE.md auto-discovery entirely
claude --bare --system-prompt "You are a minimal assistant." \
  --add-dir . --mcp-config ./mcp.json

# Append to the default system prompt without replacing it
claude --append-system-prompt "Always cite file:line when referencing code."

--bare is the escape hatch when you want a reproducible Claude run for CI or an experiment: no hooks, no LSP, no plugin sync, no auto-memory, no keychain, no CLAUDE.md auto-discovery. You provide context explicitly via the flags.

Permissions live at three levels: session, project (.claude/settings.json), user (~/.claude/settings.json).

# Scope tools explicitly for a single invocation
claude -p "tidy this repo" \
  --allowedTools 'Bash(git:*) Edit Read' \
  --disallowedTools 'Bash(rm:*) Bash(curl:*)'

# Permission modes
claude --permission-mode plan          # think, don't act
claude --permission-mode acceptEdits   # auto-accept edits
claude --permission-mode bypassPermissions  # ⚠ only in sandbox
claude --permission-mode dontAsk       # never prompt
claude --permission-mode auto          # ask the classifier

--dangerously-skip-permissions / --allow-dangerously-skip-permissions turn off the permission model. Only defensible inside a VM, jail, container, or other blast-radius-bounded environment with no credentials. Otherwise: don't.

# Pin model for this session only
claude --model opus

# Pin effort (also available as /effort in session)
claude --effort max

# Fallback when primary is overloaded (only with -p)
claude -p "..." --model opus --fallback-model sonnet

Effort is a cost/quality knob. low is fastest and cheapest; xhigh and max chew tokens. auto lets the classifier pick — reasonable default on Max with Opus 4.7.

Hooks are shell commands triggered by lifecycle events. They run in the harness, so they're deterministic. Events:

• SessionStart / SessionEnd
• UserPromptSubmit / AssistantResponseComplete
• PreToolUse / PostToolUse (can veto)
• PreCompact (new in 2.1.105 — run before context summary)
• TaskCreated
• conditional if hooks (2026-03 research preview)

Example: append a Co-Authored-By trailer automatically via PostToolUse on any git commit.

Tangle a hook script:

# guard-dangerous-bash.sh -- PreToolUse hook for the Bash tool
# Veto rm -rf /, git push --force, etc.
set -euo pipefail

# Claude passes the tool invocation as JSON on stdin
invocation=$(cat)
cmd=$(printf '%s' "$invocation" | jq -r '.input.command // ""')

case "$cmd" in
  *"rm -rf /"*|*"rm -rf ~"*|*"rm -rf /*"*)
    echo '{"decision":"deny","reason":"rm -rf at a dangerous root"}'
    exit 0
    ;;
  *"git push --force"*|*"git push -f"*)
    echo '{"decision":"deny","reason":"force-push blocked; rebase and ask"}'
    exit 0
    ;;
esac

# Default: allow
echo '{"decision":"allow"}'

Register it in ~/.claude/settings.json (tangled in Appendix D).

:CUSTOM_ID: session-8-skills :REVIEW: 2026-06-21 – Added /schedule skill to built-ins list :VERIFIED_AT: 2026-06-21T15:00Z :VERIFIED_BY: skeptic-agent :VERDICT: correct :FINDING: /schedule added in 2.1.111+ for managing cron-scheduled remote agents

A skill is a named prompt + tool scope, discoverable at /. Built-ins (2026 Q2):

• /simplify [focus] – review changed files for quality.
• /debug [description] – enable debug logging, walk through a bug.
• /loop [interval] [prompt] – run prompt repeatedly.
• /schedule [description] – create cron-scheduled remote agents for recurring tasks.
• /claude-api – load the current Claude API reference for your project language (Python, TS, Go). Triggers automatically if the code imports anthropic.
• /batch <instruction> – orchestrate 5-30 parallel agents.
• /fewer-permission-prompts – scan your transcript, propose a minimal allowlist addition.
• /less-permission-prompts – same, as of 2.1.111.

Custom skills live in .claude/skills/<name>/SKILL.md. Shape:

---
name: repo-sync
description: Analyze unstaged changes, create feature branch, commit with
  detailed git notes, push to remote.
tools: ["Bash(git:*)", "Read", "Edit"]
---

# repo-sync

Given the current working tree:

1. Summarize what changed with `git status` + `git diff`.
2. Propose a conventional-commit branch name.
3. Ask for confirmation *before* creating the branch.
4. Commit. Add a git note with the detailed rationale.
5. Push with upstream tracking.

Always use conventional commits. Never force-push to main.

opencode.ai's Skills spec walks up from pwd looking in .claude/skills/, .opencode/, .agents/ — so a skill placed in .claude/skills/ is cross-harness portable.

Custom agents are named prompt + tools scoped for delegation.

# Pin a custom agent at startup
claude --agent reviewer

# Define agents inline (rare, but valid)
claude --agents '{
  "reviewer": {
    "description": "Reviews code for bugs, logic errors, OWASP issues.",
    "prompt": "You are a rigorous code reviewer."
  },
  "scribe": {
    "description": "Writes clear commit messages.",
    "prompt": "You are a conventional-commits pedant."
  }
}'

Project-level agents live in .claude/agents/<name>.json. Tangle:

{
  "description": "Rigorous code reviewer. Reads diffs, flags high-signal issues, suppresses low-confidence nits.",
  "prompt": "You are a senior engineer doing a pull-request review. Output: (1) blocking issues, (2) non-blocking suggestions, (3) out-of-scope observations. Cite file:line. Never suggest rewrites unless asked.",
  "tools": ["Read", "Grep", "Glob", "Bash(git:*)"]
}

Subagents are delegated Claude runs launched from inside an active session via the Agent tool. Supported types visible to the harness include general-purpose, Explore, Plan, and any you register.

MCP (Model Context Protocol) servers expose tools and resources over a transport the harness speaks.

# Use a project-local MCP config
claude --mcp-config ./.mcp.json

# Use multiple configs (space-separated)
claude --mcp-config ./team.json ./personal.json

# Strict: ignore all other MCP sources
claude --mcp-config ./only.json --strict-mcp-config

# Set up a long-lived auth token for an MCP server
claude setup-token

Minimal .mcp.json:

{
  "mcpServers": {
    "fs": {
      "command": "uvx",
      "args": ["mcp-server-filesystem", "."],
      "env": {}
    },
    "gh": {
      "command": "gh-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Once connected, MCP prompts appear at /mcp__<server>__<prompt>. Inspect:

claude /mcp       # inside a session
# or
claude mcp        # subcommand form for management

Plugins add commands, skills, hooks, and MCP servers in one bundle.

claude plugin list
claude plugin install <name>
claude --plugin-dir ./local-plugins  # ephemeral, session-only

A plugin directory looks roughly like:

my-plugin/
├── manifest.json
├── skills/
│   └── my-skill/SKILL.md
├── hooks/
│   └── pre-tool.sh
├── agents/
│   └── specialist.json
└── mcp.json

When loaded, all contained surfaces register.

Git worktrees + Claude = per-feature, per-branch sandboxes that don't stomp on each other.

# Create a worktree and start Claude in it
claude -w feat-x

# Create a worktree AND open it in a tmux session
claude -w feat-y --tmux

# With a named session for /resume
claude -w feat-z -n "feature z planning"

On this project we keep worktrees inside the repo under worktrees/ (gitignored). Set BEADS_NO_DAEMON=1 in each worktree so bd doesn't fight itself.

Inside a Claude session, the harness has EnterWorktree and ExitWorktree tools. From 2.1.105 on, EnterWorktree accepts a path parameter, so subagents can operate on a named directory.

• /remote-control – make this terminal session remotely controllable from claude.ai.
• /remote-env – configure the default cloud environment for web sessions.
• /teleport – pull a Claude-on-the-web session into the terminal.
• /autofix-pr [prompt] – spawn a remote session that watches a PR and pushes fixes.
• /ide / --ide – connect to an IDE (VS Code, JetBrains) on startup.
• /chrome / --chrome – Claude-in-Chrome integration.
• /desktop, /ios, /android, /mobile – link a session to the desktop or mobile app.

Useful combination: use /autofix-pr from your laptop, then /remote-control to drive it from your phone.

The session file is the source of truth; everything else (terminal UI, Remote Control, etc.) is a view.

# Resume a specific session by ID (fork instead of mutate)
claude -r <uuid> --fork-session

# Resume by PR (opens interactive picker scoped to PR-linked sessions)
claude --from-pr 123

# Resume with a search term
claude -r "caching-layer"

# Start a session with a known UUID (for scripting)
claude --session-id $(uuidgen)

--no-session-persistence turns off session files entirely (only with -p). Pair with --bare for fully reproducible one-shots.

• /fast [on|off] – Fast mode. Same Opus 4.6 model; faster output path. Trade: slightly less deliberation, much lower latency.
• /sandbox – toggle sandbox mode on the current session.
• /tui fullscreen vs /tui default – alt-screen vs inline rendering.
• /focus – minimal UI (prompt + tool summary + response).
• auto mode (via /effort auto or /model auto on Max) – permission classifier picks effort/model per turn.

--bare is the extreme of "do less automatically"; /focus and /tui fullscreen are the extremes of "show less automatically."

# Turn on debug logging, filter to specific categories
claude -d "api,hooks"

# Send debug output to a file (implicitly enables debug)
claude --debug-file /tmp/claude-debug.log

# Category negation
claude -d "!1p,!file"   # everything except first-party and file noise

# One-shot health check
claude doctor

# Inside a session
#  /doctor      -- diagnose harness
#  /heapdump    -- JS heap snapshot + memory breakdown
#  /stats       -- daily usage, session history, streaks
#  /insights    -- session analysis report

When a session misbehaves, the triage order is usually:

1. /context — is the window saturated?
2. /doctor — is the harness healthy?
3. -d in a fresh session — reproduce with logs.
4. /heapdump — if memory is spiralling.

On a LAN with an OTel collector, the harness emits metrics and logs via OTLP when these env vars are set:

# Sample telemetry env -- source this before starting claude
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.local:4317
export OTEL_RESOURCE_ATTRIBUTES="host.name=$(hostname -s),team=solo"

The per-session resource attributes let you filter dashboards meaningfully (by repo, host, branch, conjecture).

From claude --help.

• How stable is the flag surface? --bare landed recently; historical flags like --mcp-debug are already deprecated. Anything scripted against 2.1.x should pin the CLI version or use doctor as a capability probe.
• Is there a canonical way to introspect which slash commands are available right now? /help shows a filtered list. --disable-slash-commands is the inverse. No JSON introspection endpoint as of 2.1.114.
• Hook veto semantics. PreToolUse hooks can return {"decision":"deny"}. Order of multiple hooks, short-circuit semantics, and whether deny messages surface to the model consistently remain under-documented.

• Claude Code Features — 2026 Q2 — speculative / forward-looking companion to this reference.
• Cloudflare Agents Week 2026 — how Claude Code's surface intersects managed-agent infrastructure.
• Agentic Workflow with Claude Code — the workflow around the tool, complementary to the surface here.
• Elenctic Vibe Code Review — what to do with the output once Claude produces it.