flue
Frameworkwithastro/flue
TypeScript framework for building programmable agent harnesses.
Overview
Flue is a TypeScript framework for building agents with a built-in agent harness. It supports multiple sandbox types and can be deployed anywhere. It is runtime-agnostic and programmable.
README Preview
> **Experimental** — Flue is under active development. APIs may change.\n>\n> Looking for `v0.0.x`? [See here.](https://github.com/withastro/flue/tree/v0.0.x)\n\n# Flue\n\nFlue is **The Agent Harness Framework.** If you know how to use Claude Code (or Codex, OpenCode, Pi, etc)... then you already know the basics of how to build agents with Flue.\n\nFlue is a TypeScript framework for building the next generation of agents, designed around a built-in **agent harness**. It's like Claude Code, but 100% headless and programmable. There's no baked-in assumption like requiring a human operator to function. No TUI. No GUI. Just TypeScript.\n\nBut using Flue feels like using Claude Code. The agents you build act autonomously to solve problems and complete tasks. They require very little code to run — most of the "logic" lives in Markdown: skills, context, and `AGENTS.md`.\n\nFlue isn't another AI SDK. It's a proper runtime-agnostic framework — think Astro or Next.js, but for agents. Write once, build, and deploy your agents anywhere (Node.js, Cloudflare, GitHub Actions, GitLab CI/CD, etc).\n\n## Packages\n\n| Package | Description |\n| ----------------------------- | --------------------------------------- |\n| [`@flue/sdk`](packages/sdk) | Core SDK: build system, sessions, tools |\n| [`@flue/cli`](packages/cli) | CLI for building and running agents |\n\n## Examples\n\n### Quickstart\n\nThe simplest agent — no container, no tools, just a prompt and a typed result.\n\nUnless you opt-in to initializing a full container sandbox, Flue will default to a virtual sandbox for every agent, powered by [just-bash](https://github.com/vercel-labs/just-bash). A virtual sandbox is going to be dramatically faster, cheaper, and more scalable than running a full container for every agent, which makes it perfect for building high-traffic/high-scale agents.\n\n```ts\n// .flue/agents/hello-world.ts\nimport type { FlueContext } from '@flueFAQ (5)
TroubleshootingHow to prevent flue workflow crashes caused by Anthropic overloaded API errors?
Transient model-provider failures like Anthropic's overloaded error are now automatically retried with exponential backoff. Upgrade to a version that includes commit 666289f or later.
TroubleshootingWhy does flue CLI show 'upgrade Node.js' error when using Bun?
The error occurs because @flue/cli (v0.6.2 and earlier) unconditionally checks Node.js version even when running under Bun. Since Bun handles TypeScript natively, the Node.js version requirement is unnecessary. Starting from commit 48549d9, the CLI detects Bun and provides a Bun-specific upgrade message if the Bun version is too old, instead of a misleading Node.js error. To fix, upgrade to the latest @flue/cli version. For older versions, a workaround is to bypass the check with the environment variable FLUE_NO_NODE_VERSION_CHECK=1 or temporarily run the CLI with Node.js.
TroubleshootingHow to fix 'Invalid prompt_cache_key: string too long' error when using Flue with Codex/OpenAI?
Upgrade Flue to the latest version. The error was caused by session affinity keys exceeding the 64-character limit. The fix (commit a783a7c) replaces long keys with bounded opaque aff_<ULID> keys. If you cannot upgrade immediately, as a temporary workaround, keep component names and session names short to avoid long affinity keys.
TroubleshootingWhy does flue's built-in task tool fail with 'Session is already running prompt' during session.prompt()?
This is a known bug in flue versions prior to v0.8.0. The task tool incorrectly tries to claim the same parent session that is already running a prompt. Upgrade to flue v0.8.0 or later to resolve the issue.
TroubleshootingHow to fix 'Cannot create binding for class FlueRegistry' error (code 10061) when deploying Cloudflare Workers with Flue 0.7.0?
In Flue 0.7.0, the migration for the new internal Durable Object 'FlueRegistry' appears before existing migrations in the generated wrangler.jsonc. Wrangler rejects this because unapplied migrations must come after already-applied ones. Workaround: manually edit dist/wrangler.jsonc and move the 'flue-class-FlueRegistry' tag to the end of the migrations array. For a permanent fix, upgrade to Flue 0.9.0+, which no longer generates migrations; manage your own wrangler.json with the correct order.