claude-runner: 5-Line Claude Agents SDK

npm install claude-runner. Boom. Five lines later, Claude’s ripping through your repo, suggesting refactors, firing tools — all sandboxed, cost-tracked, done.

Tired of this? Every dev building Claude agents is. Or was.

Here’s the deal. Anthropic dropped their official @anthropic-ai/claude-agent-sdk. Powerful. Low-level as hell. query() spits async generators tangled in 20+ message types. MCP servers? Buried in nested objects. Multi-turn chats? You coordinate iterators yourself. No sandbox. No quick permissions. No CLI. So teams everywhere — yours included, probably — hack together 300 lines of the exact same glue.

One dev said screw it. Built claude-runner. A razor-thin TypeScript wrapper. Turns that mess into poetry.

Every team building Claude agents writes the same 300 lines of glue code. I got tired of it and built claude-runner — a thin TypeScript wrapper that turns the official Agent SDK into a 5-line experience.

That’s the hook. Straight from the creator, Santhosh Dhandapani. And yeah, it delivers.

Why Another Wrapper? Haven’t We Seen This Movie?

Look. We’ve been here before. TensorFlow launches, clunky APIs everywhere. Devs wrap it in Keras — boom, adoption explodes. PyTorch? Same story with wrappers smoothing edges. Anthropic’s SDK screams for this. It’s not reinventing wheels; it’s inflating tires so you don’t crash.

claude-runner? Just 1,500 lines. One dep: the official SDK. 34KB gzipped. 61 tests green. MIT. Installs clean, assuming you’ve got Claude Code CLI humming.

import { Runner } from 'claude-runner';
const runner = new Runner();
const result = await runner.run('Analyze this codebase and suggest improvements');
console.log(result.text);

That’s it. Autonomous agent. Reads files. Runs commands. Tools. Typed output with cost, tokens, duration, session ID. Your project bind-mounted. Sandbox optional but dead simple.

Claude-Runner vs. Raw SDK: The Ugly Truth

Flat events. No parsing drudgery. Stream ‘em:

for await (const event of runner.stream('Refactor the auth module')) {
  switch (event.type) {
    case 'text': process.stdout.write(event.text); break;
    // etc.
  }
}

Seven types: text, tool_start, tool_end, done. Clean. Streams live — watch Claude think, tool, finish. Cost at end: $${event.result.cost.toFixed(4)}. No surprises.

MCP? Shorthand magic.

const runner = new Runner({
  mcp: {
    github: 'npx @modelcontextprotocol/server-github',
    postgres: { command: 'npx', /* etc */ }
  }
});

Auto-discovers tools. Plug in GitHub, docs, DBs. Effortless.

Sandboxes? Pick your poison.

Docker: sandbox: 'docker', docker: { image: 'node:22-slim' }. Local isolation. Bind-mount your code. Nuke on exit.

E2B: Cloud VMs. sandbox: 'e2b', e2b: { apiKey: process.env.E2B_API_KEY }. Scale if you must.

Permissions? 'auto' infers. Or callback if picky.

CLI seals it. npx claude-runner "Fix all failing tests". Or --mcp github=.... Opus model? -m opus. Sessions resume smoothly: runner.resume(id, 'Next step').

Is claude-runner the Savior or Just a Band-Aid?

Here’s my hot take — the one Anthropic’s PR gloss won’t touch. This wrapper exposes how half-baked the official SDK feels. Not malicious. Just… engineer-first, user-second. Like early Docker CLI before compose. Devs fill gaps. But what happens when Santhosh ghosts? One-man show. Forkable, sure. MIT begs for it.

Bold prediction: Anthropic yoinks this. Or ships official 2.0 inspired by it. History says so — npm wrappers dictate SDK evolution. Ignore at peril.

Stats don’t lie. 61 tests. Lean deps. Works today. Feedback loop open: GitHub issues, PRs. Missing piece? Yell.

But skepticism check. Requires Claude Code CLI auth. Docker/E2B adds deps. Not zero-config fairy dust. And agents? Still hallucinate. Wrapper doesn’t fix dumb models.

Worth it? For agent tinkerers, yes. Production? Vet hard. Sandboxes mitigate risks, but tool calls in containers — watch your env vars.

Why Does claude-runner Matter for AI Devs Right Now?

Agents exploding. Claude’s edge: reasoning chains, tool use. But SDK friction kills momentum. This unlocks solo devs, prototypes, even teams ditching custom glue.

Dry humor aside — it’s refreshing. No VC bloat. No hype. Just code that works. In a sea of AI SDKs promising moonshots, claude-runner delivers the rocket fuel.

Try it. npm i claude-runner. Run something stupid like “Write me a haiku about boilerplate.” Grin.

🧬 Related Insights

• Read more: Is Your Laravel CRM a GDPR Ticking Time Bomb?
• Read more: LeetCode 309’s Cooldown Trap: Why It Rewires Your DP Brain — And How TraceLit Cracks It

Frequently Asked Questions

What is claude-runner?

claude-runner is a 5-line TypeScript wrapper for Anthropic’s Claude Agent SDK, handling sandboxes, MCP tools, streaming, and CLI with minimal boilerplate.

How do I install claude-runner?

npm install claude-runner, ensure Claude Code CLI is installed and authenticated, then const runner = new Runner();.

Does claude-runner support session resuming?

Yes, use runner.resume(sessionId, 'Follow-up prompt') to pick up full context across turns.