cafe-engine 0.1.0

CLI Agent Flow Engine - Automated development workflow with AI agents

The CAFE Engine

AI-Driven Development Workflow Automation

Maximize your vibe coding—without losing control of your codebase.

CAFE (CLI Agent Flow Engine) is an AI-driven development workflow automation system powered by headless CLI agents. Our goal is to help individual developers leverage AI agents more effectively while maintaining code quality and long-term maintainability. It automates the entire development lifecycle—from requirements analysis to PR generation—by orchestrating specialized roles such as PM, Developer, and Reviewer, while keeping the codebase structured, inspectable, and maintainable.

CAFE is actively evolving—we're continuously iterating based on real-world usage and feedback to improve stability, usability, and integration with various AI agents.

---

Who is CAFE designed for?

CAFE is designed for individual developers who want to leverage CLI-based AI agents to accelerate development without sacrificing code quality or long-term maintainability.

CAFE is a good fit if you want to:

• Use CLI agent tools more effectively
  Automate repetitive development tasks—such as requirement breakdown, implementation, code review, and PR generation—so you can focus on higher-level thinking and creative work.

• Maintain control over AI-generated code
  CAFE enforces a multi-stage workflow that decomposes complex tasks into single-objective steps, guiding AI behavior and improving output stability and predictability.

• Improve long-term code maintainability
  By introducing explicit planning and review stages, CAFE ensures that AI-generated code is not only functional, but also readable, structured, and easier to evolve over time.

There is no magic bullet for high-quality code. Human review remains essential.
CAFE is designed to minimize the time and cognitive load required for review, not to eliminate it.

---

Key Features

High-Quality Code via Role-Oriented Workflow

If you frequently spend time correcting code produced by CLI agent tools, CAFE addresses this by introducing explicit role separation.
A PM clarifies intent, a Developer implements changes, and a Reviewer evaluates the result—ensuring each stage is handled with a clear responsibility and objective.

---

Standardized, Repeatable Development Flow

Clarify requirements → Confirm implementation plan → Grab a coffee → Review the PR → Done.

---

Git Worktree Support for Parallel Development

CAFE supports git worktree, enabling parallel development across multiple issues without context switching. Each worktree operates in an isolated environment with its own configuration, allowing you to:

• Work on multiple features simultaneously without stashing changes
• Let agents work in the background while you focus on other tasks
• Maintain separate agent configurations per task (e.g., different models for different complexity levels)

---

Flexible Integration with CLI Agent Tools

CAFE integrates with multiple CLI-based AI agents (e.g., Claude Code, Cursor CLI).
Different agents and models can be assigned per role, allowing you to balance cost, performance, and reasoning depth.

---

GitHub-Native Workflow

CAFE can fetch requirements directly from GitHub Issues and automatically generate pull requests, keeping your AI-driven workflow aligned with standard GitHub development practices.

System Requirements

Prerequisites

• Python 3.10+
• git - for version control
• gh - GitHub CLI (for PR creation and issue management)

Agent CLI Tools (at least one is required)

• Claude CLI
• GitHub Copilot CLI
• Cursor CLI
• Gemini CLI

Support for more CLI agent tools is planned for the future. Stay tuned!

Note: CAFE leverages the headless mode of these CLI tools, which means CAFE operates without requiring interactive sessions or IDE integrations. The CLI tools execute commands and return results to CAFE for processing, enabling seamless automation of the entire development workflow.

Installation

From PyPI

pip install cafe-engine

From Source

# Clone repository
git clone https://github.com/luyotw/cafe.git
cd cafe

# Install CAFE
pip install -e .

# Or install the development version (including testing tools)
pip install -e ".[dev]"

After installation, you can use the cafe command:

cafe --help

Usage

Quick Start

Please ensure you have installed the prerequisites from the System Requirements section and at least one Agent CLI tool.

1. Initialize CAFE settings:

   cafe init
   

   This command will guide you through selecting the Agent CLI tools and configuring the three roles (PM, Developer, Reviewer).

2. Start the development workflow:

   # Initialize the issue environment
   cafe prepare
   

   Switch to the worktree path if set, then:

   # Start or continue the full automated workflow
   cafe make
   

3. Finalize and sync back to original branch: You merge the PR manually on GitHub (or do nothing in local review mode), then:

   cafe close
   

   This command updates the original branch, removes the feature branch and worktree, and backs up related environment files.

4. Multiple CLI agents configuration: You can adjust the CLI agent settings at any time using the cafe config command set. For example:

   cafe config set agents.developer.cli gemini
   cafe config set agents.developer.plan.model gemini-3-pro-preview
   

   To view the current configuration:

   cafe config
   

   Or to edit the configuration file directly in your default editor:

   cafe config edit
   

   Note: In worktree mode, each worktree maintains an independent configuration, allowing for isolated agent settings per development task.

Core Architecture

5-in-1 Workflow:

• The development process consists of five main phases:
  • Phase 1: Requirements Analysis - The PM agent clarifies requirements and writes specification documents.
  • Phase 2: Implementation Analysis - The Developer agent creates an implementation plan and breaks down tasks.
  • Phase 3: Development - The Developer agent implements the features and commits the code.
  • Phase 4: Code Review - The Reviewer agent reviews the code. If modifications are needed, the process returns to Phase 3.
  • Phase 5: Create PR - The Developer agent automatically creates a GitHub PR or allows the user to review locally. If there are suggestions for changes, the process returns to Phase 3.
• You can run the entire flow with a single command, cafe make, or resume an interrupted flow.
• You can also execute each phase separately with its corresponding command:
  • Phase 1: cafe spec
  • Phase 2: cafe plan
  • Phase 3: cafe develop
  • Phase 4: cafe review
  • Phase 5: cafe pr
  • Each of these phase commands can use the --auto flag to automatically proceed to the next phase.

Agent System

• PM: Clarifies requirements, avoiding technical details.
• Developer: Analyzes implementation and writes code.
• Reviewer: Reviews code for quality assurance.

You can create and manage custom agents using the cafe agent command set. Custom agents are stored globally in ~/.cafe/agents/ and can be reused across all your CAFE projects. See cafe agent --help for more details.

Template System

• Spec Template: Defines the format for requirements clarification and specification documents.
• Plan Template: Defines the format for the implementation plan.
• Review Report Template (To be implemented): Defines the format for code review reports.
• PR Description Template (To be implemented): Defines the format for PR descriptions.

You can create and manage custom templates with the cafe template command set. Custom templates are stored globally in ~/.cafe/templates/ and can be reused across all your CAFE projects. When a custom template has the same name as a system template, the custom template takes precedence. See cafe template --help for details.

Other Features

CAFE provides additional commands for managing issues and viewing execution details:

• cafe init - Initialize CAFE configuration for the project
• cafe prepare - Prepare issue environment (directory, config, git branch)
• cafe close - Close current feature and return to base branch
• cafe restore - Restore archived issue from backup
• cafe reset - Remove iterations from a phase when agent behaves unexpectedly
• cafe config - Manage CAFE configuration
• cafe ls - List all issues
• cafe rm - Remove one or more issues and all their data
• cafe show - Display iteration file contents (output, checklist, error, etc.)
• cafe chat - Open interactive chat with specified role Agent
• cafe summary - Display a comprehensive timeline of all workflow phases and iterations
• cafe template - Manage plan and spec templates
• cafe agent - Manage agents

Use cafe <command> --help to see detailed usage for each command.

Contributing

Contributions of any kind are welcome! Please see CONTRIBUTING.md for more details.

License

This project is licensed under the MIT License. See the LICENSE file for details.