Navigate the Source: Understand, Predict & Influence Claude

Most people treat Claude as a black box. You aren't most people. With the source in hand, you can trace any behavior back to its exact origin, understand why Claude makes certain decisions, and know precisely where to look to change them. This guide is your map.

The Mental Model: What Claude Actually Sees

Before opening a single file, internalize this: from Claude's perspective, every conversation is a carefully assembled JSON payload sent to the API. The source code's primary job is constructing that payload. Once you understand what ends up in it, you understand Claude's behavior.

The payload has three major parts that the source assembles before every API call:

Tracing a Behavior Back to Source

When you see Claude do something surprising, you can always trace it. Here's the playbook. Work backwards from the observable behavior:

Example: "Why does Claude always ask before running bash commands?"

Example: "Why does Claude 'remember' things I told it in a previous session?"

Example: "Why does Claude reach for Grep before FileRead when searching?"

Tool Descriptions: Claude's Vocabulary

This is the single most actionable insight in the entire codebase: the description string in each tool file is literally what Claude reads to decide when to use that tool. It is not documentation. It is a behavioral instruction.

Every tool exports a description property (or its buildTool() config contains one). When the API payload is built, these descriptions are serialized verbatim into the tool schemas sent to Claude. So when you wonder "why did Claude use BashTool for this instead of FileReadTool?" — read both descriptions side by side and ask which one better matches what you asked for.

CLAUDE.md: Your Direct Line to Every Session

The most underused power-user feature in Claude Code is also the simplest. CLAUDE.md files are Markdown documents that get injected as context into every single session that runs in their directory. They are loaded by memdir/, assembled by context.ts → getUserContext(), and prepended to the message history as AttachmentMessage objects before the first API call.

Where Claude Looks (in priority order)

What to Put in CLAUDE.md

Because CLAUDE.md is injected into the system context (not as a user message), it has stronger influence than anything you type in the chat. Think of it as a standing order that never expires. The source's context.ts assembles it under a heading like # Memory in the system prompt, so Claude treats it as authoritative project context.

# Project: my-api-server

## Stack
- Node.js 20, TypeScript strict mode
- Postgres via Prisma ORM
- Vitest for tests (NOT Jest)

## Conventions
- Functions: camelCase. Files: kebab-case. Classes: PascalCase.
- Always add JSDoc to exported functions.
- Prefer `const` assertions over enums.

## What NOT to do
- Never use `any` type — use `unknown` and narrow.
- Never commit directly to main — always use feature branches.
- Never log secrets even in dev.

## Test pattern
- Co-locate tests: `src/foo.ts` → `src/foo.test.ts`
- Run tests: `npm test`

## Current focus
Working on the auth module. Most files in `src/auth/` are WIP.

Feature Flags: What's Actually Running

The source uses Bun's feature() DCE macro to compile entire subsystems in or out. In the public release of Claude Code, some of these flags are on and some are off. Knowing which are which tells you what capabilities are actually available versus what's in the source but not exposed.

The key file to read for flag usage is tools.ts — it has the most flag-conditional logic. Any feature('FLAG_NAME') ? require(...) : null pattern tells you that the following code only exists in builds where that flag is enabled.

Permission System: Predicting What Gets Blocked

Every tool call passes through a permission gate before execution. You can predict whether a given operation will need user approval by reading three boolean flags on the tool:

// These three flags on every tool determine permission behavior:
isReadOnly(input): boolean     // true  → auto-approve in most modes
isConcurrencySafe(input): boolean  // true  → can run in parallel batches
isDestructive(input): boolean  // true  → triggers EXTRA-prominent dialog

// The defaults in buildTool() are fail-closed:
// isReadOnly: false     → assumed to write, needs permission
// isDestructive: false  → not flagged as extra-dangerous

Context Window & Compaction: Why Claude "Forgets"

Long sessions inevitably hit the context window limit. Claude Code manages this with three compaction strategies defined in services/compact/. Understanding them explains the "memory loss" behavior many users experience.

What Gets Compacted First

Compaction is not random. The strategies prioritize removing tool_use / tool_result message pairs before touching actual conversational text. This is intentional: tool exchange data (file contents, bash output) is large and disposable once Claude has processed it. Your conversation messages (the human-readable exchanges) survive much longer.

The practical implication: if you showed Claude a large file early in the session, there's a good chance the file contents were compacted out after a few more turns. If you need Claude to reference that file again later, use FileReadTool (or ask Claude to re-read it) rather than assuming it still "remembers."

How to Control Compaction

The System Prompt: What Claude Starts With

The system prompt is assembled fresh for every API call by context.ts and injected parts from multiple sources. Understanding its structure lets you predict what "defaults" Claude operates under and where you can inject your own instructions.

Notice that CLAUDE.md is the only component in this list that you can control. Everything else is generated by the runtime. This reinforces CLAUDE.md as the primary lever for persistent behavioral modification.

Slash Commands vs Prompting: Know the Difference

There are two fundamentally different ways to direct Claude Code: slash commands and natural language prompts. They operate at different levels of the stack and have different strengths.

The 80+ built-in slash commands live in commands/. Key ones to know:

Bundled Skills: Ready-Made Power Commands

The skills/bundled/ directory contains 19 pre-packaged slash commands that ship with Claude Code. They're implemented as JavaScript files that get dynamically loaded as SkillTool instances. Think of them as first-class features that happen to be implemented in user-land.

The Deferred Tools Trick: Hidden Capabilities

Several powerful tools are hidden from Claude's initial context to save tokens. They're only available after Claude calls ToolSearchTool with the right keyword. This means there are capabilities you might not know exist — until you ask for them the right way.

To trigger a deferred tool, describe what you want in a way that matches the tool's searchHint. The tool search runs fuzzy matching against these hints. Known deferred tools and their hints:

Behavior Cheat Sheet: Observable → Source → Lever

A quick-reference map from things you observe to where they live in the source and what you can change.

How to Read Any Tool's Source File

When you browse the source repository and want to understand a specific tool, here's the standard reading order for any tools/[ToolName]/[ToolName].ts file:

1. Read the description string first. This is the behavioral contract — what Claude understands about this tool's purpose. If you want to predict when Claude will use it, this is your answer.
2. Check isReadOnly and isConcurrencySafe. These determine whether the tool auto-approves and whether multiple instances run in parallel. Two lines that tell you everything about the tool's safety profile.
3. Read checkPermissions() if it exists. Any custom permission logic is here. For BashTool, this is where the command classifier runs.
4. Skim the call() method. The actual execution logic. You don't need to understand every line — focus on what input it reads and what output it returns. The shape of the output determines what Claude sees as the tool's "result."
5. Check renderToolUseMessage() and renderToolResultMessage(). These are the terminal UI renderers. They don't affect Claude's reasoning but tell you what the user sees in the REPL.
6. Look for a shouldDefer property. If present and true, this tool is hidden from Claude's initial context and only available via ToolSearch. You'll need to use the right search phrase to access it.

Quick Reference: File → What it Controls