Cline Prompting Guide: How to Get the Most From the Open-Source AI Coding Agent (2026)

Cline is an open-source coding agent that runs as a VS Code extension. It reads your files, edits them, runs terminal commands, and chains tool calls across a multi-step task — all from inside the editor you already use. The project began as Claude Dev and was renamed Cline in 2024 once it added support for multiple model providers. Today it supports Anthropic, OpenAI, OpenRouter, and local runners like Ollama, plus a growing surface of MCP server integrations. Two design choices set it apart from other editor-resident agents: the plan/act split, which forces a specification step before edits begin, and first-class MCP support, which extends its tool surface without modifying the extension.

This guide covers how to prompt Cline well — the patterns that move quality, the failure modes that burn tokens, and the controls that keep costs honest.

Key takeaways:

• Plan mode and act mode are not workflow flair — they are the load-bearing feature. Skipping plan mode is the most common reason Cline runs go off the rails.
• The prompt belongs in three places, not one: the user message, a project-level .clinerules file, and the implicit context Cline gathers from your workspace. Treat all three as design surfaces.
• MCP server support is what scales Cline beyond the editor — installing a server and naming its tools in your prompt extends the agent's reach without changing the extension.
• Model choice is a cost dial. Use a strong reasoning model in plan mode where the work is conceptual, and consider a cheaper model in act mode for mechanical sub-tasks.
• Auto-approve toggles are a foot-gun, not a feature. Treat them like a permission system — opt in deliberately for a specific task, not by default.
• Cline sits closer to Claude Code than to Cursor on the autonomy axis. If you want a chat-with-suggestions experience, you will fight the tool. If you want a self-driving agent that stays inside your editor, you will love it.
• The prompt patterns that ship are unglamorous: name the success criterion, demand the smallest viable plan, ask the agent to surface assumptions, and keep act-mode diffs small enough to roll back without ceremony.

For the broader category context, see the pillar: the pillar guide. For the framework canonicals this post leans on, see the Agentic Prompt Stack, RCAF, and the Context Engineering Maturity Model.

What Cline Is

Cline is an open-source VS Code extension that turns the editor into an agent runtime. It installs from the marketplace, attaches a side panel for the agent conversation, and operates directly on the open workspace. Three properties define it:

• Multi-provider model support. You bring your own model. Cline talks to Anthropic, OpenAI, and OpenRouter directly, and to local models via Ollama or LM Studio. Provider choice is a config surface, not vendor lock-in.
• Tool use across the editor and shell. Cline reads files, writes files, runs terminal commands, and (with appropriate servers) calls external services. It is not a code-completion tool — it is an agentic coding loop that observes results and reacts to them.
• MCP-native. Cline is an MCP client, so any MCP server you install becomes part of its tool use surface. The integration is the protocol, not bespoke per service.

What Cline is not: not a hosted SaaS (no central billing, no remote run history); not Cursor (it does not optimize for chat-with-inline-suggestions); not Claude Code (it runs in the editor, not the terminal). For the broader category, see AI IDE.

Plan Mode vs. Act Mode — The Core Mental Model

The plan/act split is the load-bearing feature. Plan mode is for understanding; act mode is for editing. The split exists because the worst class of agent failure is acting confidently on a wrong understanding — editing the wrong files, refactoring something that did not need refactoring, or "fixing" a bug by introducing a worse one. Plan mode forces the misunderstanding to surface as text you can correct, before it surfaces as a diff you have to undo.

In plan mode, Cline can read files, browse the workspace, and run read-only commands or MCP tools that gather information. It cannot edit files. Its output is a plan — intent, file list, step order. Plan mode is cheap: bad output here is a paragraph you discard, not a diff you revert.

In act mode, Cline executes — edits files, runs commands, observes outputs, iterates. This is where tokens are burned and changes are made.

The standard loop is plan → review → act → verify: propose a plan, push back on anything that looks wrong, switch to act mode, then verify by running tests and reading the diff.

Skipping the plan step is reasonable for trivial single-file tasks ("add a console.log here"). It is a mistake for anything multi-file, anything destructive, or anything where the failure mode is hard to spot in a diff. The minutes saved by skipping the plan are paid back several times over the first time you revert a run that drifted off the requirement. This pattern lines up with the discipline described in spec-driven AI coding — Cline operationalizes it with two distinct modes instead of relying on prompt discipline alone.

Setup Essentials

Three setup decisions disproportionately shape the rest of your experience: model provider, project context, and .clinerules.

Picking a Model Provider

Cline is provider-agnostic, and the choice has real consequences:

• Anthropic or OpenAI direct. Simplest when you already have an API relationship with the provider. Latest models, no intermediary.
• OpenRouter. A multi-provider gateway that lets you switch models without changing API keys. Convenient for trying different models against the same task. The tradeoff is the extra hop and the gateway's pricing layer.
• Local models (Ollama, LM Studio). No outbound API calls, no per-token cost, full data privacy. The tradeoff is capability — local models you can run on a laptop are typically smaller and weaker than the frontier models served by hosted APIs. Reasonable for narrow mechanical tasks; harder for long-horizon reasoning.

A pragmatic default: a strong hosted model for plan mode (where capability matters most), with the option to swap in a cheaper or local model for mechanical act-mode work.

Giving Cline the Right Project Context

Cline reads the workspace you have open. That is a feature — you do not have to point it at the project — but it also means workspace hygiene matters. A workspace cluttered with unrelated folders or generated artifacts gives the agent more surface to wander across. Open the actual project root (not a parent folder full of projects), keep .gitignore sensible so generated files stay out of the way, and mention specific files and directories in your prompts. Even though Cline can browse, naming files saves a search step and tightens initial scope.

Configuring .clinerules

.clinerules is the project-level instruction file Cline reads as part of every task in the workspace. The general pattern is to capture the things you would otherwise have to type into every prompt: stack and conventions, verification commands (typecheck, lint, tests), out-of-scope directories (generated code, vendored deps, deployment configs), and house style (immutability, file-size targets, naming).

Every line in .clinerules is a line you do not have to repeat in every prompt — and one that consistently shapes Cline's behavior across teammates. This is the same discipline CLAUDE.md provides Claude Code and .cursorrules provides Cursor: durable context belongs in a project file, not in each user message.

Prompt Patterns That Work in Plan Mode

Plan mode is where the work pays off, because a good plan turns a multi-hour run into a multi-minute one. Four patterns matter most.

Name the Success Criterion Explicitly

The single highest-leverage move in any plan-mode prompt is naming what "done" looks like. "Add caching to the checkout flow" is open-ended. "Add caching to the checkout flow such that the GET /api/cart endpoint hits Redis on cache hit, falls back to Postgres on miss, with a 60-second TTL, and the existing integration tests in tests/cart.test.ts continue to pass" is a specification.

Goal:
Add Redis caching to the GET /api/cart endpoint.

Success criteria:
- Cache hit returns within 30ms p95.
- Cache miss falls back to existing Postgres query.
- TTL is 60s.
- Cache key includes user_id and cart version.
- All tests in tests/cart.test.ts pass unchanged.
- No new dependencies beyond ioredis (already in package.json).

Out of scope:
- Do not change the response shape.
- Do not modify other endpoints.

Plan first. Do not edit files yet.

The "Plan first. Do not edit files yet." line is sometimes redundant with the mode toggle, but stating it in the prompt is cheap insurance.

Ask for the Smallest Viable Plan

Plans inflate. A model with capacity to spare will propose a refactor when a function-level change would do. Push back explicitly:

Propose the smallest plan that meets the success criteria. If a more comprehensive refactor would help, mention it as a follow-up — do not include it in this plan.

Demand Surfaced Assumptions

The failures that hurt are the ones grounded in unstated assumptions: "I assumed the cache could be invalidated on every write" turns into a cache that thrashes; "I assumed user_id is always present" turns into a 500 on guest checkout. Force the assumptions out:

Before the plan, list every assumption you are making about the codebase, requirements, and runtime. Mark uncertain assumptions clearly so I can confirm before you proceed.

Ask Which Files It Will Not Touch

Scope creep is easier to catch in the negative. Asking "which files will you not touch?" forces the model to commit to a boundary:

List the files you plan to edit and the files you intentionally will not edit, even if they look related. If unsure whether a file is in scope, name it and ask.

Prompt Patterns That Work in Act Mode

Act mode is where the cost is. Four patterns keep act-mode runs honest.

Keep Diffs Small

A 30-line diff is reviewable. A 600-line diff is not — and an unreviewable diff from an autonomous agent is a recipe for shipping a bug you did not notice. Push for size discipline in the prompt:

Make the smallest diff that satisfies the success criteria. If you find yourself writing more than ~150 lines of changes, stop and report back so we can decide whether the scope expanded.

This is the act-mode echo of "smallest viable plan" — it forces the agent to stop and surface scope drift instead of plowing through it.

Run-and-Verify After Each Change

Cline can run terminal commands. Use that. After every meaningful edit, ask it to run the relevant verification:

After each file edit, run pnpm test -- tests/cart.test.ts and confirm it still passes. If it fails, stop and report before continuing.

The default failure mode without this instruction is "edit, edit, edit, and only run the tests at the end." That pattern hides which edit broke things.

Name the Rollback Path

For risky work — schema migrations, dependency upgrades, deletions — name how to undo it:

Before any database schema change, describe how to reverse it. Include the rollback in the plan, and run the migration only after I confirm.

Refuse Speculative Refactors

Helpfulness sometimes shows up as "while I was in there, I cleaned up these other files." That is scope drift. Cut it explicitly:

Do not refactor or restyle code outside the success criteria, even if it looks improvable. List anything worth changing at the end as a follow-up — do not change it now.

A useful skeleton that combines several of the above:

Mode: act

Apply the plan we agreed on. Constraints:
- Smallest viable diff. Stop and report if you exceed ~150 lines.
- After each edit, run `pnpm test -- <relevant suite>` and confirm pass.
- Do not touch files outside the agreed list.
- Do not refactor unrelated code, even if it looks improvable.
- If a step fails, stop and report — do not loop on the same file.

When done, summarize: files changed, tests run, follow-ups noticed.

Notice this has the shape of an RCAF-style structured prompt — Role implicit (you are the act-mode executor), Context provided by the agreed plan, Action is "apply the plan with these constraints," Format is the closing summary.

MCP — What It Unlocks for Cline

MCP — the Model Context Protocol — is an open standard for connecting AI agents to external tool servers. Cline is an MCP client, so you can extend its tool surface beyond the editor and shell without modifying the extension. Install a server, configure it in Cline, and its tools become part of Cline's available actions.

Common patterns that benefit from MCP: filesystem beyond the workspace (project-adjacent configs, sibling repos, shared docs); GitHub (listing PRs, reading issues, posting comments); observability (Sentry, logs, error trackers — pull recent errors as context for a debugging task); database introspection (a Postgres MCP server lets the agent inspect schemas instead of guessing); and custom internal servers that wrap your APIs.

The prompt-side discipline is to name the tools you want used:

Use the GitHub MCP server to list the open PRs against the staging branch.
For each, read the description and summarize the proposed change in one line.
Then use the Sentry MCP server to fetch errors from the last 24h on the staging environment.
Cross-reference: are any of the open PRs related to the active errors?

This is exactly what MCP is for: multi-tool composition where the agent does not need to know about your internal services — the server does, and the agent calls the server's tools by name. For deeper coverage, see the MCP canonical.

Cost and Safety Controls

Autonomous agents burn tokens fast. A run that loops on the same file because the test keeps failing in a way the agent does not understand can cost real money in real-time. Three controls matter.

Auto-Approve Toggles

Cline lets you decide which actions require explicit approval. Auto-approving file reads is almost always fine. Auto-approving file edits is reasonable on an isolated branch where reverting is cheap; on main it is a foot-gun. Auto-approving terminal commands is the highest-stakes toggle — a confidently wrong rm -rf or an accidentally invoked deploy script is not recoverable in the same way a bad diff is.

A reasonable starting point: approve reads automatically, review edits manually for your first week with the tool, and decide on auto-approving terminal commands per-repo based on what scripts exist. Treat the toggles like permissions, not preferences.

Watch the Cost Meter

Cline shows the running token cost of the current task. Watch it on long runs. Cost climbing without visible progress usually means the agent is stuck in a loop — re-reading the same files, re-running the same failing test, or otherwise spinning. Stop the run, read the last few exchanges, and either give it the missing context or revise the plan.

Switch Models for Sub-Tasks

For a multi-stage task, you do not have to use the same model the whole way through. A common pattern: a strong model in plan mode (where capability matters most), and a cheaper model in act mode for mechanical follow-through. The risk is that the cheaper model misunderstands something the stronger model would have caught — which is why the plan must be tight enough that the cheaper model does not need to make judgment calls.

This lines up with cost-aware patterns covered in the Agentic Prompt Stack. When moving between models, prompt caching behavior differs by provider — worth knowing about on long runs.

Common Failure Modes

Four failure modes account for most of the bad days. For each, the fix is on the prompt side.

Agent edits files outside the intended scope. Fix: in plan mode, ask which files it will not touch. In act mode, restate the no-touch list. If it still drifts, the plan was not specific enough — push back in plan mode rather than reverting in act mode.

Agent loses context across a long task. Fix: keep tasks bounded. If a plan has more than five or six steps, split it into two plans with a verification step in between. Long autonomous runs accumulate misunderstandings; short bounded runs do not.

Agent confidently asserts that a tool or API does not exist when it does. Fix: name it explicitly. "Use the cache.get(key) helper in src/lib/cache.ts. Do not invent a new caching abstraction — that file already has what you need." This hallucination shape disappears with a single sentence of grounding.

Agent gets stuck in a re-edit loop, fixing and re-breaking the same file. Fix: instruct it to stop and report after two consecutive failed attempts on the same step. A loop signals missing context — surface the failure to you, do not keep trying.

These map closely to the failure modes in the Context Engineering Maturity Model. The pattern is the same across all four: most agent failures are context failures, and the fix is upstream of the model.

Cline vs. Claude Code vs. Cursor

The three tools live in the same neighborhood but solve different problems:

• Cursor is chat-with-edits-in-editor. You write a prompt, see a proposed change, accept or revise. The right shape if you prefer staying close to each edit and do not want long unattended runs.
• Claude Code is autonomous-in-terminal. Runs from a shell inside your repo, no editor surface, built for self-driving runs that take many minutes. The right shape for terminal-first workflows.
• Cline is autonomous-in-VS-Code. Same autonomy shape as Claude Code, but inside the editor — file changes appear where you already work, and intervention is one click away. Plan/act is more visible than Claude Code's implicit planning, and MCP support is first-class.

Fit, not ranking. Teams in VS Code who want autonomy with visibility tend to prefer Cline. Terminal-first teams who want maximum self-driving runs tend to prefer Claude Code. Teams who want the developer close to every change tend to prefer Cursor. The category-level framework that applies to all three — including the codeact pattern that grounds them — is the same.

For a tool-agnostic framework, see the Agentic Prompt Stack. The vibe coding guide covers the loose end of the autonomy spectrum, and the test-driven development with AI coding agents sibling tutorial covers the disciplined end.

What to Read Next

Three reads to deepen the picture: the pillar guide for the full agent-prompting taxonomy; the Model Context Protocol canonical for the protocol Cline relies on; and the test-driven development with AI coding agents sibling tutorial — TDD plus plan/act is a clean pairing, because the tests become the success criterion in the plan-mode prompt.

The shortest version of this post: Cline rewards prompts that name success, demand small plans, surface assumptions, and keep act-mode diffs reviewable. The plan/act split and MCP support are what make those patterns durable. Treat plan mode as cheap and act mode as expensive, set your auto-approve toggles deliberately, and you will get most of what an autonomous coding agent can offer without the bills or bad days that often come with it.