> ## Documentation Index
> Fetch the complete documentation index at: https://ulpi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Set up ULPI Tasks and start coordinating AI agents in 3 minutes

## Your AI Agents Will Be Coordinating in 3 Minutes

No complex setup. No configuration files. Just 3 simple steps.

<Info>
  **Time estimate:** 3-5 minutes

  **Prerequisites:**

  * ULPI account ([sign up free](https://app.ulpi.io/register))
  * At least one project created
  * AI assistant with MCP support (Claude Desktop, Cursor, Windsurf, etc.)
</Info>

***

## Step 1: Enable Tasks Product

<Steps>
  <Step title="Navigate to Project Settings">
    **Dashboard** → Select your project → **Settings** → **Products**

    <Info>
      **Pro tip:** Enable Tasks for your most active project first
    </Info>
  </Step>

  <Step title="Activate Tasks">
    Click **Enable** next to "Tasks"

    **Choose your plan:**

    * **Starter** (Free): 100 tasks, 3 agents, text search
    * **Pro** (\$29/mo): 1,000 tasks, 10 agents, semantic search, dependencies
    * **Enterprise** (Custom): Unlimited everything

    <Check>
      **Instant activation:** Tasks product is ready to use immediately
    </Check>
  </Step>
</Steps>

**⏱️ Time:** 30 seconds

***

## Step 2: Configure Your AI Assistant

<Tabs>
  <Tab title="Claude Desktop">
    **Add ULPI Tasks MCP server:**

    1. Open Claude Desktop settings
    2. Navigate to **Developer** → **MCP Servers**
    3. Click **Add Server**
    4. Use these settings:

    ```json theme={null}
    {
      "ulpi-tasks": {
        "command": "npx",
        "args": [
          "@ulpi/mcp-client",
          "tasks"
        ],
        "env": {
          "ULPI_API_KEY": "your-api-key-here",
          "ULPI_PROJECT_ID": "your-project-id"
        }
      }
    }
    ```

    5. **Get your API key:**
       * Dashboard → **Settings** → **API Keys** → **Create Key**

    6. **Get your Project ID:**
       * Dashboard → Select project → URL shows `/projects/123` (123 is your project ID)

    7. Restart Claude Desktop

    <Check>
      **Verify:** Start a new chat. Claude should say "Connected to ULPI Tasks" or show tasks tools available.
    </Check>
  </Tab>

  <Tab title="Cursor">
    **Add ULPI Tasks to Cursor:**

    1. Open Cursor settings (Cmd+, or Ctrl+,)
    2. Go to **Features** → **MCP**
    3. Add new MCP server:

    ```json theme={null}
    {
      "name": "ULPI Tasks",
      "command": "npx",
      "args": [
        "@ulpi/mcp-client",
        "tasks"
      ],
      "env": {
        "ULPI_API_KEY": "your-api-key-here",
        "ULPI_PROJECT_ID": "your-project-id"
      }
    }
    ```

    4. Reload Cursor (Cmd+Shift+P → "Reload Window")

    <Info>
      **Get credentials:** Dashboard → Settings → API Keys (create new key + copy project ID from URL)
    </Info>
  </Tab>

  <Tab title="Windsurf">
    **Connect Windsurf to ULPI Tasks:**

    1. Open Windsurf settings
    2. Navigate to **Extensions** → **MCP Configuration**
    3. Add ULPI Tasks:

    ```json theme={null}
    {
      "mcpServers": {
        "ulpi-tasks": {
          "command": "npx",
          "args": ["@ulpi/mcp-client", "tasks"],
          "env": {
            "ULPI_API_KEY": "your-api-key-here",
            "ULPI_PROJECT_ID": "your-project-id"
          }
        }
      }
    }
    ```

    4. Restart Windsurf
  </Tab>

  <Tab title="Other AI Tools (40+)">
    **ULPI Tasks works with any MCP-compatible AI assistant:**

    * Claude Code
    * Continue
    * VSCode Copilot
    * Cline
    * Aider
    * And 35+ more...

    **Generic setup:**

    1. Find MCP configuration in your AI tool's settings
    2. Add ULPI Tasks MCP server with command:
       ```bash theme={null}
       npx @ulpi/mcp-client tasks
       ```
    3. Set environment variables:
       * `ULPI_API_KEY` (from Dashboard → Settings → API Keys)
       * `ULPI_PROJECT_ID` (from project URL)

    <Info>
      **Need help?** Check our [assistant compatibility guide](/tasks/assistant-compatibility) or email [support@ulpi.io](mailto:support@ulpi.io)
    </Info>
  </Tab>
</Tabs>

**⏱️ Time:** 2 minutes

***

## Step 3: Register Your First Agent & Create a Task

<Tabs>
  <Tab title="Automatic (Recommended)">
    **Just ask your AI assistant to create a task:**

    ```
    You: "Create a task to refactor the authentication controller"
    ```

    **What happens automatically:**

    1. **Agent registers itself** (if first time):
       ```
       Agent: claude-desktop-main
       Status: Active
       Capabilities: ["code-generation", "refactoring"]
       ```

    2. **Task is created**:
       ```
       Task Key: BACKEND-001
       Title: Refactor authentication controller
       Status: todo
       Assigned to: claude-desktop-main
       Created: 2025-01-12 14:23:00
       ```

    <Check>
      **Zero configuration:** The agent auto-registers on first task creation. You don't need to do anything!
    </Check>
  </Tab>

  <Tab title="Manual (Advanced)">
    **Explicitly register the agent first:**

    ```
    You: "Register yourself as an agent named 'claude-main' with capabilities: code-generation, refactoring, testing"
    ```

    **Then create tasks:**

    ```
    You: "Create a task to add OAuth2 support"
    You: "Create a bug task for session timeout issues"
    You: "Create a feature task to implement user roles"
    ```

    <Info>
      **When to use manual registration:**

      * You want to customize agent name
      * You want to pre-define capabilities
      * You're setting up multiple agents at once
    </Info>
  </Tab>
</Tabs>

**⏱️ Time:** 30 seconds

***

## ✅ You're Done! What's Next?

<CardGroup cols={2}>
  <Card title="Create Your First Task" icon="plus">
    Ask your AI: "Create a task to refactor the auth system"

    **See it in action:**

    * Auto-generated task key (PROJECT-001)
    * Assigned to your agent
    * Ready to track status
  </Card>

  <Card title="View Tasks in Dashboard" icon="table">
    **Dashboard** → Your Project → **Tasks**

    See all tasks, filter by status, search by keyword
  </Card>

  <Card title="Update Task Status" icon="arrow-progress">
    Ask your AI: "Mark BACKEND-001 as in progress"

    Track progress through the workflow
  </Card>

  <Card title="Search Tasks" icon="magnifying-glass">
    Ask your AI: "What tasks are assigned to me?"

    Or: "Show me all high priority bugs"
  </Card>
</CardGroup>

***

## Common Workflows

<AccordionGroup>
  <Accordion title="🎯 Solo Developer with 1 AI Assistant" icon="user">
    **Use case:** You + Claude Desktop working on a personal project

    **Workflow:**

    1. **Create tasks as you think of them:**
       ```
       "Create a task to add dark mode support"
       "Create a bug task for mobile layout issues"
       "Create a task to improve API response times"
       ```

    2. **Let your AI track progress:**
       ```
       You: "What should we work on next?"
       Claude: "You have 3 todo tasks. Highest priority:
                FRONTEND-012 (dark mode support)"

       You: "Let's start on FRONTEND-012"
       Claude: *marks task as in_progress*
       ```

    3. **Mark completed when done:**
       ```
       You: "Dark mode is done, mark it complete"
       Claude: *marks FRONTEND-012 as completed*
       ```

    <Check>
      **Result:** Always know what needs to be done. Never lose track of work.
    </Check>
  </Accordion>

  <Accordion title="👥 Team with Multiple AI Assistants" icon="users">
    **Use case:** Team of 3 developers, each using their own AI assistant

    **Workflow:**

    1. **Each AI registers separately:**
       ```
       Developer 1 + Claude Desktop → Agent: claude-main
       Developer 2 + Cursor → Agent: cursor-main
       Developer 3 + Windsurf → Agent: windsurf-main
       ```

    2. **Assign tasks to specific agents:**
       ```
       Claude: "Create a task to refactor auth, assign to cursor-main"

       # Cursor gets notified (Pro+ only)
       Cursor: "You have a new task: BACKEND-042 (refactor auth)"
       ```

    3. **Track who's working on what:**
       ```
       You: "What is cursor-main working on?"
       Claude: "cursor-main has 2 tasks in progress:
                - BACKEND-042: Refactor auth
                - BACKEND-045: Add rate limiting"
       ```

    4. **Use dependencies to prevent conflicts:**
       ```
       Claude: "Create a task to deploy auth changes,
                depends on BACKEND-042"

       # Can't complete deployment until BACKEND-042 is done
       ```

    <Warning>
      **Pro feature:** Task dependencies and notifications require Pro or Enterprise plan.
    </Warning>
  </Accordion>

  <Accordion title="🔄 Complex Feature with Dependencies" icon="diagram-project">
    **Use case:** Building OAuth2 support (requires multiple tasks in sequence)

    **Workflow:**

    1. **Create parent task (epic):**
       ```
       "Create an epic task for OAuth2 implementation"
       → BACKEND-050 (epic)
       ```

    2. **Create sub-tasks with dependencies:**
       ```
       "Create a task to add OAuth2 database schema"
       → BACKEND-051

       "Create a task to implement OAuth2 endpoints,
        blocked by BACKEND-051"
       → BACKEND-052 (depends on BACKEND-051)

       "Create a task to add OAuth2 frontend UI,
        blocked by BACKEND-052"
       → BACKEND-053 (depends on BACKEND-052)

       "Create a task to test OAuth2 flow,
        blocked by BACKEND-053"
       → BACKEND-054 (depends on BACKEND-053)
       ```

    3. **Work through tasks in order:**
       ```
       # Complete BACKEND-051 first
       You: "Mark BACKEND-051 as completed"

       # Now BACKEND-052 can start
       You: "Start BACKEND-052"
       Claude: *marks as in_progress*
       ```

    4. **Track overall progress:**
       ```
       You: "What's the status of OAuth2 implementation?"
       Claude: "Epic BACKEND-050 progress:
                - BACKEND-051: ✅ Completed
                - BACKEND-052: 🔄 In Progress
                - BACKEND-053: ⏳ Blocked
                - BACKEND-054: ⏳ Blocked"
       ```

    <Check>
      **Result:** Complex features stay organized. Dependencies prevent premature work.
    </Check>
  </Accordion>

  <Accordion title="🔍 Find Work Using Semantic Search" icon="magnifying-glass-chart">
    **Use case:** Quickly find relevant tasks without remembering exact titles

    **Examples:**

    ```
    You: "What authentication bugs are blocking deployment?"
    Claude: "Found 2 tasks:
             - BACKEND-038: OAuth token refresh fails
             - BACKEND-041: Session cookies not secure"

    You: "What high priority work is due this week?"
    Claude: "3 tasks due by Friday:
             - FRONTEND-067: Finish mobile redesign (Critical)
             - BACKEND-072: Fix database migration (High)
             - BACKEND-080: Add error logging (Medium)"

    You: "Show me all tasks related to performance"
    Claude: "Found 5 tasks:
             - BACKEND-023: Optimize database queries
             - FRONTEND-034: Reduce bundle size
             - BACKEND-056: Add caching layer
             - ..."
    ```

    <Warning>
      **Pro feature:** Semantic search requires Pro or Enterprise plan. Starter plan has keyword search only.
    </Warning>
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="❌ Agent Registration Failed" icon="triangle-exclamation">
    **Error:** "Failed to register agent: quota exceeded"

    **Cause:** You've reached your agent limit for your plan:

    * Starter: 3 agents
    * Pro: 10 agents
    * Enterprise: Unlimited

    **Fix:**

    1. Check how many agents you have:
       ```
       "List all registered agents"
       ```
    2. **Option 1:** Delete inactive agents
    3. **Option 2:** Upgrade to Pro or Enterprise

    ***

    **Error:** "Agent name already exists"

    **Cause:** An agent with that name is already registered

    **Fix:**

    1. Use a different name: `claude-desktop-2`
    2. Or check if the agent exists:
       ```
       "Get agent information for claude-desktop"
       ```
  </Accordion>

  <Accordion title="❌ Task Creation Failed" icon="triangle-exclamation">
    **Error:** "Failed to create task: quota exceeded"

    **Cause:** You've reached your task limit:

    * Starter: 100 tasks per project
    * Pro: 1,000 tasks per project
    * Enterprise: Unlimited

    **Fix:**

    1. Check your quota:
       ```
       "Show task statistics"
       ```
    2. **Option 1:** Delete completed tasks (frees up quota)
    3. **Option 2:** Upgrade to Pro or Enterprise

    ***

    **Error:** "Creator agent not found"

    **Cause:** Agent hasn't been registered yet

    **Fix:**
    Let the agent auto-register by creating a task normally:

    ```
    "Create a task to add feature X"
    ```

    (Agent registers automatically on first task creation)
  </Accordion>

  <Accordion title="❌ Can't Update Task Status" icon="triangle-exclamation">
    **Error:** "Invalid status transition from 'todo' to 'completed'"

    **Cause:** Status workflow prevents skipping states

    **Valid workflow:**

    ```
    todo → in_progress → completed
    ```

    **Invalid:**

    ```
    todo → completed (must go through in_progress)
    ```

    **Fix:**
    Follow the correct sequence:

    ```
    "Mark BACKEND-001 as in progress"
    # ... do the work ...
    "Mark BACKEND-001 as completed"
    ```

    ***

    **Error:** "Cannot complete task. Blocked by: BACKEND-038"

    **Cause:** Task has dependencies that aren't completed yet

    **Fix:**
    Complete the blocking task first:

    ```
    1. "Mark BACKEND-038 as completed"
    2. Now you can: "Mark BACKEND-042 as completed"
    ```
  </Accordion>

  <Accordion title="🔍 Search Returns No Results" icon="magnifying-glass">
    **Problem:** Semantic search returns 0 results for obvious queries

    **Possible causes:**

    **1. Semantic search not enabled (Starter plan)**

    * Starter plan has keyword search only
    * Upgrade to Pro for semantic search

    **2. Tasks recently created (indexing delay)**

    * Wait 10-30 seconds for indexing
    * Try again

    **3. Query too vague**

    * Use more specific terms
    * Include task type, status, or priority

    **Better queries:**

    ```
    ❌ "bugs"
    ✅ "authentication bugs blocking deployment"

    ❌ "features"
    ✅ "high priority features due this week"
    ```
  </Accordion>

  <Accordion title="🔌 MCP Connection Issues" icon="plug">
    **Problem:** AI assistant doesn't recognize ULPI Tasks commands

    **Diagnosis:**

    1. Check MCP server status in your AI assistant
    2. Verify API key is correct
    3. Verify project ID is correct

    **Fix for Claude Desktop:**

    ```json theme={null}
    // Check ~/Library/Application Support/Claude/claude_desktop_config.json
    {
      "mcpServers": {
        "ulpi-tasks": {
          "command": "npx",
          "args": ["@ulpi/mcp-client", "tasks"],
          "env": {
            "ULPI_API_KEY": "sk_...",  // Must start with sk_
            "ULPI_PROJECT_ID": "123"   // Numeric project ID
          }
        }
      }
    }
    ```

    **Verify connection:**

    1. Restart your AI assistant
    2. Start new chat
    3. Check for "Connected to ULPI Tasks" message

    <Info>
      **Still stuck?** Email [support@ulpi.io](mailto:support@ulpi.io) with:

      * Your AI assistant name
      * Error message (if any)
      * MCP configuration (remove API key before sending)
    </Info>
  </Accordion>

  <Accordion title="📊 Statistics Not Updating" icon="chart-line">
    **Problem:** Task statistics show old data

    **Possible causes:**

    **1. Caching (normal)**

    * Statistics are cached for 5 minutes
    * Wait 5 minutes for fresh data

    **2. Task status not saved**

    * Check task details: `"Get task BACKEND-001"`
    * Verify status is what you expect

    **Force refresh:**

    ```
    "Show me updated task statistics"
    # Or wait 5 minutes for cache to expire
    ```
  </Accordion>
</AccordionGroup>

***

## Quick Reference

<Tabs>
  <Tab title="Essential Commands">
    ```bash theme={null}
    # Create task
    "Create a task to [description]"
    "Create a bug task for [issue]"
    "Create a feature task to [description]"

    # Update status
    "Mark [TASK-KEY] as in progress"
    "Mark [TASK-KEY] as completed"
    "Mark [TASK-KEY] as blocked"

    # Search
    "What tasks are assigned to me?"
    "Show all high priority tasks"
    "What bugs are blocking deployment?"

    # Get details
    "Get task [TASK-KEY]"
    "What's the status of [TASK-KEY]?"

    # Statistics
    "Show task statistics"
    "How many tasks do I have?"
    ```
  </Tab>

  <Tab title="Status Workflow">
    ```
    Valid Transitions:
    ==================
    todo → in_progress
    todo → cancelled

    in_progress → blocked
    in_progress → in_review
    in_progress → completed
    in_progress → cancelled

    blocked → in_progress
    blocked → cancelled

    in_review → in_progress
    in_review → completed
    in_review → cancelled

    completed → (terminal state)
    cancelled → (terminal state)
    ```
  </Tab>

  <Tab title="Task Properties">
    ```yaml theme={null}
    Task Key: PROJECT-001 (auto-generated)

    Required:
      - title: string (max 500 chars)
      - status: todo|in_progress|blocked|in_review|completed|cancelled

    Optional:
      - description: string
      - priority: critical|high|medium|low (default: medium)
      - type: feature|bug|improvement|question|task|epic (default: task)
      - estimate_hours: integer
      - due_date: ISO 8601 date
      - tags: array of strings
      - assigned_to: agent name

    Auto-set:
      - created_by: agent who created task
      - assigned_to: defaults to creator
      - started_at: when status → in_progress
      - completed_at: when status → completed
    ```
  </Tab>

  <Tab title="Subscription Limits">
    ```
    Starter (Free):
    ===============
    - 100 tasks per project
    - 3 agents per project
    - 10 dependencies per task
    - Text keyword search
    - No bulk operations
    - No notifications

    Pro ($29/month):
    ================
    - 1,000 tasks per project
    - 10 agents per project
    - 50 dependencies per task
    - Semantic vector search
    - Bulk operations (100 tasks at once)
    - Notifications

    Enterprise (Custom):
    ====================
    - Unlimited tasks
    - Unlimited agents
    - Unlimited dependencies
    - Everything in Pro +
      - Task templates
      - Advanced analytics
      - Custom workflows
      - SSO/SAML
      - SLA guarantee
    ```
  </Tab>
</Tabs>

***

## What's Next?

<Steps>
  <Step title="Learn Task Orchestration">
    [Explore workflows, dependencies, and coordination patterns](/tasks/task-orchestration)
  </Step>

  <Step title="Try Bulk Operations">
    [Learn how to manage 100+ tasks efficiently](/tasks/parallel-execution)
  </Step>

  <Step title="Explore All Tools">
    [Check the complete API reference](/tasks/api-reference) for 18 MCP tools
  </Step>
</Steps>

***

## Need Help?

<CardGroup cols={3}>
  <Card title="Documentation" icon="book" href="/tasks/task-orchestration">
    Advanced guides
  </Card>

  <Card title="Support" icon="life-ring" href="mailto:support@ulpi.io">
    Email us anytime
  </Card>

  <Card title="Community" icon="discord" href="https://discord.gg/ulpi">
    Join our Discord
  </Card>
</CardGroup>