Installing Claude Code: a working configuration, explained line by line

On this page#

• Before you install anything
• The steps
• A working configuration
• Objective
• Invariants
• Workflow
• Repository boundaries
• Validation
• What to skip
• First real task
• FAQ

Before you install anything#

Install the tool last. First define repository invariants, permitted commands, secret boundaries, and the task you will use to validate the setup. Otherwise, installing Claude Code merely gives a powerful agent access to an undocumented environment—and the first session becomes an improvised permissions review inside a production repository.

Claude Code is an agentic coding tool that can inspect a repository, propose changes, edit files, and invoke approved commands; the official Claude Code overview covers the product mechanics. The missing half is repository policy.

Write down four things before installation:

• Invariants: behavior that must not change.
• Validation: the exact commands that establish correctness.
• Boundaries: files and directories the agent must not read or modify.
• Authority: actions that always require a human, such as publishing or pushing.

The order matters because permissions are not documentation. An allowlist can permit npm test, but it cannot explain which failures are expected or whether generated files may change. That context belongs in a committed CLAUDE.md, where the next engineer—and every later agent session—can see it.

Treat local preferences and repository rules differently:

| Concern | Where it belongs | |---|---| | Personal display or interaction preference | User-level configuration | | Repository-approved tools and commands | .claude/settings.json | | Architecture, invariants, and workflow | CLAUDE.md | | Secrets | Outside agent-readable paths |

If a rule matters to every contributor, committing it is better than explaining it in chat.

Photo by Boris K. on Pexels.

The steps#

Use this sequence: establish a clean baseline, install through one controlled package path, start Claude Code at the repository root, add repository-owned instructions, narrow permissions, and validate with a read-only task. Each step prevents a different failure, so skipping ahead makes later debugging ambiguous.

1. Confirm the repository starts clean. This prevents existing edits from being mistaken for agent changes.

2. Record the repository’s real validation commands. This prevents Claude Code from guessing how correctness is established.

3. Install the package globally with npm:

   npm install -g @anthropic-ai/claude-code

   This follows npm’s global installation model; the relevant command behavior is documented in the official npm install reference.

4. Start it from the repository root:

   claude

   This prevents the session from beginning with the wrong working-directory boundary.

5. Complete the authentication flow presented by the tool. This prevents credentials from being copied into repository configuration.

6. Add CLAUDE.md and .claude/settings.json before requesting edits. This prevents the first prompt from becoming an undocumented policy layer.

7. Run a read-only repository task first. This exposes missing context and excessive permissions without mixing setup errors with code changes.

Do not use elevated privileges to force a failed installation through. A permissions error in the package environment is an environment problem, not evidence that the package deserves broader machine access. Resolve that boundary before continuing.

The Claude Code documentation remains the authority for supported installation and configuration behavior. The configuration below is the repository policy layered on top of those mechanics.

A working configuration#

A useful default grants repository inspection, allows only named validation commands, and blocks destructive or external side effects. It deliberately does not grant unrestricted shell access, pushing, publishing, or secret reads. Add permissions only when a real repository task proves they are necessary.

Create .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(npm test:*)",
      "Bash(npm run lint:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push:*)",
      "Bash(git reset --hard:*)",
      "Bash(rm -rf:*)",
      "Bash(npm publish:*)"
    ]
  }
}

This is valid JSON, so the explanation stays outside the file:

• "permissions" makes tool authority explicit instead of relying on conversational restraint.
• "allow" contains capabilities that normal repository analysis needs.
• "Read", "Glob", and "Grep" permit inspection and discovery.
• "Edit" permits changes to existing files, but does not turn the shell into a general-purpose escape hatch.
• "Bash(git status)" allows baseline checks without mutation.
• "Bash(git diff:*)" allows review of pending changes.
• The two npm rules permit tests and linting, not arbitrary npm commands.
• "deny" records hard boundaries even when broader rules are introduced later.
• The .env and secrets rules keep common credential locations unreadable.
• The remaining rules block pushing, destructive reset, recursive deletion, and publication.

Adapt command names to the repository; do not add commands merely because a tutorial includes them. Permission syntax and supported behavior should be checked against the official Claude Code documentation when the tool reports that a rule is invalid.

Next, create a committed CLAUDE.md:

# Repository operating rules


![Detailed view of Ruby on Rails code highlighting software development intricacies. — illustrating installing claude code](/blog/installing-claude-code-2.jpg)
*Photo by Digital Buggu on [Pexels](https://www.pexels.com/photo/monitor-displaying-computer-application-374559/).*

## Objective
Make the smallest change that satisfies the requested behavior.

## Invariants
- Preserve public interfaces unless the task explicitly changes them.
- Do not weaken validation, authentication, or authorization checks.
- Do not edit generated files unless their source is changed first.
- Do not add dependencies without explicit approval.


![A female engineer works on code in a contemporary office setting, showcasing software development. — illustrating instal](/blog/installing-claude-code-3.jpg)
*Photo by ThisIsEngineering on [Pexels](https://www.pexels.com/photo/female-software-engineer-coding-on-computer-3861951/).*

## Workflow
1. Read the relevant implementation and tests.
2. State the proposed change and affected files.
3. Make the smallest coherent edit.
4. Run the approved lint and test commands.
5. Summarize the diff, validation result, and remaining risk.

## Repository boundaries
- Never read `.env`, `.env.*`, or `secrets/`.
- Never push, publish, delete recursively, or rewrite Git history.
- Stop and ask when the task conflicts with an invariant.

## Validation
- Lint: `npm run lint`
- Tests: `npm test`

Every section has one job: objective controls scope, invariants protect behavior, workflow makes execution reviewable, boundaries define escalation, and validation removes command guessing. Replace the example validation commands if the repository uses different ones.

For a more complete reusable policy set, the PairFoundry Agent Operating Kit provides an organized next step. The point is not more prose; it is making authority, invariants, and handoff behavior consistent across repositories.

What to skip#

Skip any setup step that expands authority without solving an observed repository need. Most installation tutorials optimize for a frictionless demo, so they quietly erase the boundaries that matter in maintained software. That is the wrong default for a team repository.

Do not:

• Grant unrestricted shell access “for convenience.”
• Put tokens, credentials, or authentication instructions in CLAUDE.md.
• Copy a generic instruction file without replacing its validation commands.
• Approve every prompt until interruptions disappear.
• Add formatters, hooks, dependencies, or MCP integrations during installation.
• Ask the first session to refactor multiple modules.
• Maintain critical rules only in a private user-level configuration.
• Treat a successful launch as a successful Claude Code installation.

Official material explains supported operation; it cannot know your repository’s invariants, ownership model, or release authority. That difference is intentional, not a documentation defect. Use the official overview for product behavior and repository-owned files for local policy.

If you are still defining the basics, use PairFoundry’s free foundations track. For broader packaged options, see the PairFoundry packs overview, or continue through the agent setup articles.

First real task#

Make the first task a read-only change plan for one small, already-understood issue. Ask Claude Code to identify the relevant files, trace the behavior, name the invariant at risk, and propose validation—without editing anything. This tests context quality and permission boundaries before code generation can hide setup mistakes.

Use a prompt like this:

Investigate this issue without editing files.

Identify:
1. the execution path involved,
2. the smallest likely change,
3. the repository invariant most at risk,
4. the tests that should fail before the change,
5. the approved commands needed to validate it.

Stop after presenting the plan and affected files.

Evaluate the response against the repository, not against how confident it sounds. If it selects the wrong files, invents a command, overlooks an invariant, or requests unrelated access, fix the configuration before assigning implementation.

Only then ask for the smallest edit. Review the diff, run the approved checks, and revert the working-tree change if the result is wrong. That sequence validates the installation as an operating system for agent work—not merely as a binary that launches.

Related reading#

• Claude Code tutorial — the setup that survives a real repo
• Codex CLI install in fifteen minutes, and what to skip

FAQ#

How narrow should Claude Code permissions be in a working repository?#

Start with read access, existing-file edits, status and diff inspection, and the repository’s named validation commands. Do not grant general shell access preemptively. When a legitimate task is blocked, add the smallest rule that enables that action while preserving explicit denials for secrets, publication, destructive deletion, and history rewriting.

How is this different from the official Claude Code installation?#

The official documentation explains how Claude Code is installed and operated. This approach adds the repository-specific layer the vendor cannot provide: invariants, approved validation commands, secret boundaries, destructive-action denials, and committed instructions for the next contributor. You need both; repeating the official setup alone leaves the important decisions implicit.

What usually breaks when a second engineer uses the configuration?#

Private assumptions break first. Commands exist only in one person’s memory, user-level settings hide required permissions, and chat instructions disappear between sessions. Commit shared policy in CLAUDE.md and .claude/settings.json, while keeping credentials and personal preferences outside the repository.

How do I back out a bad first change?#

Stop the agent, inspect the diff, and revert only the files changed by that task using your normal version-control workflow. Do not use destructive repository-wide reset commands as a convenience. If you cannot distinguish agent edits from pre-existing work, the baseline step was skipped; restore that discipline before continuing.

When should I not install Claude Code in a repository?#

Do not introduce it when you cannot state the repository’s invariants, identify safe validation commands, or separate secrets from readable project files. Also stop when policy requires unreviewed publishing, unrestricted production access, or irreversible actions. Installation should follow a workable authority model, not substitute for one.