deerwork-ai/deer-workflow: orchestration in TypeScript, semantic work in a replaceable agent

Code is the plan, and the agent fills in the nodes

The positioning is a code-first implementation of graph engineering, and the split is precise: TypeScript defines the valid execution paths while coding agents perform the semantic work inside each node.

What that buys is stated as control flow, phases, inputs and failure handling living in reviewable TypeScript rather than in an opaque agent conversation. The failure mode being argued against is specific. In a conversation-driven design, the sequence of steps is a transcript you read, and changing the order of two steps means rewriting prose and hoping the model follows it. Here the sequence is code, so reordering two steps is moving two statements.

The project describes itself as a Dynamic Workflow runtime for building observable, reusable agent graphs, and as a pilot project for DeerFlow 3.0, which is also known as DeerWork. The two descriptions in the repository differ slightly, with the manifest calling it a runtime for AI agents and the repository description calling it a graph engineering runtime that keeps orchestration in TypeScript, and both point the same way.

The published package declares no dependencies at all

Look at what the manifest ships and the shape of the project becomes clear. The package @deerwork-ai/deer-workflow has no dependencies key. Not an empty one, not a short one: the key does not appear. Everything under devDependencies is tooling, among them typescript, eslint, prettier, husky and lint-staged.

So the runtime installs nothing. What it needs at execution time is already on your machine: Bun to run it, and a signed-in agent CLI to talk to. That is a deliberate consequence of the design rather than a shortcut, since replacing the agent is the point and a tree of agent SDK dependencies would work against it.

The published surface is also narrow. The files list contains exactly two entries, src and skills/workflow-creator, and the export map has a root plus five subpaths: agents, events, flow, logging and runner. Install it and you get the library, the event and runner plumbing, and the skill that teaches an agent how to write a workflow. You do not get the repository's own docs or examples.

Codex is the default runtime, not an architectural dependency

Agent choice is the second pillar, and the wording is careful in a useful way. Codex is the default runtime, Claude Code and Pi are built in, and the public Agent interface remains vendor-neutral.

The contribution section repeats the point in sharper terms: Codex CLI is the default Agent runtime, not an architectural dependency. ClaudeAgent and PiAgent ship as built-in Harnesses, and integrations for other coding agents are welcome. The agents export path in the manifest is where a fourth one would go.

This matters for the generate step, which is where the choice surfaces. The create command asks Codex to apply the bundled workflow-creator Skill and write a runnable TypeScript module. Passing --agent claude or --agent pi generates with another installed harness instead, and Codex remains the default when you pass nothing.

So swapping the agent is a flag on one command, not a fork of the project, provided you have that harness installed and signed in.

A phase-aware TUI for people, one JSON event per line for pipelines

Observability is the third pillar, and it splits along output format rather than along audience.

On an interactive terminal, a run shows phases and Markdown logs in a live TUI. The phases are the workflow's own, which is what the code-first design buys: the phase boundaries you see are the phase boundaries you wrote, not a model's narration of what it thinks it is doing.

For servers, CI and process pipelines, adding --print or -p streams one JSON event per stdout line. That is the format a job can consume, and the word used for it is a stable JSONL event stream, which is a promise about the shape of that output rather than a description of it.

The same run therefore has two front ends over one execution, and the distinction is worth planning around early: if you intend to run workflows in CI, design against the JSONL stream from the start rather than scraping the TUI.

create writes the module, run executes it, the two are separate steps

The quick start is three commands and the middle one is the interesting part.

Install Bun, sign in to the Codex CLI, then install the released CLI globally:

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

Then describe the orchestration you want in prose. The command is `deer-workflow create`, it takes a quoted description, and it redirects a generated TypeScript module to a file:

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

The generated file is then run with its own input:

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

Because generation is a separate step, the output is a file you own. You can read it, edit the phases, change the fan-out, and re-run it without asking a model anything, which is the practical payoff of treating the plan as code.

The bundled examples are not in the tarball you install

Two examples ship in the repository and neither is in the npm package, and the reason is visible in the manifest rather than guessed at.

Deep Research discovers research angles, investigates them in parallel, verifies claims, and produces an interactive HTML report. Blog Writer plans an article, drafts its sections through a pipeline, reviews them, and returns structured output. Both are reference implementations of the two shapes the documentation keeps describing: parallel fan-out with verification, and a staged pipeline with review between stages.

The files list in package.json contains src and skills/workflow-creator. examples/ is not in it, and neither is docs/ or tests/. The instruction that follows the examples is explicit about the consequence: they live in the repository, so clone or download it before running their documented commands.

That is the whole difference between evaluating the runtime and reading its best two examples. The runtime is a two-file install, and the examples cost you a clone.

One command runs four quality gates in sequence

The development path is short because the gate is one command. Clone the repository, cd into it, and run bun install, which also installs the Git hooks since the manifest binds prepare to husky. Then the CLI runs straight from source:

git clone https://github.com/deerwork-ai/deer-workflow.git
cd deer-workflow
bun install

bun run dev -- --help

Validation is a single command, and it is worth reading what it expands to rather than running it blind. bun run check is typecheck, then lint, then format:check, then bun test. Typecheck is bunx tsc --noEmit, lint is eslint . with --max-warnings=0, so warnings fail the gate rather than scrolling past, format:check is prettier in check mode, and tests run under bun test. Four gates, no ordering surprises, and a contributor cannot pass one and skip the others.

The full command reference lives in the Getting Started guide under a develop-the-repository section rather than in the top-level file.

v0.2.0 shipped in July and the tree moved in August

The release record is short and easy to date. Three tags exist: v0.0.1 on 26 July 2026, v0.1.0 on 26 July 2026, and v0.2.0 on 27 July 2026. All three landed inside about thirty hours, which is the shape of an initial public release rather than an ongoing cadence.

The manifest reads 0.2.0, so the published package matches the newest tag. The last push to the default branch main is dated 9 August 2026, about two weeks after v0.2.0, and the repository is not archived. So there is work on main that no release contains, and the npm version is a floor rather than a description of the tree.

The tree itself is conventional for this kind of project: src/, skills/, docs/, examples/, tests/, tsconfig.json, eslint.config.js, lint-staged.config.js, bun.lock, a .husky/ directory for the hooks, plus AGENTS.md, CLAUDE.md, CHANGELOG.md and a Chinese README alongside the English one. The license is MIT.

Editorial conclusion

deer-workflow fits a team that wants agent orchestration to be reviewable code, diffable in a pull request and runnable in CI as a JSON event stream rather than only watched in a terminal. It is a poor fit if you need a packaged runtime with its own dependency tree, since the package declares none and expects Bun plus a signed-in agent CLI on the machine, or if you want the bundled examples, which are deliberately left out of the npm tarball. Before you adopt it, check four things: which agent CLI you have signed in, since Codex is the default and the other two are opt-in, whether the agent support you need exists beyond the three built-ins, what your CI does with the --print stream, and how far the July v0.2.0 release sits from the current tree.

Frequently asked questions

Official sources

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