Setting Up Claude Code on Your Local Machine: From Install to First Agent

Claude Code is Anthropic's official coding agent — a command-line tool that lives in your terminal, reads your repository, runs commands, edits files, and works autonomously on multi-step engineering tasks. It is the same agent framework used inside Anthropic, released as a CLI you can run on your own machine.

This guide covers a clean local installation, sensible defaults, and the workflow patterns that we use every day at FindCoder.

Prerequisites

• macOS, Linux, or Windows with WSL2
• Node.js 18 or newer
• A Claude account — either an Anthropic API key, or a Claude Pro / Max subscription for OAuth sign-in
• Git (Claude Code is aware of git state and uses it)

Installation

The simplest path is npm: ``` npm install -g @anthropic-ai/claude-code ```

On macOS you can also use Homebrew: ``` brew install --cask claude-code ```

Once installed, verify: ``` claude --version ```

First Run and Authentication

From any directory, run: ``` claude ```

On the first launch, Claude Code will prompt you to authenticate. You have two choices: - OAuth with a Claude Pro or Max account — best for individual developers. Usage counts against your subscription, no billing setup needed. - Anthropic API key — best for teams, CI, and anything programmatic. Set `ANTHROPIC_API_KEY` in your shell profile.

For work machines we recommend the API key path with a team account, because it gives you per-seat billing and usage dashboards.

Configuring Permissions

Claude Code runs tools (bash, file edits, web fetches) on your behalf. By default it asks before each potentially destructive action. You can tune that in `~/.claude/settings.json`: ``` { "permissions": { "allow": ["Read", "Grep", "Glob", "Bash(npm test)", "Bash(git status)"], "deny": ["Bash(rm -rf *)"] } } ```

The pattern we recommend: - Allow read-only tools globally (Read, Grep, Glob) - Allow your common safe commands (`npm test`, `git status`, `npm run lint`) - Leave destructive commands to prompt - Never auto-allow `rm`, `git push --force`, or anything that touches production systems

Project Context with CLAUDE.md

The biggest leverage move in Claude Code is a well-written `CLAUDE.md` file at your project root. This file is loaded into every session and tells Claude about your codebase — conventions, scripts, architecture notes, things to avoid.

Example `CLAUDE.md`: ``` # Project Conventions

• This is a Next.js 15 app using the App Router
• All new components go in src/components and use Tailwind
• Run `npm run lint` and `npm test` before declaring work done
• Do not run `npm install` without asking
• Database migrations live in /migrations and must be reviewed by a human

Claude Code also supports nested CLAUDE.md files in subdirectories for area-specific instructions, and a global `~/.claude/CLAUDE.md` for your personal preferences across all projects.

Running Your First Real Task

Once configured, the workflow looks like this: ``` cd ~/code/my-app claude > Add a /health endpoint that returns { status: "ok", version }. Wire it up, add a test, and run the test suite. ```

Claude Code will: 1. Read the relevant files to understand the project 2. Propose a plan 3. Make the edits 4. Run the tests 5. Iterate until they pass

You stay in the loop. You can interrupt, redirect, or ask for an explanation at any point.

Slash Commands and Skills

Claude Code has built-in slash commands like `/init` (to scaffold a CLAUDE.md), `/clear` (to reset context), and `/review` (to review the current diff). You can define your own in `.claude/commands/` — for example, a `/deploy` command that runs your deployment script with guardrails.

Skills go further: reusable capability packs that ship their own instructions and scripts. If your team has a standard way to add a new feature or run a migration, encoding it as a Skill lets every Claude Code session follow the same playbook.

MCP Servers for Integrations

Model Context Protocol (MCP) servers are plugins that give Claude Code access to external systems — your Jira, your GitHub, your internal docs, your database. Configure them in `.claude/mcp_servers.json`: ``` { "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }, "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"] } } } ```

With those wired up, Claude Code can read Jira tickets, open PRs on GitHub, and query your dev database directly.

Hooks for Automation

Hooks run shell commands in response to Claude Code events — session start, before tool use, after edits. Use them to enforce conventions without nagging. Common patterns: - Run the linter after every file edit - Block commits that contain secrets - Auto-run tests after any change to `src/`

Configure in `settings.json` under `hooks`.

A Few Hard-Won Lessons

• **Keep CLAUDE.md short.** Everything in it costs tokens on every turn.
• **Use `/clear` liberally** between unrelated tasks to keep the context clean.
• **Let Claude plan before executing** on any non-trivial task — `/plan` mode catches a lot of misunderstandings early.
• **Review diffs yourself.** Claude Code is fast; good reviews are still your job.
• **Treat Claude Code as a junior engineer with a perfect memory.** It will do exactly what you ask. Ask precisely.

At FindCoder, every engineer runs Claude Code on their machine, and every project ships with a CLAUDE.md tuned to the codebase. The productivity lift is real — but only after the setup is right.