tardigrade README

The project's README from github.com/clavia-labs/tardigrade. As one markdown file: README.md.


Tardigrade

npm version Join Discord

Tardigrade

Tardigrade is a typescript framework for building modular agents around an immutable event log. It is built on Effect TS and is inspired by React's declarative approach to building user interfaces.

Agents that can self-improve

As models get increasingly smart, they will be capable of writing their own harnesses to improve themselves (Meta-Harness). A harness that is too rigid and complex is a bottleneck to this. We need something more composable, and easy to author.

We took inspiration from React. React derives its component tree and declared effects from state. Tardigrade applies the same idea to agent harnesses. Each component derives a view and enabled transitions from an event log.

{ view, transitions } = f(event log)

Why Tardigrade

Quickstart

Install Tardigrade and initialize an editable template actor. Use Bun 1.4 or later. If you are using a coding agent, the Tardigrade skill can help.

If you have an existing agent application, follow the migration guide to move its harness, history, API, client, and deployment configuration.

bun add -g tardie@latest
tdg init tardie-agent --template quickstart
cd tardie-agent
bun run dev

tdg init configures the first provider and model. Edit actor.ts to describe the agent. The CLI guide covers non-interactive setup, more providers, and deployment.

From another shell, discover the actor's methods, allocate a root thread, and send it a message:

tdg methods
tdg thread create --name quickstart
tdg call message '{"text":"What is the weather in Singapore?"}' --thread quickstart

The API listens at localhost:4242 by default.

An actor serving API requests from its generated Bun development server

Examples

Deploy

Deploy the generated Worker with either platform CLI:

Cloudflare:

bunx wrangler deploy

Celld:

celld deploy --config celld.jsonc

See the Cloudflare and Celld guides for platform configuration and secrets.

Build your own harness

bun add tardie

You can use npm install tardie instead. Install tardie@next to test a release candidate.

Create a component

An agent is made of components. Each component owns a machine with initial, step, and output. Its state retains the information from prior events that can affect its future output. An agent view includes system fragments, tool bindings, and context policy. This component gives the model one tool and owes no autonomous work:

import { component } from "tardie/core"
import { type AgentComponent, type AgentView } from "tardie/agent"

const deploys: AgentComponent = component<undefined, AgentView>({
  name: "deploys",
  initial: () => undefined,
  step: (state, _event) => state,
  output: () => ({
    view: {
      system: ["Inspect recent deployments when a release may explain an incident."],
      tools: [{
        spec: {
          name: "recent_deploys",
          description: "List recent production deploys",
          inputSchema: { type: "object", properties: {}, additionalProperties: false }
        },
        serve: (_call, _log, answer) => [
          answer([{ service: "api", revision: "a17c", summary: "Add rate limiting" }])
        ]
      }],
      context: [],
      output: []
    },
    transitions: []
  })
})

initial creates private state. step updates it for each event. This component ignores events and preserves its state. output derives its view and enabled transitions. Each tool keeps its specification and handler together. answer records the result. Replace the sample result with your deployment API.

An offered tool follows this lifecycle:

  1. The component adds recent_deploys to the agent's composed view.
  2. infer includes its specification in the model request.
  3. The model calls it. Tardigrade records ToolCalled.
  4. Tardigrade runs the attached handler and records ToolReturned.
  5. infer includes the result in the next model request.

Compose an agent

Mount the component beside the built-in parts that this task needs:

import { actor } from "tardie/core"
import { agentMethods, agentsPackage, budget, budgetAuthority, caller, codeMode, compaction, infer, outputValidateOnce, system } from "tardie/agent"
import { fetchPackage, filesPackage, workspacePackage } from "tardie/code"

const instructions = system(
  "You are a release analyst. Identify risky changes and recommend the safest next action."
)

const releaseAnalyst = actor({
  // name supplies the actor's stable identity.
  name: "release-analyst",
  // methods declare how the world can communicate with this actor.
  methods: agentMethods,
  // components implement those methods and derive transitions from the actor's private log.
  components: [
    // infer handles messages as model loops composed by children.
    infer([
      instructions, // system prompt
      deploys,      // provides recent_deploys tool and paired handler
      // budget scopes the tool-call limit to the codeMode subtree
      budget([
        codeMode([  // sandboxed code execution
          filesPackage(),
          fetchPackage(),
          agentsPackage(),
          workspacePackage()
        ])
      ], { authority: caller() }),
      compaction(), // bounded model context
      outputValidateOnce // validates structured result once without correction
    ]),
    budgetAuthority() // budgetAuthority handles requestBudget for this actor.
  ]
})

This agent can inspect deployments and files, fetch sources, delegate research, and analyze results with JavaScript. Change the package list to create another harness.

A run can follow this path:

MessageReceived -> recent_deploys -> execute -> TurnCompleted

Each action and result becomes an event that every component can interpret.

Run the composition

Bind a model and durable SQLite host

The three code blocks form one program. Run it in a project configured by tdg init or tdg setup, with the provider credentials available in the environment. This example registers the adapter for OpenAI Responses and compatible chat completions; use the adapter for your configured protocol.

import { createBunHost } from "tardie/bun"
import { modelAdapters } from "tardie/model/adapter"
import { openAICompatibleAdapter } from "tardie/model/openai"
import { bunModelServices } from "tardie/server/model-services"

const { layers } = await bunModelServices({
  env: process.env,
  adapters: modelAdapters(openAICompatibleAdapter)
})

const host = await createBunHost({
  actor: releaseAnalyst,
  storage: ".tardigrade",
  layersFor: () => layers
})

try {
  const thread = await host.allocateRootThread({ instance: "analyst", name: "main" })
  const result = await thread.methods.message(
    { text: "What changed in the deploy?" },
    { key: "deploy-review" }
  )
  console.log(result)
} finally {
  await host.close()
}

bunModelServices reads the model policy from wrangler.jsonc and binds inference and platform services. createBunHost stores actor instances under storage. The method call returns the completed result; retries with the same key return the same invocation. Use a new key for each new request.

How durability works

Every message, model action, tool result, and checkpoint lands in the log. Component machines consume those events and derive keyed transitions from their current state.

Sₙ₊₁ = step(Sₙ, eₙ₊₁)

The host runs transitions with unrecorded keys. It appends their events and repeats until the agent rests.

If the process stops during recent_deploys, the log still contains its unanswered ToolCalled. host.recover() replays the log through the component machines, derives the same key and input, then runs the handler again. Live execution only steps the machines with newly appended events.

External effects have at-least-once execution. Each keyed result is recorded once. Providers can use the transition key as an idempotency key.

Learn more

Contributing

Read CONTRIBUTING.md and run bun run gate before finishing a change.

tardigrade (clavia-labs/tardigrade)

cloudflare-workers
Searching Database…

425 ·GitHub
Tardigrade
What is this?Tardigrade is a TypeScript framework for building modular agents around an immutable event log. It's built on Effect TS and borrows React's declarative component model, deriving an agent's view and enabled transitions from the log instead of mutable state.
Is this a framework I build on, or a ready-made agent app?It's a framework for authoring agent harnesses, not an off-the-shelf agent. You compose independent components (tools, budgets, compaction, code execution) into an 'actor' and run that composition yourself.
How do I get it running?Install Tardigrade and run `tdg init` to scaffold an editable actor template, edit actor.ts to describe the agent, then call its methods from another shell. The local API listens on port 4242 by default.
What do I need installed before trying it?Bun 1.4 or later is required to run the CLI and framework, plus credentials for your chosen model provider (e.g. OpenAI) and a durable store such as SQLite locally, or Cloudflare/Celld if deploying to those platforms.
What happens if my process crashes mid-run?Nothing is lost: every action lands in the event log first, and `host.recover()` replays that log through the component machines, re-deriving and re-running any unfinished transitions, including unanswered tool calls.
Why build on an immutable event log instead of normal state?The log-as-state design makes runs crash-proof, serverless (no process has to stay alive), and fully inspectable — you can replay or fork experiments from any checkpoint in a run's history.
What's the Tardigrade skill mentioned for coding agents?It's a helper skill for coding agents (noted in the quickstart) that assists with scaffolding and working inside a Tardigrade project when a coding agent is doing the setup instead of a human.
Can I use npm instead of Bun's tooling?The framework itself is published as the `tardie` npm package, installable with `npm install tardie` (or `tardie@next` for release candidates), though the CLI and project tooling are built around Bun.
Where can I deploy a Tardigrade agent?Generated agents deploy as Workers to either Cloudflare or Celld using each platform's own CLI; both have dedicated deployment guides for configuration and secrets.
What are similar projects?flue, cayu, ruflo, go-micro, open-multi-agent, hive, MiMo-Code, computer
Which topics is it in?harness-framework, event-sourcing, durable-execution, cloudflare-workers, serverless, bun, cloudflare, harness, agent-framework, agentic-ai, sqlite, multi-agent
Creator
clavia-labs
Size
14 MB
Stars
425
Updated
CommitOct 16Releasev0.50.0Oct 16
Age
2mo
Commits · 90 Days