Cline AI Agent

Overview

Cline is an advanced AI coding assistant designed to function as a versatile software engineer. It operates within the user's development environment, providing direct access to file systems, command-line operations, and web browsing capabilities.

The agent is built with a comprehensive toolset that enables it to read, write, and modify files; execute system commands; perform code searches; interact with web content; and integrate with MCP (Model Context Protocol) servers for extended functionality.

Open Source Nature

Cline is an Open Source AI agent project, meaning its prompt configuration, system architecture, and integration code are publicly available for community contribution, modification, and customization.

The open-source approach ensures that Cline can evolve with community input while maintaining accountability in its AI interactions and tool usage patterns.

Capabilities

Cline possesses comprehensive capabilities for software engineering tasks, powered by its extensive toolset and intelligent agent loop.

Key Capability Areas

• File System Access: Read, write, search, and list files across the project directory
• Command Execution: Run CLI commands, build processes, and development servers
• Code Analysis: Extract function and class definitions to understand code structure
• Web Interaction: Browse websites, capture screenshots, and interact with pages
• MCP Integration: Connect to external servers for extended tool capabilities
• Iterative Development: Plan, execute, verify, and refine in continuous cycles

Tools

Cline's functionality is powered by a comprehensive set of tools organized into several categories:

File Operations

System Operations

Search & Discovery

MCP Protocol

Planning Mode

Rules & Guidelines

Cline operates under a comprehensive set of rules designed to ensure safe, efficient, and reliable operation.

Critical Rules

• Cannot use the ~ character or $HOME to refer to the home directory - must use absolute paths
• Must consider current working directory and pass correct path parameters to all tools
• Execute ONE tool per message and wait for results before proceeding
• Must ask for user input only through ask_followup_question when absolutely necessary
• Must never end responses with questions or requests for further conversation

Important Guidelines

• Before executing commands, analyze the environment_details to understand the user's system
• Prefer replace_in_file over write_to_file for small, targeted changes
• Use write_to_file for initial file creation or complete file restructuring
• Craft regex patterns carefully when using search_files for optimal results
• Auto-formatting may modify file contents - use final state as reference for subsequent edits

Standard Practices

• New projects should be organized within dedicated project directories
• Consider project type when determining appropriate file structure
• Provide clear explanations when using execute_command
• Review context from list_code_definition_names before making changes
• Use MCP servers as preferred over browser_action when available

Execution Modes

Cline operates in two distinct modes, each serving specific purposes in the agent lifecycle.

┌─────────────────────────────────────────────────────────────┐
│                    MODE SWITCHING LOGIC                     │
└─────────────────────────────────────────────────────────────┘

    ┌──────────────┐
    │   NEW TASK   │
    └──────┬───────┘
           │
           ▼
    ┌──────────────┐
    │   PLAN MODE  │◄── User switches mode for complex task planning
    │              │
    │ • Gather     │• Context exploration
    │   context    │• Information gathering
    │ • Create     │• Architecture planning
    │   plan       │• Requirement clarification
    │ • Clarify    │
    │   questions  │
    └──────┬───────┘
           │
           │ plan_mode_respond()
           ▼
    ┌──────────────┐
    │ User Reviews │
    │   & Approve   │
    └──────┬───────┘
           │
           │ User switches: PLAN → ACT
           ▼
    ┌──────────────┐
    │   ACT MODE   │◄── Default mode for tool execution
    │              │
    │ • Execute    │• Direct tool usage
    │   tools      │• File modifications
    │ • Iterate    │• Command execution
    │ • Complete   │• Problem solving
    └──────────────┘

PLAN MODE

• Access: Special mode activated by user
• Tools: All tools EXCEPT plan_mode_respond (which is exclusive)
• Communication: Uses plan_mode_respond to share plans and ask questions
• Flow: Information gathering → Plan creation → User review → Mode switch

ACT MODE

• Default: Most common operational state
• Tools: All tools EXCEPT plan_mode_respond
• Principle: Execute tools sequentially, analyzing results before next action
• Completion: Uses attempt_completion to present final results

Agent Workflow

Cline follows a systematic workflow that ensures methodical, verifiable task completion.

    ┌─────────────────────────────────────────────────────────────┐
    │                    AGENT WORKFLOW CYCLE                     │
    └─────────────────────────────────────────────────────────────┘

                       ┌──────────────┐
                       │   Task Input │
                       │   (Event)    │
                       └──────┬───────┘
                              │
                              ▼
                 ┌────────────────────────┐
                 │  1. ANALYZE EVENTS     │
                 │ • Understand state     │
                 │ • Review user message  │
                 │ • Check observations   │
                 └──────────┬─────────────┘
                            │
                            ▼
                 ┌────────────────────────┐
                 │  2. SELECT TOOLS       │
                 │ • Choose next action   │
                 │ • Consider planning    │
                 │ • Reference knowledge  │
                 └──────────┬─────────────┘
                            │
                            ▼
                 ┌────────────────────────┐
                 │  3. WAIT EXECUTION     │
                 │ • Tool runs            │
                 │ • Process completes    │
                 │ • New observation log  │
                 └──────────┬─────────────┘
                            │
                     ┌──────┴──────┐
                     ▼             │
              ┌──────────┐       │
              │ COMPLETE? ├───────┘
              └──────┬───┘
                     │ NO
                     │
                     ▼
              ┌──────────────┐
              │  4. ITERATE   │
              │ • Update plan │
              │ • Re-analyze  │
              └──────┬───────┘
                     │
                     ▼
               [BACK TO STEP 1]

                  ┌──────────────┐
                  │ Task Success?│
                  └──────┬───────┘
                         │ YES
                         ▼
              ┌────────────────────┐
              │   SUBMIT RESULTS   │
              │ • Send message     │
              │ • Attach artifacts  │
              └────────────────────┘

MCP Integration

Cline supports the Model Context Protocol (MCP), enabling connection to external servers that provide additional tools, resources, and capabilities.

MCP Server Configuration

Using MCP Tools

When an MCP server is connected, its tools become available alongside Cline's native tools. The agent uses the same tool selection process to determine when to use MCP-provided capabilities.

┌─────────────────────────────────────────────────────────────┐
│                MCP TOOL INTEGRATION FLOW                    │
└─────────────────────────────────────────────────────────────┘

    Cline starts
        │
        ├─→ Check MCP configuration
        │
        ├─→ Connect to configured servers
        │   │
        │   └─→ Discover available tools
        │
        └─→ During agent loop:
            │
            ├─→ Analyze task requirements
            │
            ├─→ Check tool selection:
            │   │
            │   ├─→ Native tool suitable? → Use native tool
            │   │
            │   └─→ MCP tool suitable? → use_mcp_tool()
            │
            └─→ Execute and process results

Usage Guidelines

Best practices for effective use of Cline as a development assistant.

When to Use Cline

• Code Generation: Creating new files, scaffolding projects, implementing features
• Code Modification: Refactoring, bug fixes, performance improvements
• Code Analysis: Understanding complex codebases, finding patterns
• System Operations: Build processes, testing, deployment tasks
• Research: Web browsing for documentation, APIs, solutions
• Planning: Complex task breakdown using PLAN MODE

Tool Selection Guidelines

Safety Considerations

Tool Usage Examples

Examples of how Cline uses its tools in practice.

Reading a File

<read_file>
<path>src/components/Button.js</path>
</read_file>

Making a Targeted Edit

<replace_in_file>
<path>src/utils/helpers.js</path>
<diff>
<<<<<< SEARCH
function formatDate(date) {
  return date.toISOString().split('T')[0];
}
=======
function formatDate(date) {
  return new Intl.DateTimeFormat('pt-BR').format(date);
}
>>>>>> REPLACE
</diff>
</replace_in_file>

Executing a Command

<execute_command>
<command>npm run build</command>
<requires_approval>false</requires_approval>
</execute_command>

Using an MCP Tool

<use_mcp_tool>
<server_name>github-mcp</server_name>
<tool_name>create_issue</tool_name>
<arguments>
{
  "repo": "user/repo",
  "title": "Bug report",
  "body": "Description..."
}
</arguments>
</use_mcp_tool>

Starting PLAN MODE

<plan_mode_respond>
<plan_mode_respond_bottom>
I've analyzed the task and created a plan:

1. Explore the codebase structure
2. Identify files to modify
3. Implement changes incrementally
4. Verify each change

Ready to proceed when you switch to ACT mode.
</plan_mode_respond_bottom>
</plan_mode_respond>

Completing a Task

<attempt_completion>
<result>
Task completed successfully!

Created:
- src/components/Button.js
- src/styles/button.css

Modified:
- src/index.js (added button import)

The button component is ready with full TypeScript support
and follows the project's design system.
</result>
</attempt_completion>

Advanced Topics

Event Stream Understanding

Cline operates based on an event stream that includes:

• User Messages: New input from the user
• Action Results: Outputs from executed tools
• Planning Updates: Changes to task plans
• Knowledge Injections: Context or data additions

Each iteration processes the chronological event stream to make decisions about next actions.

System Information Context

Cline uses this information to tailor commands to the user's system. For example, directory paths and shell-specific syntax are derived from these details.

Auto-Formatting Awareness

When files are edited, the user's editor may apply auto-formatting that changes:

• Line breaks and indentation
• Quote style (single vs double)
• Import organization and sorting
• Trailing commas in objects/arrays
• Brace style placement

Cline must use the final formatted file state as reference for subsequent replace_in_file operations.