Forem: Karan Singh Chandel

Claude Code Under the Hood: How It Actually Works

Karan Singh Chandel — Mon, 06 Apr 2026 06:49:27 +0000

In March 2026, Anthropic accidentally published a source map in an npm package.

That map pointed to a zip on R2. That zip contained unobfuscated TypeScript for Claude Code. Someone posted it on X. And suddenly, a lot of us had front-row seats to how a modern coding agent is actually built.

I spent some time digging through the code, docs, and community notes. This post is the version I wish I had on day one: practical, opinionated.

No hype. Just architecture, tradeoffs, and what this means if you build AI tooling.

Quick take

Claude Code is not magic. It is a very disciplined system around a very capable model.

The model is the brain. The product quality comes from the nervous system: loop orchestration, permissions, context compaction, tool contracts, caching, retries, and UI responsiveness.

You can clone the outer loop in a weekend. You cannot clone the reliability story in a weekend.

The moment it clicked for me

I had that "oh" moment while tracing one simple task: "fix failing tests."

On paper, that's one sentence. In production, it's a chain of fragile decisions:

Decide to run tests first without being told.
Parse noisy failures and isolate relevant files.
Search a big repo without getting lost.
Make a minimal edit instead of a destructive rewrite.
Re-run tests and interpret second-order failures.
Recover when the first fix was wrong.

If you've ever built an internal "code agent" prototype, you know where this usually dies. Not on step one. On step four or five, when context is bloated, terminal output is huge, and one flaky command derails the run.

That is where Claude Code is strongest: not in the first answer, but in the 17th decision.

Architecture in simple diagram

If you remember one thing from this article, remember this: the loop is the skeleton, but the guardrails and context strategy are the organs.

Start: the first 200 ms are engineered, not lucky

When you run claude, startup does something I love from a DevRel perspective: it optimizes what users feel, not just what engineers measure.

Before heavy modules fully finish loading, it can kick off parallel work like:

policy lookups (MDM/enterprise settings)
secure token retrieval
warming a connection to API infrastructure

That means by the time your first prompt lands, expensive setup has already started.

Funny Analogy: this is the restaurant that starts warming your plate while your order is still being typed. You call it a "fast kitchen," but really it's choreography.

Bootstrap: boring systems that prevent expensive pain

Initialization has all the things seasoned platform teams eventually add:

schema-validated config with migrations
auth and token lifecycle handling
telemetry and feature flags
environment-specific policy resolution

None of this is flashy. All of this is what keeps large org rollouts from becoming support tickets.

One detail I found especially smart is build-time elimination for disabled features. If a feature flag is off, code can be stripped from shipped artifacts rather than merely gated at runtime.

Why this matters:

smaller runtime surface
fewer hidden interactions
safer gradual rollout

Let's see QueryEngine

People say "it's just an agent loop." Sure.

So is saying "a database is just read and write."

The core loop is conceptually small:

append user input
build system and user context
stream model output
execute tool calls if present
feed tool output back and continue
stop when final response is produced

The hard part is everything around those six steps:

streaming that survives partial network failures
retry behavior that does not duplicate dangerous actions
concurrency control for tools that can safely run in parallel
token and cost accounting
context compaction under pressure
UX that stays responsive during long-running commands

Think of QueryEngine as an air traffic control tower. Planes landing is the easy part. Preventing collisions, handling weather, and rerouting under stress is the job.

Why context engineering is the hidden moat

Most people underestimate this.

Context windows are finite and agent sessions are greedy. Every file read, terminal dump, and tool result consumes budget.

Claude Code's split is simple and very effective:

stable session metadata goes where caching benefits most
rapidly changing memory and turn-specific data stay separate

That design improves cache hit rates and reduces reprocessing overhead.

When pressure increases, compaction strategy kicks in:

trim stale tool output first
summarize older history when needed
preserve recent user intent and high-signal artifacts longest

Analogy: this is not deleting notes randomly; it's compressing your meeting transcript while pinning the action items.

Tools: one contract, many capabilities

This was one of the cleanest design choices I saw.

Whether a tool is built-in, remote, or plugin-provided, it follows a common shape:

validated input schema
permission semantics
execution implementation
rendering behavior
concurrency declaration

That single contract enables a lot:

minimal special-casing in the loop
easier extension via MCP
safer composition at scale

If you've ever maintained a platform where every plugin needed custom branching logic, you know how valuable this is.

Permissions: trust the model, verify the action

Giving an AI shell access without controls is how you get a postmortem.

The effective pattern is layered, not binary:

organization and project policy
tool-level risk semantics
current operation mode
safety classification pass
user confirmation when needed

This turns "agent autonomy" into managed autonomy.

Analogy: modern CI/CD lets engineers ship fast, but only through protected branches, checks, and approvals. Same philosophy here.

Subagents: practical answer to context bloat

Subagents are not just a shiny feature. They are a memory-management strategy.

A subagent gets a fresh context, solves a bounded task, and returns a summary. The primary thread keeps signal without inheriting every intermediate breadcrumb.

In real teams, this feels like delegation:

give a teammate a narrow problem
let them research independently
ask for a concise brief, not raw logs

That is exactly the shape of healthy agent orchestration.

"React in a terminal" sounds weird, but it makes sense

Yes, terminal UI implemented with React primitives can sound like overkill.

But after reading the architecture, I get it.

For a state-heavy, component-driven, asynchronous interface, the React mental model is useful even outside the browser:

deterministic render updates
composable UI states
reusable hooks for permissions, sessions, and notifications

It is less about "React everywhere" and more about "use a model your team can reason about under pressure."

The part many posts miss: this is a product bet, not a feature bet

There are two philosophies in AI devtools right now.

Approach A: heavily script workflows, tightly constrain decisions, make behavior predictable.

Approach B: give the model broader agency and build hard safety systems around it.

Claude Code leans toward B.

That only works if infrastructure is serious: permissions, checkpoints, compaction, retries, cost visibility, extension boundaries. Without that, "agentic" quickly becomes "chaotic."

With that, model improvements flow through the product with less product-level rewiring.

Final thought

You can absolutely build a capable coding loop in a weekend.

What takes real engineering maturity is making that loop feel trustworthy on Tuesday at 6:40 PM, when tests are flaky, output is noisy, context is tight, and a teammate is waiting on your fix.

That is what I came away respecting most. Not that it can answer. That it can keep operating.

If you're building in this space, study the orchestration and safety architecture as much as the prompts. The prompts get demos. The architecture gets adoption.

Let's keep building!

I Built a CLI Tool to Fix dbt Governance Problem Using DataHub

Karan Singh Chandel — Wed, 21 Jan 2026 09:58:41 +0000

The Problem

I use dbt to write transformations, manage dependencies, run tests, and keep everything in version control. For building data pipelines, dbt is excellent.

But when it comes to governance, dbt falls short.

I wanted to know who owns each model. I wanted to enforce documentation standards. I wanted to catch when someone depends on deprecated data. I wanted these checks to run during development, in my terminal, in CI, not after deployment.

dbt doesn't do this. It's a transformation tool, not a governance platform.

So I built a CLI tool that brings governance into the dbt workflow by connecting it to DataHub.

Pain Points with dbt (When It Comes to Governance)

No Ownership Tracking

dbt has no concept of ownership. When dim_customer_metrics breaks at 2 AM, who do you contact? The original author might have left the company months ago. There's no ownership field in dbt.

Documentation is Optional

You can add descriptions in dbt. But nothing enforces it. Half my models have no description. The other half say "customer table" which tells you nothing.

No Awareness of Deprecated Data

dbt doesn't know if an upstream source is deprecated. You can depend on a table scheduled for removal and dbt won't warn you. You find out when production breaks.

No Data Classification

Which models contain PII? Which are safe to share externally? dbt has no built-in tagging for sensitivity or compliance. Teams track this in spreadsheets that go stale.

Governance Happens After the Fact

Even if you try to enforce standards, it's manual. Someone reviews a PR, maybe checks ownership, maybe doesn't. It's inconsistent and depends on who's reviewing.

The Solution: DataHub as the Governance Platform

DataHub solves exactly what dbt lacks. It's a metadata platform that tracks:

Ownership: who's responsible for each dataset
Domains: which business area owns the data
Deprecation status: what's scheduled for removal
Tags: PII classification, sensitivity levels
Descriptions: rich documentation
Lineage: upstream and downstream dependencies

DataHub has the governance metadata. The question was: how do I use it during dbt development?

What I Built

I built dbt-datahub-cli, a command-line tool that validates your dbt models against governance rules stored in DataHub.

The idea is simple:

You have dbt models
You have governance metadata in DataHub (ownership, tags, etc.)
This CLI checks if your models meet the governance standards

How It Works

When you run the CLI:

Reads your dbt manifest - gets all your models from manifest.json
Looks up each model in DataHub - fetches ownership, domain, tags, deprecation status
Checks against your rules - does this model have an owner? a description? is it using deprecated data?
Reports what passed and failed - with clear messages about what to fix

CLI Commands

The main command is validate:

dbt-datahub-cli validate --manifest target/manifest.json

Other useful commands:

init - creates a starter config file
list-rules - shows all available rules
test-connection - checks if DataHub is reachable

No DataHub Yet? Use Dry Run

dbt-datahub-cli validate --manifest target/manifest.json --dry-run

This runs validation without connecting to DataHub. Good for trying out the tool first.

Architecture

The Rules

Rule	What It Enforces
`require_owner`	Every model must have an owner in DataHub
`require_description`	Models must have meaningful descriptions
`no_deprecated_upstream`	Can't depend on deprecated datasets
`require_domain`	Models must belong to a business domain
`require_tags`	Required tags (like PII) must be present
`upstream_must_have_owner`	Dependencies must have owners too
`naming_convention`	Model names follow your patterns

Each rule can be set as error or warning.

Why DataHub?

I chose DataHub because it already tracks everything I needed:

Single source of truth - ownership, domains, tags in one place
Clean API - easy to fetch metadata with Python SDK
Lineage aware - knows what depends on what
Extensible - custom metadata works too

The data was already there. I just needed to use it at the right time.

Quick Start

1. Clone and Install


git clone https://github.com/karan0207/dbt-datahub-cli.git
cd dbt-datahub-cli
pip install -e ".[all]"

2. Create Config

dbt-datahub-cli init

This creates a governance.yml where you enable the rules you want.

3. Connect to DataHub

export DATAHUB_GMS_URL="http://your-datahub:8080"

4. Run Validation

dbt-datahub-cli validate --manifest examples/sample_manifest.json

Sample Output

Web Dashboard

Prefer a GUI? I also built a Streamlit dashboard:

dbt-datahub-cli dashboard

Same validation engine, visual interface.

Before & After

Before	After
Ownership unknown	Ownership enforced via DataHub
Descriptions are "nice to have"	Descriptions required to merge
Deprecated deps break prod	Deprecated deps blocked in CI
Governance is manual	Governance runs automatically

Try it out: https://github.com/karan0207/dbt-datahub-cli

Questions or ideas for new rules? Drop a comment or open an issue.