Skip to content
/
Tier B A6 Multi-agent orchestrator

Clean-Coder-AI

clean-coder-ai · Grigorij-Dudnik/Clean-Coder-AI · ★ 576 · last commit 2025-10-02

Autonomous 2-in-1 AI developer + scrum master that plans an entire project as Todoist tasks and executes them task-by-task with a LangGraph multi-agent pipeline.

Best whenTodoist as external persistent task state — humans see live project progress in their project manager while AI works autonomously.
Skip ifMaking up information when uncertain — always ask human or research files, Writing code inside task descriptions
vs seeds
claude-flow(Archetype 3 — multi-agent with external state), but implemented as a standalone LangGraph Python process rather than an…
Primitive shape 7 total
Subagents 7
00

Summary

Clean-Coder-AI — Summary

Clean-Coder-AI is a Python-based autonomous coding agent framework built on LangGraph that combines a Todoist-integrated project manager with a multi-agent coder pipeline — giving AI the ability to plan an entire project as Todoist tasks, then execute tasks one-by-one using specialized sub-agents (Manager, Planner, Executor, Researcher, Debugger).

Problem it solves: Coding agents lack persistent project management context and tend to implement features in isolation without a coherent project plan; Clean-Coder-AI uses Todoist as an external task ledger so the AI always has a structured, updatable backlog and can work through it autonomously across multiple sessions.

Distinctive trait: Todoist integration as a first-class external state store — the Manager agent creates, reorders, and marks tasks in Todoist, and the system uses Todoist task state to track project progress across sessions (persistent beyond conversation context).

Target audience: Developers who want a fully autonomous coding agent that plans projects end-to-end, maintains state in an external task manager, and can work through a backlog without manual task decomposition.

Production-readiness: Active (576 GitHub stars, 6 contributors, last pushed October 2025, Apache-2.0 license).

Differs from seeds: Closest to claude-flow (Archetype 3 — MCP-anchored toolserver with external state); Clean-Coder-AI uses Todoist + optional RAG vector store as external state (rather than SQLite), and LangGraph as the orchestration runtime (rather than a custom MCP server). Unlike claude-flow's hive-mind consensus, Clean-Coder-AI uses a strictly hierarchical Manager → Planner/Executor pipeline.

01

Overview

Clean-Coder-AI — Overview

Origin

Grigorij Dudnik, an independent developer, created Clean-Coder-AI as a 2-in-1 AI Developer + Project Manager. The framework uses LangGraph for orchestration and integrates with Todoist for persistent task management. It is Apache-2.0 licensed and actively maintained.

Philosophy

Clean-Coder-AI is built on the premise that AI-assisted development requires external state management beyond the conversation context window. By storing all project tasks in Todoist, the system can persist across sessions, be inspected by humans via the Todoist UI, and be updated by both the AI and the developer.

The framework emphasizes code quality through DRY principles and udiff-format code changes. Prompts explicitly instruct: "If you're unsure how to implement a given task, don't improvise. Simply state that you don't know."

Manifesto-style quotes (verbatim from prompts)

From manager_system.prompt:

"You are seasoned scrum-master that plans future tasks for a programmer. You need to plan the work task by task in proper order. When you unsure how some feature need to be implemented, ask human. Make good file research before creating a task to understand how to implement task the best and to describe it in all details. Avoid creating flaky tasks, where it's unclear how to do task and if it is needed at all."

From planner_system.prompt:

"If you're unsure how to implement a given task, don't improvise. Simply state that you don't know. Assuming is not allowed - just tell 'please provide me with more files' when needed."

Design Choices

  • LangGraph state machines for each agent (not a monolithic AI loop)
  • Todoist API as persistent project task store — survives context window limitations
  • RAG vector store (optional) for large codebase file description lookup
  • Multi-intelligence LLM routing: high-intelligence for planner, medium for manager/executor, mini for file controller
  • Docker-based isolation via docker-compose.yml for sandboxed code execution
  • Frontend feedback agent with screenshot analysis (Playwright + vision)
02

Architecture

Clean-Coder-AI — Architecture

Distribution

GitHub repo + pip/requirements.txt. Python package, no PyPI release. Install via clone + pip install.

Install

git clone https://github.com/Grigorij-Dudnik/Clean-Coder-AI
cd Clean-Coder-AI
pip install -r requirements.txt
# Configure .env with API keys (Todoist, OpenAI/Anthropic/OpenRouter, etc.)
python manager.py  # Start project manager
# OR
python single_task_coder.py  # Run single-task coder

Directory Tree

Clean-Coder-AI/
├── manager.py                    # Entry point: project manager + Todoist integration
├── single_task_coder.py          # Single task coder pipeline entry point
├── docker-compose.yml            # Sandboxed execution environment
├── .env.template                 # Environment configuration template
├── Makefile                      # Build/run helpers
├── requirements.txt
└── src/
    ├── agents/
    │   ├── planner_agent.py      # LangGraph planner (high intelligence)
    │   ├── executor_agent.py     # LangGraph executor (medium intelligence)
    │   ├── debugger_agent.py     # LangGraph debugger
    │   ├── researcher_agent.py   # LangGraph file researcher
    │   ├── file_answerer.py      # File Q&A subagent
    │   ├── doc_harvester.py      # Documentation harvester
    │   └── frontend_feedback.py  # Screenshot + browser feedback agent
    ├── prompts/
    │   ├── manager_system.prompt
    │   ├── planner_system.prompt
    │   ├── executor_system.prompt
    │   ├── debugger_system.prompt
    │   ├── researcher_system.prompt
    │   ├── researcher_file_answerer.prompt
    │   ├── planner_logic_pseudocode.prompt
    │   ├── planner_files_controller.prompt
    │   ├── planner_finalizer.prompt
    │   ├── frontend_feedback.prompt
    │   ├── manager_progress.prompt
    │   ├── binary_ranker.prompt
    │   ├── describe_files.prompt
    │   ├── describe_file_chunks.prompt
    │   └── actualize_progress_description.prompt
    ├── tools/
    ├── linters/
    └── utilities/

Required Runtime

  • Python >= 3.10
  • Docker (optional, for sandboxed execution)
  • Todoist account + API key
  • OpenAI/Anthropic/OpenRouter API key (multi-model routing supported)
  • Optional: Ollama for local models

Target AI Tools

Standalone Python runtime — not a Claude Code plugin. Integrates with: Anthropic Claude, OpenAI GPT, OpenRouter, Ollama, local models via LangChain.

Config Files

  • .env (created from .env.template) — all API keys
  • .clean_coder/ — project-specific state directory created at runtime
03

Components

Clean-Coder-AI — Components

Agents (LangGraph state machines)

Agent File Purpose LLM Tier
Manager manager.py Orchestrates project — creates/reorders Todoist tasks, executes task pipeline Medium
Planner planner_agent.py Plans implementation with udiff code changes, file research High
Executor executor_agent.py Applies code changes from plan, interacts with filesystem Medium
Debugger debugger_agent.py Diagnoses and fixes bugs iteratively Medium
Researcher researcher_agent.py Searches codebase for relevant files Medium
File Answerer file_answerer.py Answers questions about file content Medium
Doc Harvester doc_harvester.py Harvests external documentation Medium
Frontend Feedback frontend_feedback.py Screenshot analysis + Playwright browser feedback Medium

Prompt Files (15 total)

Prompt Purpose
manager_system.prompt Scrum-master persona — task planning
manager_progress.prompt Progress description actualization
planner_system.prompt Senior programmer persona — udiff planning
planner_logic_pseudocode.prompt Logic planning with pseudocode
planner_files_controller.prompt File selection control
planner_finalizer.prompt Plan finalization
executor_system.prompt Code execution instructions
debugger_system.prompt Debugging instructions
researcher_system.prompt File research instructions
researcher_file_answerer.prompt File Q&A instructions
frontend_feedback.prompt Browser feedback instructions
binary_ranker.prompt Binary relevance ranking
describe_files.prompt File description for RAG indexing
describe_file_chunks.prompt Chunk-level description
actualize_progress_description.prompt Progress update instructions

Tools

  • Todoist API tools: add_task, modify_task, finish_project_planning, reorder_tasks
  • Filesystem tools: prepare_list_dir_tool, prepare_see_file_tool, prepare_create_file_tool, prepare_replace_code_tool, prepare_insert_code_tool
  • Semantic search: retrieve_files_by_semantic_query (RAG/vector store)
  • Vision: see_image (screenshot analysis)
  • Human-in-loop: ask_human_tool

External Integrations

  • Todoist — persistent task store (required)
  • RAG/Vector Store — optional, for large codebases
  • Playwright — optional, for browser feedback
  • Docker — optional, for sandboxed execution via docker-compose.yml
05

Prompts

Clean-Coder-AI — Prompts

Excerpt 1: manager_system.prompt (verbatim)

File: src/prompts/manager_system.prompt Technique: Scrum-master role injection with anti-hallucination constraints. Forces task specificity and human escalation when uncertain.

You are seasoned scrum-master that plans future tasks for a programmer. You need to plan the work task by task in proper order.
When you unsure how some feature need to be implemented, ask human.

Make good file research before creating a task to understand how to implement task the best and to describe it in all details.

Tasks you are creating are always very concrete and concise, showing programmer how he can implement the change. If you unsure which technologies to use, ask human first.
Avoid creating flaky tasks, where it's unclear how to do task and if it is needed at all.

- Never make up information when describing task. Ask human or make file research to get more info instead.
- Never write code inside of task description.
- If you don't know how exactly task should be done - again, do not make it up. Instead, ask programmer in description to figure it out.

Here is description of changes in the project you work on:
'''
{project_plan}
'''
Some of the changes may be already implemented, some not.

Some important project informations and rules:
'''
{project_rules}
'''

Excerpt 2: planner_system.prompt (verbatim)

File: src/prompts/planner_system.prompt Technique: Senior programmer persona + udiff format enforcement + anti-hallucination constraint (explicit "I don't know" is acceptable). Note: DRY principle hard-wired, code snippets must be in udiff format.

You are a senior programmer AI agent tasked with planning and detailing code modifications for a given project. Your primary goal is to provide a clear, step-by-step plan for implementing the requested changes while adhering to the project's rules and best coding practices.

First, familiarize yourself with the file contents you have access to:

<file_contents>
{file_contents}
</file_contents>

Now, review the project rules:

<project_rules>
{project_rules}
</project_rules>

Instructions:

1. Draft a detailed modification plan, based on previous plan and user instructions:
   - Follow the DRY (Don't Repeat Yourself) principle.
   - Use meaningful variable names.
   - Write concise code. Try to keep it simple and short when possible.

2. Format code snippets in your plan properly:
   In your code snippets, follow udiff format with filename we working on in the header. For each code modification, use the following structure:

   ```filename.extension
   - line_to_remove
   + line_to_add
   unchanged_line
   + another_line_to_add

Only include the functions you want to replace, not the entire file content.

Remember:

  • If you're unsure how to implement a given task, don't improvise. Simply state that you don't know.
  • Assuming is not allowed - just tell "please provide me with more files" when needed.
  • Previous plan proposition have not been implemented. Always reference your code changes to code files you have in the context, not to the previous plan proposition.
09

Uniqueness

Clean-Coder-AI — Uniqueness

Differs from Seeds

Closest to claude-flow (Archetype 3 — MCP-anchored toolserver with external state) but implemented as a standalone Python LangGraph process rather than an MCP server. Clean-Coder-AI's most distinctive feature is Todoist as external state store: unlike claude-flow's SQLite/HNSW memory or taskmaster-ai's tasks.json, Todoist is a human-facing project management UI that both AI and developer can read and modify — creating a collaborative state layer. The LangGraph multi-agent architecture is more explicit and inspectable than claude-flow's hive-mind pattern. Compared to taskmaster-ai, Clean-Coder-AI fully generates and manages its own task backlog (the Manager creates Todoist tasks from scratch), whereas taskmaster-ai requires the developer to seed tasks. The frontend feedback agent with screenshot vision is a unique capability not seen in any of the 11 seed frameworks.

Positioning

Clean-Coder-AI positions itself as a fully autonomous developer — "AI agents plan an entire project in Todoist and code it task by task." This is a higher autonomy bar than most frameworks: the AI both generates the project plan AND executes it.

Distinctive Opinion

udiff format enforcement in planner prompts is architecturally deliberate — by requiring all code changes in udiff format, the Planner stage produces a diff that the Executor can apply precisely, reducing the chance of the Executor misinterpreting natural-language instructions.

Observable Failure Modes

  1. Todoist dependency: Requires a Todoist account and API key; the entire project state tracking breaks without it
  2. Plan review is blocking: The human-in-loop plan review gate means the system cannot fully run autonomously without human approval — contradicting the "autonomous" framing
  3. Context management: Despite cut_off_context(), long-running projects may still hit limits
  4. Multi-model cost: Using high-intelligence models for Planner can be expensive at scale
  5. No TDD: No test-first enforcement — code is implemented and debugged reactively
04

Workflow

Clean-Coder-AI — Workflow

Entry Points

Two modes:

  1. Full Project Mode (python manager.py) — Manager orchestrates entire project from backlog
  2. Single Task Mode (python single_task_coder.py) — Direct single-task coder pipeline

Full Project Workflow

Phase Agent Action Artifact
Project Setup Manager User provides project description, Manager creates Todoist tasks Todoist task list
File Indexing Doc Harvester Indexes codebase files for RAG lookup Vector store
Task Execution Loop Manager Reads next Todoist task, dispatches to coder pipeline
Planning Planner Researches files, creates udiff change plan Plan with udiff patches
Review Gate Human Planner presents plan, waits for approval Approved/revised plan
Execution Executor Applies udiff patches from plan Modified source files
Debug (if needed) Debugger Diagnoses failures, iterates until tests pass Fixed source files
Task Completion Manager Marks Todoist task complete, moves to next Updated Todoist

Approval Gates

  1. Plan Review: Planner presents plan to human before Executor applies changes
  2. Human Help: Any agent can call ask_human_tool when blocked
  3. Loop Break: Agents have loop-detection logic; if looped, escalate to human

Artifacts Per Phase

Phase Artifact
Planning udiff-format implementation plan (in conversation)
Execution Modified source files
Task Tracking Todoist tasks (created/modified/completed)
State .clean_coder/ directory with manager messages JSON

FAST vs SLOW Mode

Not applicable (Clean-Coder-AI doesn't have project speed modes; it is always thorough).

06

Memory Context

Clean-Coder-AI — Memory & Context

Primary State Store: Todoist

All project tasks are stored in Todoist — an external, persistent task manager. This is the framework's most distinctive memory mechanism: tasks survive context window limits and can be inspected/modified by humans via the Todoist UI.

Secondary State: .clean_coder/ directory

Created at runtime in the project working directory:

  • manager_messages.json — serialized LangGraph message history for the Manager agent (persisted to disk after each turn)
  • Other session state files

RAG Vector Store (optional)

File descriptions are indexed into a vector store for semantic retrieval. The prompt_index_project_files() call indexes the codebase at startup. The retrieve_files_by_semantic_query tool queries the vector store to find relevant files for a given task.

Context Compaction

Handled via LangGraph message history management: the Manager agent has a cut_off_context() method that trims old messages when context grows too large.

Cross-Session Handoff

Yes — Todoist tasks persist; manager messages are saved to .clean_coder/manager_messages.json and reloaded at startup via get_manager_messages().

Memory Persistence Level

Project-scoped (.clean_coder/) + external global (Todoist account).

Search Mechanism

Vector search (RAG) for file content lookup.

State Files

  • .clean_coder/manager_messages.json — LangGraph message state
  • Todoist project (external) — task list

Multi-LLM Routing for Memory Tasks

  • High intelligence models: Planner (complex reasoning)
  • Medium intelligence: Manager, Executor, Debugger
  • Mini models: File Controller (fast/cheap file selection)
07

Orchestration

Clean-Coder-AI — Orchestration

Multi-Agent

Yes. Clean-Coder-AI uses a hierarchical multi-agent pipeline built on LangGraph.

Agent Hierarchy

Manager (LangGraph)
├── Planner (LangGraph)
│   ├── Files Controller (mini LLM)
│   ├── Logic Planner (high LLM)
│   └── Plan Finalizer (medium LLM)
├── Executor (LangGraph)
├── Debugger (LangGraph)
├── Researcher (LangGraph)
│   └── File Answerer (LangGraph)
├── Doc Harvester (LangGraph)
└── Frontend Feedback (LangGraph + Playwright)

Orchestration Pattern

Hierarchical. Manager dispatches to Planner → Executor pipeline. Debugger is invoked on failures.

Spawn Mechanism

Subprocess / direct Python function calls. Manager instantiates agent classes and calls their run() methods.

Execution Mode

Continuous. Manager runs in a loop reading Todoist tasks and dispatching the coder pipeline until all tasks are complete or human intervention is needed.

Isolation Mechanism

Optional Docker container (docker-compose.yml) for sandboxed code execution. Without Docker, code runs in-place.

Multi-Model

Yes. Three LLM tiers:

  • High intelligence: init_llms_high_intelligence() — used by Planner
  • Medium intelligence: init_llms_medium_intelligence() — used by Manager, Executor, Debugger
  • Mini: init_llms_mini() — used by File Controller

Default models (via OpenRouter): Claude Sonnet 4 (medium), GPT-4.1 (medium fallback), configurable. All tiers support fallback chains: if primary LLM fails, next in list is tried.

Supports BYOK

Yes. Supports OpenAI, Anthropic, OpenRouter, Ollama, local models — configured via .env.

Consensus Mechanism

None. Strictly hierarchical.

Prompt Chaining

Yes. Manager creates Todoist tasks with descriptions → Planner reads task → produces udiff plan → Executor consumes plan. One stage's output is the next stage's input.

Crash Recovery

Partial. Manager messages saved to disk after each turn. If process crashes, it can reload from .clean_coder/manager_messages.json.

Context Compaction

Yes. cut_off_context() method trims Manager message history when it grows too large.

08

Ui Cli Surface

Clean-Coder-AI — UI / CLI Surface

CLI Binary

No dedicated binary. Entry points are Python scripts:

  • python manager.py — full project mode
  • python single_task_coder.py — single task mode

Local UI

None (no web dashboard). However, Todoist serves as a human-readable UI for viewing and managing project tasks — giving humans a visual interface to the task state that the AI manages programmatically.

IDE Integration

None. Clean-Coder-AI is a standalone Python process, not a Claude Code plugin or IDE extension.

Terminal Interactions

Clean-Coder-AI prints formatted output to the terminal (using print_formatters.py) with colored text and ASCII art logo at startup.

Observability

  • Todoist task list: Human-inspectable project task state (real-time)
  • .clean_coder/manager_messages.json: Serialized LangGraph message history
  • LangSmith (optional): LangGraph tracing for debugging agent execution

Frontend Feedback Agent

The frontend_feedback.py agent provides a unique observability feature — it can take browser screenshots and analyze UI state to provide feedback on frontend implementations, using vision models to "see" the rendered application.

Makefile

Standard dev commands via make:

  • make / make run — start manager
  • Other developer utilities

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k
A6 Multi-agent orchestrator

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k
A6 Multi-agent orchestrator

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k
A6 Multi-agent orchestrator

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k
A6 Multi-agent orchestrator

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k
A6 Multi-agent orchestrator

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k
A6 Multi-agent orchestrator

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…