flue

Flue is an open-source agent harness framework built by the Astro team that takes a fundamentally different approach from traditional AI SDKs. Instead of wrapping LLM API calls or providing opinionated chat abstractions, Flue gives agents the full infrastructure they need for truly autonomous operation: persistent sessions, a secure sandbox environment, typed tool definitions, reusable skills packaged as Markdown, and durable execution with automatic recovery from failures.

At its core, Flue’s TypeScript harness composes everything an agent needs in a single createAgent() call — the model, tools, skills, sandbox, and instructions. Agents run with filesystem access, bash execution, file editing, and grep search built in from the start. The framework handles session continuity across conversations, compaction of long context windows, and subagent delegation for parallel workstreams.

Flue ships with a rich ecosystem of adapters out of the box. On the deployment side it supports Node.js and Cloudflare Workers. For sandboxing it integrates with local containers, E2B, and Daytona. For observability it provides adapters for OpenTelemetry, Braintrust, and Sentry. For event channels it connects to Slack, Teams, Discord, GitHub, Linear, Notion, Stripe, Shopify, and more — enabling agents that respond to real-world events without custom webhook plumbing.

The project is maintained by the creators of Astro and is itself built using AI agents in an AI-native development workflow. With over 5,700 GitHub stars and 304 commits per month since its February 2026 launch, Flue represents one of the fastest-growing agent frameworks in the TypeScript ecosystem.

What You Get

• A createAgent() harness API that composes model, tools, skills, sandbox, and instructions into a single deployable unit
• Built-in filesystem tools (read, write, edit, grep, bash, glob) available to every agent session without extra configuration
• Persistent session management with context compaction, durable submission recovery, and subagent delegation via the task tool
• Skills system that packages reusable expertise as Markdown files, lazily loaded by agents when needed
• Secure sandbox adapters for local containers, E2B, and Daytona — agents run code in isolated environments
• MCP (Model Context Protocol) integration for connecting agents to authenticated external tool ecosystems
• Event channel adapters for Slack, Teams, Discord, GitHub, Linear, Notion, Stripe, Shopify, and 15+ more
• OpenTelemetry-compatible observability with adapters for Braintrust and Sentry

Common Use Cases

• Automated code triage agents that reproduce bugs, diagnose root causes, and propose fixes when GitHub issues are filed
• Customer support automation that connects agents to Zendesk, Intercom, or Salesforce channels for context-aware ticket resolution
• Developer workflow agents that monitor Linear issues, Slack threads, or GitHub PRs and take autonomous action
• Data processing pipelines built as structured workflows where agent reasoning is guided from a defined input to a finished result
• Multi-agent systems where a coordinator agent delegates specialized subtasks to expert subagents with separate sandboxed environments
• Scheduled automation agents (via node-schedules example) that run recurring tasks with durable execution guarantees

Under The Hood

Architecture Flue’s runtime package (packages/runtime) is organized as a layered modular system with clear separation between the public API, the internal harness, and platform adapters. The entry point is createAgent() in agent-definition.ts, which returns a descriptor that the Harness class in harness.ts uses to wire sessions, tools, sandbox, and event callbacks together. Sessions are managed through session.ts with a facade pattern — user code only receives a FlueSession interface while the internal Session class owns durable submission execution, abort handling, and context compaction. Platform-specific logic lives in isolated sub-directories (cloudflare/, node/) implementing the SessionEnv interface, so core session logic is entirely decoupled from the execution environment. The dispatch and routing layers (runtime/dispatch.ts, routing.ts) sit on top of Hono, exposing agents as HTTP handlers with OpenAPI-compatible route definitions.

Tech Stack Flue is written in TypeScript 6 targeting ESM modules and built with tsdown. The monorepo uses pnpm workspaces with Turborepo for orchestration and Biome for linting and formatting alongside Prettier for style. The core runtime depends on @earendil-works/pi-agent-core and @earendil-works/pi-ai for the LLM streaming and agentic loop abstractions, hono for HTTP routing with @hono/standard-validator for input validation, valibot for schema definitions (with @valibot/to-json-schema for tool schemas), ulidx for session ID generation, and @modelcontextprotocol/sdk for MCP tool integration. Persistence adapters cover libsql, postgres, redis, and mongodb. Vitest 4 is used for the test suite.

Code Quality The codebase maintains comprehensive test coverage across 38 test files in packages/runtime/test/ covering harness sessions, sandbox behavior, dispatch queues, Cloudflare adapters, MCP integration, skill loading, context compaction, stream chunk handling, and structured results. Error handling uses typed error classes (SessionNotFoundError, SkillNotRegisteredError, SubmissionTimeoutError, etc.) exported from errors.ts, with explicit abort signal composition in abort.ts. The SessionEnv interface enforces a clean abstraction boundary: all sandbox adapters implement the same contract for exec, readFile, writeFile, stat, and readdir. Inline comments are thorough in complex areas — the bash tool timeout logic in agent.ts, the writeFileCreatingParents lazy-mkdir strategy in sandbox.ts, and the abort signal composition rationale are all well-documented.

What Makes It Unique Flue’s most distinctive design choice is the Skills system: reusable expertise is packaged as Markdown files with YAML frontmatter and imported via TypeScript’s with { type: 'skill' } import assertion, making skills a first-class language construct rather than runtime strings. The agent framework ships with its own built-in file operation tools (read, write, edit, bash, grep, glob with truncation guards and rg/grep auto-detection) so every agent gets a Claude Code-like environment without any configuration. Durable execution with automatic retry and progress preservation across restarts is built into the submission layer rather than being an optional add-on. The project is also notable for being developed using AI agents in a ‘surgical team’ model inspired by Fred Brooks’ Mythical Man-Month — the CONTRIBUTING.md explicitly describes this AI-native development process.

Self-Hosting

Licensing Model Apache-2.0 licensed — all features available in self-hosted deployments with no restrictions or license keys required.

Self-Hosting Notes Flue runs on Node.js 22+ or Cloudflare Workers. Sandbox providers like E2B and Daytona are external paid services; the framework itself has no dependency on them beyond optional adapters. All framework capabilities including sessions, tools, skills, observability adapters, and channel integrations are fully open.