Overview

Flue is a TypeScript framework for building autonomous agents and AI workflows around a programmable harness rather than around a thin model-call wrapper. The repository presents Flue as “not another SDK” because the main abstraction is the complete operating environment an agent needs: instructions, tools, skills, sessions, filesystem access, and a sandbox in which the agent can safely do work. The top-level README and package READMEs lead with the same triage-agent example, making the harness idea the public entry point for both application developers and package consumers.

Sources: README.md, packages/runtime/README.md, packages/cli/README.md

Purpose and Scope

Use this page as the starting map for the Flue documentation set. It explains the repository’s value proposition, the core primitives that appear throughout the guides, and how the public monorepo packages relate to everyday development tasks. Flue is aimed at builders who want agents to complete open-ended work, not just respond to messages or execute a fixed chain of prompts. The README contrasts early raw LLM API calls with more capable tools such as Claude Code and Codex, then positions Flue as the framework that brings that architecture to user-defined TypeScript applications.

The practical distinction is that a Flue agent is not only a prompt. A Flue agent definition composes the model, reusable skill content, application-owned tools, routing policy, and sandbox selection into a durable resource that can be run locally or deployed to a target runtime. The example agent imports a local sandbox helper, Markdown skills, and GitHub-related tools, then exports an HTTP route guard and a default agent definition. That shape previews the rest of the framework: author resources in code, decide explicitly how they are exposed, and let the runtime coordinate long-lived agent work.

Sources: README.md, packages/runtime/README.md

Relevant Source Files

• README.md — Defines the public Flue positioning, the triage agent example, the feature list, and the “Agent Harness Framework” terminology used throughout the docs.
• package.json — Describes the repository as a private pnpm and Turbo monorepo, records Node and pnpm engine expectations, and lists the main build, test, type-check, lint, and format scripts.
• packages/runtime/README.md — Repeats the public runtime package overview and demonstrates that the agent harness primitives are exported for application code through the runtime package.
• packages/cli/README.md — Repeats the public CLI package overview and anchors the command-line package in the same agent harness workflow described by the root documentation.

Core Primitives

The central primitive is the agent harness. In the README example, the harness is assembled with a model string, tools, skills, a sandbox, and instructions. Instructions describe the mission in natural language; in the example, the agent is told to triage a bug report end to end, reproduce the issue, diagnose the root cause, verify intent, and attempt a fix. Tools are imported from application code and give the model typed ways to call APIs or perform controlled changes. Skills are imported Markdown files that package reusable procedural knowledge and can be shared across agents.

A sandbox is the execution environment where the agent can inspect files, modify state, or run work without being handed unchecked access to the host. The README describes virtual, local, or remote container sandbox choices, while the example uses the Node-target local sandbox helper. This is important because Flue’s promise is not only better prompting; it is a safer environment for autonomous work. The sandbox, tool boundary, and route handler together let developers decide what the model may do, where it may do it, and how external callers are admitted.

Sessions and durable execution are the continuity layer. The feature list describes agents that keep context across conversations and events while working toward a goal, and it points readers to durable execution for preserving progress through failures and restarts. Workflows complement agents when the process should be more structured: application code guides reasoning from a defined input to a finished result. Subagents let an agent delegate to specialized roles, while channels receive verified events from systems such as Slack, Teams, Discord, and GitHub so work can begin where users already collaborate.

MCP servers and observability round out the first set of concepts a new reader should recognize. MCP connects agents to authenticated tools and services through the open Model Context Protocol ecosystem, which differs from local tools because the capability boundary is a server connection rather than a function exported by the application. Observability gives operators a way to monitor agents and export telemetry through OpenTelemetry, Braintrust, Sentry, or a custom observer. Together, these primitives explain why Flue is a harness: it surrounds model reasoning with context, capability, policy, persistence, ingress, and feedback.

Sources: README.md, packages/runtime/README.md

Monorepo Packages and Development Surface

The repository is a private workspace managed with pnpm and Turbo. The root package declares Node and pnpm engine ranges and provides scripts for development, building, tests, integration tests, linting, type checking, formatting, and a combined check command. Those scripts show that Flue is maintained as a multi-package TypeScript system rather than a single distributable library. In practice, readers will mostly touch package entry points such as the runtime, CLI, SDK, React bindings, database adapters, channel packages, and observability tooling, while the root scripts coordinate the repo-wide development lifecycle.

The two package READMEs in scope for this page reinforce that the runtime and CLI are complementary surfaces. The runtime package is where application code imports agent definitions, route handler types, sandbox helpers, tools, skills, and other public programming abstractions. The CLI package is the developer workflow surface: official docs show installing it as a development dependency, running a local server with the development command, invoking one resource from the terminal, and building target-specific artifacts. The framework therefore separates authoring primitives from project operations while keeping them aligned around discovered Flue resources.

Sources: package.json, packages/runtime/README.md, packages/cli/README.md

System-to-Code Mapping

The important pattern is that discovery does not automatically equal public exposure. The official CLI overview notes that local development serves the real HTTP and SDK surface, but agents and workflows are not public merely because the project discovers them. That matches the README example, where the agent file exports a route handler next to the agent definition. New developers should therefore read resource definition and routing together: define the resource, decide how callers are authorized or admitted, then test through the same application mount that production traffic will use.

Sources: README.md, packages/cli/README.md

First Project Flow

A minimal first project flow starts with installing the CLI in an application workspace and running the development server. The official CLI docs require a modern Node runtime and show the CLI being invoked through the package manager. During authoring, the development server watches source files and serves the configured Node.js or Cloudflare target. This lets you test the same HTTP and SDK surface that your app will expose later, rather than using a separate mock runner that bypasses routing, middleware, or resource mounting decisions.

npm install --save-dev @flue/cli
npx flue dev

After defining an agent or workflow, exercise one resource with the run command. Official docs show prompts or workflow inputs being passed as JSON. When no absolute server URL is supplied, the command can start the configured runtime temporarily and call through the authored application mount. That behavior is useful because it keeps middleware and route policy in the loop during local testing. For a non-root mount, pass a relative server path; for an already running local or deployed app, pass an absolute URL.

npx flue run assistant --input '{"message":"Summarize this repository."}'
npx flue run workflow:summarize-ticket --server https://example.com/api/flue --input '{"ticket":"Ticket details"}'

When the application is ready, the build command packages the discovered application for the configured target. The official CLI overview is explicit about what a build does not do: it does not choose a model, add credentials, expose extra routes, or configure platform-owned bindings. Those decisions remain application and deployment responsibilities. This separation is a recurring Flue design choice. The framework helps you define durable agent and workflow resources, run them locally, and produce target-specific artifacts, but it does not silently invent security, credential, model, or platform policy on your behalf.

Sources: packages/cli/README.md, package.json

Learning Path

Start with the quickstart if you want to create and run an application immediately, then move to the agent and routing guides before exposing anything to external callers. Read the building-agents page to understand how instructions, tools, skills, models, and sandboxes compose into a harness. Read durable execution when you begin accepting long-running work or need recovery semantics. Choose a channel page when events should arrive from Slack, Discord, GitHub, Teams, Google Chat, messaging services, or business SaaS systems. Use the CLI and API reference pages once you are refining commands, resource names, invocation inputs, or package-level entry points.

The main mental model to carry forward is simple: Flue applications are TypeScript programs that define durable AI resources, connect them to trusted capabilities, and expose them deliberately through routes, SDKs, or verified channels. The monorepo supplies the runtime primitives, the CLI workflow, and ecosystem packages that make that pattern repeatable across local development and deployed targets. If you are evaluating Flue, read why-flue next. If you are building, continue to quickstart and project-layout, then return to this overview when choosing deeper pages about tools, workflows, sandboxes, channels, databases, and observability.

Sources: README.md, package.json, packages/runtime/README.md, packages/cli/README.md