Skip to content
/
Tier A A4 Markdown scaffold

FlowCoder

flowcoder · px-pride/flowcoder · ★ 26 · last commit 2026-05-22

Build complex multi-step autonomous agent workflows visually via a flowchart builder — no orchestration code required.

Best whenAgent responses should be typed structured JSON, not raw text — typed outputs enable programmatic conditional branching in visual workflows.
Skip ifWriting orchestration code (use the visual builder instead), Using interactive mode for CI/CD (use --flowchart CLI flag)
vs seeds
claude-flowin orchestration complexity (sequential + looping + composition) but FlowCoder defines workflows as JSON DAGs in a Tkint…
Primitive shape 5 total
Commands 5
00

Summary

FlowCoder — Summary

FlowCoder (px-pride/flowcoder) is a Python + Tkinter web application that provides a visual flowchart builder for creating custom automated workflows for Claude Code (and Codex via proxy). Users construct workflows by connecting typed blocks (Start, Prompt, Bash, Variable, Branch, Command, Refresh, Cast, End) on a canvas, save them as JSON slash commands, and execute them against isolated Claude Code sessions. The key innovation is visual conditional loop construction: a Branch block evaluates agent output fields and follows True/False paths, enabling retry-until-done patterns, test-fix loops, and N-iteration improvement cycles without writing any orchestration code. FlowCoder auto-commits after each executed block and supports pause/resume/stop/force-stop execution control per session. Session data persists to ~/.flowcoder/sessions.json.

Differs from seeds: closest to claude-flow (multi-step orchestration, sequential + looping patterns) but FlowCoder is visual-first — workflows are defined as JSON DAGs in a GUI rather than slash-commands or skill markdown. Unlike claude-flow's hive-mind consensus and multi-agent patterns, FlowCoder is single-agent with explicit flowchart-driven orchestration that a non-programmer can construct.

01

Overview

FlowCoder — Origin and Philosophy

Origin

Author: px-pride (GitHub). 26 stars, 2 forks. Created December 2025. Python, MIT license. Last push May 2026. Single contributor.

Philosophy

FlowCoder's description: "Visual autonomous workflows for Claude Code and Codex."

The README opens with a YouTube demo video, suggesting the audience is visual thinkers who find JSON/markdown workflow definitions opaque. The core philosophy is:

Visual workflow composition over code: Users drag and connect blocks on a canvas. No programming knowledge required to build complex retry loops, conditional branches, or multi-step agents.

Structured output as workflow logic: Prompt blocks extract structured JSON from the agent (via output_schema), which Branch blocks then evaluate. This turns agent outputs into typed variables that drive workflow branching — a key design decision that separates FlowCoder from prompt-chaining frameworks that pass raw text.

Example Commands Philosophy: The repo ships 5 example flowcharts (ex0 through ex3 + all-examples) demonstrating increasing complexity. From the README:

"It is recommended you understand how they work by reviewing them in the Commands tab"

The examples progress from simple design-doc generation (ex0) to full implement-audit-loop (ex2) to N-iteration improvement cycles with nested command calls (ex3).

Codex/GPT Model Support

FlowCoder supports non-Claude models via anthropic-proxy-rs (an external Rust proxy that translates Anthropic API calls to OpenAI Chat Completions API). When creating a session the user picks "Codex" backend — under the hood it still spawns the claude binary but with ANTHROPIC_BASE_URL and ANTHROPIC_MODEL set to route through the proxy.

02

Architecture

FlowCoder — Architecture

Distribution

Clone + Python dependency install:

uv sync
npm install
uv run python -m src.main

Required Runtime

  • Python 3.12+
  • uv (Python package manager)
  • Node.js 18+
  • Claude Code CLI (for agent execution)
  • Optionally: anthropic-proxy-rs for Codex/GPT model support

Directory Structure

px-pride/flowcoder/
├── src/
│   ├── main.py            # Entry point; GUI or CLI mode dispatch
│   ├── adapters/          # Claude Code / Codex adapters
│   ├── cli/               # Terminal-based CLI agent mode
│   ├── controllers/       # MVC controllers
│   ├── exceptions/
│   ├── models/            # Session, flowchart, block models
│   ├── services/          # Execution engine, git integration
│   ├── utils/
│   ├── validators/
│   ├── views/             # Tkinter GUI views
│   └── widgets/           # Custom Tkinter widgets
├── commands/              # Saved flowchart JSON files
│   ├── ex0-design-doc.json
│   ├── ex1-do-until-done.json
│   ├── ex2-testing-loop.json
│   ├── ex3-improve-project.json
│   └── all-examples.json
├── packages/              # Node.js packages (canvas libs)
├── pyproject.toml
└── package.json

GUI vs CLI Mode

GUI mode (default): uv run python -m src.main — launches Tkinter desktop application

CLI agent mode: uv run python -m src.main cli --cwd <dir> --service claude --flowchart <cmd> [args] — non-interactive execution of a flowchart command

Sessions

Session data persists to ~/.flowcoder/sessions.json. Each session has: name, working directory, git remote settings, execution history. Multiple sessions supported but cannot run simultaneously (architectural issue leading to memory leaks — disabled as of repo analysis date).

Git Integration

Automatically initializes a git repo in each session's working directory. Commits after each Prompt or Bash block finishes. Commit labels include block type and name. Optional: git remote URL, branch, auto-push.

03

Components

FlowCoder — Components

Block Types

Block Purpose
Start Entry point (required)
Prompt Send prompt to Claude Code; capture structured output via JSON schema
Bash Execute shell commands
Variable Set a variable to a value
Branch Conditional branching; True path (black arrow) / False path (blue arrow, Ctrl+drag)
Command Invoke another saved flowchart command (enables composition)
Refresh Restart the Claude session (context reset)
Cast Convert variable types
End Exit point

Branch Condition Syntax

Format Example
field == value status == "done"
field != value count != 0
field > value score > 80
field isComplete (truthy check)
!field !hasErrors (negated boolean)

Saved Commands (JSON in commands/)

File Purpose
ex0-design-doc.json Simple prompt to generate a design doc; argument substitution
ex1-do-until-done.json Loop: implement design doc → check fullyImplemented → retry until done
ex2-testing-loop.json Write test suite → run tests via bash → diagnose/fix loop
ex3-improve-project.json For-loop N iterations: design feature → run ex1 → run ex2
all-examples.json Execute all 4 examples sequentially

CLI Subcommands

From src/main.py argument parser:

python -m src.main [--debug]
python -m src.main cli [--cwd] [--service claude|codex|mock] [--model] 
                       [--system-prompt|--no-system-prompt] [--session-name]
                       [-f/--flowchart <cmd> [args]]

Session Control Buttons

Button Behavior
Halt Pause execution after current block
Resume Continue from halted state
Stop Stop after current block; terminate agent
Force Stop Immediately terminate (may leave work incomplete)
Refresh Stop + fresh agent instance
05

Prompts

FlowCoder — Prompts

Prompt 1: ex1-do-until-done — IMPLEMENT block

Technique: Argument substitution ($1), conditional context injection ("if file exists"), structured output schema to produce typed boolean.

{
  "type": "prompt",
  "name": "IMPLEMENT",
  "prompt": "Fully implement ./design_docs/$1, and document your progress in ./progress-reports/PROGRESS_FOR_$1\n\nIf ./audits/AUDIT_FOR_$1 exists, it means that the task has been partially implemented already but has issues.\n\nMake sure you include a README.md for the end user explaining how to launch and use the program.\n\nWhen you're done working, answer this question: has  ./design_docs/$1 been fully implemented?",
  "output_schema": {
    "type": "object",
    "properties": {
      "fullyImplemented": {
        "type": "boolean"
      }
    },
    "required": ["fullyImplemented"]
  }
}

The Branch block then evaluates fullyImplemented to route True → END or False → KEEP GOING.

Prompt 2: ex2-testing-loop — design

Technique: Two-pass loop. First pass writes test suite. Second pass runs tests via Bash block. Branch checks test results. Fix loop sends agent back to diagnose.

From README description:

"The flowchart for that slash command will begin executing. When it finishes, you'll see 'Execution completed: ex2-testing-loop' in the Output section."

The ex2-testing-loop.json command structure:

  1. START
  2. WRITE_TESTS (Prompt block) — writes test suite fitting the design document
  3. RUN_TESTS (Bash block) — npm test or equivalent
  4. TESTS_PASSING (Branch) — evaluates bash exit code or test output field
  5. True → END; False → DIAGNOSE (Prompt) → RUN_TESTS → loop

Key Prompting Technique: Structured Output Extraction

The most distinctive prompt pattern in FlowCoder: structured output schema on Prompt blocks. The agent is asked to answer a yes/no question or return a JSON field, which the Branch block then uses for conditional routing. This converts natural language agent responses into typed variables for programmatic workflow control.

09

Uniqueness

FlowCoder — Uniqueness and Positioning

Differs from Seeds

No seed uses a visual flowchart builder. The closest seed in terms of orchestration complexity is claude-flow (multi-step orchestration, sequential + looping patterns) but claude-flow defines workflows in TypeScript/JSON skill files and MCP tools, not a visual canvas. FlowCoder's distinctive differences:

  1. Visual workflow composition: blocks dragged onto a canvas, connections drawn by mouse. No code required to build complex loops.
  2. Structured output schema on Prompt blocks: agent responses are typed JSON, not raw text — enabling programmatic branch conditions (fullyImplemented == true).
  3. Tkinter desktop application: the only seed/near-seed that ships as a native Python GUI desktop app (not a web dashboard, not a TUI, not a VSCode extension).
  4. Auto-commit per block: git commits happen atomically per block execution, not per task. Creates a fine-grained execution timeline.
  5. Composition via Command blocks: flowcharts can invoke other flowcharts, enabling hierarchical composition without any code.

Compared to openspec (11 commands + 11 skills, sequential flow): openspec is markdown-based and text-driven; FlowCoder is visual and data-driven.

Positioning

FlowCoder targets developers who think in flowcharts rather than code, or who want to build reusable multi-step agent workflows without writing orchestration logic. The visual editor makes branching and looping legible — a non-programmer can understand what /ex2-testing-loop does by looking at the canvas.

Observable Failure Modes

  1. Single-session constraint: multiple sessions cannot run simultaneously (memory leak architectural issue). Limits concurrency.
  2. Structured output fragility: Branch conditions depend on the agent reliably returning valid JSON matching output_schema. If the agent returns malformed output, the branch cannot evaluate.
  3. Context accumulation: long workflows (many Prompt blocks) accumulate context without a compaction strategy. The Refresh block is manual.
  4. Tkinter portability: Tkinter rendering varies across platforms. Windows/Linux users may see different layouts.
  5. Proxy dependency for GPT models: Codex/GPT support requires running anthropic-proxy-rs separately — an external Rust service not managed by FlowCoder.
04

Workflow

FlowCoder — Workflow

Phases

Phase Trigger Artifact
1. Session creation New Session in Agents tab Session entry in ~/.flowcoder/sessions.json
2. Command creation New Command in Commands tab JSON flowchart in commands/<name>.json
3. Block construction Drag blocks onto canvas Flowchart DAG
4. Execution Run / CLI --flowchart <cmd> Claude Code output per block
5. Auto-commit After each Prompt/Bash block Git commit: [block-type] block-name
6. Session review Chat panel + flowchart canvas Execution trace

Approval Gates

No explicit approval gates. Execution is fully autonomous once started. The Halt button is a manual pause, not a gate.

Key Workflow Patterns (from example commands)

Pattern 1: Do-Until-Done Loop (ex1-do-until-done.json):

START → IMPLEMENT (prompt) → DONE? (branch, field: fullyImplemented)
  True path → END
  False path → KEEP GOING (prompt) → loop back to DONE?

Pattern 2: Test-Fix Loop (ex2-testing-loop.json):

START → WRITE_TESTS (prompt) → RUN_TESTS (bash) → PASSING? (branch)
  True path → END
  False path → DIAGNOSE_AND_FIX (prompt) → RUN_TESTS (bash) → loop

Pattern 3: For-Loop (ex3-improve-project.json):

START → SET_COUNTER → LOOP_CONDITION (branch, count < N)
  False path → END
  True path → DESIGN_FEATURE (prompt) → INVOKE ex1 (command) → INVOKE ex2 (command)
           → INCREMENT_COUNTER → LOOP_CONDITION

Prompt Chaining

Yes — one block's output_schema fields become variables injected into subsequent blocks via {{variable_name}} substitution. This is explicit prompt chaining: structured output → variable → next prompt.

Example Verbatim (ex1-do-until-done.json IMPLEMENT block)

"prompt": "Fully implement ./design_docs/$1, and document your progress in ./progress-reports/PROGRESS_FOR_$1\n\nIf ./audits/AUDIT_FOR_$1 exists, it means that the task has been partially implemented already but has issues.\n\nMake sure you include a README.md for the end user explaining how to launch and use the program.\n\nWhen you're done working, answer this question: has ./design_docs/$1 been fully implemented?",
"output_schema": {
  "type": "object",
  "properties": {
    "fullyImplemented": { "type": "boolean" }
  },
  "required": ["fullyImplemented"]
}
06

Memory Context

FlowCoder — Memory and Context

State Storage

Session data

  • File: ~/.flowcoder/sessions.json
  • Content: session name, working directory, git remote settings, execution history
  • Persistence: global (all sessions)

Git repository (per session)

  • Each session has its own working directory with a git repo
  • Auto-commits after each Prompt/Bash block create a git history of the execution
  • This git log IS the execution audit trail

In-memory execution state

  • Variable values (set by Variable/Prompt blocks) — in-memory only during execution
  • Not persisted across sessions (stateless restart)

Context Reset (Refresh block)

The Refresh block stops the Claude Code agent process and starts a fresh instance. This resets the agent's context window — useful for multi-stage workflows where later stages should not be confused by earlier stage context.

No External Memory

FlowCoder has no vector DB, no sqlite memory store, no CLAUDE.md injection. The agent's context is whatever Claude Code has in its session window. The Refresh block is the only explicit context management primitive.

Cross-Session Handoff

Limited. Session metadata persists (name, working directory, git settings) but variable state does not. Workflows must be re-run from start; the git history provides a record of past work but the agent does not automatically load it.

07

Orchestration

FlowCoder — Orchestration

Multi-Agent

No — single agent per session. Multiple sessions are supported but cannot run simultaneously (architectural memory leak issue, disabled).

Orchestration Pattern

Sequential with explicit branching and looping — a flowchart DAG where:

  • Nodes are execution blocks (Prompt, Bash, Branch, etc.)
  • Edges are execution flow
  • Branch blocks implement conditional routing (if/else)
  • Back-edges from later blocks to earlier blocks implement retry loops
  • Command blocks enable composition (invoke another flowchart as a sub-workflow)

This is not task-decomposition-tree (no task graph), not hierarchical (no sub-agents), not parallel — it is sequential with deterministic branching.

Execution Mode

Interactive loop with pause/resume capability. The GUI shows execution progress on the canvas in real time. The CLI mode (--flowchart) is one-shot/non-interactive.

Isolation

None — the agent works in-place in the session's working directory. Git commits after each block provide a checkpoint, but there is no worktree isolation or sandboxing.

Multi-Model

Limited: same flowchart can target Claude Code or Codex (via proxy). Not true multi-model routing — it's session-level model selection, not within-workflow routing.

Git Automation

Yes — auto-commits after each Prompt/Bash block. Optional auto-push to remote. Commit messages include block type and name.

08

Ui Cli Surface

FlowCoder — UI and CLI Surface

Local Desktop Application

Type: Tkinter desktop application (Python GUI framework)

Launch: uv run python -m src.main

Key UI Tabs:

  • Sessions (Agents tab) — create/select sessions; shows agent status; Halt/Resume/Stop/Force Stop/Refresh buttons
  • Commands tab — browse, create, edit saved flowchart commands
  • Chat panel — shows Claude Code output for active session
  • Canvas — flowchart visualization with draggable blocks; execution progress shown in real-time; block palette on side

Tech Stack: Python Tkinter + custom Tkinter widgets + Node.js (canvas-related packages in packages/)

No web server. No browser required. Native desktop window.

CLI Mode

uv run python -m src.main cli \
  --cwd /path/to/workdir \
  --service claude \
  --flowchart ex1-do-until-done DESIGN_DOC.md

Non-interactive: executes flowchart and exits. Suitable for CI/CD or scripted automation.

Observability

  • Chat panel: real-time Claude Code output
  • Canvas: block execution state shown on canvas (active block highlighted)
  • Output section: "Execution completed: " messages
  • Git log: auto-commits provide execution timeline in git log
  • Session history: ~/.flowcoder/sessions.json stores session metadata

No Web Dashboard

No localhost web server. No browser UI. Tkinter only.

No MCP Servers

No MCP integration.

Related frameworks

same archetype · same primary tool · same memory type

BMAD-METHOD ★ 48k
A4 Markdown scaffold

Provides a full agile delivery lifecycle with named expert-persona AI collaborators that elicit the human's best thinking rather…

Agent OS ★ 4.6k
A4 Markdown scaffold

Extracts implicit codebase conventions into token-efficient markdown standards files and injects them selectively into AI agent…

Claude Conductor ★ 367
A4 Markdown scaffold

Gives Claude Code a persistent, cross-linked, auto-analyzed documentation system so it retains codebase context across sessions.

Spec-Driver (Greenfield Spec-Driven Development) ★ 25
A4 Markdown scaffold

Prevents spec rot in AI-assisted development by making implementation changes flow back into evergreen, authoritative specs via…

Anthropic Knowledge Work Plugins ★ 16k
A4 Markdown scaffold

Role-specialized plugin bundles with live MCP connectors that turn Claude into a domain expert for enterprise knowledge workers.

Codex Integration for Claude Code (skill-codex) ★ 1.3k
A4 Markdown scaffold

Single Claude Code skill that handles Codex CLI invocation correctly (stdin blocking, thinking token suppression, session resume)…