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)

Searching Database…

429 ·GitHub
Tardigrade
Что это?Tardigrade — фреймворк на TypeScript для построения модульных агентов вокруг неизменяемого лога событий. Он построен на Effect TS и заимствует декларативную компонентную модель React, выводя представление агента и доступные переходы из лога, а не из изменяемого состояния.
Это фреймворк, на котором я строю своё, или готовое приложение-агент?Это фреймворк для создания агентской обвязки (harness), а не готовый из коробки агент. Вы собираете независимые компоненты (инструменты, бюджеты, компакцию, исполнение кода) в «актора» и сами запускаете эту композицию.
Как его запустить?Установите Tardigrade, выполните `tdg init` для создания редактируемого шаблона актора, отредактируйте actor.ts, описав агента, а затем вызывайте его методы из другой оболочки. Локальный API по умолчанию слушает порт 4242.
Что должно быть установлено, прежде чем пробовать?Для запуска CLI и фреймворка нужен Bun 1.4 или новее, плюс учётные данные выбранного провайдера моделей (например, OpenAI) и постоянное хранилище — локально, например SQLite, либо Cloudflare/Celld, если разворачиваете на этих платформах.
Что будет, если мой процесс упадёт посреди выполнения?Ничего не теряется: каждое действие сначала попадает в лог событий, а `host.recover()` проигрывает этот лог через машины компонентов, заново вычисляя и повторяя все незавершённые переходы, включая неотвеченные вызовы инструментов.
Почему строить на неизменяемом логе событий, а не на обычном состоянии?Такой дизайн, где лог выступает состоянием, делает запуски устойчивыми к сбоям, serverless (никакой процесс не обязан оставаться живым) и полностью просматриваемыми — вы можете переиграть или форкнуть эксперимент с любой контрольной точки в истории запуска.
Что за скилл Tardigrade, упомянутый для кодинг-агентов?Это вспомогательный скилл для кодинг-агентов (упомянут в quickstart), который помогает создать каркас и работать внутри проекта Tardigrade, когда настройку выполняет кодинг-агент, а не человек.
Можно использовать npm вместо инструментов Bun?Сам фреймворк опубликован как npm-пакет `tardie`, устанавливаемый через `npm install tardie` (или `tardie@next` для release-кандидатов), хотя CLI и проектные инструменты построены вокруг Bun.
Куда можно развернуть агента Tardigrade?Сгенерированные агенты разворачиваются как Workers на Cloudflare или Celld с помощью CLI соответствующей платформы; у обеих есть отдельные руководства по развёртыванию, посвящённые конфигурации и секретам.
What are similar projects?flue, cayu, ruflo, penguin-harness, go-micro, open-multi-agent, hive, computer
Which topics is it in?harness-framework, event-sourcing, durable-execution, cloudflare-workers, serverless, bun, cloudflare, agent-framework, harness, agentic-ai, sqlite, multi-agent
Creator
clavia-labs
Size
14.3 MB
Stars
429
Updated
CommitOct 20Releasev0.50.0Oct 16
Age
2mo
Commits · 90 Days