How do their APIs compare?

These two projects don't really occupy the same layer, so "API" means something different in each — let me lay out what each actually exposes.

caveman: no runtime API — it's prompts/config, plus one small proxy

Caveman isn't a library you import or call. Its "interface" is:

• Skill files (Markdown instructions consumed by an AI agent), e.g. [skills/caveman-review/SKILL.md:L35-L48] and [skills/caveman-commit/SKILL.md:L36-L58]. These define behavior contracts (few-shot examples of terse vs. verbose output) rather than functions.
• A CLI installer — node bin/install.js --list to inspect what's installed, as shown in [INSTALL.md:L149-L168].
• An MCP proxy tool (caveman-shrink) with a small config-based interface: you wrap another MCP server's command/args in a mcpServers JSON config, and it intercepts tools/list, prompts/list, resources/list responses to rewrite description fields, configurable via CAVEMAN_SHRINK_FIELDS [src/mcp-servers/caveman-shrink/README.md:L17-L36].
• An eval harness (evals/llm_run.py), which is more of an internal dev script than a public API — it drives the claude CLI across baseline/terse/skill conditions and writes JSON snapshots [evals/llm_run.py:L1-L42].

So caveman has no request/response object model, no routing, no middleware — its "API surface" is closer to configuration + prompt contracts + one thin process-wrapping proxy.

koa: a small, explicit HTTP middleware/context API

Koa's API is a conventional Node HTTP framework surface, built around three delegating objects:

• Context — passed to every middleware, wrapping the request/response pair, e.g. app.use(async (ctx, next) => { await next(); }) [Readme.md:L88-L141].
• Request — property getters/setters that delegate to Node's IncomingMessage, e.g. querystring, search, protocol, secure, type, .is(), .get() [lib/request.js:L201-L240, L401-L440, L641-L680].
• Response — the mirror object for ServerResponse (referenced in [Readme.md:L88-L141] but not expanded in the shown chunks).
• Middleware composition is the core "API contract": functions of (ctx, next) that can be sync or async, chained via app.use(), executing in an onion pattern (call order 1→2→3, then unwind 4→5→6), as demonstrated in [tests/application/use.test.js:L36-L75].
• A small internal query-string helper module (lib/search-params.js) backs ctx.query/querystring, with its own stringify/parse functions tested directly in [tests/lib/search-params.test.js:L1-L42], and exercised through the request API in [tests/request/query.test.js:L36-L44] (setting ctx.query mutates .url but leaves .originalUrl untouched).

The comparison

• Nature of the API: koa's is a real programmatic API — objects, methods, getters/setters, and a middleware contract enforced by tests. caveman's is a behavioral/prompt API — Markdown instruction sets and a CLI/config surface, not code you call.
• Composition model: koa has an explicit, testable composition primitive (next() chaining, onion model). caveman has no equivalent; its "composition" is picking which skill/level to load into an agent's context.
• Extensibility surface: koa extends via middleware functions and delegation to Node's http primitives without monkey-patching them. caveman extends via adding new skill files or new proxy field configs (CAVEMAN_SHRINK_FIELDS), which is a data/config extension, not a code interface.
• Testing: koa's API guarantees are backed by unit tests asserting exact call order and object behavior [tests/application/use.test.js:L36-L75, tests/lib/search-params.test.js:L1-L42]. caveman's guarantees (token savings, tone) are validated by the eval harness comparing LLM output snapshots rather than deterministic assertions [evals/llm_run.py:L1-L42].

In short: koa exposes a stable, typed-by-convention JS API for