@caveman-ai/agent

More work, per dollar, with Caveman Agent SDK

git clone https://github.com/JuliusBrussee/agent-sdk.git

Apache-2.0 · Node 22.19+ · v0.2 is on main, not npm.

Claude Agent SDKVercel AI SDKMastraEve
Apache-2.0 · inferred
01Cost

Your agent pays before it works. More tools means more words. You pay for words.

60
240
52
model

$2.50 / 1M in · $0.25 cached · OpenAI list

what your tool list costs todaylist price · estimate
$1,709/ month

52 tools · 20.8K tokens re-read every message · $20,510 a year

→ with Caveman
1 tool · 400 tokens
$33 / mo
kept
$20,115 a year
$1,676 / mo

Tool list only, at list prices, August 2026. An estimate, not a bill. 400 tokens per tool, 22 working days.

02How

Follow one run. Four leaks. Four fixes.

Before the call01

Send one tool, not fifty

Most SDKs send every tool's manual, every message. Caveman sends one tool. The rest work inside it. Still checked. Still billed.

a typical SDK50 schemas
Caveman1

tool schemas per message

While it answers02

Remembers without slowing the answer

It remembers between turns, not during. The cache stays warm. Cached words cost a tenth.

turn n
prefix
history
you
turn n+1
prefix
history
recall
you

recall, placed before your message

AdaptersDon't feel like building with yet another framework? Use our adapters.docs.caveman.so
When it runs long03

Long runs finish instead of failing

Full context kills most agents. The money is gone. Caveman trims and keeps going.

a typical run dies hereCaveman keeps going
When it ends04

Every run hands back a receipt

What it did. What it cost. Where to resume. A crash never eats your money.

model calls6
tool calls1 sent · 13 inside
cost at list price$0.4127
stop reasoncompleted
safe to resume fromstep 7
savings we can prove$0.0000

zero until real traffic proves it

03Start

Ten lines and it's running. In code, or as a folder.

code-based
agent.ts
import { agent, auto, run } from "@caveman-ai/agent";
const support = agent({
id: "support",
instructions: "Answer from policy. Never invent policy.",
model: auto(),
});
vs
directory-based
support-bot/
support-bot/
├── instructions.md
├── skills/
│ ├── refund-policy.md
│ └── shipping-claims.md
├── tools/
│ └── lookup_order.ts
└── evals/
└── support.eval.ts
code-based
run.ts
const result = await run(support, "Can I get a refund?");
console.log(result.text);
console.log(result.receipt);
vs
directory-based
index.ts
import { loadAgentDir, run } from "@caveman-ai/agent";
const support = await loadAgentDir("./support-bot");
const result = await run(support, "Where is order A-123?");
code-based
agent.ts
import { agent, auto, memory, run } from "@caveman-ai/agent";
const support = agent({
id: "support",
instructions: "Resolve support requests.",
model: auto(),
memory: memory({ namespace: "support" }),
});
vs
directory-based
skills/refund-policy.md
---
name: refund-policy
description: When and how to refund an order.
---
# Refund policy
Full body of the skill. Loaded on demand when
the agent uses it. Never in the frozen prefix.
04Connect

Connect it to everything you already run. Anything in. One tool out.

Your tools

OAuth apps, MCP servers, REST APIs, your own functions. Every call is typed, capped, and on the receipt.

Your repo, read as-is
  • AGENTS.mdevery folder up
  • Agent Skills.agents/skills
  • Agent Plugins v1plugin.json
  • Vercel OpenPlugin.plugin/plugin.json
  • Slash commandswith arguments
  • MCP & hookslisted, not run
Your loop

Pinned adapters for Pi, Claude Agent SDK, Vercel AI SDK, Eve, Mastra.

OAuth apps · MCP servers · REST APIs · your keys

MCP
caveman_codethe one tool on the wire
Eve
Pi

your loop, exact-pinned adapters

05Builds

It tries cheaper plans and proves them first. If a check fails, the old build keeps serving.

  1. 01
    Watch the real workload
    approved evals only
  2. 02
    Try cheaper plans
    development cases
  3. 03
    Lock the winner
    before the final tests open
  4. 04
    Check on unseen tests
    untouched until now
every gate passes
.caveman/agent.lock.json
.caveman/workload-profile.json
.caveman/build-report.json
a gate fails
no lock is written.
the previous build keeps serving.
06Honesty

We'd rather print a zero.

savings we can prove
Printed as $0.0000 until real traffic proves them. Never a made-up percentage.
unknown price
Never counted as $0. A run capped in dollars stops instead.
sandbox: "host"
Means uncontained, and says so. Never implied.
observe-only
No Caveman engine: your provider, your calls, no optimization claim.

Build the agent.
Keep the receipt.

quick start
git clone https://github.com/JuliusBrussee/agent-sdk.git
cd agent-sdk
npm ci --prefix packages/agent
npm test
v0.2 is on main, not npm.