Configuring Claude Code

Claude Code is Anthropic’s CLI agent. It is the most polished of the four agents covered in this section and has the largest set of extension points. This page walks through the parts you will customise most often, with copy-pasteable snippets.

Install and authenticate

On macOS and Linux, the official installer is a shell script:

curl -fsSL https://claude.ai/install.sh | bash

This places the claude binary on your PATH without going through npm. The npm package is no longer the recommended path on macOS and Linux. On Windows, follow the installer linked from the docs.

Run claude from any directory. The first launch opens a browser window for OAuth login. You can also authenticate with an API key (ANTHROPIC_API_KEY) for headless and CI use.

A Pro or Team subscription unlocks the CLI with reasonable usage limits. API key billing is per-token, useful for unattended jobs.

Project memory: CLAUDE.md

CLAUDE.md is a plain markdown file Claude reads at the start of every session. It contains persistent instructions that shape behaviour without you re-typing them.

Three locations matter:

File	Scope	Shared via git
~/.claude/CLAUDE.md	All your projects	No
<repo>/CLAUDE.md	This project	Yes
<repo>/CLAUDE.local.md	This project, your machine only	No

Files load from the filesystem root down to the working directory. Imports work with the @path/to/file syntax. Imports still consume context tokens; they do not save tokens, they organise them.

Aim to keep each file under 200 lines. Move long reference material into a skill or an external doc and import only when needed. Inspect what is loaded with /context-window.

A starter CLAUDE.md for a bioinformatics project looks like this:

# Project

RNA-seq differential expression for the airway dataset using DESeq2.

## Build and test

- Install deps: `uv sync`
- Run analysis: `uv run python scripts/run_deseq.py`
- Tests: `uv run pytest tests/`

## Conventions

- Reference: GRCh38, GENCODE v45 annotation
- DESeq2 LFC shrinkage: apeglm
- Figures: ggplot2 only, never base R plotting
- Add new dependencies with `uv add`, never with `pip`

The full bioinformatics example is on the Bioinformatics CLAUDE.md Patterns page.

Settings: settings.json

settings.json controls the tool itself: model, permissions, environment variables, hooks, and MCP servers.

Three locations, in increasing precedence:

File	Scope	Shared via git
~/.claude/settings.json	All your projects	No
<repo>/.claude/settings.json	This project	Yes
<repo>/.claude/settings.local.json	This project, your machine only	No

A minimal global settings.json that pre-allows safe shell commands and blocks the destructive ones looks like this:

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Bash(ls *)",
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(uv *)",
      "Bash(python3 *)",
      "Bash(Rscript *)",
      "Bash(podman ps*)",
      "Bash(podman build *)",
      "Bash(podman run *)",
      "WebSearch",
      "WebFetch"
    ],
    "deny": [
      "Bash(sudo *)",
      "Bash(rm -rf /)",
      "Bash(rm -rf /*)",
      "Bash(pip install*)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)"
    ]
  }
}

The pattern is allowlist for the commands you actually use, denylist for the destructive ones. Anything not matched falls back to an interactive prompt.

The Bash(pip install*) deny rule is deliberate: it forces the agent to use uv instead, which keeps Python environments reproducible.

Project-level settings can override the global allowlist for tools the project actually uses, like a specific bcftools or samtools invocation.

Skills: reusable slash commands

Skills are custom commands that show up as /skill-name in the CLI. They live in ~/.claude/skills/<name>/SKILL.md (personal) or .claude/skills/<name>/SKILL.md (project, shared).

A skill is a markdown file with YAML frontmatter and a body that describes the task. A simple bioinformatics example:

---
name: validate-fastq
description: Check FASTQ files for basic format issues before pipeline submission. Use after copying new sequencing data into the project.
allowed-tools: Bash(seqkit *) Read(data/raw/*.fastq.gz)
---

For each file in `data/raw/`:

1. Run `seqkit stats $file` and report read count, mean length, and quality.
2. Flag files with read count below 1M as potentially failed.
3. Flag files with mean Q-score below 30.
4. Write a markdown summary to `reports/fastq_qc_$(date +%Y_%m_%d).md`.

Frontmatter keys worth knowing:

• name: optional, defaults to the directory name.
• description: how Claude decides whether to invoke automatically.
• disable-model-invocation: true: only the user can call this skill.
• allowed-tools: tools the skill can use without re-prompting.
• model: override the session model for this skill only.

Invoke with /validate-fastq or let Claude choose it based on the description.

Hooks: automated rules

Hooks are shell commands that run on lifecycle events. They sit in settings.json under the hooks key. Use them to enforce rules that you do not want to repeat in CLAUDE.md.

Useful events:

• PreToolUse — before a tool runs; can block it.
• PostToolUse — after a tool succeeds; good for auto-format.
• UserPromptSubmit — before Claude reads your prompt.
• Stop — when Claude finishes a response.

Example: auto-format Python files after every edit.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "ruff format $CLAUDE_PROJECT_DIR && ruff check --fix $CLAUDE_PROJECT_DIR"
          }
        ]
      }
    ]
  }
}

Example: block git push to main from this branch.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git push * main*)",
            "command": "echo 'Pushing to main is blocked. Use a PR.' && exit 2"
          }
        ]
      }
    ]
  }
}

A hook that exits with code 2 blocks the action. Other non-zero codes log a warning but allow the action to continue.

MCP servers: connect external tools

Model Context Protocol servers expose tools to the agent. Common ones for bioinformatics work:

• github: list issues, view PRs, fetch a file from another repo.
• filesystem: explicit file access outside the project root.
• memory: persistent notes that survive across sessions.

Configure in settings.json:

{
  "mcpServers": {
    "github": { "command": "gh-mcp" },
    "memory": { "command": "mcp-memory" }
  },
  "enabledMcpServers": ["github", "memory"]
}

Once enabled, the tools appear automatically in Claude’s tool list.

Plugins: shareable bundles

A plugin is a directory containing skills, hooks, agents, and MCP configs with a manifest. Plugins are versioned and installable from a marketplace, which makes them better than copying skill files between projects.

A minimal plugin layout:

my-bioinformatics-plugin/
├── .claude-plugin/plugin.json
├── skills/validate-fastq/SKILL.md
└── hooks/hooks.json

Install during development with claude --plugin-dir ./my-plugin. Reload after changes with /reload-plugins.

Useful built-in commands

Command	What it does
/init	Generate a starter CLAUDE.md by reading the repo.
/config	Open the settings UI.
/memory	View and edit CLAUDE.md files.
/context-window	Show what is currently consuming context.
/doctor	Diagnose configuration problems.
/compact	Summarise the current conversation to free context.
/status	Active model, MCP servers, hooks, plugins.
claude --continue	Resume the last session.
claude --print	One-shot prompt for scripts.

For a CLI-only headless invocation (CI, cron):

claude --print "Run pytest and summarise failures" \
  --output-format json

Gotchas

• Permission scope: an allow rule for Bash(git push) does not grant Bash(git push origin main) automatically. Patterns are exact unless you use a trailing wildcard.
• CLAUDE.md token cost: every line counts. Keep the file lean and move details to skills.
• Skill selection: write a precise description so Claude picks the right skill. “Use this for X” is better than “X helper”.
• Hooks block silently: if a hook exits 2 with no message, you only see “tool blocked”. Always echo a reason before exiting.
• MCP server reliability: a slow MCP server can stall the session. Set timeouts and disable servers you are not actively using.

Where to go next

The remaining configuration pages cover Codex CLI, OpenCode, and Gemini CLI. After those, the Bioinformatics CLAUDE.md Patterns page shows a complete example file used in production.