eharness weekly downloads statistics

eharness

Build your own agent harness on the Vercel AI SDK v7: plugins, context, messages, streaming, sessions and compaction, with storage you plug in.

Every agent built on AI SDK ends up writing the same harness around streamText: a step loop, prompt assembly, skills, MCP, history that survives restarts, compaction, approvals, a UI stream. eharness is that skeleton as a library. You keep your server, auth, database and domain logic; it standardises the parts every harness reimplements and stays out of the rest.

Status. The contracts in docs/specs are implemented and tested. Before 1.0, breaking changes ship only in minor versions with a migration note in the changelog and in Upgrading (API stability). Modules marked Draft below may change in a minor release.

Why

• Plugins and typed context. Tools, skills, instructions, hooks, services and UI data parts bundle into plugins. Declare them as constants or load them at runtime (per user, per turn, from a database, from MCP); the agent does not care which.
• AI SDK all the way down. The stream is the AI SDK UI message stream (it works with useChat as is), messages are UIMessages, tools are tool(), models are LanguageModel. No parallel types.
• Storage is yours. A two-method MessageAdapter, a StateAdapter, an optional durable inbox. The library ships memory adapters and conformance suites, so your Postgres, JSON or Redis adapter is provably correct.
• Built for long, interactive, multi-instance turns. 500 steps by default with a progress guard, fixed compaction, USD budgets, risk-based approvals, steering, crash recovery, locks and a Stop button that reaches the instance running the turn.
• Product building blocks, all optional. Filesystem, shell, permissions, subagents, memory, todos, an LLM approval guard, OpenAPI tools, providers, connectors, an activity feed, an HTTP module and a browser client.

How it compares:

	What it is	Relation to eharness
AI SDK core (ai)	Model calls, tools, streams, UI messages	eharness is built directly on it; no parallel types
AI SDK Harnesses (@ai-sdk/harness)	Adapter layer to run existing harness runtimes (Claude Code, Codex, ...) in a sandbox	Different layer: eharness is for building your own harness
eve (Vercel)	Filesystem-first, opinionated agent framework with Vercel-native durability	eharness is code-first, unopinionated about infrastructure and much thinner
Mastra	Full framework (workspaces, memory, workflows, deployment)	eharness is a library, not a framework: it owns no server, routes, auth or UI
LangChain Deep Agents	Harness on LangGraph with pluggable filesystem backends	Similar ideas (backends, composition); eharness has no graph runtime dependency

More in concept (what eharness is and is not, principles, glossary).

Install

npm install eharness ai zod     # or: bun add / pnpm add
npm install @ai-sdk/mcp         # only if you use eharness/mcp

Node ≥ 22 or Bun. ESM only. ai and zod are peer dependencies; eharness has no runtime dependencies of its own.

Quick start

import { tool } from 'ai'
import { defineHarnessAgent, defineSkill } from 'eharness'
import { filesystem } from 'eharness/filesystem'
import { inMemoryFs } from 'eharness/filesystem/memory'
import { z } from 'zod/v4'

const agent = defineHarnessAgent({
  model: 'anthropic/claude-sonnet-4.6', // AI Gateway id or any AI SDK model
  contextWindow: 200_000,
  instructions: 'You are a careful assistant. Keep notes as files under /notes.',
  tools: {
    get_time: tool({
      description: 'Current time as an ISO string',
      inputSchema: z.object({}),
      execute: async () => new Date().toISOString(),
    }),
  },
  skills: [
    defineSkill({
      name: 'note-style',
      description: 'Use before writing a note.',
      content: 'Bullets only.',
    }),
  ],
  plugins: [filesystem({ fs: inMemoryFs() })],
})

const session = agent.session('demo')
const run = session.send('Write the current time to /notes/now.md')
for await (const chunk of run.stream) {
  if (chunk.type === 'text-delta') process.stdout.write(chunk.delta) // or, in a route: await run.toResponse()
}

const result = await run.result // never rejects: errors end the turn with stop: 'error'
console.log(`\n${result.stop} after ${result.steps} steps`)
if (result.stop === 'error') console.error(result.error?.code, result.error?.message) // e.g. EH_PROVIDER_AUTH: set AI_GATEWAY_API_KEY
console.log(`${(await session.messages()).length} messages stored`)

The model string goes through the AI Gateway (AI_GATEWAY_API_KEY); any AI SDK provider model (anthropic('claude-sonnet-4-6'), ...) works too. This code is examples/quick-start.ts; bun examples/quick-start.ts runs it offline with a scripted model. Walkthrough: getting started. Terms such as turn, step, kind message and commit point are in the glossary.

Tour

Each snippet is small; the guide linked under it has the full version. Values marked // yours: ... are your application's.

Serve it to useChat

import { handleChatRequest } from 'eharness'
import { agent } from './agent' // yours: the agent from the quick start

declare function authenticate(req: Request): Promise<{ id: string }> // yours
declare function userOwnsChat(userId: string, chatId: string): Promise<boolean> // yours…