# Taskr — Full Documentation

# 🚀 Welcome to Taskr - Your AI's Project Manager

Welcome to **Taskr**, the tool that turns your AI assistant into a super-organized project manager. If you've never coded before or don't know what an IDE is, don't worry—we've got you covered. This guide will walk you through everything step-by-step, in plain English.

---

## 1.1 What's Taskr All About?

### The Simple Version

You know how when you ask AI to help with a big project, it sometimes forgets what it was doing? Or gets confused halfway through? **Taskr fixes that.**

Think of Taskr as a **smart to-do list that your AI assistant can read and update automatically**. It's like giving your AI a perfect memory and a project manager's brain.

### What Makes Taskr Special?

Here's what Taskr does that regular AI can't:

**🧠 Never Forgets Context**
- Your AI remembers everything about your project, even after you close your computer and come back days later
- It knows exactly where it left off and what to do next
- No more "wait, what were we working on again?"

**📋 Smart Task Management**
- Breaks big projects into bite-sized pieces automatically
- Knows which tasks depend on others
- Works through them in the right order (no jumping around randomly)

**👥 Team-Friendly**
- Multiple AI agents can work on the same project without stepping on each other's toes
- Each agent knows who's doing what
- Perfect for when you want one agent coding while another handles research or planning

**📝 Keeps Perfect Notes**
- Documents everything it does automatically
- You can see what files were changed, what decisions were made, and why
- Great for understanding what your AI actually built

### How It Actually Works (The Technical Stuff, Explained Simply)

**The Big Picture:** Taskr is like a bridge between you and your AI that keeps everything organized.

Here's the flow:

1. **Your AI (Cursor, Claude Desktop, OpenClaw, etc.) connects to Taskr** through a quick one-time setup
2. **You tell your AI what you want to do** (like "I want an app that tracks my workout routine" or "research competitors for my new product")
3. **Your AI creates a smart plan** — a cloud-based, multi-layered breakdown that lives in Taskr (not just a flat to-do list)
4. **As it works, it updates Taskr** with what it's done and what it learned
5. **You can watch the progress** in real-time through the Taskr extension or website

The magic happens through something called **MCP (Model Context Protocol)**—but don't worry about the name. Just know it's the technology that lets your AI talk to Taskr automatically, kind of like how your phone apps talk to the internet.

### The Tools Your AI Gets (12 Superpowers)

When connected to Taskr, your AI gets 12 special abilities it didn't have before:

**For Managing Work:**
- Create new tasks when it discovers something needs doing
- Update tasks as it completes them
- Delete tasks that aren't needed anymore
- Get the next task automatically (no more asking "what's next?")
- View the entire project structure at once
- Sync completed work retroactively (catch up on anything it forgot to track)

**For Keeping Notes:**
- Write down what it's working on
- Update notes as things change
- Remove notes that are outdated
- Browse through all project documentation
- Read specific notes when needed
- Search through everything it's written

These tools mean your AI can manage itself—you just tell it what to build, and it handles the rest!

### Key Concepts (Things You'll See)

Before we dive in, here are the main things you'll encounter:

**Projects** 📁
- Think of these like folders for different things you're building
- Each project is completely separate (your recipe app won't mix with your workout tracker)
- You get a unique ID for each project (looks like: `PR_01JGYV...` - 26 characters after PR_)

**Tasks** ✅
- Individual things that need to be done
- Organized like an outline (1.0, 1.1, 1.2, 2.0, etc.)
- Each has a type: setup (preparing), analysis (researching), implementation (building), validation (checking), or testing
- Status shows if it's waiting, being worked on, done, or skipped

**Notes** 📝
- Documentation your AI writes as it works
- Different types for different info:
  - **FILE_LIST** - What files were created or changed
  - **PROGRESS** - Major milestones achieved
  - **CONTEXT** - Background info and decisions made
  - **FINDING** - Problems discovered and how they were fixed
  - **OTHER** - Everything else

**Guidance** 🎯
- Smart hints that Taskr gives your AI to keep it on track
- Changes based on what the AI is doing
- Prevents your AI from getting confused or going off-track

---

## 1.2 Quick Start - Let's Build Something!

### The Super Fast Version (5 Minutes)

**If you just want to start building right now:**

1. **Sign up** at [taskr.one](https://taskr.one) (it's free to start)
2. **Follow the setup wizard** - it walks you through connecting your AI tool step by step
3. **Tell it what to build** - just type what you want, like "I want a simple website for my bakery"
4. **Start building** - Tell your AI to "use Taskr and start working"

That's it! Your AI will take it from there.

### Recommended: Use the Taskr Extension

If you're comfortable installing extensions from the marketplace in Cursor or Windsurf, this is the easiest way to get started. The extension works right inside your editor—no switching between windows, and it handles your credentials automatically.

**How to set it up:**
1. Open the Extensions panel in Cursor or Windsurf
2. Search for **"Taskr"** and click Install
3. Click the Taskr icon in the sidebar and sign in
4. Create a new project or pick an existing one — the extension handles your credentials automatically
5. That's it! You can now see your tasks, notes, and progress right in your editor

The extension also makes it easy to switch between projects or accounts without hunting for credentials.

> **Prefer using the website instead?** No problem! The step-by-step walkthrough below covers everything you need.

### Step-by-Step Walkthrough

#### Step 1: Sign Up and Connect Your AI

1. Head over to [taskr.one](https://taskr.one) and create a free account
2. After signing up, the **setup wizard** walks you through everything:
   - **Pick your AI tool** — Choose from Cursor, Claude Code, Windsurf, or VS Code
   - **Connect it to Taskr** — The wizard gives you exactly what to copy-paste (or a one-click install for Cursor)
   - **Test the connection** — Taskr checks that everything is working before you move on

The wizard handles your credentials automatically — no need to hunt for API keys or project IDs.

**Don't have an AI tool yet?** Here are the best options:
- **[Cursor](https://cursor.com/)** ⭐ - AI-powered code editor (recommended for beginners, one-click Taskr setup)
- **[Claude Desktop](https://claude.ai/download)** - Powerful AI app with full coding capabilities, no IDE needed
- **[Windsurf](https://codeium.com/windsurf)** - Fast and modern AI code editor
- **[OpenClaw](https://openclaw.ai)** - Personal AI assistant for tasks beyond coding (WhatsApp, Telegram, etc.)

#### Step 2: Tell Your AI What to Build

Once connected, just tell your AI what you want to create. You can do this right from your code editor — no need to go back to the website.

**What to say (keep it simple!):**
- Bad: "app"
- Good: "I want an app that helps me track what books I've read"
- Great: "I want an app that tracks books I've read, lets me rate them 1-5 stars, and shows me stats about my reading habits"

Your AI will use Taskr to break your idea into a structured plan and start working through it.

#### Step 3: Watch It Work

Now that your AI has a plan, it'll start working through it. Here's what to expect:

**Your first command to the AI:**
> "Please use Taskr to get and start working on the first task"

**What happens next:**
1. Your AI connects to Taskr and gets the first task
2. It sees what needs to be done and any helpful notes
3. It starts working on it automatically
4. When done, it marks the task complete
5. It moves to the next task

**To continue working:**
> "Get the next Taskr task please"

**Other things you can say:**
- "Show me what tasks are left"
- "What have you completed so far?"
- "Create a note about what we've built"
- "Skip this task and move to the next one"

### Creating Tasks

Just tell your AI what you want to build:
> "Build a simple contact form for my website"

Your AI will:
- Look at your project
- Figure out what tasks are needed
- Create them in Taskr
- Start working immediately

**Tips:**
- For bigger projects, write down your requirements first and paste them into the chat — your AI will create a more structured plan
- You can be as brief or as detailed as you like
- **Best for everything:** Quick features, complex apps, or anything in between

---

## 1.3 What's Next?

Congrats! You're ready to build with AI that actually remembers what it's doing. Here's where to go next:

### Essential Reads
1. **[Connecting Your AI](/docs/setup)** - Detailed setup for Cursor, Claude Desktop, OpenClaw, and more
2. **[Understanding How Taskr Works](/docs/how-taskr-works)** - Deep dive into projects, tasks, and notes

### Quick Tips for Success

**Start Small** 🐣
- Your first project should be simple
- Try something like "a webpage that shows the weather" before attempting "the next Facebook"

**Be Specific** 🎯
- "Build me an app" = confused AI
- "Build me a todo list app where I can add tasks, mark them complete, and see them sorted by date" = happy AI

**Watch and Learn** 👀
- Check the Taskr extension, website, or just ask your AI about progress
- Read the notes it creates to understand what it's doing
- Don't be afraid to ask it questions about its work

**Trust the Process** 🎭
- Let your AI complete one task before asking about the next
- If something goes wrong, your AI will create a note about it
- You can always create new tasks if you think of something

### Common Questions

**"What if I don't know how to code?"**
Perfect! That's the whole point. Your AI does the coding, you just tell it what you want.

**"What if my AI gets stuck?"**
It'll create a note explaining the problem and you can help it figure out what to do next.

**"Can I use this for real projects?"**
Absolutely! Taskr is built for production use. Start small and work your way up.

**"Do I need to pay?"**
There's a free tier to get started. Paid plans give you more tool calls and additional features.

---

Ready to build something amazing? Your AI agent is waiting for instructions! 🚀

---

# 🔧 Connecting Your AI to Taskr

Most users won't need this guide—the **setup wizard** after sign-up handles everything automatically. But if you skipped the wizard, want to set things up manually, or need to connect a second AI tool, this guide walks you through it step by step.

---

## 2.1 First Things First

### What We're Doing Here

We're going to connect your AI to Taskr so they can talk to each other. Think of it like adding Taskr to your AI's contact list so they can work together.

### Choose Your Path

There are three ways to use Taskr, depending on how you like to work:

**AI Code Editors (IDEs)**
- **Cursor** ⭐ - Complete IDE with AI built-in, everything in one place
- **Windsurf** - Fast and modern IDE by Codeium
- **Antigravity** - Google's AI coding environment
- **VS Code** - Traditional IDE with built-in AI agent and MCP support (v1.102+)

These are "all-in-one" tools—your AI writes code, saves files, and manages Taskr tasks all in the same app. Great for hands-on coding.

**Claude Desktop**
- Anthropic's full-featured AI app with powerful coding capabilities
- A great option if you prefer a chat-first workflow over a traditional IDE
- Claude Desktop can read, write, and manage files, run commands, and build entire projects—all through conversation
- Works on macOS and Windows
- See [Section 2.6](/docs/setup/2-6) for setup

**OpenClaw**
- A personal AI assistant that works from WhatsApp, Telegram, or any chat app
- Goes beyond coding—handles research, email workflows, project management, and more
- Connects to Taskr through ClawHub, an open skill registry for AI agents
- See [Section 2.7](/docs/setup/2-7) for setup

**My Recommendation:** If you're building software, start with **Cursor** or **Claude Desktop**. If you want an AI that handles tasks beyond coding, try **OpenClaw**.

### Already Done the Setup Wizard?

If you followed the setup wizard after signing up (covered in the [Getting Started](/docs/getting-started) guide), you're already connected! The sections below are for manual setup — useful if you skipped the wizard, need to connect a different AI tool, or want to tweak your configuration.

### What You Need Before Starting

Good news: there's **nothing to install and no API keys to copy and paste**. You point your AI tool at Taskr's web address and it signs you in through your browser—just like logging into any website.

All you need is:

**1. A Taskr account** 🔑
- The one you signed up with. The first time your AI tool connects, a browser window opens asking you to sign in and approve the connection. Click approve and you're done—your sign-in is securely cached so you won't be asked again.

**2. A project (optional)** 📁
- Taskr automatically works in your most recent project, so you don't have to pick one to get started.
- Want to target a specific project? Just ask your AI: *"Switch Taskr to my 'Website Redesign' project"* — it has a built-in `project` tool that can list, create, and switch projects for you. No IDs to copy.

> **Why no API key and no install?** Taskr connects over the web (a remote MCP server) and signs you in with a secure browser flow (OAuth). That means **no Node.js to install, no `npx`, and no secret tokens sitting in your config files** — just a web address.

> **Prefer the old local connector?** The `npx taskr-mcp-client` bridge still works if you'd rather run a local helper (it needs Node.js installed). It's no longer required—see [Section 2.8](/docs/setup/2-8).

---

## 2.2 Setting Up Cursor

Cursor is our recommended IDE for beginners—everything in one place and easy to set up:

### Step 1: Install Cursor

1. Go to [cursor.com](https://cursor.com)
2. Download and install it
3. Open Cursor

### Step 2: Open Cursor Settings

1. Press `Cmd + Shift + J` (Mac) or `Ctrl + Shift + J` (Windows) to open Cursor Settings

### Step 3: Add Taskr MCP Server

1. Click **"Tools & MCP"** in the sidebar
2. Click **"New MCP Server"**
3. Copy and paste the configuration below into your `mcpServers` section, then save:

```json
{
  "taskr": {
    "url": "https://www.taskr.one/api/mcp"
  }
}
```

That's the whole thing—just a web address, no keys, no IDs. 🎉

### Step 4: Sign In

The first time Cursor connects to Taskr, **a browser window opens asking you to sign in and approve**. Sign in with your Taskr account and click approve. That's it—your sign-in is remembered, so you won't be asked again.

### Step 5: Verify Connection

1. Open MCP Settings again (`Cmd/Ctrl + Shift + J`)
2. Look for the **Taskr** server in your list
3. You should see a **green dot** next to it - this means it's connected! ✅
4. Click on "# tools enabled" to see all the Taskr tools available

If you see a **red dot**, click it (or reload the server) to trigger the browser sign-in again.

---

## 2.3 Setting Up Windsurf

Windsurf is the new kid on the block but works great with Taskr:

### Step 1: Install Windsurf

1. Visit [windsurf.com/editor](https://windsurf.com/editor)
2. Download and install Windsurf
3. Open it up

### Step 2: Open MCP Settings

1. Open Windsurf Settings (`Cmd + ,` on Mac, `Ctrl + ,` on Windows)
2. Click **"Open MCP Marketplace"**
3. Click the **Settings gear icon** (top right) to open `mcp_config.json`

### Step 3: Add Taskr MCP Server

1. Add the configuration below to your `mcpServers` section, then save:

```json
{
  "taskr": {
    "serverUrl": "https://www.taskr.one/api/mcp"
  }
}
```

### Step 4: Sign In

The first time Windsurf connects to Taskr, **a browser window opens asking you to sign in and approve**. Sign in with your Taskr account and approve—your sign-in is remembered for next time.

### Step 5: Verify Connection

1. In the Cascade panel, click the **three-dot menu** (⋯) in the top right
2. Look for **Taskr** in your list of MCP servers
3. You should see it listed with available tools

---

## 2.4 Setting Up VS Code

VS Code has built-in MCP support starting from version 1.102, making setup straightforward:

### Step 1: Install VS Code

1. Go to [code.visualstudio.com](https://code.visualstudio.com)
2. Download and install VS Code (version 1.102 or later)
3. Open it

### Step 2: Open MCP Configuration

1. Open Command Palette (`Cmd + Shift + P` on Mac, `Ctrl + Shift + P` on Windows)
2. Type **"MCP: Open User Configuration"** and select it

### Step 3: Add Taskr MCP Server

1. Add the configuration below to your `servers` section, then save:

```json
{
  "taskr": {
    "type": "http",
    "url": "https://www.taskr.one/api/mcp"
  }
}
```

### Step 4: Sign In

The first time VS Code connects to Taskr, **it prompts you to sign in through your browser**. Approve the connection with your Taskr account, and you're set.

### Step 5: Verify Connection

1. Open Command Palette and run **"MCP: List Servers"**
2. You should see **taskr** listed and running, with its tools available in Chat (Agent mode)

---

## 2.5 Setting Up Claude Code

Claude Code is Anthropic's AI coding agent. It runs as an extension inside VS Code and Cursor, with a built-in terminal CLI:

### Step 1: Install Claude Code

Install the extension from your editor's marketplace:
1. Open VS Code or Cursor
2. Go to Extensions (`Cmd+Shift+X` on Mac, `Ctrl+Shift+X` on Windows)
3. Search for **"Claude Code"** and click **Install**
4. When prompted, sign in with your Anthropic account

### Step 2: Add Taskr MCP Server

1. Open the integrated terminal in your editor (`` Ctrl+` `` on Windows, `` Cmd+` `` on Mac)
2. Copy and run the command below—no keys or IDs needed:

```bash
claude mcp add --transport http --scope user taskr https://www.taskr.one/api/mcp
```

### Step 3: Sign In

Inside Claude Code, run the `/mcp` command and choose to authenticate **taskr**. A browser window opens—sign in with your Taskr account and approve. Your sign-in is cached, so this is a one-time step.

### Step 4: Verify Connection

Check that Taskr is properly configured:

```bash
claude mcp list
```

You should see `taskr` listed and connected. Run `/mcp` inside Claude Code to confirm its tools are available.

---

## 2.6 Setting Up Claude Desktop

Claude Desktop is Anthropic's full-featured AI app. It connects to Taskr as a **custom connector**—no files to edit, no Node.js to install. You get a powerful way to plan, manage, and even build projects through conversation.

### What Makes Claude Desktop Great for Taskr

- **Full coding power** — Claude Desktop can read and write files, run terminal commands, and build entire projects. It's a capable coding tool on its own, not just a chat window.
- **Chat-first workflow** — Perfect if you prefer conversing with AI over navigating IDE menus and panels
- **Plan + execute** — Use it to plan your project in Taskr, then have Claude execute the work—all in one place
- **Works alongside IDEs** — You can also use Claude Desktop for planning while your IDE agent (Cursor, Windsurf) handles execution

### Step 1: Install Claude Desktop

1. Download [Claude Desktop](https://claude.ai/download) and install it
2. That's it—no Node.js, no config file. Taskr connects over the web.

### Step 2: Add the Taskr Connector

1. Open Claude Desktop
2. Go to **Settings** → **Connectors**
3. Click **"Add custom connector"**
4. Fill in:
   - **Name:** `Taskr`
   - **Remote MCP server URL:** `https://www.taskr.one/api/mcp`
5. Click **Add**

### Step 3: Sign In

1. Back on the Connectors screen, click **Connect** next to Taskr
2. A browser window opens—**sign in with your Taskr account and approve** the connection
3. Claude Desktop shows Taskr as connected ✅

### How to Use It

Once connected, just chat naturally:

- **"Create a task list for building a landing page"** — Claude uses Taskr to organize the work
- **"Switch to my Marketing project, then get the next task"** — Claude picks the project and starts working
- **"What's left to do?"** — Check progress anytime through conversation

Claude Desktop handles both the planning and execution sides of Taskr. You tell it what to build, it creates the tasks, works through them, and documents everything along the way.

> **Picking a project:** Claude Desktop doesn't have a workspace folder, so it relies on Taskr's built-in `project` tool. Just ask Claude to list or switch projects—no config edits needed.

> **Don't see "Add custom connector"?** Custom connectors are available on Claude's Free, Pro, Max, Team, and Enterprise plans. Make sure Claude Desktop is up to date.

---

## 2.7 Setting Up OpenClaw

OpenClaw is a personal AI assistant that works from WhatsApp, Telegram, or any chat app you already use. When connected to Taskr, it can manage tasks and track progress for work that goes beyond coding—research, email workflows, project management, and more.

### What is OpenClaw?

Think of OpenClaw as an AI that actually does things for you: clears your inbox, manages your calendar, handles research, and now—with Taskr—tracks all that work in an organized way. It connects to Taskr through **ClawHub**, an open registry for AI agent skills.

### Step 1: Install the Taskr Skill

Run this command to install the Taskr skill from ClawHub:

```bash
npx clawhub@latest install taskr
```

This downloads the Taskr skill and makes it available to your OpenClaw agent.

### Step 2: Configure Your Credentials

OpenClaw runs on a server without a browser, so it uses an **API key** instead of the browser sign-in (there's no browser to open on a headless gateway). Add your Taskr credentials to your OpenClaw gateway config:

```json
{
  "skills": {
    "entries": {
      "taskr": {
        "env": {
          "MCP_USER_API_KEY": "YOUR_API_KEY_HERE",
          "MCP_PROJECT_ID": "YOUR_PROJECT_ID_HERE"
        }
      }
    }
  }
}
```

- **`MCP_USER_API_KEY`** — your API key. Find it in Taskr: profile → **API Keys** → click the eye icon → copy. Keep it secret!
- **`MCP_PROJECT_ID`** *(optional)* — pins OpenClaw to a specific project. Find it under Projects (starts with `PR_`). Omit it and Taskr uses your most recent project, or let the agent switch with the `project` tool.

> Headless environments (OpenClaw, CI servers) use an API key because they can't open a browser for sign-in. Interactive tools like Cursor and Claude Desktop use the browser sign-in instead—no key required.

### Step 3: Start Using It

Once configured, your OpenClaw agent will automatically use Taskr for substantial work. Just tell it what you need:

- **"Research competitors for my new product and track your findings"**
- **"Plan out the launch for next month's campaign"**
- **"What tasks are still open from yesterday?"**

Your agent creates tasks, works through them, and writes notes—all visible in real-time on the Taskr web app or VS Code extension.

### Learn More

- [OpenClaw](https://openclaw.ai) — The AI that actually does things
- [ClawHub](https://clawhub.ai) — Skill registry for AI agents
- [Taskr on ClawHub](https://clawhub.ai/echo-of-machines/taskr) — The Taskr skill listing

---

## 2.8 Other AI Tools

If you're using something else that supports MCP, here's the universal setup.

### Interactive Tools (with a browser)

Most modern AI tools can connect to a **remote MCP server** over the web. Point yours at Taskr's URL—no install, no keys. You'll sign in through your browser on first connect:

```json
{
  "taskr": {
    "url": "https://www.taskr.one/api/mcp"
  }
}
```

Some tools use a slightly different key for the address (e.g. `serverUrl`) or want a `"type": "http"` field—check your tool's MCP docs. When the tool connects, it opens your browser to sign in and approve.

### Headless Tools (servers, CI, no browser)

If your tool runs on a server with no browser, send your **API key** as a request header instead of doing the browser sign-in:

```
x-user-api-key: YOUR_API_KEY_HERE
```

Get your API key from Taskr (profile → **API Keys**). Point the tool at `https://www.taskr.one/api/mcp` and add the header above. To pin a project, also send `x-project-id: PR_...` (optional).

### Legacy: the local `npx` bridge

If your tool only supports local (stdio) MCP servers and can't reach a URL, you can still run the local connector (requires Node.js):

```json
{
  "taskr": {
    "command": "npx",
    "args": ["-y", "taskr-mcp-client@latest"]
  }
}
```

It signs you in through your browser on first run (or run `npx taskr-mcp-client@latest auth` once). For headless use, add an `env` block with `MCP_USER_API_KEY`.

### Where to Put It

Look for:
- A file ending in `.json` with "mcp" in the name
- Settings or preferences mentioning "MCP" or "Model Context Protocol"
- Documentation about "external tools" or "integrations"

---

## 2.9 You're Connected! Now What?

### First Commands to Try

Once everything's working, try these with your AI:

**Check the connection:**
> "Can you connect to Taskr and tell me which project you're in?"

**Switch project (if needed):**
> "List my Taskr projects and switch to the Website one"

**Start working:**
> "Get the first task from Taskr and start working on it"

**See progress:**
> "What tasks have been completed in Taskr so far?"

**Continue working:**
> "Get the next task from Taskr"

### Tips for Success

**Let Your AI Lead** 🤖
- Once connected, your AI knows how to use Taskr—including picking and switching projects
- You don't need to micromanage—just check in occasionally

**Watch Progress in Real Time** 👀
- Use the Taskr extension in your editor or log into [taskr.one](https://taskr.one) to see real-time progress
- You'll see tasks moving from "open" to "in progress" to "done"
- This works no matter which tool your AI is using—IDE, Claude Desktop, or OpenClaw

**Read the Notes** 📝
- Your AI writes notes as it works
- These explain what it's doing and why
- Great for learning what's happening behind the scenes

### What If Nothing Happens?

If your AI seems stuck:
1. Ask: "Are you connected to Taskr?"
2. Ask: "Which project are you in?"
3. If still nothing, check your configuration again

---

## 2.10 Troubleshooting

### "My AI says it can't find Taskr"

**Check these things:**

1. **Did you finish the browser sign-in?**
   - The first connection opens a browser to sign in and approve. If you missed it, reconnect the server in your tool's MCP settings (or click the red dot next to Taskr) to trigger it again.
2. **Is the web address exactly right?**
   - It must be `https://www.taskr.one/api/mcp`
3. **Any typos in the JSON?**
   - Every quote mark needs a matching pair
   - Don't accidentally delete any commas or brackets
4. **Is your tool up to date?**
   - Remote MCP + browser sign-in needs a recent version of your AI tool

### "The browser didn't open for sign-in"

1. In your tool's MCP settings, find **taskr** and reconnect / re-authenticate it
2. Approve the sign-in in the browser that opens
3. Still nothing? Make sure pop-ups aren't blocked, and that you're signed in to [taskr.one](https://taskr.one) in your default browser

### "It keeps asking me to sign in"

1. Your cached sign-in may have expired or your account access changed.
2. Reconnect / re-authenticate **taskr** in your tool's MCP settings to refresh it.
3. If it persists, sign out of Taskr in the browser, sign back in, then reconnect.

### "I see a JSON error"

The configuration is very picky about formatting. Common mistakes:
- Missing a comma between lines
- Extra comma at the end of the last item
- Missing quotes around text
- Mismatched brackets or braces

**Pro tip:** Click **"Start Setup"** on your project page—the wizard gives you a configuration that's guaranteed to be formatted correctly!

### Still Stuck?

1. Look for the **"Connect your code editor"** banner on your project page and click **"Start Setup"**
2. Make sure you're using the latest version of your AI tool
3. Try a different AI tool to see if the problem is tool-specific

---

## Next Steps

Now that you're connected:

1. **[Learn How Taskr Works](/docs/how-taskr-works)** - Understand the magic behind the scenes

Remember: The hardest part is over! Once you're connected, it's smooth sailing from here. Your AI knows what to do—you just need to tell it what you want! 🚀

---

# 🎯 How Taskr Actually Works

Let's peek behind the curtain and see how Taskr keeps your AI organized! Don't worry—we'll explain everything in simple terms, but also show you what's really happening in the code if you're curious.

---

## 3.1 Projects - Your AI's Different Workspaces

### The Simple Version

Think of projects like different notebooks on your desk. When you're working on your recipe app in one notebook and your workout tracker in another, you don't want the pages getting mixed up. Projects work the same way for your AI.

### What Actually Happens

Every project gets a unique ID that looks like this: `PR_ABC123XYZ...` (PR stands for "Project"). Your AI uses this ID to know which "notebook" it's working in.

**Real example from your project:**
- When you create a project for "My Recipe App", Taskr generates: `PR_01JGYVYMA0Q0K8OOFK12345678`
- All tasks for recipes go in this project
- Your workout tracker gets its own ID: `PR_01JGYVYMA0Q0K8OOFK87654321`
- They never mix!

### Why This Matters

**Without project isolation:**
- Your AI might add "Do 50 pushups" to your recipe app 😅
- Tasks from different projects would get jumbled
- You'd lose track of what belongs where

**With project isolation:**
- Each project is a clean slate
- Your AI focuses on one thing at a time
- Switch projects = switch context completely

### Behind the Scenes

In the database, every task, note, and piece of data has a `project_id` field that ties it to your project. It's like a label on every page saying which notebook it belongs to. The system uses PostgreSQL's Row Level Security (RLS) to ensure data never leaks between projects—even at the database level!

---

## 3.2 Task Lists - Keeping Features Organized

### The Mental Model

Imagine you're organizing a big party:
- **"Food & Drinks"** task list - Buy ingredients, prep food, set up bar
- **"Decorations"** task list - Hang lights, arrange flowers, set tables
- **"Entertainment"** task list - Create playlist, set up games, test speakers

Each list is independent. You can work on decorations without thinking about food. That's exactly how task lists work in Taskr!

### Why Task Lists Are Brilliant

**Without task lists:** Everything would be one giant mess of tasks
**With task lists:** Each feature/component stays organized in its own space

Your AI agent naturally stays focused because it works on one task list at a time. When working on "User Authentication," it won't suddenly jump to "Payment Processing."

### How They're Created

Task lists appear automatically when your AI creates tasks:

1. **When you ask your AI to plan a feature** - "Generate tasks for adding user profiles"
2. **When your AI creates a batch of tasks** - It organizes them into logical lists
3. **When your AI breaks down work** - Related tasks get grouped into feature-based lists

### How It Works Under the Hood

Task lists aren't a separate thing—they're actually the **top-level tasks** in your project. When your AI creates a task list called "User Authentication," it's really creating a root task with a special `TL_` prefix ID. All the subtasks underneath it use `TS_` prefix IDs.

This unified design means task lists and tasks share the same hierarchy—a task list is just a task that happens to be at the top level. Your AI's `get_task` function filters by task list to stay focused on one feature at a time.

---

## 3.3 Tasks - The Building Blocks

### Understanding Task Hierarchy

Tasks are organized like an outline for a paper:

```
1.0 Build user authentication (parent task)
  1.1 Set up database tables (subtask)
    1.1.1 Create users table (sub-subtask)
    1.1.2 Add password hashing
  1.2 Create login page
    1.2.1 Design login form
    1.2.2 Add validation
  1.3 Implement logout
```

**The clever bit:** When all of 1.1.1 and 1.1.2 are done, 1.1 automatically completes. When all of 1.1, 1.2, and 1.3 are done, 1.0 completes itself!

### Task Types Explained

Each task has a type that tells your AI what kind of work it is:

- **setup** 🔧 - Getting things ready (installing packages, creating folders)
- **analysis** 🔍 - Figuring things out (researching APIs, planning approach)
- **implementation** 💻 - Actually building stuff (writing code, creating features)
- **validation** ✓ - Making sure it works (checking logic, reviewing code)
- **testing** 🧪 - Proving it works (writing tests, running test suites)

### Task Status Flow

Tasks move through statuses like a conveyor belt:

1. **open** ⭕ - Waiting to be started
2. **wip** 🔄 - Being worked on right now (work in progress)
3. **done** ✅ - Completed successfully
4. **skipped** ⏭️ - Intentionally skipped (not needed)

### The One-Task Rule

Here's something crucial: **Your AI can only work on ONE task at a time**.

Why? Because multitasking leads to confusion! When your AI marks a task as "wip," it gets exclusive ownership through a `wip_agent_id` field. No other agent can touch it, and this agent can't start another task until it finishes this one.

This is enforced in the database with PostgreSQL triggers and the MCP handler code!

### Creating New Tasks

Your AI creates tasks using the `create_task` tool:

```
Your AI: "I need to break this down into smaller pieces"
Creates: Subtasks under the current task, or a whole new task list
Speed: Instant
Control: Your AI decides the structure based on your requirements
```

**Tip:** For bigger projects, paste your requirements into your AI's chat first — it'll create a more thorough, well-structured task hierarchy.

### The Magic of `get_task`

When your AI calls `get_task`, here's what happens behind the scenes:

1. **Checks for existing WIP** - "Am I already working on something?"
2. **Looks for next logical task** - "What's the next 'open' task in order?"
3. **Marks it as WIP** - "This is mine now!"
4. **Returns full context** - Task details + notes + guidance rules
5. **Prevents conflicts** - No other agent can claim this task

The database function `get_task_for_agent` handles all this atomically!

---

## 3.4 Notes - Your AI's Memory System

### What Notes Really Are

Notes aren't just random text—they're structured memories that help your AI understand what happened before. Think of them like:
- **Sticky notes** on important pages
- **Margin notes** in a textbook
- **Lab notebook** entries for experiments

### The Five Note Types

**FILE_LIST** 📁
- "I changed these 5 files"
- Lists what was modified and why
- Helps track the scope of changes

**PROGRESS** 📈
- "I finished the login system!"
- Major milestones and achievements
- Only for big wins, not every tiny task

**CONTEXT** 📚
- "We're using JWT tokens because..."
- Background info and decisions
- The "why" behind choices

**FINDING** 🔍
- "Found a bug in the validation"
- "The API returns data differently than expected"
- Discoveries, issues, and solutions

**OTHER** 📝
- Everything else
- General observations
- Last resort category

### How Notes Connect to Tasks

Every note can be "attached" to a task using `task_id`. This creates a timeline:

```
Task 1.2: "Create login form"
  └─ NOTE (FILE_LIST): Modified login.tsx, auth.css
  └─ NOTE (FINDING): Form library has built-in validation
  └─ NOTE (PROGRESS): Login form complete and working
```

Future agents can see exactly what happened during each task!

### Note IDs

Each note gets a unique ID like `NT_ABC123XYZ...` (NT = Note). You'll see these in the corner of note cards in the web interface. You can reference them like: "As mentioned in note NT_ABC123..."

### Database Implementation

Notes are stored in the `notes` table with:
- Strong typing via PostgreSQL enum for note types
- Full-text search indexing for the search_notes function
- Soft deletion (deleted_at field) to preserve history
- Task association through foreign key relationship

---

## 3.5 Dynamic Guidance - Keeping Your AI on Track

### The Problem It Solves

Ever notice how AI sometimes "drifts" during long conversations? It might start organized but gradually forget the rules or best practices. Dynamic guidance fixes this!

### How It Works

Every time your AI uses a Taskr tool, the response includes three parts:

```json
{
  "data": {
    // The actual result (task created, note saved, etc.)
  },
  "rules": [
    // Markdown rules relevant RIGHT NOW
    "- Work on one task at a time",
    "- Mark tasks complete before moving on",
    "- Create notes for important discoveries"
  ],
  "actions": [
    // Suggested next steps
    "Call get_task to continue working",
    "Create a PROGRESS note if you completed something major"
  ]
}
```

### Context-Aware Adaptation

The guidance changes based on what your AI is doing:

- **Starting work?** → Rules about task selection
- **Creating notes?** → Rules about note types and quality
- **Generating tasks?** → Rules about organization and structure
- **Updating status?** → Rules about completion criteria

### Real Examples

**When calling `get_task`:**
- Guidance includes the "process-task-list" rule
- Reminds AI to work sequentially
- Suggests creating notes for discoveries

**When calling `create_note`:**
- Guidance includes note type definitions
- Reminds about task attachment
- Suggests using specific types for specific content

### Smart Actions

Beyond rules, Taskr also sends **actions** with its responses—these are practical next steps tailored to what your AI just did:

- **Workflow actions** — Step-by-step guidance like "Step 1 complete, now drill into the relevant task list"
- **Hint actions** — Suggested tool calls like "Use `get_task_hierarchy` to verify changes" or "Create a PROGRESS note for this milestone"

These actions change dynamically based on context. After completing a task, the hints suggest getting the next one. After creating tasks, they suggest verifying the hierarchy. It's like a GPS that recalculates after every turn.

### Why This Matters

Without dynamic guidance:
- AI forgets project conventions after 50+ messages
- Starts creating wrong note types
- Might work on multiple tasks simultaneously
- Loses track of workflow requirements

With dynamic guidance:
- Every response reinforces best practices
- AI stays consistent for hundreds of tasks
- Project standards are maintained automatically
- No "drift" even in long sessions

---

## Summary - Putting It All Together

Here's how all these pieces work as a system:

1. **Projects** isolate different builds (your recipe app vs. workout tracker)
2. **Task Lists** organize features into focused workstreams
3. **Tasks** break work into hierarchical, trackable pieces
4. **Notes** capture knowledge and decisions as work happens
5. **Dynamic Guidance** keeps your AI following best practices

The beauty is that your AI handles all of this automatically through the MCP protocol. You just say "build me a recipe app" and watch the magic happen!

Each component is backed by solid PostgreSQL database design, TypeScript services, and React UI components—but you never need to worry about that. It just works! 🚀

---

## Next Steps

Now that you understand how Taskr works:
1. **[Start Building](/docs/getting-started)** - Put this knowledge to use!

---