Things I Learned from the Claude Code Source Code

The Claude Code CLI ships as a compiled binary, but the TypeScript source underneath is remarkably readable once you unpack it. I spent a week going through all 512,000 lines across 1,884 files, looking for the engineering decisions that reveal where Anthropic thinks AI developer tools are going.

What stood out wasn't any single feature. It was the tension between two competing visions: a polished, safe coding assistant on the surface, and an autonomous agent architecture underneath that's waiting to be switched on.

An autonomous agent hiding behind a feature flag

The biggest surprise in the codebase is KAIROS, a system spanning 61 files and controlled by at least seven sub-flags. The name comes from ancient Greek, meaning "the opportune moment," and the architecture matches the ambition.

KAIROS turns Claude Code from a tool you invoke into a process that runs continuously. It includes a SleepTool that lets the agent pause and resume on its own schedule. A CronCreateTool so it can schedule future tasks. A PushNotificationTool for alerting you on your phone. A SubscribePRTool that watches GitHub pull requests and reacts to changes autonomously.

The session model shifts entirely. Instead of starting and stopping with each conversation, KAIROS sessions persist between interactions, maintain state, and wake up when triggered by external events like cron schedules or webhook payloads.

There's also an "assistant mode" where Claude Code runs as a background daemon, reading its persona from .claude/agents/assistant.md, managing sub-agents, and accepting remote commands through a bridge to claude.ai. This isn't a tool you open when you need help. It's a colleague that never logs off.

The whole thing is locked behind a GrowthBook feature gate called tengu_kairos, with directory trust verification to prevent malicious repositories from hijacking an autonomous agent. It requires an explicit --assistant flag for headless operation.

Tengu: the codename that appears everywhere

Speaking of tengu, that's the internal project name. Every analytics event, every MCP server registration, every telemetry beacon carries the tengu_ prefix. Tengu are shape-shifting creatures from Japanese folklore, known for intelligence and mischief. The name shows up in events like tengu_started, tengu_exit, tengu_worktree_created, and tengu_memdir_loaded.

It's a small thing, but it tells you something about the team's self-image. They named their AI coding agent after a trickster spirit.

Memory consolidation they call "dreaming"

Inside services/autoDream/ sits a feature that borrows directly from neuroscience. After enough coding sessions accumulate, Claude Code fires a background subagent with a specific prompt:

"You are performing a dream, a reflective pass over your memory files. Synthesize what you've learned recently into durable, well-organized memories so that future sessions can orient quickly."

The dream agent reads the existing memory directory, searches recent session transcripts for new information (using targeted grep on JSONL files rather than exhaustive reads), merges findings into existing topic files, converts relative dates to absolute ones, and prunes the index to stay under a size limit.

A cross-process lock prevents multiple Claude Code instances from dreaming at the same time, and timestamps track when the last consolidation happened.

The naming choice is deliberate. They could have called it "background sync" or "memory compaction." They called it dreaming, because that's what it is: the agent processing its experiences during downtime.

How it fights the context window problem

Long coding sessions generate enormous conversation histories. Claude Code attacks this with five separate strategies, which is itself evidence of how difficult the problem remains.

Auto-compact kicks in when context exceeds a threshold, summarizing older messages while keeping recent ones intact. Snip compaction surgically removes specific history sections, triggered by the /compact command. Microcompact runs more frequently with lighter trimming. Reactive compact fires as a recovery mechanism when the API returns a context-too-long error. And context collapse is the nuclear option, essentially starting fresh while preserving critical state.

The system tracks which messages are "snip-safe," meaning they can be removed without losing important information. Tool results often qualify once their conclusions have been absorbed into the conversation.

Five approaches to one problem. That's not over-engineering. That's a team that's tried four approaches that weren't sufficient on their own.

The bridge: remote control from your browser

When you use Claude Code through the claude.ai desktop app or web interface, the execution still happens on your local machine. The architecture uses a WebSocket-based bridge system.

Your local CLI starts a polling loop, registers with a remote session endpoint, and begins accepting commands from claude.ai, including messages, tool approvals, and configuration changes. Results stream back through the same connection. This is how MCP tool calls get forwarded between the web interface and your local environment.

The bridge also handles session spawning and permission bridging, so the security model stays consistent whether you're typing in a terminal or clicking in a browser.

Seven ways to handle permissions

Security leaves the heaviest fingerprints in the codebase. The permission system has seven distinct modes:

default asks before anything risky. acceptEdits auto-approves file changes but prompts for everything else. bypassPermissions skips all checks but requires the --dangerously-skip-permissions flag, cannot be set from project settings (preventing malicious .claude/settings.json files from granting themselves access), and demands explicit trust dialog acceptance. dontAsk never prompts, just denies. plan requires approval of a plan before execution begins. auto uses a transcript classifier, a separate ML model that reads the conversation and decides what's safe. bubble is for subagents, inheriting and restricting parent permissions.

When a permission check fires, it doesn't just show you a dialog. The handler runs a four-way race between the local terminal prompt, the claude.ai bridge interface, channel relays through Telegram or iMessage, and background ML classifiers. Whichever responds first wins. You can approve a command from your phone while the terminal is still waiting.

A full gacha pet system with RPG stats

The most unexpected discovery is the Buddy system, a complete companion engine hidden in the codebase.

Every user gets a procedurally generated pet based on a seeded PRNG derived from their user ID. There are 18 species including duck, axolotl, capybara, and "chonk." Five rarity tiers run from Common (60%) through Legendary (1%). Each companion has RPG-style stats: DEBUGGING, PATIENCE, CHAOS, WISDOM, and SNARK, with one peak stat and one dump stat.

Cosmetic options include six eye styles and eight hat choices, among them crown, wizard hat, and "tinyduck," which is a tiny duck sitting on your companion's head. There's a shiny variant for the luckiest rolls.

The companion's "soul," its name and personality, gets generated by the AI model on first hatch. The physical attributes regenerate from your user ID hash every time, so editing your config file won't give you a legendary.

Someone at Anthropic built a weighted rarity drop system with gacha mechanics into a professional coding tool. On purpose.

Two builds from one codebase

The build system uses Bun's feature() function for compile-time dead code elimination. When feature('KAIROS') evaluates to false in the external build, the entire code path and all its imports vanish from the bundle.

The external build cannot contain staging URLs, internal model codenames, dev API keys, REPL tools, or something called "undercover mode." A USER_TYPE=ant environment variable controls another layer, making tools like REPLTool and SuggestBackgroundPRTool available only to Anthropic employees.

This dual-build approach means the public binary is genuinely stripped of internal capabilities, not just hidden behind UI. The code paths don't exist.

Five api providers behind the scenes

Claude Code supports five distinct API backends: Anthropic Direct, AWS Bedrock, Azure Foundry, Google Vertex, and Claude.ai OAuth. Each has its own authentication flow, endpoint construction, and header requirements. The code assembles over 15 beta headers for capabilities like extended thinking, million-token context, fast mode, and client attestation.

35+ tools with the Bash tool locked down hardest

The tool system contains more than 35 tool directories. BashTool gets the most protection: full AST parsing of commands via tree-sitter, path validation against dangerous locations, a security classifier analyzing intent, sandbox support with filesystem and network restrictions, concurrent safety analysis that defaults to worst-case assumptions, secret detection, UNC path blocking on Windows, and device path protection.

The dangerouslyDisableSandbox parameter exists in the code but is deliberately excluded from the tool schema sent to the model. The AI literally cannot ask for it.

What the architecture reveals

Three patterns repeat across these 512,000 lines.

The first is that autonomy is the destination. KAIROS, the sleep/wake cycle, scheduled tasks, push notifications, the assistant daemon, all of it points toward an AI that works independently and reports back, rather than waiting for instructions.

The second is that granting autonomy to an agent that executes shell commands is genuinely dangerous, and the team knows it. Seven permission modes, ML-based safety classifiers, a four-way approval race, and a flag literally named "dangerously" are the marks of engineers who understand what can go wrong.

The third is that behind the enterprise architecture and security infrastructure, there are people who named their project after a trickster spirit, called memory consolidation "dreaming," and hid a tiny duck hat in the companion cosmetics. That sensibility, building serious tools without taking yourself too seriously, might be the most important thing the source code reveals about Anthropic's engineering culture.