Skip to content
/
Tier A A12 UI passthrough

cline-max (theogbrand)

cline-max · theogbrand/cline-max · ★ 4 · last commit 2025-02-27

VS Code extension fork that adds Plan/Act mode separation to enforce architecture-before-code discipline.

Best whenThe planning gate should be enforced at tool-availability level (planning tools unavailable in Act, write tools unavailable in Plan), not just via prompt ins…
Skip ifWriting code before a plan is agreed upon, Switching to Act Mode before the user is satisfied with the plan
vs seeds
superpowers' skill activation. Predates the broader spec-driven development movement; now superseded by native Plan/Act mode in ups…
Primitive shape
No installable primitives
00

Summary

cline-max — Summary

cline-max is a full fork of the Cline VS Code extension (the popular open-source AI coding assistant, formerly Claude Dev) with a specific focus on introducing a Plan/Act two-mode architecture before spec-driven development became mainstream in AI coding tools. The fork adds an explicit planning mode (plan_mode_response tool) that allows the AI to architect solutions and ask clarifying questions without executing any code — the user manually toggles from Plan to Act mode when satisfied with the proposed approach. The codebase is a complete TypeScript/React extension (~50k+ lines) with full VS Code integration: webview UI, terminal integration, browser automation (Puppeteer), MCP support, and multi-model routing via OpenRouter, Anthropic, OpenAI, Google Gemini, and others. Importantly, the repository description explicitly states "fork of Cline, before spec-driven development became a thing" — framing it as an early experiment in structured AI coding workflows.

differs_from_seeds: This framework does not match any seed cleanly because it is a full IDE extension fork, not a prompt/configuration layer. The closest archetype is kiro (Archetype 5 — closed IDE with proprietary primitives) except cline-max is an open-source VSCode extension fork rather than a proprietary IDE. The plan_mode_response tool is functionally similar to kiro's spec workflow (architect before code), but implemented as a togglable mode in a VS Code extension. Unlike agent-os or superpowers (which augment an existing AI tool), cline-max IS the AI tool. The framework predates kiro's spec format but shares the same philosophical root: prevent the AI from coding until a plan has been reviewed and approved.

01

Overview

cline-max — Overview

Origin

Fork of cline/cline by GitHub user theogbrand. The upstream Cline extension is the #1 extension on OpenRouter with ~millions of downloads. The fork was created circa early 2025, before "spec-driven development" was a widely-used phrase in AI coding tooling.

Philosophy

"fork of Cline, before spec-driven development became a thing"

The author's core insight was that an AI coding agent should have two distinct operational modes:

  1. Plan Mode: The agent gathers information, asks questions, and architects a solution — without writing any code. The agent uses plan_mode_response to engage in conversational back-and-forth.
  2. Act Mode: The agent executes the agreed-upon plan by actually modifying files and running commands.

The manual toggle between modes forces a checkpoint: the human must consciously decide when planning is done and implementation should begin.

System Prompt Philosophy

From src/core/prompts/system.ts:

"You are Cline, a highly skilled software engineer with extensive knowledge in many programming languages, frameworks, design patterns, and best practices."

In Plan Mode:

"In this mode you should focus on information gathering, asking questions, and architecting a solution. Once you have a plan, use the plan_mode_response tool to engage in a conversational back and forth with the user. Do not use the plan_mode_response tool until you've gathered all the information you need e.g. with read_file or ask_followup_question."

"(Remember: If it seems the user wants you to use tools only available in Act Mode, you should ask the user to 'toggle to Act mode' (use those words) — they will have to manually do this themselves with the Plan/Act toggle button below. You do not have the ability to switch to Act Mode yourself, and must wait for the user to do it themselves once they are satisfied with the plan.)"

Key Differentiator from Upstream Cline

The Plan/Act mode toggle is the primary addition. The upstream Cline is a pure Act-mode agent by default (it just executes tasks). cline-max adds the planning layer before execution.

Historical Significance

This fork predates cline-spec-kit-workflows and the broader "spec-driven" movement in AI coding, making it an early exploration of the same architectural idea.

02

Architecture

cline-max — Architecture

Distribution

VS Code Extension (TypeScript/React fork of cline/cline). Published to VS Code Marketplace as a fork. Full extension with:

  • Webview UI (React)
  • Backend extension host (TypeScript)
  • Terminal integration
  • Browser automation (Puppeteer)
  • MCP protocol support

Install

Install via VS Code Marketplace (fork version) or clone and build:

git clone https://github.com/theogbrand/cline-max
npm install
npm run build

Directory Tree (Key Paths)

cline-max/
├── src/
│   ├── core/
│   │   ├── Cline.ts              # Main agent loop (~3500+ lines)
│   │   ├── prompts/
│   │   │   └── system.ts         # System prompt with Plan/Act mode logic
│   │   ├── assistant-message/    # Message parsing
│   │   ├── mentions/             # @-mention handling
│   │   └── webview/              # UI bridge
│   ├── api/                      # Multi-model API adapters
│   ├── services/
│   │   └── mcp/McpHub.ts        # MCP server management
│   ├── integrations/             # Terminal, editor, git integrations
│   └── shared/                   # Types, settings
├── webview-ui/                   # React frontend
├── assets/
├── docs/
└── package.json

Key Architectural Feature: Plan/Act Mode

The mode is stored in chatSettings.mode and consulted in Cline.ts at multiple points:

if (this.chatSettings.mode === "plan") {
    // Inject plan mode instructions into system prompt
    // Only plan_mode_response tool is available
}

The plan_mode_response tool is only available in Plan Mode. Act Mode tools (file write, terminal exec) are unavailable in Plan Mode.

Rule File Format

No .cursorrules or .clinerules files. This is a full extension fork — behavioral rules are encoded in:

  • src/core/prompts/system.ts (system prompt)
  • Cline.ts (tool availability logic)
  • Extension settings (persisted to VS Code settings.json)

Target AI Tools

Primary: VS Code (fork of VS Code extension) Multi-model support: OpenRouter, Anthropic, OpenAI, Google Gemini, AWS Bedrock, Azure, GCP Vertex, OpenAI-compatible endpoints, LM Studio/Ollama

Required Runtime

  • Node.js (extension build)
  • VS Code
03

Components

cline-max — Components

Mode: Plan Mode

The central addition over upstream Cline. Activated via Plan/Act toggle button in the UI.

Available tools in Plan Mode:

  • read_file — can gather information
  • ask_followup_question — ask user for clarification
  • plan_mode_response — present plan/conversation back to user (Plan-Mode-only tool)

Unavailable tools in Plan Mode:

  • write_to_file / apply_diff
  • execute_command
  • browser_action

Mode: Act Mode

Full execution mode — all upstream Cline tools available.

Tools:

  • execute_command — run CLI commands
  • read_file — read file content
  • write_to_file — write/overwrite files
  • apply_diff — targeted file patching
  • search_files — regex search
  • list_files — directory listing
  • list_code_definition_names — code structure analysis
  • browser_action — browser automation (Puppeteer)
  • use_mcp_tool — call MCP server tools
  • access_mcp_resource — access MCP resources
  • ask_followup_question — ask user questions
  • attempt_completion — signal task done

plan_mode_response Tool

Unique addition — tool for presenting plans and engaging in conversational back-and-forth without executing code:

case "plan_mode_response":
    // Handles plan presentation to user
    // Does NOT trigger any file modifications or commands

Multi-Model Support (inherited from Cline)

Adapters in src/api/:

  • Anthropic (Claude models)
  • OpenRouter (all models)
  • OpenAI (GPT models)
  • Google Gemini
  • AWS Bedrock
  • Azure OpenAI
  • GCP Vertex
  • OpenAI-compatible (DeepSeek, LLaMA via LM Studio/Ollama)

MCP Support

MCP hub at src/services/mcp/McpHub.ts — connects to any external MCP server configured by user. Tool count is dynamic (user-configured).

Hooks / Scripts

None beyond what upstream Cline provides (VS Code extension event lifecycle). No custom hooks shipped in this fork.

Commands

No custom slash commands. Interaction is purely conversational with Plan/Act mode toggle.

05

Prompts

cline-max — Prompts

Prompt 1: System Prompt (Base Identity)

From src/core/prompts/system.ts:

Technique: Role definition + capability declaration. Standard Cline base prompt.

export const SYSTEM_PROMPT = async (...) => `You are Cline, a highly skilled 
software engineer with extensive knowledge in many programming languages, 
frameworks, design patterns, and best practices.

====

TOOL USE

You have access to a set of tools that are executed upon the user's approval. 
You can use one tool per message, and will receive the result of that tool use 
in the user's response. You use tools step-by-step to accomplish a given task, 
with each tool use informed by the result of the previous tool use.

Technique: Sequential tool use protocol — one tool per message, result-informed next step. This creates a controlled execution loop where the human sees and approves each step.

Prompt 2: plan_mode_response Tool Definition

From src/core/prompts/system.ts:

Technique: Mode-gated tool that prevents code execution during planning phase.

## plan_mode_response
Description: Respond to the user's inquiry in an effort to plan a solution to 
the user's task. This tool should be used when you need to provide a response 
to a question or statement from the user about how you plan to accomplish the 
task. This tool is only available in PLAN MODE. The environment_details will 
specify the current mode, if it is not PLAN MODE then you should not use this 
tool. Depending on the user's message, you may ask questions to get clarification 
about the user's request, architect a solution to the task, and to brainstorm 
ideas with the user. For example, if the user's task is to create a website, 
you may start by asking some clarifying questions, then present a detailed plan 
for how you will accomplish the task given the context, and perhaps engage in 
a back and forth to finalize the details before the user switches you to ACT 
MODE to implement the solution.

Technique: Tool-availability-as-mode-enforcement. By making code-writing tools unavailable in Plan Mode and making plan_mode_response unavailable in Act Mode, the system enforces mode separation at the tool schema level rather than relying on prompt instructions alone.

Prompt 3: Plan Mode System Prompt Addition

From Cline.ts line 3363-3368:

Technique: Dynamic system prompt injection based on current mode state.

if (this.chatSettings.mode === "plan") {
    systemPrompt += 
        "\nIn this mode you should focus on information gathering, asking " +
        "questions, and architecting a solution. Once you have a plan, use " +
        "the plan_mode_response tool to engage in a conversational back and " +
        "forth with the user. Do not use the plan_mode_response tool until " +
        "you've gathered all the information you need e.g. with read_file or " +
        "ask_followup_question."
    systemPrompt += 
        '\n(Remember: If it seems the user wants you to use tools only available ' +
        'in Act Mode, you should ask the user to "toggle to Act mode" (use those ' +
        'words) - they will have to manually do this themselves with the Plan/Act ' +
        'toggle button below. You do not have the ability to switch to Act Mode ' +
        'yourself, and must wait for the user to do it themselves once they are ' +
        'satisfied with the plan.)'
}

Technique: Runtime mode injection — the system prompt is dynamically modified based on the current chatSettings.mode value, creating a behavior-governing constraint that activates only in planning contexts.

09

Uniqueness

cline-max — Uniqueness

differs_from_seeds

cline-max is closest to kiro in the seed taxonomy (Archetype 5 — IDE with proprietary primitives), except it is an open-source VS Code extension rather than a proprietary IDE. The core innovation is the Plan/Act mode split enforced at tool-availability level: in Plan Mode, code-writing tools are literally absent from the tool schema (not just prohibited by prompt text), making it impossible for the agent to accidentally write code during planning. This is a harder constraint than kiro's spec workflow gates or agent-os's [EXECUTE] token approach. Unlike superpowers or spec-driver (which add behavior on top of Claude Code), cline-max IS the AI coding engine itself. Compared to openspec or spec-kit (which generate spec files), cline-max's "spec" is the conversational plan in the chat history — there are no spec files written to disk.

Positioning

  • Niche: Early experiment in plan-before-code discipline, predating the broader spec-driven movement
  • Competitive position: Feature-equivalent to upstream Cline + Plan Mode gate
  • Historical value: Documents the pre-spec-driven-dev era; the description "before spec-driven development became a thing" is an honest framing

Observable Failure Modes

  1. No persistent plan artifact: The plan lives in the chat conversation but is not saved to a spec file on disk. If the session is cleared or context compacted, the plan is lost.
  2. Manual mode toggle burden: The user must manually click to switch Plan → Act. Forgetting to toggle (or toggling too early) defeats the purpose.
  3. Dormant fork: Last commit was February 2025. The upstream Cline has evolved significantly since then (upstream now supports Plan/Act mode natively), making this fork potentially stale.
  4. Upstream superseded it: The upstream Cline project has added Plan/Act mode natively, making this fork's primary innovation obsolete. The fork's description even acknowledges this ("before spec-driven development became a thing").
  5. No spec files: Without persistent spec artifacts, there is no way to review, version, or audit the plan independent of the conversation history.
04

Workflow

cline-max — Workflow

Two-Phase Workflow

Phase 1: Plan Mode

Trigger: User activates Plan Mode via toggle button in the webview UI.

Agent behavior:

  • Reads relevant files to understand codebase
  • Asks clarifying questions via ask_followup_question
  • Presents architectural plan via plan_mode_response
  • Cannot write files, cannot execute commands
  • Can engage in back-and-forth discussion with user

Approval gate: User manually toggles to Act Mode when satisfied with the plan.

Phase 2: Act Mode

Trigger: User toggles to Act Mode.

Agent behavior:

  • Executes the agreed plan step-by-step
  • Uses full tool set: file write, terminal, browser
  • Each tool use requires user approval (unless auto-approve is configured)
  • Monitors linter/compiler errors after file edits
  • Can run browser for visual testing

Artifacts Per Phase

Phase Artifact
Plan Conversation history, architectural decisions in chat
Act Modified files, terminal outputs, screenshots (if browser used)

Approval Gates

Gate Type Mechanism
Plan → Act toggle yes-no Manual button in webview UI
Tool use approval yes-no Per-tool approval dialog (unless auto-approve enabled)
Terminal command yes-no Per-command approval (safety-critical commands require approval even in auto-approve mode)
File write yes-no Diff view approval

Plan Mode System Prompt Addition

In this mode you should focus on information gathering, asking questions, and 
architecting a solution. Once you have a plan, use the plan_mode_response tool 
to engage in a conversational back and forth with the user. Do not use the 
plan_mode_response tool until you've gathered all the information you need 
e.g. with read_file or ask_followup_question.

(Remember: If it seems the user wants you to use tools only available in Act 
Mode, you should ask the user to "toggle to Act mode" (use those words) — 
they will have to manually do this themselves with the Plan/Act toggle button 
below. You do not have the ability to switch to Act Mode yourself.)
06

Memory Context

cline-max — Memory & Context

State Storage

File-based, project-scoped (same as upstream Cline). The extension reads files from the workspace directory and maintains conversation history in VS Code's extension storage.

Context Window Management

From Cline.ts:

  • Context window is managed via sliding window truncation when approaching limits
  • Different models have different context limits (64k for DeepSeek, 128k for most, 200k for Claude)
  • When switching models, truncation is recalculated
  • Historical messages are summarized/truncated to stay within limits

Plan Mode Conversation Persistence

Plan Mode conversations are stored as part of the task conversation history. When the user switches to Act Mode, the full conversation (including the plan discussion) remains in context.

Memory Type

None beyond in-session context and VS Code extension storage. No persistent memory across sessions beyond what the user explicitly saves to files.

Context Files (User-Managed)

Users can reference files via @ mentions in the chat:

  • @/path/to/file — inject file content into context
  • @url — inject web page content

Handoff

No cross-session handoff mechanism. Each session starts fresh. The Plan/Act architecture is session-local — if the user closes VS Code and reopens, plan mode state is reset.

Compaction

From Cline.ts context window logic:

// Since the user may switch between models with different context windows, 
// truncating half may not be enough (ie if switching from claude 200k to 
// deepseek 64k, half truncation will only remove 100k tokens, but we need 
// to remove much more)

Context is compacted by truncating older conversation history when approaching the model's context limit.

Memory Type Summary

Dimension Value
Memory type none (session-only)
Persistence scope session
State files VS Code extension storage (not directly accessible)
Search mechanism none
Compaction yes (sliding window truncation)
07

Orchestration

cline-max — Orchestration

Multi-Agent

No. Single-agent architecture. The extension runs one agent per task.

Orchestration Pattern

Sequential. One tool use per message, result informs next tool use. The Plan/Act toggle adds a sequential phase boundary.

Isolation Mechanism

None enforced by the framework. File edits happen in-place in the workspace.

Multi-Model

Yes (inherited from upstream Cline). Different models can be selected by the user, but there is no automatic role-based model routing. The user picks a single model for the session.

Supported providers: Anthropic, OpenRouter, OpenAI, Google Gemini, AWS Bedrock, Azure, GCP Vertex, OpenAI-compatible (DeepSeek, LLaMA, etc.)

Execution Mode

Interactive loop. Each tool use requires user approval (unless auto-approve is configured). The Plan/Act toggle is a human-gated phase transition.

Crash Recovery

No explicit crash recovery. VS Code extension state is maintained by VS Code's extension host — if it crashes, the session is lost.

Context Compaction

Yes. Sliding window truncation when approaching model context limits. Context-aware recalculation when switching between models with different context windows.

Consensus Mechanism

None.

Plan Mode Tool Enforcement

The mode boundary is enforced at the tool availability level — plan_mode_response is only in Plan Mode, code-writing tools only in Act Mode. This is a hard constraint encoded in the tool schema, not just a prompt suggestion.

Summary Table

Dimension Value
Multi-agent no
Orchestration pattern sequential
Max concurrent agents 1
Isolation none
Consensus none
Prompt chaining yes (plan conversation feeds act mode context)
Multi-model yes (user-selectable, not role-routed)
Execution mode interactive-loop
Crash recovery no
Context compaction yes
08

Ui Cli Surface

cline-max — UI / CLI Surface

IDE Integration

Primary IDE: VS Code

This is a full VS Code extension fork. The UI surface is:

  • Webview panel (React) in VS Code sidebar or tab
  • Plan/Act mode toggle button in the webview
  • Per-tool-use approval dialogs
  • Diff view for file changes
  • Timeline integration (VS Code file timeline shows all Cline changes)
  • MCP server management panel

Dedicated CLI Binary

None from this fork specifically. The upstream Cline project has a separate CLI (cline npm package), but this fork focuses on the VS Code extension only.

Local UI / Dashboard

The webview UI is the local interface — it is the chat interface, mode toggle, approval panel, and settings panel all in one. It runs inside VS Code (not a separate web server).

Features:

  • Chat interface (Plan/Act)
  • Plan/Act mode toggle button
  • Tool use approval dialogs with diff view
  • File history / timeline
  • Token usage and cost tracking
  • Model selector
  • MCP server configuration

Browser Automation

Built-in Puppeteer-based browser automation:

  • Launch browser, navigate URLs
  • Click, type, scroll, capture screenshots
  • Monitor console logs
  • Used for visual testing and end-to-end verification

Observability

  • Per-task token count and API cost display
  • VS Code file Timeline shows all file modifications
  • No structured audit log or replay capability

Cross-Tool Portability

Low. This is a full VS Code extension — it works only in VS Code (or VS Code forks like Cursor/Windsurf that support VS Code extensions, but with caveats).

Related frameworks

same archetype · same primary tool · same memory type

Goose (Block/AAIF) ★ 46k
A12 UI passthrough

General-purpose AI agent (not just code) with security-first tool inspection, recipe-based shareable configurations, and 15+ LLM…

Vibe Kanban ★ 27k
A12 UI passthrough

Eliminate the overhead of planning, switching between agent terminals, and reviewing diffs by providing a single web dashboard…

1Code ★ 5.5k
A12 UI passthrough

Cursor-like desktop experience for Claude Code and Codex with cloud background agents, event-driven automations, and a full…

Crystal (stravu) ★ 3.1k
A12 UI passthrough

Manage multiple parallel AI coding sessions in isolated git worktrees from a single desktop GUI.

Maestro (RunMaestro) ★ 3.0k
A12 UI passthrough

Orchestrate unlimited parallel AI agent sessions with a keyboard-first desktop app including Group Chat coordination and Auto Run…

AgentsMesh ★ 2.1k
A12 UI passthrough

Multi-tenant workforce platform that gives every team member a squad of AI coding agents coordinated through channels, pod…