## **Claude Code Setup Guide: From Beginner to High-Performance Agentic Workflow**
### **Introduction**
Most Claude Code setups never progress beyond the initial installation phase. Users run the installer, log in, execute a prompt, and receive useful output—only to encounter a series of frustrations weeks later: sessions losing track of earlier decisions, repetitive permission prompts, and context warnings that force abandonment of long tasks. These issues are not limitations of the model itself but stem from an incomplete initial configuration.
Claude Code provides sensible defaults, but high-performance agentic programming requires intentional setup. This guide bridges the gap between basic installation and robust, sustained performance by focusing on actual configuration, permissions, hooks, and command habits. The guidance is verified against Anthropic’s current documentation to ensure accuracy and relevance.
—
### **Installing Claude Code the Right Way**
The recommended installation method is the native installer rather than npm, although npm remains a valid fallback:
“`bash
# macOS, Linux, or WSL
curl -fsSL https://raw.githubusercontent.com/anthropic/claude-code/main/install.sh | bash
# Windows PowerShell
irm https://raw.githubusercontent.com/anthropic/claude-code/main/install.ps1 | iex
# Or via npm
npm install -g @anthropic-ai/claude-code
“`
After installation, **always launch Claude from your project directory**. This ensures that project-specific memory and settings are properly applied.
“`bash
cd your-project-directory
claude
“`
Authentication is handled via OAuth or API keys, and the tool is accessible through multiple interfaces (VS Code extension, JetBrains plugin, desktop app, and web). However, the real power lies in three foundational files that most tutorials overlook.
—
### **The Three Files That Actually Run the Show**
Claude Code reads configuration from two sources:
– **Project-level**: `.claude/` directory and `CLAUDE.md` at the project root.
– **Global-level**: `~/.claude/` directory, which applies across all projects.
#### 1. **CLAUDE.md – Project Memory**
This file serves as persistent memory for the project. It should include architecture notes, build/test commands, and code style rules. Use `/init` to generate a starting version and `/memory` to refine it.
– Keep it under ~2,500 tokens.
– Move long or path-specific rules into `.claude/rules/*.md`.
#### 2. **settings.json – Configuration Control**
Located at `.claude/settings.json` (project) or `~/.claude/settings.json` (global), this file manages permissions, hooks, environment variables, and model defaults. It’s central to reducing interruptions and ensuring model efficiency.
#### 3. **Auto Memory**
Claude can automatically maintain working notes across sessions. Toggle this via `autoMemoryEnabled` or disable it with `CLAUDE_CODE_DISABLE_AUTO_MEMORY` if you prefer full manual control through `CLAUDE.md`.
> **Best Practice:** Stable rules belong in `CLAUDE.md`; volatile or personal preferences can reside in `settings.json`.
—
### **Setting Up Permissions and Hooks**
Claude Code operates in three permission modes, toggled with **Shift+Tab**:
1. **Default** – Prompts before risky actions.
2. **Auto-Accept Edits** – Allows file edits without prompts but still gates other tools.
3. **Plan Mode** – Read-only mode until you approve a plan.
#### Permission Rules (settings.json)
Define what Claude can do automatically:
“`json
{
“permissions”: {
“allow”: [“Bash(npm test:*)”, “Read(**)”],
“ask”: [“Bash(git push:*)”],
“deny”: [“Bash(rm -rf /*)”, “Read(.env)”]
}
}
“`
Deny rules take precedence over allow rules, enabling broad read/test access while blocking destructive commands.
#### Hooks
Hooks automate actions in response to tool usage:
– **PostToolUse**: Auto-format edited files using Prettier.
– **PreToolUse**: Block dangerous commands before execution.
Example PostToolUse hook:
“`json
{
“hooks”: {
“PostToolUse”: [
{
“matcher”: “Write|Edit”,
“hooks”: [
{
“type”: “command”,
“command”: “npx prettier –write “$CLAUDE_TOOL_INPUT_FILE_PATH””
}
]
}
]
}
}
“`
Example PreToolUse security script:
“`python
#!/usr/bin/env python3
# .claude/hooks/block-dangerous-bash.py
import json, re, sys
DANGEROUS_PATTERNS = [
r’brms+.*-[a-z]*r[a-z]*f’,
r’sudos+rm’,
r’chmods+777′,
r’gits+pushs+–force.*main’
]
input_data = json.load(sys.stdin)
if input_data.get(‘tool_name’) == ‘Bash’:
command = input_data.get(‘tool_input’, {}).get(‘command’, ”)
for pattern in DANGEROUS_PATTERNS:
if re.search(pattern, command, re.IGNORECASE):
print(“BLOCKED: matches a dangerous command pattern”, file=sys.stderr)
sys.exit(2)
sys.exit(0)
“`
—
### **Commands Worth Learning First**
Focus on these high-impact commands to resolve common frustrations:
| Command | Category | Purpose |
|——–|———|——–|
| `/init` | Setup | Generates initial project memory |
| `/clear` | Context | Starts fresh conversation while preserving memory |
| `/compact` | Context | Summarizes history to manage context window |
| `/plan` | Planning | Toggles read-only mode for safer execution |
| `/diff` | Review | Reviews all changes made during a session |
| `/debug` | Diagnostics | Checks configuration issues |
| `/model` | Cost & Performance | Switches models without losing context |
| `/effort` | Cost & Performance | Adjusts reasoning depth |
| `/agents` | Delegation | Manages specialized subagents |
Master these before exploring advanced features.
—
### **Building Your Own `/truth` Command**
While `/truth` isn’t a native command, you can create a custom verification skill that checks Claude’s claims against actual files.
Create `.claude/skills/truth/SKILL.md`:
“`markdown
—
description: Verify Claude’s most recent claims against the actual codebase
allowed-tools: Read, Grep, Glob, Bash(git diff:*)
—
Re-examine everything you just told me in this conversation against what
actually exists in the codebase right now. Specifically:
1. For every file you claim to have edited, verify the changes.
2. For every claim about existing code, validate against the real file.
3. Run `git diff` and compare the actual diff against described changes.
4. Report discrepancies honestly without softening them.
“`
This skill is read-only and enhances reliability by forcing Claude to cross-check its own output.
—
### **Using Subagents and Parallel Work**
Subagents run with isolated contexts, ideal for large or parallel tasks:
– Create via `/agents` or define `.claude/agents/
– Example subagents: `code-reviewer`, `test-runner`, `dependency-auditor`.
For parallel work, use `/batch` or `–worktree` to run multiple Claude instances in isolated git worktrees.
—
### **Starter Configuration Files**
#### **CLAUDE.md**
“`markdown
# Project Context
## Stack
– TypeScript, React, Node.js
## Commands
– Test: `npm test`
– Lint: `npm run lint`
– Dev: `npm run dev`
## Conventions
– 2-space indentation, PascalCase for components
## Before finishing
– Run tests and `/truth` if multiple files were edited
“`
#### **.claude/settings.json**
“`json
{
“permissions”: {
“allow”: [“Bash(npm test:*)”, “Read(**)”],
“ask”: [“Bash(git push:*)”],
“deny”: [“Bash(rm -rf /*)”, “Bash(sudo:*)”, “Read(.env)”]
},
“hooks”: {
“PreToolUse”: [
{
“matcher”: “Bash”,
“hooks”: [{ “type”: “command”, “command”: “python3 .claude/hooks/block-dangerous-bash.py” }]
}
],
“PostToolUse”: [
{
“matcher”: “Write|Edit”,
“hooks”: [{ “type”: “command”, “command”: “npx prettier –write “$CLAUDE_TOOL_INPUT_FILE_PATH”” }]
}
]
}
}
“`
Commit these files (excluding secrets) to ensure consistent, high-performance setups across your team.
—
### **Conclusion**
The difference between a basic and a high-performance Claude Code setup lies in deliberate initial configuration—spending 20 minutes on `CLAUDE.md`, `settings.json`, and a few hooks prevents countless hours of friction later. By investing in memory, permissions, and automation upfront, every subsequent session starts from a stronger baseline.
Implement these strategies once, commit them to your repository, and experience consistently elevated performance with Claude Code from day one.
—
### **FAQ**
**Q1: Why does Claude keep forgetting earlier decisions?**
This usually happens when sessions exceed context limits. Use `/compact` regularly or enable `autoMemoryEnabled` in settings.
**Q2: How do I prevent repeated permission prompts?**
Define explicit `allow` rules in `settings.json` for safe, recurring commands like `npm test`.
**Q3: Can hooks block harmful commands entirely?**
Yes. Use a `PreToolUse` hook with a security script to block dangerous patterns before they execute.
**Q4: What’s the difference between `CLAUDE.md` and `settings.json`?**
`CLAUDE.md` contains domain-specific instructions; `settings.json` manages tool behavior, permissions, and hooks.
**Q5: Are custom skills safe?**
Yes, especially read-only skills like `/truth`. They expand capabilities without granting write access unless explicitly configured.
