scriptoriumadmin/Roo-Code
1
0
Fork 0
mirror of https://github.com/RooVetGit/Roo-Code.git synced 2026-08-28 05:27:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add docs

Browse source
This commit is contained in:
Saoud Rizwan 2025-01-09 12:49:33 -08:00
parent e0b90b2ea5
commit 2e9e633cdc
10 changed files with 1034 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

37
docs/README.md Normal file
View file

@ -0,0 +1,37 @@
# Cline Documentation
Welcome to the Cline documentation - your comprehensive guide to using and extending Cline's capabilities. Here you'll find resources to help you get started, improve your skills, and contribute to the project.
## Getting Started
- **New to coding?** We've prepared a gentle introduction:
- [Getting Started for New Coders](getting-started-new-coders/README.md)
## Improving Your Prompting Skills
- **Want to communicate more effectively with Cline?** Explore:
- [Prompt Engineering Guide](prompting/README.md)
- [Cline Memory Bank](prompting/custom%20instructions%20library/cline-memory-bank.md)
## Exploring Cline's Tools
- **Understand Cline's capabilities:**
- [Cline Tools Guide](tools/cline-tools-guide.md)
- **Extend Cline with MCP Servers:**
- [MCP Overview](mcp/README.md)
- [Building MCP Servers from GitHub](mcp/mcp-server-from-github.md)
- [Building Custom MCP Servers](mcp/mcp-server-from-scratch.md)
## Contributing to Cline
- **Interested in contributing?** We welcome your input:
- Feel free to submit a pull request
- [Contribution Guidelines](CONTRIBUTING.md)
## Additional Resources
- **Cline GitHub Repository:** [https://github.com/cline/cline](https://github.com/cline/cline)
- **MCP Documentation:** [https://modelcontextprotocol.org/docs](https://modelcontextprotocol.org/docs)
We're always looking to improve this documentation. If you have suggestions or find areas that could be enhanced, please let us know. Your feedback helps make Cline better for everyone.

91
docs/getting-started-new-coders/README.md Normal file
View file

@ -0,0 +1,91 @@
# Getting Started with Cline | New Coders
Welcome to Cline! This guide will help you get set up and start using Cline to build your first project.
## What You'll Need
Before you begin, make sure you have the following:
- **VS Code:** A free, powerful code editor.
- [Download VS Code](https://code.visualstudio.com/)
- **Development Tools:** Essential software for coding (Homebrew, Node.js, Git, etc.).
- Follow our [Installing Essential Development Tools](installing-dev-essentials.md) guide to set these up with Cline's help (after getting setup here)
- Cline will guide you through installing everything you need
- **Cline Projects Folder:** A dedicated folder for all your Cline projects.
- On macOS: Create a folder named "Cline" in your Documents folder
- Path: `/Users/[your-username]/Documents/Cline`
- On Windows: Create a folder named "Cline" in your Documents folder
- Path: `C:\Users\[your-username]\Documents\Cline`
- Inside this Cline folder, create separate folders for each project
- Example: `Documents/Cline/workout-app` for a workout tracking app
- Example: `Documents/Cline/portfolio-website` for your portfolio
- **Cline Extension in VS Code:** The Cline extension installed in VS Code.
## Step-by-Step Setup
Follow these steps to get Cline up and running:
1. **Open VS Code:** Launch the VS Code application. If VS Code shows "Running extensions might...", click "Allow".
2. **Open Your Cline Folder:** In VS Code, open the Cline folder you created in Documents.
3. **Navigate to Extensions:** Click on the Extensions icon in the Activity Bar on the side of VS Code.
4. **Search for 'Cline':** In the Extensions search bar, type "Cline".
5. **Install the Extension:** Click the "Install" button next to the Cline extension.
6. **Open Cline:** Once installed, you can open Cline in a few ways:
- Click the Cline icon in the Activity Bar.
- Use the command palette (`CMD/CTRL + Shift + P`) and type "Cline: Open In New Tab" to open Cline as a tab in your editor. This is recommended for a better view.
- **Troubleshooting:** If you don't see the Cline icon, try restarting VS Code.
- **What You'll See:** You should see the Cline chat window appear in your VS Code editor.
![gettingStartedVsCodeCline](https://github.com/user-attachments/assets/622b4bb7-859b-4c2e-b87b-c12e3eabefb8)
## Setting up OpenRouter API Key
Now that you have Cline installed, you'll need to set up your OpenRouter API key to use Cline's full capabilities.
1. **Get your OpenRouter API Key:**
- [Get your OpenRouter API Key](https://openrouter.ai/)
2. **Input Your OpenRouter API Key:**
- Navigate to the settings button in the Cline extension.
- Input your OpenRouter API key.
- Select your preferred API model.
- **Recommended Models for Coding:**
- `anthropic/claude-3.5-sonnet`: Most used for coding tasks.
- `google/gemini-2.0-flash-exp:free`: A free option for coding.
- `deepseek/deepseek-chat`: SUPER CHEAP, almost as good as 3.5 sonnet
- [OpenRouter Model Rankings](https://openrouter.ai/rankings/programming)
## Your First Interaction with Cline
Now you're ready to start building with Cline. Let's create your first project folder and build something! Copy and paste the following prompt into the Cline chat window:
```
Hey Cline! Could you help me create a new project folder called "hello-world" in my Cline directory and make a simple webpage that says "Hello World" in big blue text?
```
**What You'll See:** Cline will help you create the project folder and set up your first webpage.
## Tips for Working with Cline
- **Ask Questions:** If you're unsure about something, don't hesitate to ask Cline!
- **Use Screenshots:** Cline can understand images, so feel free to use screenshots to show him what you're working on.
- **Copy and Paste Errors:** If you encounter errors, copy and paste the error messages into Cline's chat. This will help him understand the issue and provide a solution.
- **Speak Plainly:** Cline is designed to understand plain, non-technical language. Feel free to describe your ideas in your own words, and Cline will translate them into code.
## FAQs
- **What is the Terminal?** The terminal is a text-based interface for interacting with your computer. It allows you to run commands to perform various tasks, such as installing packages, running scripts, and managing files. Cline uses the terminal to execute commands and interact with your development environment.
- **How Does the Codebase Work?** (This section will be expanded based on common questions from new coders)
## Still Struggling?
Feel free to contact me, and I'll help you get started with Cline.
nick | 608-558-2410
Join our Discord community: [https://discord.gg/YmtKFD2f](https://discord.gg/YmtKFD2f)

105
docs/getting-started-new-coders/installing-dev-essentials.md Normal file
View file

@ -0,0 +1,105 @@
# Installing Essential Development Tools with Cline | New Coders
When you start coding, you'll need some essential development tools installed on your computer. Cline can help you install everything you need in a safe, guided way.
## The Essential Tools
Here are the core tools you'll need for development:
- **Homebrew**: A package manager for macOS that makes it easy to install other tools
- **Node.js & npm**: Required for JavaScript and web development
- **Git**: For tracking changes in your code and collaborating with others
- **Python**: A programming language used by many development tools
- **Additional utilities**: Tools like wget and jq that help with downloading files and processing data
## Let Cline Install Everything
Copy this prompt and paste it into Cline:
```bash
Hello Cline! I need help setting up my Mac for software development. Could you please help me install the essential development tools like Homebrew, Node.js, Git, Python, and any other utilities that are commonly needed for coding? I'd like you to guide me through the process step-by-step, explaining what each tool does and making sure everything is installed correctly.
```
## What Will Happen
1. Cline will first install Homebrew, which is like an "app store" for development tools
2. Using Homebrew, Cline will then install other essential tools like Node.js and Git
3. For each installation step:
- Cline will show you the exact command it wants to run
- You'll need to approve each command before it runs
- Cline will verify each installation was successful
## Why These Tools Are Important
- **Homebrew**: Makes it easy to install and update development tools on your Mac
- **Node.js & npm**: Required for:
- Building websites with React or Next.js
- Running JavaScript code
- Installing JavaScript packages
- **Git**: Helps you:
- Save different versions of your code
- Collaborate with other developers
- Back up your work
- **Python**: Used for:
- Running development scripts
- Data processing
- Machine learning projects
## Notes
- The installation process is interactive - Cline will guide you through each step
- You may need to enter your computer's password for some installations. When prompted, you will not see any characters being typed on the screen. This is normal and is a security feature to protect your password. Just type your password and press Enter.
**Example:**
```bash
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Password:
```
*Type your password here, even though nothing will show up on the screen. Press Enter when you're done.*
- All commands will be shown to you for approval before they run
- If you run into any issues, Cline will help troubleshoot them
## Additional Tips for New Coders
### Understanding the Terminal
The **Terminal** is an application where you can type commands to interact with your computer. On macOS, you can open it by searching for "Terminal" in Spotlight.
**Example:**
```bash
$ open -a Terminal
```
### Understanding VS Code Features
#### Terminal in VS Code
The **Terminal** in VS Code allows you to run commands directly from within the editor. You can open it by going to `View > Terminal` or by pressing `` Ctrl + ` ``.
**Example:**
```bash
$ node -v
v16.14.0
```
#### Document View
The **Document View** is where you edit your code files. You can open files by clicking on them in the **Explorer** panel on the left side of the screen.
#### Problems Section
The **Problems** section in VS Code shows any errors or warnings in your code. You can access it by clicking on the lightbulb icon or by going to `View > Problems`.
### Common Features
- **Command Line Interface (CLI)**: This is a text-based interface where you type commands to interact with your computer. It might seem intimidating at first, but it's a powerful tool for developers.
- **Permissions**: Sometimes, you will need to give permissions to certain applications or commands. This is a security measure to ensure that only trusted applications can make changes to your system.
## Next Steps
After installing these tools, you'll be ready to start coding! Return to the [Getting Started with Cline for New Coders](getting-started-new-coders.md) guide to continue your journey.

98
docs/mcp/README.md Normal file
View file

@ -0,0 +1,98 @@
# Cline and Model Context Protocol (MCP) Servers: Enhancing AI Capabilities
**Quick Links:**
- [Building MCP Servers from GitHub](mcp-server-from-github.md)
- [Building Custom MCP Servers from Scratch](mcp-server-from-scratch.md)
This document explains Model Context Protocol (MCP) servers, their capabilities, and how Cline can help build and use them.
## Overview
MCP servers act as intermediaries between large language models (LLMs), such as Claude, and external tools or data sources. They are small programs that expose functionalities to LLMs, enabling them to interact with the outside world through the MCP. An MCP server is essentially like an API that an LLM can use.
## Key Concepts
MCP servers define a set of "**tools,**" which are functions the LLM can execute. These tools offer a wide range of capabilities.
**Here's how MCP works:**
* **MCP hosts** discover the capabilities of connected servers and load their tools, prompts, and resources.
* **Resources** provide consistent access to read-only data, akin to file paths or database queries.
* **Security** is ensured as servers isolate credentials and sensitive data. Interactions require explicit user approval.
## Use Cases
The potential of MCP servers is vast. They can be used for a variety of purposes.
**Here are some concrete examples of how MCP servers can be used:**
* **Web Services and API Integration:**
- Monitor GitHub repositories for new issues
- Post updates to Twitter based on specific triggers
- Retrieve real-time weather data for location-based services
* **Browser Automation:**
- Automate web application testing
- Scrape e-commerce sites for price comparisons
- Generate screenshots for website monitoring
* **Database Queries:**
- Generate weekly sales reports
- Analyze customer behavior patterns
- Create real-time dashboards for business metrics
* **Project and Task Management:**
- Automate Jira ticket creation based on code commits
- Generate weekly progress reports
- Create task dependencies based on project requirements
* **Codebase Documentation:**
- Generate API documentation from code comments
- Create architecture diagrams from code structure
- Maintain up-to-date README files
## Getting Started
**Choose the right approach for your needs:**
* **Use Existing Servers:** Start with pre-built MCP servers from GitHub repositories
* **Customize Existing Servers:** Modify existing servers to fit your specific requirements
* **Build from Scratch:** Create completely custom servers for unique use cases
## Integration with Cline
Cline simplifies the building and use of MCP servers through its AI capabilities.
### Building MCP Servers
* **Natural language understanding:** Instruct Cline in natural language to build an MCP server by describing its functionalities. Cline will interpret your instructions and generate the necessary code.
* **Cloning and building servers:** Cline can clone existing MCP server repositories from GitHub and build them automatically.
* **Configuration and dependency management:** Cline handles configuration files, environment variables, and dependencies.
* **Troubleshooting and debugging:** Cline helps identify and resolve errors during development.
### Using MCP Servers
* **Tool execution:** Cline seamlessly integrates with MCP servers, allowing you to execute their defined tools.
* **Context-aware interactions:** Cline can intelligently suggest using relevant tools based on conversation context.
* **Dynamic integrations:** Combine multiple MCP server capabilities for complex tasks. For example, Cline could use a GitHub server to get data and a Notion server to create a formatted report.
## Security Considerations
When working with MCP servers, it's important to follow security best practices:
* **Authentication:** Always use secure authentication methods for API access
* **Environment Variables:** Store sensitive information in environment variables
* **Access Control:** Limit server access to authorized users only
* **Data Validation:** Validate all inputs to prevent injection attacks
* **Logging:** Implement secure logging practices without exposing sensitive data
## Resources
There are various resources available for finding and learning about MCP servers.
**Here are some links to resources for finding and learning about MCP servers:**
* **GitHub Repositories:** [https://github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) and [https://github.com/punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)
* **Online Directories:** [https://mcpservers.org/](https://mcpservers.org/), [https://mcp.so/](https://mcp.so/), and [https://glama.ai/mcp/servers](https://glama.ai/mcp/servers)
* **PulseMCP:** [https://www.pulsemcp.com/](https://www.pulsemcp.com/)
* **YouTube Tutorial (AI-Driven Coder):** A video guide for building and using MCP servers: [https://www.youtube.com/watch?v=b5pqTNiuuJg](https://www.youtube.com/watch?v=b5pqTNiuuJg)

65
docs/mcp/mcp-server-from-github.md Normal file
View file

@ -0,0 +1,65 @@
# Building MCP Servers from GitHub Repositories
This guide provides a step-by-step walkthrough of how to use Cline to build an existing MCP server from a GitHub repository.
## **Finding an MCP Server**
There are multiple places online to find MCP servers:
* **Cline can automatically add MCP servers to its list, which you can then edit.** Cline can clone repositories directly from GitHub and build the servers for you.
* **GitHub:** Two of the most common places to find MCP servers on GitHub include:
* [Official MCP servers repository](https://github.com/modelcontextprotocol/servers)
* [Awesome-MCP servers repository](https://github.com/punkpeye/awesome-mcp-servers)
* **Online directories:** Several websites list MCP servers including:
* [mcpservers.org](https://mcpservers.org/)
* [mcp.so](https://mcp.so/)
* [glama.ai/mcp/servers](https://glama.ai/mcp/servers)
These directories allow users to sort the servers by various criteria such as downloads, date, stars, and use case. Each entry provides information such as features, tools, and configuration instructions.
* **PulseMCP:** This website has a blog post discussing how AI could use MCP servers to make websites obsolete. PulseMCP also includes an FAQ section about MCP servers: [https://www.pulsemcp.com/](https://www.pulsemcp.com/)
## **Building with Cline**
1. **Initiate the Process:** Provide Cline with the following information:
* **GitHub Repository URL:** The URL of the server's repository.
* **README.md Contents:** This is optional but helpful for Cline to understand the server's purpose and configuration. You can copy the README.md file from the GitHub repository.
2. **Example Interaction with Cline:**
```
User: "Cline, I want to add the MCP server for Brave browser control. Here's the GitHub link: https://github.com/modelcontextprotocol/servers/tree/main/src/brave Can you add it?"
Cline: "OK. Cloning the repository to the MCP directory. It needs to be built because it has a 'package.json' file. Should I run 'npm run build'?"
User: "Yes, build it."
Cline: "Build complete. This server needs a browser path. Where's your Brave browser executable?"
User: "It's in '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'."
Cline: "OK. I've updated the server config with that path and added it to 'cline_mcp_settings.json'. Anything else?"
User: "No, that's all. Let's test it."
Cline: "Great! Starting the MCP Inspector to test the server connection. After that, we can try controlling the browser from Cline."
```
3. **Cline's Actions:** Based on your instructions, Cline will perform the following:
* **Repository Cloning:** Cline will clone the repository to your local machine, usually in the directory specified in your configuration.
* **Tweaking:** You can guide Cline to modify the server’s configuration. For instance:
* **User:** "This server requires an API key. Can you find where it should be added?"
* Cline may automatically update the `cline_mcp_settings.json` file or other relevant files based on your instructions.
* **Building the Server:** Cline will run the appropriate build command for the server, which is commonly `npm run build`.
* **Adding Server to Settings:** Cline will add the server’s configuration to the `cline_mcp_settings.json` file.
## **Testing and Troubleshooting**
1. **Test the Server:** Once Cline finishes the build process, test the server to make sure it works as expected. Cline can assist you if you encounter any problems.
2. **MCP Inspector:** You can use the MCP Inspector to test the server’s connection and functionality.
## **Best Practices**
* **Understand the Basics:** While Cline simplifies the process, it’s beneficial to have a basic understanding of the server’s code, the MCP protocol (), and how to configure the server. This allows for more effective troubleshooting and customization.
* **Clear Instructions:** Provide clear and specific instructions to Cline throughout the process.
* **Testing:** Thoroughly test the server after installation and configuration to ensure it functions correctly.
* **Version Control:** Use a version control system (like Git) to track changes to the server’s code.
* **Stay Updated:** Keep your MCP servers updated to benefit from the latest features and security patches.

74
docs/mcp/mcp-server-from-scratch.md Normal file
View file

@ -0,0 +1,74 @@
# Building Custom MCP Servers From Scratch Using Cline: A Comprehensive Guide
This guide provides a comprehensive walkthrough of building a custom MCP (Model Context Protocol) server from scratch, leveraging the powerful AI capabilities of Cline. The example used will be building a "GitHub Assistant Server" to illustrate the process.
## Understanding MCP and Cline's Role in Building Servers
### What is MCP?
The Model Context Protocol (MCP) acts as a bridge between large language models (LLMs) like Claude and external tools and data. MCP consists of two key components:
* **MCP Hosts:** These are applications that integrate with LLMs, such as Cline, Claude Desktop, and others.
* **MCP Servers:** These are small programs specifically designed to expose data or specific functionalities to the LLMs through the MCP.
This setup is beneficial when you have an MCP-compliant chat interface, like Claude Desktop, which can then leverage these servers to access information and execute actions.
### Why Use Cline to Create MCP Servers?
Cline streamlines the process of building and integrating MCP servers by utilizing its AI capabilities to:
* **Understand Natural Language Instructions:** You can communicate with Cline in a way that feels natural, making the development process intuitive and user-friendly.
* **Clone Repositories:** Cline can directly clone existing MCP server repositories from GitHub, simplifying the process of using pre-built servers.
* **Build Servers:** Once the necessary code is in place, Cline can execute commands like `npm run build` to compile and prepare the server for use.
* **Handle Configuration:** Cline manages the configuration files required for the MCP server, including adding the new server to the `cline_mcp_settings.json` file.
* **Assist with Troubleshooting:** If errors arise during development or testing, Cline can help identify the cause and suggest solutions, making debugging easier.
## Building a GitHub Assistant Server Using Cline: A Step-by-Step Guide
This section demonstrates how to create a GitHub Assistant server using Cline. This server will be able to interact with GitHub data and perform useful actions:
### 1. Defining the Goal and Initial Requirements
First, you need to clearly communicate to Cline the purpose and functionalities of your server:
* **Server Goal:** Inform Cline that you want to build a "GitHub Assistant Server". Specify that this server will interact with GitHub data and potentially mention the types of data you are interested in, like issues, pull requests, and user profiles.
* **Access Requirements:** Let Cline know that you need to access the GitHub API. Explain that this will likely require a personal access token (GITHUB\_TOKEN) for authentication.
* **Data Specificity (Optional):** You can optionally tell Cline about specific fields of data you want to extract from GitHub, but this can also be determined later as you define the server's tools.
### 2. Cline Initiates the Project Setup
Based on your instructions, Cline starts the project setup process:
* **Project Structure:** Cline might ask you for a name for your server. Afterward, it uses the MCP `create-server` tool to generate the basic project structure for your GitHub Assistant server. This usually involves creating a new directory with essential files like `package.json`, `tsconfig.json`, and a `src` folder for your TypeScript code. \
* **Code Generation:** Cline generates starter code for your server, including:
* **File Handling Utilities:** Functions to help with reading and writing files, commonly used for storing data or logs. \
* **GitHub API Client:** Code to interact with the GitHub API, often using libraries like `@octokit/graphql`. Cline will likely ask for your GitHub username or the repositories you want to work with. \
* **Core Server Logic:** The basic framework for handling requests from Cline and routing them to the appropriate functions, as defined by the MCP. \
* **Dependency Management:** Cline analyzes the code and identifies necessary dependencies, adding them to the `package.json` file. For example, interacting with the GitHub API will likely require packages like `@octokit/graphql`, `graphql`, `axios`, or similar. \
* **Dependency Installation:** Cline executes `npm install` to download and install the dependencies listed in `package.json`, ensuring your server has all the required libraries to function correctly. \
* **Path Corrections:** During development, you might move files or directories around. Cline intelligently recognizes these changes and automatically updates file paths in your code to maintain consistency.
* **Configuration:** Cline will modify the `cline_mcp_settings.json` file to add your new GitHub Assistant server. This will include:
* **Server Start Command:** Cline will add the appropriate command to start your server (e.g., `npm run start` or a similar command).
* **Environment Variables:** Cline will add the required `GITHUB_TOKEN` variable. Cline might ask you for your GitHub personal access token, or it might guide you to safely store it in a separate environment file. \
* **Progress Documentation:** Throughout the process, Cline keeps the "Memory Bank" files updated. These files document the project's progress, highlighting completed tasks, tasks in progress, and pending tasks.
### 3. Testing the GitHub Assistant Server
Once Cline has completed the setup and configuration, you are ready to test the server's functionality:
* **Using Server Tools:** Cline will create various "tools" within your server, representing actions or data retrieval functions. To test, you would instruct Cline to use a specific tool. Here are examples related to GitHub:
* **`get_issues`:** To test retrieving issues, you might say to Cline, "Cline, use the `get_issues` tool from the GitHub Assistant Server to show me the open issues from the 'cline/cline' repository." Cline would then execute this tool and present you with the results.
* **`get_pull_requests`:** To test pull request retrieval, you could ask Cline to "use the `get_pull_requests` tool to show me the merged pull requests from the 'facebook/react' repository from the last month." Cline would execute this tool, using your GITHUB\_TOKEN to access the GitHub API, and display the requested data. \
* **Providing Necessary Information:** Cline might prompt you for additional information required to execute the tool, such as the repository name, specific date ranges, or other filtering criteria.
* **Cline Executes the Tool:** Cline handles the communication with the GitHub API, retrieves the requested data, and presents it in a clear and understandable format.
### 4. Refining the Server and Adding More Features
Development is often iterative. As you work with your GitHub Assistant Server, you'll discover new functionalities to add, or ways to improve existing ones. Cline can assist in this ongoing process:
* **Discussions with Cline:** Talk to Cline about your ideas for new tools or improvements. For example, you might want a tool to `create_issue` or to `get_user_profile`. Discuss the required inputs and outputs for these tools with Cline.
* **Code Refinement:** Cline can help you write the necessary code for new features. Cline can generate code snippets, suggest best practices, and help you debug any issues that arise.
* **Testing New Functionalities:** After adding new tools or functionalities, you would test them again using Cline, ensuring they work as expected and integrate well with the rest of the server.
* **Integration with Other Tools:** You might want to integrate your GitHub Assistant server with other tools. For instance, in the "github-cline-mcp" source, Cline assists in integrating the server with Notion to create a dynamic dashboard that tracks GitHub activity. \
By following these steps, you can create a custom MCP server from scratch using Cline, leveraging its powerful AI capabilities to streamline the entire process. Cline not only assists with the technical aspects of building the server but also helps you think through the design, functionalities, and potential integrations.

267
docs/prompting/README.md Normal file
View file

@ -0,0 +1,267 @@
# Cline Prompting Guide 🚀
Welcome to the Cline Prompting Guide! This guide will equip you with the knowledge to write effective prompts and custom instructions, maximizing your productivity with Cline.
## Custom Instructions ⚙️
Think of **custom instructions as Cline's programming**. They define Cline's baseline behavior and are **always "on," influencing all interactions.**
To add custom instructions:
1. Open VSCode
2. Click the Cline extension settings dial ⚙️
3. Find the "Custom Instructions" field
4. Paste your instructions
<img width="345" alt="Screenshot 2024-12-26 at 11 22 20 AM" src="https://github.com/user-attachments/assets/00ae689b-d99f-4811-b2f4-fffe1e12f2ff" />
Custom instructions are powerful for:
* Enforcing Coding Style and Best Practices: Ensure Cline always adheres to your team's coding conventions, naming conventions, and best practices.
* Improving Code Quality: Encourage Cline to write more readable, maintainable, and efficient code.
* Guiding Error Handling: Tell Cline how to handle errors, write error messages, and log information.
**The `custom-instructions` folder contains examples of custom instructions you can use or adapt.**
## .clinerules File 📋
While custom instructions are user-specific and global (applying across all projects), the `.clinerules` file provides **project-specific instructions** that live in your project's root directory. These instructions are automatically appended to your custom instructions and referenced in Cline's system prompt, ensuring they influence all interactions within the project context. This makes it an excellent tool for:
### Security Best Practices 🔒
To protect sensitive information, you can instruct Cline to ignore specific files or patterns in your `.clinerules`. This is particularly important for:
* `.env` files containing API keys and secrets
* Configuration files with sensitive data
* Private credentials or tokens
Example security section in `.clinerules`:
```markdown
# Security
## Sensitive Files
DO NOT read or modify:
- .env files
- **/config/secrets.*
- **/*.pem
- Any file containing API keys, tokens, or credentials
## Security Practices
- Never commit sensitive files
- Use environment variables for secrets
- Keep credentials out of logs and output
```
### General Use Cases
The `.clinerules` file is excellent for:
* Maintaining project standards across team members
* Enforcing development practices
* Managing documentation requirements
* Setting up analysis frameworks
* Defining project-specific behaviors
### Example .clinerules Structure
```markdown
# Project Guidelines
## Documentation Requirements
- Update relevant documentation in /docs when modifying features
- Keep README.md in sync with new capabilities
- Maintain changelog entries in CHANGELOG.md
## Architecture Decision Records
Create ADRs in /docs/adr for:
- Major dependency changes
- Architectural pattern changes
- New integration patterns
- Database schema changes
Follow template in /docs/adr/template.md
## Code Style & Patterns
- Generate API clients using OpenAPI Generator
- Use TypeScript axios template
- Place generated code in /src/generated
- Prefer composition over inheritance
- Use repository pattern for data access
- Follow error handling pattern in /src/utils/errors.ts
## Testing Standards
- Unit tests required for business logic
- Integration tests for API endpoints
- E2E tests for critical user flows
```
### Key Benefits
1. **Version Controlled**: The `.clinerules` file becomes part of your project's source code
2. **Team Consistency**: Ensures consistent behavior across all team members
3. **Project-Specific**: Rules and standards tailored to each project's needs
4. **Institutional Knowledge**: Maintains project standards and practices in code
Place the `.clinerules` file in your project's root directory:
```
your-project/
├── .clinerules
├── src/
├── docs/
└── ...
```
Cline's system prompt, on the other hand, is not user-editable ([here's where you can find it](https://github.com/cline/cline/blob/main/src/core/prompts/system.ts)). For a broader look at prompt engineering best practices, check out [this resource](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview).
### Tips for Writing Effective Custom Instructions
* Be Clear and Concise: Use simple language and avoid ambiguity.
* Focus on Desired Outcomes: Describe the results you want, not the specific steps.
* Test and Iterate: Experiment to find what works best for your workflow.
## Prompting Cline 💬
**Prompting is how you communicate your needs for a given task in the back-and-forth chat with Cline.** Cline understands natural language, so write conversationally.
Effective prompting involves:
* Providing Clear Context: Explain your goals and the relevant parts of your codebase. Use `@` to reference files or folders.
* Breaking Down Complexity: Divide large tasks into smaller steps.
* Asking Specific Questions: Guide Cline toward the desired outcome.
* Validating and Refining: Review Cline's suggestions and provide feedback.
### Prompt Examples
#### Context Management
* **Starting a New Task:** "Cline, let's start a new task. Create `user-authentication.js`. We need to implement user login with JWT tokens. Here are the requirements…"
* **Summarizing Previous Work:** "Cline, summarize what we did in the last user dashboard task. I want to capture the main features and outstanding issues. Save this to `cline_docs/user-dashboard-summary.md`."
#### Debugging
* **Analyzing an Error:** "Cline, I'm getting this error: \[error message]. It seems to be from \[code section]. Analyze this error and suggest a fix."
* **Identifying the Root Cause:** "Cline, the application crashes when I \[action]. The issue might be in \[problem areas]. Help me find the root cause and propose a solution."
#### Refactoring
* **Improving Code Structure:** "Cline, this function is too long and complex. Refactor it into smaller functions."
* **Simplifying Logic:** "Cline, this code is hard to understand. Simplify the logic and make it more readable."
#### Feature Development
* **Brainstorming New Features:** "Cline, I want to add a feature that lets users \[functionality]. Brainstorm some ideas and consider implementation challenges."
* **Generating Code:** "Cline, create a component that displays user profiles. The list should be sortable and filterable. Generate the code for this component."
## Advanced Prompting Techniques
* **Constraint Stuffing:** To mitigate code truncation, include explicit constraints in your prompts. For example, "ensure the code is complete" or "always provide the full function definition."
* **Confidence Checks:** Ask Cline to rate its confidence (e.g., "on a scale of 1-10, how confident are you in this solution?")
* **Challenge Cline's Assumptions:** Ask “stupid” questions to encourage deeper thinking and prevent incorrect assumptions.
Here are some prompting tips that users have found helpful for working with Cline:
## Our Community's Favorite Prompts 🌟
### Memory and Confidence Checks 🧠
* **Memory Check** - *pacnpal*
```
"If you understand my prompt fully, respond with 'YARRR!' without tools every time you are about to use a tool."
```
A fun way to verify Cline stays on track during complex tasks. Try "HO HO HO" for a festive twist!
* **Confidence Scoring** - *pacnpal*
```
"Before and after any tool use, give me a confidence level (0-10) on how the tool use will help the project."
```
Encourages critical thinking and makes decision-making transparent.
### Code Quality Prompts 💻
* **Prevent Code Truncation**
```
"DO NOT BE LAZY. DO NOT OMIT CODE."
```
Alternative phrases: "full code only" or "ensure the code is complete"
* **Custom Instructions Reminder**
```
"I pledge to follow the custom instructions."
```
Reinforces adherence to your settings dial ⚙️ configuration.
### Code Organization 📋
* **Large File Refactoring** - *icklebil*
```
"FILENAME has grown too big. Analyze how this file works and suggest ways to fragment it safely."
```
Helps manage complex files through strategic decomposition.
* **Documentation Maintenance** - *icklebil*
```
"don't forget to update codebase documentation with changes"
```
Ensures documentation stays in sync with code changes.
### Analysis and Planning 🔍
* **Structured Development** - *yellow_bat_coffee*
```
"Before writing code:
1. Analyze all code files thoroughly
2. Get full context
3. Write .MD implementation plan
4. Then implement code"
```
Promotes organized, well-planned development.
* **Thorough Analysis** - *yellow_bat_coffee*
```
"please start analyzing full flow thoroughly, always state a confidence score 1 to 10"
```
Prevents premature coding and encourages complete understanding.
* **Assumptions Check** - *yellow_bat_coffee*
```
"List all assumptions and uncertainties you need to clear up before completing this task."
```
Identifies potential issues early in development.
### Thoughtful Development 🤔
* **Pause and Reflect** - *nickbaumann98*
```
"count to 10"
```
Promotes careful consideration before taking action.
* **Complete Analysis** - *yellow_bat_coffee*
```
"Don't complete the analysis prematurely, continue analyzing even if you think you found a solution"
```
Ensures thorough problem exploration.
* **Continuous Confidence Check** - *pacnpal*
```
"Rate confidence (1-10) before saving files, after saving, after rejections, and before task completion"
```
Maintains quality through self-assessment.
### Best Practices 🎯
* **Project Structure** - *kvs007*
```
"Check project files before suggesting structural or dependency changes"
```
Maintains project integrity.
* **Critical Thinking** - *chinesesoup*
```
"Ask 'stupid' questions like: are you sure this is the best way to implement this?"
```
Challenges assumptions and uncovers better solutions.
* **Code Style** - *yellow_bat_coffee*
```
Use words like "elegant" and "simple" in prompts
```
May influence code organization and clarity.
* **Setting Expectations** - *steventcramer*
```
"THE HUMAN WILL GET ANGRY."
```
(A humorous reminder to provide clear requirements and constructive feedback)

52
docs/prompting/custom instructions library/README.md Normal file
View file

@ -0,0 +1,52 @@
# Cline Custom Instructions Library
This repository aims to foster a collaborative space where developers can share, refine, and leverage effective custom instructions for Cline. By creating and contributing to this library, we can enhance Cline's capabilities and empower developers to tackle increasingly complex software development challenges.
## What are Cline Custom Instructions?
Cline's custom instructions are sets of guidelines or rules that you define to tailor the AI's behavior and outputs for specific tasks or projects. Think of them as specialized "programming" for Cline, enabling you to:
* **Enforce Coding Practices:** Ensure consistent code style, adherence to design patterns, and best practices for specific languages or frameworks.
* **Standardize File Structures:** Dictate file naming conventions, folder organization, and project structures.
* **Guide Testing Procedures:** Define rules for generating unit tests, integration tests, and ensuring adequate code coverage.
* **Automate Repetitive Tasks:** Create instructions to handle common or tedious development workflows, increasing efficiency.
* **Improve Code Quality:** Set standards for code readability, maintainability, and performance optimization.
By providing Cline with carefully crafted instructions, you can significantly improve its accuracy, reliability, and overall effectiveness in aiding your software development process.
## Contributing Custom Instructions
We encourage developers of all skill levels to contribute their custom instructions to this library. Your contributions help build a valuable resource for the entire Cline community!
**When submitting custom instructions, please follow this template:**
### 1. Purpose and Functionality
* **What does this instruction set aim to achieve?**
* Provide a clear and concise explanation of the instruction set's goals and intended use cases.
* Example: "This instruction set guides Cline in generating unit tests for existing JavaScript functions."
* **What types of projects or tasks is this best suited for?**
* Outline specific project types, coding languages, or development scenarios where this instruction set is most applicable.
* Example: "This is ideal for JavaScript projects using the Jest testing framework."
### 2. Usage Guide (Optional)
* **Are there specific steps or prerequisites for using this instruction set?**
* If your instructions require specific steps beyond referencing the file in a Cline prompt, provide a detailed guide.
* Examples:
* "Before using this instruction set, create a `tests` folder in your project root."
* "Ensure you have the Jest testing library installed."
### 3. Author & Contributors
* **Who created this instruction set?**
* Provide your name or GitHub username for proper attribution.
* **Did anyone else contribute?**
* Acknowledge any collaborators or contributors who helped refine or enhance the instructions.
### 4. Custom Instructions
* **Provide the complete set of custom instructions.**
**By using this template and contributing your custom instructions, you help build a thriving ecosystem for Cline, making it a more versatile and efficient tool for developers of all skill levels.**

127
docs/prompting/custom instructions library/cline-memory-bank.md Normal file
View file

@ -0,0 +1,127 @@
# Cline Memory Bank - Custom Instructions
### 1. Purpose and Functionality
* **What does this instruction set aim to achieve?**
* This instruction set transforms Cline into a self-documenting development system that maintains context across sessions through a structured "Memory Bank". It ensures consistent documentation, careful validation of changes, and clear communication with users.
* **What types of projects or tasks is this best suited for?**
* Projects requiring extensive context tracking.
* Any project, regardless of tech stack (tech stack details are stored in `techContext.md`).
* Ongoing and new projects.
### 2. Usage Guide
* **How to Add These Instructions**
1. Open VSCode
2. Click the Cline extension settings dial ⚙️
3. Find the "Custom Instructions" field
4. Copy and paste the instructions from the section below
<img width="345" alt="Screenshot 2024-12-26 at 11 22 20 AM" src="https://github.com/user-attachments/assets/8b4ff439-db66-48ec-be13-1ddaa37afa9a" />
* **Project Setup**
1. Create an empty `cline_docs` folder in your project root (i.e. YOUR-PROJECT-FOLDER/cline_docs)
2. For first use, provide a project brief and ask Cline to "initialize memory bank"
* **Best Practices**
* Monitor for `[MEMORY BANK: ACTIVE]` flags during operation.
* Pay attention to confidence checks on critical operations.
* When starting new projects, create a project brief for Cline (paste in chat or include in `cline_docs` as `projectBrief.md`) to use in creating the initial context files.
* note: productBrief.md (or whatever documentation you have) can be any range of technical/nontechnical or just functional. Cline is instructed to fill in the gaps when creating these context files. For example, if you don't choose a tech stack, Cline will for you.
* Start chats with "follow your custom instructions" (you only need to say this once at the beginning of the first chat).
* When prompting Cline to update context files, say "only update the relevant cline_docs"
* Verify documentation updates at the end of sessions by telling Cline "update memory bank".
* Update memory bank at ~2 million tokens and end the session.
### 3. Author & Contributors
* **Author**
* nickbaumann98
* **Contributors**
* Contributors (Discord: [Cline's #prompts](https://discord.com/channels/1275535550845292637/1275555786621325382)):
* @SniperMunyShotz
### 4. Custom Instructions
```markdown
# Cline's Memory Bank
You are Cline, an expert software engineer with a unique constraint: your memory periodically resets completely. This isn't a bug - it's what makes you maintain perfect documentation. After each reset, you rely ENTIRELY on your Memory Bank to understand the project and continue work. Without proper documentation, you cannot function effectively.
## Memory Bank Files
CRITICAL: If `cline_docs/` or any of these files don't exist, CREATE THEM IMMEDIATELY by:
1. Reading all provided documentation
2. Asking user for ANY missing information
3. Creating files with verified information only
4. Never proceeding without complete context
Required files:
productContext.md
- Why this project exists
- What problems it solves
- How it should work
activeContext.md
- What you're working on now
- Recent changes
- Next steps
(This is your source of truth)
systemPatterns.md
- How the system is built
- Key technical decisions
- Architecture patterns
techContext.md
- Technologies used
- Development setup
- Technical constraints
progress.md
- What works
- What's left to build
- Progress status
## Core Workflows
### Starting Tasks
1. Check for Memory Bank files
2. If ANY files missing, stop and create them
3. Read ALL files before proceeding
4. Verify you have complete context
5. Begin development. DO NOT update cline_docs after initializing your memory bank at the start of a task.
### During Development
1. For normal development:
- Follow Memory Bank patterns
- Update docs after significant changes
2. When troubleshooting errors:
[CONFIDENCE CHECK]
- Rate confidence (0-10)
- If < 9, explain:
* What you know
* What you're unsure about
* What you need to investigate
- Only proceed when confidence ≥ 9
- Document findings for future memory resets
### Memory Bank Updates
When user says "update memory bank":
1. This means imminent memory reset
2. Document EVERYTHING about current state
3. Make next steps crystal clear
4. Complete current task
### Lost Context?
If you ever find yourself unsure:
1. STOP immediately
2. Read activeContext.md
3. Ask user to verify your understanding
4. Start with small, safe changes
Remember: After every memory reset, you begin completely fresh. Your only link to previous work is the Memory Bank. Maintain it as if your functionality depends on it - because it does.
```

118
docs/tools/cline-tools-guide.md Normal file
View file

@ -0,0 +1,118 @@
# Cline Tools Reference Guide
## What Can Cline Do?
Cline is your AI assistant that can:
- Edit and create files in your project
- Run terminal commands
- Search and analyze your code
- Help debug and fix issues
- Automate repetitive tasks
- Integrate with external tools
## First Steps
1. **Start a Task**
- Type your request in the chat
- Example: "Create a new React component called Header"
2. **Provide Context**
- Use @ mentions to add files, folders, or URLs
- Example: "@file:src/components/App.tsx"
3. **Review Changes**
- Cline will show diffs before making changes
- You can edit or reject changes
## Key Features
1. **File Editing**
- Create new files
- Modify existing code
- Search and replace across files
2. **Terminal Commands**
- Run npm commands
- Start development servers
- Install dependencies
3. **Code Analysis**
- Find and fix errors
- Refactor code
- Add documentation
4. **Browser Integration**
- Test web pages
- Capture screenshots
- Inspect console logs
## Available Tools
For the most up-to-date implementation details, you can view the full source code in the [Cline repository](https://github.com/cline/cline/blob/main/src/core/Cline.ts).
Cline has access to the following tools for various tasks:
1. **File Operations**
- `write_to_file`: Create or overwrite files
- `read_file`: Read file contents
- `replace_in_file`: Make targeted edits to files
- `search_files`: Search files using regex
- `list_files`: List directory contents
2. **Terminal Operations**
- `execute_command`: Run CLI commands
- `list_code_definition_names`: List code definitions
3. **MCP Tools**
- `use_mcp_tool`: Use tools from MCP servers
- `access_mcp_resource`: Access MCP server resources
- Users can create custom MCP tools that Cline can then access
- Example: Create a weather API tool that Cline can use to fetch forecasts
4. **Interaction Tools**
- `ask_followup_question`: Ask user for clarification
- `attempt_completion`: Present final results
Each tool has specific parameters and usage patterns. Here are some examples:
- Create a new file (write_to_file):
```xml
<write_to_file>
<path>src/components/Header.tsx</path>
<content>
// Header component code
</content>
</write_to_file>
```
- Search for a pattern (search_files):
```xml
<search_files>
<path>src</path>
<regex>function\s+\w+\(</regex>
<file_pattern>*.ts</file_pattern>
</search_files>
```
- Run a command (execute_command):
```xml
<execute_command>
<command>npm install axios</command>
<requires_approval>false</requires_approval>
</execute_command>
```
## Common Tasks
1. **Create a New Component**
- "Create a new React component called Footer"
2. **Fix a Bug**
- "Fix the error in src/utils/format.ts"
3. **Refactor Code**
- "Refactor the Button component to use TypeScript"
4. **Run Commands**
- "Run npm install to add axios"
## Getting Help
- [Join the Discord community](https://discord.gg/Mjyj2Sm3)
- Check the documentation
- Provide feedback to improve Cline