---
title: "How to set up Claude Code on a new repository"
slug: "set-up-claude-code"
category: "howto"
tags: ["howto", "claude-code", "ai-agents", "tutorial", "workflow"]
status: "stable"
last_updated: 2026-05-14
summary: "Install Claude Code, write the CLAUDE.md anchor, set up TODO.md, configure hooks, and ship the first PR through the brief-then-verify loop."
related: ["[[ai-agents/claude-code]]", "[[tooling/claude-code-workflow]]", "[[prompt-engineering/prompt-design]]", "[[ai-agents/multi-agent]]", "[[howto/deploy-quartz-site]]", "[[coding/general-principles]]"]
---

## Overview

Claude Code is at its best when the repo gives it durable context. This guide installs Claude Code on a fresh project, writes the three anchor files it needs (`CLAUDE.md`, `TODO.md`, optionally `SESSION_LOG.md`), wires the hooks that keep automation honest, and lands the first PR through the brief-then-verify loop from [[ai-agents/claude-code]].

## Prerequisites

- Node 22 and `npm` on the path. Claude Code runs on Node.
- A Git repository, local or remote. The anchor files live in source control.
- `gh` CLI authenticated, if you want CC to open PRs directly. `gh auth status` should print "Logged in".
- A working build command (`npm run build`, `npm test`, or equivalent) that exits non-zero on failure.

## Steps

### 1. Install Claude Code

```bash
npm install -g @anthropic-ai/claude-code
claude --version
```

Authenticate on first run. `claude` opens the login flow; pick the Anthropic Console or Pro account that owns the API budget.

### 2. Write `CLAUDE.md` at the repo root

`CLAUDE.md` is the file CC reads first on every session. Keep it under 300 lines. Put the mission, the schema (if any), the voice rules, the folder map, and the "how to add a page" or "how to add a feature" walk-through.

```markdown
# CLAUDE.md

## Mission
<One paragraph: what this repo is, who it serves, what it deploys to.>

## Voice rules
- Lead with the rule.
- No em-dashes; use periods or commas.
- Concrete examples over abstractions.

## Folder structure
<tree>

## How to add a <thing>
1. ...
```

See [[ai-agents/claude-code]] for the full anchor file pattern.

### 3. Set up `TODO.md`

`TODO.md` is the live backlog. Use checkboxes; CC checks them off as work ships.

```markdown
# TODO

## Active
- [ ] Wire CI to run lint on PRs.
- [ ] Add `/about` page.

## Backlog
- [ ] Migrate the blog from Hugo.
```

Commit both files. CC reads them on session start; humans read them in PRs.

### 4. Configure hooks in `.claude/settings.json`

Hooks let the harness run commands at specific lifecycle points. The most useful one is a `SessionStart` hook that prints the current build and test status so CC opens with the truth.

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "git status --short && npm test --silent 2>&1 | tail -20" }
        ]
      }
    ]
  }
}
```

Commit `.claude/settings.json` so every contributor gets the same start state. Keep secrets in `.claude/settings.local.json` and gitignore that path.

### 5. Land the first PR through the brief-then-verify loop

Write a brief in a chat session. Include mission, file paths, phased steps, acceptance criteria, and explicit non-goals. Paste it into `claude` running in the repo. CC executes phase by phase; verify each phase by running the verification command in the brief.

```
## Acceptance criteria
- [ ] `npm run build` exits 0.
- [ ] `npm test` exits 0.
- [ ] New page renders at /foo.
- [ ] CHANGELOG.md updated.
```

When the brief is done, CC opens a PR with `gh pr create`. Review the diff, merge, move on. See [[tooling/claude-code-workflow]] for the day-two patterns.

## Verify it worked

Three checks confirm the setup is sound.

```bash
# 1. The CLI is installed and authenticated.
claude --version
claude /help

# 2. The anchor files are tracked.
git ls-files CLAUDE.md TODO.md .claude/settings.json

# 3. The first PR is open or merged.
gh pr list --author "@me"
```

If `claude /help` prints the help text and `git ls-files` lists all three files, you are done.

## Common errors

- `claude` exits with "command not found". The global `npm` bin is not on `PATH`. Add `$(npm config get prefix)/bin` to your shell `PATH`.
- The `SessionStart` hook hangs the session. The hook command runs synchronously; replace any long-running command with a fast status check.
- CC ignores `CLAUDE.md`. The file is not at the repo root, or it exceeds the model's context budget. Move it to the root and trim it below 300 lines.
- CC opens PRs against the wrong branch. Set the default branch in the brief, or run `gh repo edit --default-branch main` once.
- Secrets leak into `.claude/settings.json`. Move them to `.claude/settings.local.json` and add that file to `.gitignore`.

## Related

- [[ai-agents/claude-code]]
- [[tooling/claude-code-workflow]]
- [[prompt-engineering/prompt-design]]
- [[ai-agents/multi-agent]]
- [[coding/general-principles]]