Note: DeepWork is in active development. We welcome feedback and contributions!
Framework for enabling AI agents to perform complex, multi-step work tasks
DeepWork is a tool for defining and executing multi-step workflows with AI coding assistants like Claude Code, Google Gemini, and GitHub Copilot. It enables you to decompose complex tasks into manageable steps, with clear inputs, outputs, and dependencies.
| Platform | Status | Command Format | Hooks Support |
|---|---|---|---|
| Claude Code | Full Support | Markdown | Yes (stop_hooks, pre/post) |
| Gemini CLI | Full Support | TOML | No (global only) |
| OpenCode | Planned | Markdown | No |
| GitHub Copilot CLI | Planned | Markdown | No (tool permissions only) |
Tip: New to DeepWork? Claude Code has the most complete feature support, including quality validation hooks and automated policies. For browser automation, Claude in Chrome (Anthropic's browser extension) works well with DeepWork workflows.
In your Agent CLI (ex. claude), ask:
Please fully install https://pypi.org/project/deepwork/ and make sure you see the new commands.
Agents: - be sure to perform all the steps, not just the package install.
- Python 3.11 or higher
- Git repository
- One of: Claude Code or Gemini CLI
# Using pipx (recommended - isolated environment)
pipx install deepwork
# Or using uv
uv tool install deepwork
# Or using pip
pip install deepworkcd your-project/
deepwork install --platform claude
# Or Gemini CLI, etc.
deepwork install --platform geminiThis will:
- Create
.deepwork/directory structure - Generate core DeepWork jobs
- Install DeepWork jobs for your AI assistant
- Configure hooks for your AI assistant to enable policies
Jobs are multi-step workflows where each Step has clear input and output artifacts, making them easier to manage effectively.
The process of defining a job itself is actually a DeepWork job. You can see it at .deepwork/jobs/deepwork_jobs/.
To start the process, just run the first Step in the job:
/deepwork_jobs.define
Follow the interactive prompts to:
- Name your job
- Define steps with inputs/outputs
- Specify dependencies between steps
It will also prompt you to go on the the next Step in the job.
Run individual steps of your job:
/your_job_name.step_1
The AI will:
- Create a work branch
- Execute the step's instructions
- Generate required outputs
- Guide you to the next step
Use the refine skill to update existing jobs:
/deepwork_jobs.refine
Here's a sample 4-step workflow for competitive analysis:
job.yml:
name: competitive_research
version: "1.0.0"
summary: "Systematic competitive analysis workflow"
description: |
A comprehensive workflow for analyzing competitors in your market segment.
Helps product teams understand the competitive landscape by identifying
competitors, researching their offerings, and developing positioning strategies.
changelog:
- version: "1.0.0"
changes: "Initial job creation"
steps:
- id: identify_competitors
name: "Identify Competitors"
description: "Research and list competitors"
inputs:
- name: market_segment
description: "Market segment to analyze"
- name: product_category
description: "Product category"
outputs:
- competitors.md
dependencies: []
- id: primary_research
name: "Primary Research"
description: "Analyze competitors' self-presentation"
inputs:
- file: competitors.md
from_step: identify_competitors
outputs:
- primary_research.md
- competitor_profiles/
dependencies:
- identify_competitors
# ... additional stepsUsage:
/competitive_research.identify_competitors
# AI creates work branch and asks for market_segment, product_category
# Generates competitors.md
/competitive_research.primary_research
# AI reads competitors.md
# Generates primary_research.md and competitor_profiles/
DeepWork follows a Git-native, installation-only design:
- No runtime daemon: DeepWork is purely a CLI tool
- Git-based workflow: All work happens on dedicated branches
- Skills as interface: AI agents interact via generated markdown skill files
- Platform-agnostic: Works with any AI coding assistant that supports skills
your-project/
├── .deepwork/
│ ├── config.yml # Platform configuration
│ └── jobs/ # Job definitions
│ └── job_name/
│ ├── job.yml # Job metadata
│ └── steps/ # Step instructions
├── .claude/ # Claude Code commands (auto-generated)
│ └── commands/
│ ├── deepwork_jobs.define.md
│ └── job_name.step_name.md
└── .gemini/ # Gemini CLI commands (auto-generated)
└── commands/
└── job_name/
└── step_name.toml
Note: Work outputs are created on dedicated Git branches (e.g., deepwork/job_name-instance-date), not in a separate directory.
- Architecture: Complete design specification
- Contributing: Setup development environment and contribute
deepwork/
├── src/deepwork/
│ ├── cli/ # Command-line interface
│ ├── core/ # Core functionality
│ │ ├── parser.py # Job definition parsing
│ │ ├── detector.py # Platform detection
│ │ └── generator.py # Skill file generation
│ ├── templates/ # Jinja2 templates
│ │ ├── claude/ # Claude Code templates
│ │ └── gemini/ # Gemini CLI templates
│ ├── schemas/ # JSON schemas
│ └── utils/ # Utilities (fs, yaml, git, validation)
├── tests/
│ ├── unit/ # Unit tests (147 tests)
│ ├── integration/ # Integration tests (19 tests)
│ └── fixtures/ # Test fixtures
└── doc/ # Documentation
Define structured, multi-step workflows where each step has clear requirements and produces specific results.
- Dependency Management: Explicitly link steps with automatic sequence handling and cycle detection.
- Artifact Passing: Seamlessly use file outputs from one step as inputs for future steps.
- Dynamic Inputs: Support for both fixed file references and interactive user parameters.
- Human-Readable YAML: Simple, declarative job definitions that are easy to version and maintain.
Maintain a clean repository with automatic branch management and isolation.
- Automatic Branching: Every job execution happens on a dedicated work branch (e.g.,
deepwork/my-job-2024). - Namespace Isolation: Run multiple concurrent jobs or instances without versioning conflicts.
- Full Traceability: All AI-generated changes, logs, and artifacts are tracked natively in your Git history.
Enforce project standards and best practices without manual oversight. Policies monitor file changes and automatically prompt your AI assistant to follow specific guidelines when relevant code is modified.
- Automatic Triggers: Detect when specific files or directories are changed to fire relevant policies.
- Contextual Guidance: Instructions are injected directly into the AI's workflow at the right moment.
- Common Use Cases: Keep documentation in sync, enforce security reviews, or automate changelog updates.
Example Policy:
# Enforce documentation updates when config changes
- name: "Update docs on config changes"
trigger: "app/config/**/*"
instructions: "Configuration files changed. Please update docs/install_guide.md."Generate native commands and skills tailored for your AI coding assistant.
- Native Integration: Works directly with the skill/command formats of supported agents.
- Context-Aware: Skills include all necessary context (instructions, inputs, and dependencies) for the AI.
- Expanding Ecosystem: Currently supports Claude Code and Gemini CLI, with more platforms planned.
DeepWork is currently in MVP phase. Contributions welcome! See CONTRIBUTING.md for the full development guide.
DeepWork is licensed under the Business Source License 1.1 (BSL 1.1). See LICENSE.md for details.
- Free for non-competing use: You can use DeepWork freely for internal workflow automation, education, research, and development
- Change Date: On January 14, 2030, the license will automatically convert to Apache License 2.0
- Prohibited Uses: You cannot use DeepWork to build products that compete with DeepWork or Unsupervised.com, Inc. in workflow automation or data analysis
- Contributing: Contributors must sign our Contributor License Agreement (CLA)
For commercial use or questions about licensing, please contact [email protected]
- Inspired by GitHub's spec-kit