All tools are implemented with actual functionality and can be extended with custom tools as needed.

📚 Table of Contents

• Installation
• Quick Start
• Usage Examples
• Project Structure
• Configuration
• Permission System
• Contributing
• API Documentation
• Advanced Usage
• Limitations and Considerations
• Roadmap
• License
• Acknowledgements

🚀 Installation

Prerequisites

• Python 3.8+
• API keys for Anthropic and/or OpenAI

Via pip

pip install cursor-agent-tools

From Source

git clone https://github.com/civai-technologies/cursor-agent.git
cd cursor-agent
pip install -e .  # Install in development mode

# Or with development dependencies
pip install -e ".[dev]"

Environment Setup

Create a .env file in your project root (copy from .env.example):

# Environment (local, development, production)
ENVIRONMENT=local

# OpenAI configuration
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_API_MODEL=gpt-4o
OPENAI_TEMPERATURE=0.0

# Anthropic configuration
ANTHROPIC_API_KEY=your_anthropic_api_key_here
ANTHROPIC_API_MODEL=claude-3-5-sonnet-latest
ANTHROPIC_TEMPERATURE=0.0

# Google Search API (for web_search tool)
GOOGLE_API_KEY=your_google_api_key_here
GOOGLE_SEARCH_ENGINE_ID=your_search_engine_id_here

# Ollama configuration (for local models)
OLLAMA_HOST=http://localhost:11434

⚡ Quick Start

import asyncio
from cursor_agent_tools import create_agent

async def main():
    # Create a Claude agent instance
    agent = create_agent(model='claude-3-5-sonnet-latest')
    
    # Chat with the agent
    response = await agent.chat("Create a Python function to calculate Fibonacci numbers")
    print(response)

if __name__ == "__main__":
    asyncio.run(main())

🔍 Usage Examples

Chat with Different Models

import asyncio
from cursor_agent_tools import create_agent

# Use Claude
claude_agent = create_agent(model='claude-3-5-sonnet-latest')
response = await claude_agent.chat("What's a good way to implement a cache in Python?")

# Use OpenAI
openai_agent = create_agent(model='gpt-4o')
response = await openai_agent.chat("What's a good way to implement a cache in Python?")

# Use Ollama (local open-source model)
ollama_agent = create_agent(model='ollama-llama3')
response = await ollama_agent.chat("What's a good way to implement a cache in Python?")

Using Local Ollama Models

import asyncio
from cursor_agent_tools import create_agent

async def main():
    # Create an agent with a local Ollama model
    # Models must be pulled via Ollama CLI first: ollama pull MODEL_NAME
    agent = create_agent(
        model='ollama-llama3',  # prefix with "ollama-" followed by model name
        host='http://localhost:11434',  # optional, this is the default
        temperature=0.3  # optional temperature setting
    )
    
    # Chat with the local model
    response = await agent.chat("Write a Python script to download YouTube videos")
    print(response)
    
    # Handle multimodal capabilities if model supports it
    # image_path = "/path/to/your/image.png"
    # image_response = await agent.query_image(
    #     image_paths=[image_path],
    #     query="What does this code screenshot show?"
    # )
    # print(image_response)

if __name__ == "__main__":
    asyncio.run(main())

Supported Ollama Models

The agent supports any model available in Ollama. Some popular options include:

• ollama-llama3 - Meta's Llama 3 model
• ollama-llama3.1 - Meta's Llama 3.1 model
• ollama-mistral - Mistral AI's model
• ollama-gemma3 - Google's Gemma model
• ollama-deepseek-r1 - DeepSeek's reasoning model
• ollama-phi4 - Microsoft's Phi model
• ollama-qwen2.5 - Qwen's latest model

For a complete list of available models, see Ollama Library.

Note that tool calling and multimodal support depend on the capabilities of the specific model.

Creating a Custom Agent with Custom System Prompt

import asyncio
from cursor_agent_tools import create_agent

async def main():
    # Define a custom system prompt for a coding tutor
    custom_system_prompt = """
    You are an expert coding tutor specialized in helping beginners learn to code.
    When asked coding questions:
    1. First explain the concept in simple terms
    2. Always provide commented example code
    3. Suggest practice exercises
    4. Anticipate common mistakes and warn against them
    
    Be patient, encouraging, and avoid technical jargon unless you explain it.
    Focus on building good habits and understanding core principles.
    """
    
    # Create agent with custom system prompt
    coding_tutor = create_agent(
        model='claude-3-5-sonnet-latest',
        system_prompt=custom_system_prompt
    )
    
    # Example interaction with the custom agent
    student_question = "I'm confused about Python list comprehensions. Can you help me understand them?"
    
    response = await coding_tutor.chat(student_question)
    print(response)
    
    # Example using image analysis capabilities
    image_path = "/path/to/your/image.png"
    image_response = await coding_tutor.query_image(
        image_paths=[image_path],
        query="What does this code screenshot show and what issues do you see?"
    )
    print(image_response)
    
    # The response will follow the guidelines in the custom system prompt,
    # explaining list comprehensions in a beginner-friendly way with examples, 
    # practice exercises, and common pitfalls to avoid

if __name__ == "__main__":
    asyncio.run(main())

This example creates a specialized coding tutor agent with a custom personality and behavior guidelines. You can similarly create custom agents for various domains by crafting appropriate system prompts:

• Data analysis assistant (focusing on pandas/numpy)
• DevOps automation expert (for CI/CD and deployment scripts)
• Documentation writer (generating well-structured docs from code)
• Security code reviewer (identifying vulnerabilities in code)
• Algorithm optimization specialist (improving performance)

Interactive Mode

from cursor_agent_tools import run_agent_interactive
import asyncio

async def main():
    # Parameters:
    # - model: The model to use (e.g., 'claude-3-5-sonnet-latest', 'gpt-4o')
    # - initial_query: The task description
    # - max_iterations: Maximum number of steps (default 10)
    # - auto_continue: Whether to continue automatically without user input (default True)
    
    await run_agent_interactive(
        model='claude-3-5-sonnet-latest',
        initial_query='Create a simple web scraper that extracts headlines from a news website',
        max_iterations=15
        # auto_continue=True is the default - agent continues automatically
        # To disable automatic continuation, set auto_continue=False
    )

if __name__ == "__main__":
    asyncio.run(main())

The interactive mode is designed to automatically continue without user interaction unless:

1. The AI explicitly requests more information from the user
2. An error occurs that requires user decision
3. The --auto flag is used, which will prompt for user input after each step
4. The maximum tool call limit is reached, prompting for user confirmation to continue

When user input is requested or provided, the system intelligently incorporates this input into the conversation flow by:

1. Using the AI model itself to generate a contextually appropriate continuation prompt
2. Seamlessly integrating the user's input with the existing conversation history
3. Maintaining the natural flow of the implementation process

Automatic User Input Detection

The interactive mode has built-in detection for when the agent is explicitly asking for user input. When the agent's response includes phrases like:

• "I need more information about..."
• "Could you provide more details on..."
• "Please let me know your preference for..."
• "What would you like me to do about..."

The system will automatically pause and wait for user input, even in auto-continue mode. This ensures that when the agent genuinely needs clarification or a decision from you, the conversation pauses appropriately.

Tool Call Limit Confirmation

For safety and to prevent runaway automation, the agent tracks the total number of tool calls made during processing a single agent response. When this count reaches a certain threshold (default: 5), the agent will request user confirmation before making more changes. This is a safeguard that:

• Prevents unintended extensive changes to your codebase
• Gives you visibility into complex operations
• Allows you to review progress before continuing
• Provides an opportunity to redirect the agent if needed

Important details about how tool call tracking works:

• The counter tracks all tool calls within one logical iteration (one agent response)
• The counter is NOT reset until new user input is provided or a new query is started
• The counter persists even when the agent continues with the same iteration

When the limit is reached, you'll