deer-workflow

Name: deer-workflow
Author: deerwork-ai

English: README ·
Guide ·
API |
简体中文：README ·
快速入门 ·
API

An open-source Dynamic Workflow runtime that combines deterministic TypeScript
orchestration with replaceable Agent runtimes.

deer-workflow is a pilot project for
DeerFlow 3.0, also known as
DeerWork. The package name is @deerwork-ai/deer-workflow; the executable is
named deer-workflow.

How to use

Prerequisites

Install Bun and
Codex CLI, then sign in:

Bun is a fast, Node.js-compatible JavaScript runtime and
toolkit; see its installation guide.

npm install -g @openai/codex
codex login
codex --version

Codex CLI and Codex Desktop are separate installations. Installing the Desktop
app does not install the codex terminal command.

Install the CLI

Install the released CLI from npm:

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

Running bun install without --global only installs dependencies for the
current project. It does not install the deer-workflow command globally.

Run an Agent

deer-workflow agent "Inspect this repository"

Create a Workflow

Describe the orchestration you need. The command runs the bundled
workflow-creator Skill through Codex and writes generated source to stdout:

deer-workflow create \
  "Research several independent angles, verify the findings, and synthesize a report" \
  > workflow.ts

Alternatively, install the bundled Skill for your Agents, then ask any Agent
that supports Agent Skills to create a Workflow:

deer-workflow skill install

The command copies the Skill into existing ~/.agents/skills and
~/.claude/skills directories and reports which destinations it changed or
skipped.

Run a Workflow

deer-workflow run ./workflow.ts --input '{"question":"Why has Neo Labs recently emerged as a new force in AI?"}'

Interactive runs show meta.phases and rendered Markdown logs in a live
two-pane TUI, together with the Workflow name, module path, working directory,
and an animated highlight on the active phase. In the default mode, redirected
stderr remains JSONL for automation.

Use --print / -p when running on servers or in automation such as CI/CD,
task queues, process pipelines, and event collectors. It exposes a stable
stdout Event Stream with one JSON event per line:

deer-workflow run ./workflow.ts --print \
  --input '{"question":"Why has Neo Labs recently emerged as a new force in AI?"}'

Examples

Run Deep Research:

deer-workflow run ./examples/deep-research/workflow.ts \
  --input '{"question":"How are Agent Skills and Dynamic Workflows evolving?","outputPath":"./report.html"}'

Run Blog Writer:

deer-workflow run ./examples/blog-writer/workflow.ts \
  --input '{"topic":"The Emerging Trends of Neo Labs","audience":"Agent builders"}'

These paths refer to files in this repository. Clone or download the repository
before running them.

How to develop

Development documentation

The API Reference covers Agents, Flow Controls, Workflow Events, Logging,
Runner behavior, JSON Schema output, and programmatic usage.

Set up

Clone the repository, then install its local dependencies and Git hooks:

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

Run the CLI directly from source while developing:

bun run dev -- --help

Validate changes

Run the complete quality gate before submitting changes:

bun run check

Contribute an Agent integration

Codex CLI is the default Agent runtime, not an architectural dependency.
Contributions for other Coding Agent integrations are welcome.

License

This project is licensed under the MIT License.