deer-workflow

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.

Index

• How to use
  • Prerequisites
  • Install the CLI
  • Run an Agent
    • Other Agents / Harnesses
  • Create a Workflow
  • Run a Workflow
  • Examples
• How to develop
  • Development documentation
  • Set up
  • Validate changes
  • Contribute an Agent / Harness integration
  • License

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"
deer-workflow agent --agent claude "Inspect this repository"

Other Agents / Harnesses

The agent() helper and Agent-backed CLI commands use the Codex harness by default. Claude Code is also included as a built-in harness. Select it with --agent claude on agent or create. First install Claude Code CLI and sign in:

npm install -g @anthropic-ai/claude-code
claude auth login
claude --version

From TypeScript, instantiate ClaudeAgent directly:

import { ClaudeAgent } from "@deerwork-ai/deer-workflow/agents";

const runtime = new ClaudeAgent({ model: "sonnet" });
const result = await runtime.run("Inspect this repository.");

See ClaudeAgent in the API Reference for sandbox, model, and structured-output options.

Create a Workflow

Describe the orchestration you need. The command runs the bundled workflow-creator Skill through Codex by default and writes generated source to stdout. Pass --agent claude to select the Claude Code harness:

deer-workflow create --agent claude \
  "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

• Getting Started
• API Reference
• Workflow Creator Skill
• 中文开发文档

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 / Harness integration

Codex CLI is the default Agent runtime, not an architectural dependency. ClaudeAgent (Claude Code CLI) ships as another built-in harness; contributions for other Agent and Harness integrations are welcome.

License

This project is licensed under the MIT License.