deer-workflow

deer-workflow is a code-first implementation of “Graph Engineering”: instead of asking a single agent conversation to hold an entire orchestration plan in its head, deer-workflow keeps the plan in reviewable TypeScript and delegates only the semantic, judgment-heavy work to a Coding Agent running inside each node. Control flow, phases, concurrency, and failure handling are ordinary code; agent(), parallel(), and pipeline() are the primitives that let that code launch and coordinate agent loops.

The project ships as a Bun-first CLI and library. deer-workflow create asks a Coding Agent (Codex by default, with Claude Code and Pi built in) to apply a bundled workflow-creator Skill and generate a runnable TypeScript module from a natural-language description of the orchestration you want. deer-workflow run then executes that module, either as an interactive phase-aware terminal UI or, with --print, as a stream of JSON Lines events suitable for servers, CI, and process pipelines.

Because the vendor-neutral Agent interface is implemented identically by CodexAgent, ClaudeAgent, and PiAgent, a workflow’s orchestration logic does not change when the underlying coding-agent runtime is swapped. parallel() starts every task immediately and preserves input order while converting a failure into a null result rather than cancelling siblings; pipeline() advances each item through ordered stages independently, so partial completion is a first-class outcome the caller must explicitly handle rather than something the runtime hides.

deer-workflow is a pilot project for the upcoming DeerFlow 3.0 (“DeerWork”) from the team behind ByteDance’s deer-flow, and is still early: three releases in, with an active but small (3-person) contributor base.

What You Get

• A workflow()/WorkflowRunner execution engine that loads a TypeScript module, runs its handler inside an async context, and emits a structured lifecycle event stream (start, phase transitions, logs, end, error) as JSON Lines.
• Three orchestration primitives — agent() for a single tool-using Agent Loop call, parallel() for launching independent lazy tasks that resolve failures to null instead of cancelling siblings, and pipeline() for advancing each item through ordered stages independently.
• Three built-in, interchangeable Agent runtimes (CodexAgent, ClaudeAgent, PiAgent) behind one vendor-neutral Agent interface, so a generated workflow’s code does not change when you swap the underlying coding agent.
• A deer-workflow create CLI command that hands a natural-language orchestration request to a Coding Agent running the bundled workflow-creator Agent Skill inside a read-only sandbox, and writes the generated module to stdout for review before execution.
• A phase-aware interactive terminal UI (rendered when stderr is a TTY) that shows the workflow name, declared phases, and live Markdown log output, alongside a --print mode that instead streams one compact JSON event per line for CI and process pipelines.
• A deer-workflow skill install command that copies the workflow-creator Skill into ~/.agents/skills and ~/.claude/skills so other Agent-Skill-aware coding agents (including Pi) can generate workflows without a separate install step.

Common Use Cases

• Parallel research and synthesis pipelines - fan a topic list out to concurrent agent() research calls, then feed the successful findings through a pipeline() of draft and edit stages, as shown in the bundled Deep Research and Blog Writer examples.
• Swapping coding-agent vendors without rewriting orchestration - teams standardized on Codex can migrate individual workflows to Claude Code or Pi by instantiating a different Agent adapter, since all three implement the same interface.
• CI/CD and server-embedded agent orchestration - deer-workflow run --print or an embedded WorkflowRunner gives process pipelines and backend services a stable JSONL event contract instead of screen-scraping an interactive agent session.
• Auditable multi-step agent automation - because control flow, concurrency, and failure handling live in versioned TypeScript rather than an implicit agent plan, changes to “what runs when” go through normal code review.
• Generating first-draft workflow code from a plain-English spec - deer-workflow create "..." produces a runnable, editable TypeScript module scaffold instead of requiring the orchestration to be hand-written from scratch.

Under The Hood

Architecture deer-workflow is a small, cleanly layered monolith split across src/flow (the workflow()/agent()/parallel()/pipeline() primitives and AsyncLocalStorage-backed execution context in flow/context.ts), src/agents (the vendor-neutral Agent interface in agents/types.ts plus CodexAgent, ClaudeAgent, and PiAgent implementations bound through bindAgent() in agents/agent.ts), src/runner (WorkflowRunner, which wires the event emitter, JSON writer, and logging sink around a workflow() call), src/events (a typed event emitter and JSON Lines writer), and src/tui (the interactive terminal dashboard). Loading a workflow module happens through dynamic import() of a resolved file path, module metadata is strictly validated (kebab-case name, unique phase titles, JSON-safe example args), and nesting is deliberately capped at one level via WorkflowNestingError to keep execution graphs shallow and traceable. Swapping the active Agent runtime touches only the adapter instantiation, not the orchestration code that calls it, since every caller depends on the same narrow interface.

Tech Stack The project targets the Bun runtime with TypeScript compiled at ESNext/Preserve module settings and no separate build step for source consumption (bin points directly at src/cli.ts). It has zero runtime dependencies — only devDependencies (typescript, typescript-eslint, eslint, prettier, husky, lint-staged) — so the shipped package surface is entirely first-party code. It publishes to GitHub Packages via a release-triggered GitHub Actions workflow that runs the full bun run check gate (typecheck, lint, format check, tests) before bun publish.

Code Quality Testing uses Bun’s built-in test runner (bun test) with a tests/ tree that mirrors src/ one-to-one (tests/flow, tests/agents, tests/runner, tests/events, tests/logging, tests/tui, tests/cli, tests/examples), covering roughly a dozen and a half test files for a project this size. TypeScript runs in strict mode with noUncheckedIndexedAccess and noImplicitOverride enabled, ESLint enforces typescript-eslint recommended rules plus consistent type-only imports, and Husky/lint-staged run formatting and linting on every commit before a full project type-check. Error handling favors typed, named error classes (WorkflowLoadError, WorkflowNestingError) with attached context (script path, depth) over generic thrown strings, and public APIs carry TSDoc comments with @remarks, @throws, and runnable @example blocks.

What Makes It Unique Rather than another agent framework that asks a single LLM conversation to hold the entire orchestration plan, deer-workflow inverts the relationship: the orchestration plan is ordinary, statically-typed, versioned TypeScript, and the LLM-backed Coding Agent is invoked only for the individual steps that genuinely require judgment or tool use. The three built-in Agent adapters are functionally interchangeable through one interface, letting a workflow module written against Codex run unmodified against Claude Code or Pi. Failure handling is also unusually explicit for this space: parallel() and pipeline() never retry, queue, or fail the whole graph on one bad task — they surface null and force the calling code to decide what “partial success” means for that workflow.

Self-Hosting

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