Claude Code
Claude Code setup: every file, tool and fix
Claude Code reads a handful of files: a CLAUDE.md for instructions, settings.json for permissions and hooks, folders for skills, subagents and commands, and .mcp.json for MCP servers. Set them up in this order, with a free generator or checker for each, and fix errors with tested steps.
Start here
Set up Claude Code in this order
- 01Write the project CLAUDE.mdCommands, conventions and the traps in your codebase. It loads into every session, so keep it short; Anthropic suggests under 200 lines.CLAUDE.md generator →
- 02Set permissions in .claude/settings.jsonAllow the commands you run all day, ask about the rest and deny secrets. Claude Code enforces these rules whatever the model decides.Settings and permissions builder →
- 03Connect MCP servers in .mcp.jsonGive Claude your issue tracker, browser or database. Keep tokens in environment variables, not in the committed file.MCP config generator →
- 04Add hooks for what must always happenA formatter after every edit or a block on a risky command. Hooks run every time; an instruction in CLAUDE.md is only advice.Hooks builder →
- 05Hand big jobs to subagentsA subagent works in its own context window and returns a summary, so long searches and logs stay out of your conversation.Subagent builder →
- 06Package repeat work as skillsA skill is a folder with a SKILL.md and any scripts it needs. Claude loads it only when the task fits, or when you type its name.Skill generator →
- 07Keep one-line prompts as slash commandsSingle-file commands still work. Anthropic now treats them as the simple form of a skill.Slash command builder →
Reference
Where every Claude Code file lives
| Path | Scope | Shared? | What it holds |
|---|---|---|---|
| CLAUDE.md or .claude/CLAUDE.md | Project | Committed | Project instructions, loaded every session. Claude Code can read AGENTS.md instead. CLAUDE.md Generator |
| CLAUDE.local.md | Project, personal | Add to .gitignore | Your own notes for this project, read after CLAUDE.md. |
| .claude/rules/*.md | Project | Committed | Topic rules, optionally limited to matching file paths. |
| .claude/settings.json | Project | Committed | Permissions, hooks and other settings for everyone on the project. Claude Code Settings Builder |
| .claude/settings.local.json | Project, personal | Gitignored | Your overrides for this project; beats the shared file. Claude Code Settings Builder |
| .mcp.json | Project | Committed | MCP servers shared with the team. MCP Config Generator |
| .claude/skills/<name>/SKILL.md | Project | Committed | Skills, with supporting files beside SKILL.md. Claude Skill Generator |
| .claude/agents/<name>.md | Project | Committed | Subagents with their own prompt, tools and model. Claude Code Subagent Builder |
| .claude/commands/<name>.md | Project | Committed | Single-file slash commands (skills are the newer form). Claude Code Slash Command Builder |
| .claude/output-styles/ | Project | Committed | Output styles your team shares. |
| ~/.claude/CLAUDE.md | User | Only you | Your preferences across every project. CLAUDE.md Generator |
| ~/.claude/settings.json | User | Only you | Your default settings; project files override it. Claude Code Settings Builder |
| ~/.claude/skills/, agents/, commands/, rules/ | User | Only you | Personal skills, subagents, commands and rules for every project. |
| ~/.claude/keybindings.json | User | Only you | Custom keyboard shortcuts. |
| ~/.claude/projects/<project>/memory/MEMORY.md | User | Claude writes it | Auto memory: notes Claude keeps for each repository. |
| ~/.claude.json | User | Claude writes it | Sign-in, MCP servers added with claude mcp add, per-project state. You rarely edit it. |
| /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux, WSL), C:\Program Files\ClaudeCode\CLAUDE.md (Windows) | Organization | Set by IT | Managed instructions for everyone in the organization. |
Checked against Anthropic’s Claude Code documentation on .
About
Which file wins, and which ones are enforced
When the same setting appears in several files, Claude Code takes the most specific one it is allowed to: managed settings from your organization first, then --settings on the command line, then .claude/settings.local.json, then the shared .claude/settings.json, and last your user ~/.claude/settings.json. Instructions work differently. Every CLAUDE.md that applies is loaded and joined, from the top of the folder tree down to where you started Claude, so the file closest to your work is read last.
Two kinds of file shape what Claude does, and they are not equally strong. CLAUDE.md, rules and skills are context: Claude reads them and usually follows them. Permissions and hooks are enforced by Claude Code itself, so a deny rule or a blocking hook holds even when the model would rather do something else. Put anything that must never happen in settings.json or a hook, not in prose.
Most setup problems are a file in the wrong place or a key in the wrong scope. Run /context in a session to see which memory files loaded, and /status to see which settings sources apply. If Claude Code prints an error, the error database has the exact message, the cause and the fix for each operating system.
Tools
Free Claude Code tools
- CLAUDE.md GeneratorGenerate a CLAUDE.md and AGENTS.md for your project.
- Claude Code Settings BuilderBuild and check a settings.json with permission rules.
- MCP Config GeneratorBuild MCP server configs for Claude, Cursor, VS Code and Devin Desktop (Windsurf).
- Claude Code Hooks BuilderBuild and check settings.json hooks, with tested Bash and PowerShell scripts.
- Claude Code Subagent BuilderBuild and check subagent files for .claude/agents.
- Claude Skill GeneratorCreate a SKILL.md and skill folder, or validate one you have.
- Claude Code Slash Command BuilderBuild and check custom slash command files for Claude Code.
- AI Rules ConverterConvert Cursor rules, Copilot instructions, Devin Desktop rules and CLAUDE.md.
- Subscription vs API CalculatorFind out whether a chat plan or the API is cheaper for you.
Fixes
Claude Code errors, fixed
Every message below is checked against the current Claude Code build. Search them all in the Claude Code error database.
Certificates and network
- Claude Code SSL certificate error: verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY)
- Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN)
- SSL certificate is not yet valid (CERT_NOT_YET_VALID)
- SSL certificate has expired (CERT_HAS_EXPIRED)
- SSL certificate hostname mismatch (ERR_TLS_CERT_ALTNAME_INVALID)
- curl: (60) SSL certificate problem: unable to get local issuer certificate
- Unable to connect to API
- Request timed out
Server and limits
Sign-in
Requests and models
Read
Claude Code guides
- How to write a good CLAUDE.md, with a complete example
- Claude Code hooks: a practical guide with examples
- Claude Code subagents: how to create and use them
- How to set up MCP servers in Claude Code
- How to reduce Claude Code token usage, and what each fix costs you
- Claude Code pricing: plans vs API, and which costs less
- The best model for coding agents, and how to choose one
FAQ
Questions people ask
Where does Claude Code keep its settings?
In ~/.claude/settings.json for you across every project, .claude/settings.json in a project for the whole team, and .claude/settings.local.json for your own overrides in that project. Organizations can add managed settings that nothing else overrides. The settings builder writes valid files for each scope.
Should CLAUDE.md go in the project root or in .claude/?
Either works: Claude Code reads ./CLAUDE.md and ./.claude/CLAUDE.md. Use CLAUDE.local.md for notes you don't want to commit, and ~/.claude/CLAUDE.md for preferences that apply everywhere. The CLAUDE.md guide covers what to put in it.
Where are MCP servers configured for Claude Code?
Servers shared with your team go in .mcp.json at the project root. Servers you add with claude mcp add for yourself are stored in ~/.claude.json. The MCP config generator writes the JSON, and the MCP guide explains the scopes.
What is the difference between a skill, a subagent and a slash command?
A slash command is one saved prompt. A skill is a folder with a SKILL.md and supporting files that Claude can load by itself when the task fits. A subagent is a separate worker with its own context window, tools and model that reports back a summary. The subagents guide shows when each one saves tokens.
Is this site affiliated with Anthropic?
No. AI Dev Toolkit is an independent, free site by Tahir Nazir. Every file location on this page links to Anthropic’s documentation, and the date it was last checked is shown below.