deerwork-ai/deer-workflow
A TypeScript runtime that writes the workflow's rules while AI agents like Codex do the actual thinking inside each step
deer-workflow is an open-source runtime where the overall control flow, steps, and error handling are written as reviewable TypeScript code, and only the meaning-making work inside each node is handed off to a coding agent such as Codex, Claude Code, or Pi. Instead of letting an AI agent freely decide what to do next through conversation, the execution paths are fixed in code, and you can describe what you want in plain language to have it generate a runnable workflow file. It positions itself as a pilot project for DeerFlow 3.0 (also called DeerWork).
What it does
- Approach: code defines valid execution paths and failure handling, agents only perform the semantic work inside each node ('Graph Engineering')
- How to use: install with Bun, sign in to Codex CLI, then run 'deer-workflow create' with a natural language description to auto-generate a TypeScript workflow file
- Swappable agents: Codex CLI is the default runtime, but Claude Code and Pi are built in, and other coding agents can be integrated through a public interface
- Observability: interactive runs show a phase-aware terminal UI (TUI), while automation/CI can consume a JSONL event stream of one JSON event per line
- Included examples: a Deep Research workflow that investigates topics in parallel and produces a report, and a Blog Writer workflow that plans, drafts, and reviews an article
Why it matters
For teams building AI agent automations, mixing unpredictable agent conversations with business logic makes debugging and review hard; putting control flow into ordinary code while keeping agents swappable gives more predictable and auditable systems. It also matters for anyone tracking DeerFlow, since this project is explicitly a pilot for its next major version.
Terms in this repo
- Graph Engineering · An approach where code defines execution paths (a graph) and AI agents only handle the meaning-based work inside each node
- Coding Agent · An AI system that writes or executes code autonomously, such as Codex CLI, Claude Code, or Pi
- TUI (Terminal UI) · A visual, phase-aware interface shown directly in the terminal during interactive runs
- JSONL event stream · A log format where each line is one JSON-encoded event, used for automation and CI pipelines
- Harness · The integration layer that plugs a specific coding agent (Codex, Claude, Pi) into the workflow runtime
Repository description (English)
An open-source graph engineering runtime that keeps orchestration in TypeScript and delegates semantic work to replaceable Agent runtimes.
Open on GitHubTrending repos
- vorssaint/vorssaint-utilsOne free menu bar app replaces a dozen paid Mac utilities
- Alishahryar1/free-claude-codeA local proxy that lets coding AI agents run on 49 free or cheap model providers instead of one paid service
- freestylefly/awesome-gpt-image-2A library of 532 reverse-engineered prompts that turn GPT-Image2 into a predictable image-making tool
- block/buzzAn open-source workspace where humans and AI agents chat, code, and review in the same rooms
- NousResearch/hermes-agentNous Research's Hermes is an AI agent that gets smarter the more you use it
- virgiliojr94/book-to-skillA tool that turns technical book PDFs into on-demand reference skills for AI coding agents
- VoltAgent/awesome-agent-skillsA single hub collecting over 1000 'how-to' manuals that make AI coding assistants act like experts
- anthropics/claude-plugins-communityA shared shelf where anyone's Claude add-ons get listed for install