deer-workflow: TypeScript graph control flow with swappable coding agents

The problem deer-workflow targets: orchestration logic buried in agent conversation

Most agent frameworks put the plan inside the model's context. You describe a task, the agent decides which steps to take, and the sequence exists only as a transcript. That makes the control flow hard to review, hard to test and hard to reuse across runs. deer-workflow inverts this. The README states the premise directly: code is the plan, and control flow, phases, inputs and failure handling live in TypeScript rather than an opaque agent conversation. The semantic work still goes to a model, but the graph around it is a file you can open in an editor. The intended audience is engineers building repeatable multi-step pipelines (research, drafting, verification) who want the branching and the parallel fan-out to be deterministic, while the actual text generation stays with a coding agent. The README frames the whole approach as Graph Engineering and points to an external guide for that term. Whether you accept that framing or not, the concrete claim is narrower and checkable: the orchestration is a runnable TypeScript module, and the agent is a pluggable component behind a public interface.

How the runtime splits plan from execution

The architecture has two layers. The outer layer is the Workflow module, a TypeScript file that declares control flow, phases, inputs and failure handling. The inner layer is the Agent, which the README describes as replaceable and vendor-neutral behind a public interface. Codex is the default runtime, with Claude Code and Pi shipping as built-in harnesses. That split is the design decision worth evaluating, because it means the runtime does not own inference. It owns sequencing. When a node needs semantic work, the runtime hands that work to whichever harness is configured and takes the result back into the graph. Observability follows from the same split. Interactive terminals get a phase-aware TUI that shows phases and Markdown logs as the run proceeds. Non-interactive environments get a stable JSONL event stream, one JSON event per stdout line, enabled with --print or -p. That second path is the one that matters for servers and CI, because it turns a run into a parseable log rather than a rendered screen. The README does not specify the event schema in the material available here; the API reference is the place that would document exact event types, so treat any assumption about field names as unverified until you read docs/api.md.

Getting a workflow running: install, create, run

The prerequisites are explicit. Install Bun, then sign in to Codex CLI. After that, install the released CLI globally:

bun install --global @deerwork-ai/deer-workflow

Generation is a single command that takes a natural-language description and writes a runnable TypeScript module to stdout. The README gives this example:

deer-workflow create "Create a Workflow that accepts a topics string array, researches each topic in parallel, and synthesizes a report" > workflow.ts

Under the hood, the CLI asks Codex to apply the bundled workflow-creator Skill, documented at skills/workflow-creator/SKILL.md. You can switch the generating harness with --agent claude or --agent pi; Codex remains the default. Running the generated file takes an input object:

deer-workflow run ./workflow.ts --input '{"topics":["Agent Skills","Dynamic Workflows"]}'

Add --print or -p for the JSONL stream. Two shipped examples, Deep Research and Blog Writer, live in the repository and the README notes they must be cloned or downloaded before their documented commands will work. For repository work, bun run dev -- --help runs the CLI from source, and bun run check is the full quality gate before submitting changes.

The dependency you cannot code around: an external coding agent CLI

deer-workflow does not ship a model. Running anything requires an installed and authenticated coding agent, and the quick start names Codex CLI specifically. That is a real constraint on three fronts. First, the runtime's behaviour is partly the harness's behaviour: latency, token accounting and failure modes inside a node belong to the agent, not to the graph. Second, the vendor-neutral Agent interface is a claim in the README, and the built-in set is Codex, Claude Code and Pi. If your organisation has approved a different agent, the README says integrations are welcome, which is an invitation to write one rather than a statement that one exists. Third, the generation step is itself agent-driven. deer-workflow create asks a harness to apply a skill and emit TypeScript. The quality of the emitted module therefore depends on the harness you selected with --agent, and you should read the generated file before running it. None of this is hidden by the project, but it does mean deer-workflow is a layer on top of a tool you already have to operate, not a replacement for it.

Version maturity and what the release line tells you

The released line is short. v0.0.1 landed on 2026-07-26, v0.1.0 on 2026-07-26, and v0.2.0 on 2026-07-27. The last push to the repository was 2026-08-09, and the project is not archived. The README describes deer-workflow as a pilot project for DeerFlow 3.0, also called DeerWork. Pilot is the operative word. A runtime at 0.2.x can change its exported functions, its event shape and its CLI flags between minor versions, and the README's own documentation map (Getting Started, API Reference, Workflow Creator Skill) is where that surface is defined. If you build on this, pin the version in your manifest and read the release notes before moving. The licence is MIT, which is permissive and places few obligations on redistribution; the repository carries a LICENSE file and the README states the project is licensed under it. That is a statement about the project's terms, not legal advice about your situation, and if you are embedding this in a product you should read the LICENSE text yourself.

Where a different approach fits better

The closest alternative in spirit is a general-purpose agent orchestration library that runs the model loop inside the same process, where nodes call the model API directly and the framework owns retries, streaming and tool dispatch. The difference is where the boundary sits. In that model the framework and the model provider are coupled, and swapping providers means changing the integration layer. In deer-workflow the boundary is the Agent interface, and the agent is an external CLI process that you install and authenticate separately. That buys replaceability at the cost of an extra moving part outside your dependency tree. The choice is not about which is more capable. It is about whether you want your pipeline to depend on a library that talks to a model API, or on a library that shells out to a coding agent you already run. If your team already lives inside Codex or Claude Code, the second shape matches your existing workflow. If you want a single installable package with no external CLI, the first shape is a better fit, and deer-workflow will feel like it has a missing half.

Who should adopt this, and what to check before you do

Adopt deer-workflow if the orchestration itself is the artefact you care about: you want the phases, the parallel fan-out and the failure handling to be a TypeScript file that goes through code review, and you are comfortable with the semantic work happening in a coding agent CLI that you install and sign in to. Do not adopt it if you need the runtime to provide inference, if you need an API that will not move under you in the next few months, or if your approved agent is not Codex, Claude Code or Pi and you are not prepared to implement the Agent interface yourself. Before committing, do three things. Run deer-workflow create with a description that resembles your real task and read the generated module line by line, since it is produced by a harness applying a skill rather than by a fixed template. Run it with --print and inspect the JSONL events to confirm the stream carries the phase information your monitoring needs. And read docs/api.md for the exact exported functions and event types, because the README describes the shape of the system but not its signatures. The MIT licence and the pilot status are both stated plainly; the second one is the one that should shape how much you build on top of v0.2.0.

Editorial conclusion

Adopt deer-workflow if your orchestration is already something you want to read, diff and review as TypeScript, and if you are willing to install and sign in to a coding agent CLI first. Do not adopt it if you need a runtime that ships its own inference, or if you need a stable API surface today, since the released line is v0.2.0 from 2026-07-27 and the README calls the project a pilot for DeerFlow 3.0. Before committing, verify that the bundled workflow-creator skill generates a module that matches your own type definitions by running deer-workflow create and reading the emitted file, and confirm that your target agent harness is one of the built-in Codex, Claude Code or Pi integrations.

Official sources

1. deerwork-ai/deer-workflow on GitHub
2. License: MIT
3. Project website
4. README
5. Releases