Documentation

Web App

The TaskPilot web app is your control center. Connect task sources, configure AI providers, and launch coding sessions — all from your browser.

What You Can Do

Connect Task Sources

Link your Trello, GitHub, or GitLab accounts to pull in boards, repos, and issues as tasks for the AI to work through.

Choose AI Providers

Configure API keys for Claude, OpenAI, or Groq. Switch between providers per session depending on your needs.

Run Sessions

Select a board or repo, review the tasks, and launch an AI coding session. Watch progress in real time as items get checked off.

Parallel Agents

Run multiple agents simultaneously — one per card or issue — in isolated git worktrees. Changes merge back automatically.

Getting Started

Create an account

Connect a task source

After signing in you'll land on the onboarding page. Connect at least one task source:

Trello — click "Connect Trello" to authorize via OAuth
GitHub — click "Connect GitHub" to authorize via OAuth
GitLab — click "Connect GitLab" to authorize via OAuth

You can connect multiple sources and switch between them from the sidebar.

Add an AI provider API key

Paste your API key for at least one AI provider. Keys are encrypted (AES-256-GCM) before being stored — they're never visible after saving.

Provider	Key prefix	Where to get it
Claude	`sk-ant-api03-`	console.anthropic.com
OpenAI	`sk-`	platform.openai.com
Groq	`gsk_`	console.groq.com

Launch a session

Once onboarding is complete you'll land on the dashboard. Select a board or repo, review the cards/issues, and hit Start Session to begin.

Dashboard

Trello

Navigate to Trello in the sidebar to see your connected boards. Select a board to view its lists and cards.

Cards are grouped by list (To Do, In Progress, etc.)
Each card shows its checklist items and completion progress
Done cards are greyed out and excluded from sessions
When the agent completes all checklist items on a card, it automatically moves to your Done list

GitHub

Navigate to GitHub in the sidebar to browse your repositories. Select a repo to view its open issues.

Issues with markdown task lists (- [ ] item) are parsed into checkable items
The agent checks off task list items in the issue body as it works
The agent can close issues, leave comments, and create pull requests

GitLab

Navigate to GitLab in the sidebar to see your projects. Select a project to view its open issues.

Works the same as GitHub — task lists in issue descriptions become checkable items
The agent can close issues, add notes, and create merge requests

Running a Session

Select your tasks — Pick a Trello board, GitHub repo, or GitLab project from the dashboard. Review the active cards or issues that the agent will work through.

Choose a mode — Select Sequential (one card at a time) or Parallel (one agent per card, running concurrently in isolated git worktrees). Adjust the concurrency slider if using parallel mode.

Pick your AI provider — If you have multiple provider keys configured, a dropdown lets you choose which model to use. Defaults to Claude.

Select a branch — When working with a GitHub or GitLab repo, a searchable branch selector lets you choose an existing branch for the agent to commit to. Leave it on “Auto-generate” to create a new branch from the issue title (the default behavior).

Start the session — Click Start Session. The session log streams AI output in real time. In sequential mode you see a single log. In parallel mode each agent gets its own tab with a status grid showing progress.

Tasks update automatically — As the agent finishes items, your task source updates in real time. Trello cards move to Done. GitHub/GitLab task list items get checked off. The board panel refreshes automatically.

Parallel Mode

Parallel mode launches one agent per card or issue, each in an isolated git worktree. This lets multiple tasks be worked on simultaneously without conflicts.

Setting	Value
Max concurrency	1 to 5 agents (default: 3)
Per-agent cost budget	$2 (default across all providers)
Isolation	Each agent runs in its own git worktree
Merge strategy	Sequential merge after agents complete

After all agents finish, changes are merged back one at a time. If two agents modify the same files, a merge conflict may occur. The summary panel reports any conflicts so you can resolve them manually.

Settings

The Settings page (accessible from the sidebar) lets you manage all your connections and API keys at any time.

Task Sources

Connect or disconnect Trello, GitHub, and GitLab
Each source uses OAuth — click to connect and authorize in your browser
Tokens are stored securely on the server and never exposed to the client

AI Provider Keys

Add or remove API keys for Claude, OpenAI, and Groq
Keys are validated by prefix before saving (e.g. sk-ant-api03- for Claude)
All keys are encrypted with AES-256-GCM — the stored key is never displayed, even partially
The provider dropdown on the dashboard only shows providers you have keys for

Cloud Storage Workspaces

TaskPilot isn't just for code. Connect Google Drive or OneDrive in Settings and use a cloud storage folder as your workspace. Agents can read, write, and edit files directly in your connected storage.

Supported file operations

Text files — read, write, edit (find & replace), search
Google Sheets / Excel — read structured data, update specific cell ranges, append rows
Google Docs — read as Markdown, replace content, create new documents
Any file — list, search by name or content

How to use

Connect Google Drive or OneDrive in Settings
On a Trello board, open the Workspace dropdown and select your provider
Browse and select a folder — files are previewed so you can confirm it's the right one
Click Use this folder, then start a session

The workspace selector shows subfolders you can navigate into, plus a preview of the files in the current folder.

How It Works

Browser                         Server                      Task Source API
        │                                │                              │
        │  1. Sign in (email/password)   │                              │
        │───────────────────────────────>│                              │
        │        session cookie          │                              │
        │<───────────────────────────────│                              │
        │                                │                              │
        │  2. Connect source (OAuth)     │                              │
        │───────────────────────────────>│──── OAuth flow ─────────────>│
        │        token stored            │        token                 │
        │<───────────────────────────────│<─────────────────────────────│
        │                                │                              │
        │  3. Save API key               │                              │
        │───────────────────────────────>│                              │
        │        encrypt + store         │                              │
        │<───────────────────────────────│                              │
        │                                │                              │
        │  4. Select board + start       │   GET boards/repos/issues    │
        │───────────────────────────────>│─────────────────────────────>│
        │        task data               │         tasks                │
        │<───────────────────────────────│<─────────────────────────────│
        │                                │                              │
        │  5. Session streams via SSE    │                              │
        │<═══════════════════════════════│  AI agent processes tasks    │
        │        real-time output        │         │                    │
        │                                │         │  check/close task  │
        │                                │         │───────────────────>│
        │  6. Board panel refreshes      │                              │
        │<═══════════════════════════════│                              │

Task Format by Source

Trello

Cards with checklists. Each checklist item becomes a task for the agent. Structure your board with lists like "To Do", "In Progress", and "Done".

Board: My Project
      ├── To Do
      │   ├── Card: Fix auth bug
      │   │   └── Checklist:
      │   │       ├── [ ] Fix token refresh logic
      │   │       ├── [ ] Add error handling
      │   │       └── [ ] Write tests
      │   └── Card: Add dark mode
      │       └── Checklist:
      │           ├── [ ] Add theme toggle
      │           └── [ ] Update color variables
      └── Done
          └── (completed cards moved here)

GitHub / GitLab

Issues with markdown task lists. Write task lists in the issue body and the agent will check them off as it works.

Issue #42: Fix authentication bug

      Description:
      The token refresh flow is broken. Fix the following:

      - [ ] Fix token refresh logic in auth.ts
      - [ ] Add error handling for expired tokens
      - [ ] Write unit tests for the refresh flow
      - [ ] Update API docs with new error codes

Troubleshooting

I connected Trello/GitHub/GitLab but no boards or repos appear

Make sure your OAuth token hasn't expired. Go to Settings, disconnect the source, and reconnect it. For GitHub, ensure the OAuth app has access to the repos you expect (check your GitHub OAuth app permissions).

The session started but nothing is happening

Check that your AI provider API key is valid and has sufficient credits. Go to Settings to verify your key is configured. If using Claude, make sure you have @anthropic-ai/claude-code installed globally on the server.

Can I run multiple sessions at the same time?

Each user is limited to one active session at a time. Wait for the current session to finish, or stop it before starting another. In parallel mode, the concurrency limit controls how many agents run simultaneously within a single session.

Parallel mode has merge conflicts

When multiple agents edit the same files, merge conflicts can occur during the sequential merge phase. The summary panel will flag these. Resolve them manually in your working directory after the session finishes.

The provider dropdown only shows Claude

The dropdown only appears when you have two or more provider keys configured. Go to Settings and add API keys for OpenAI or Groq to see additional options.

Where is my data stored?

TaskPilot uses Turso (cloud SQLite) for all persistent data. Passwords are hashed with bcrypt. API keys are encrypted with AES-256-GCM. OAuth tokens are stored server-side and never sent to the client. Session cookies are HTTP-only and signed.

Security

Passwords hashed with bcrypt — managed by Better Auth, never stored or logged in plaintext
API keys encrypted at rest (AES-256-GCM) — decrypted only at the moment a session is launched, never returned to the browser
OAuth tokens stored server-side only — Trello, GitHub, and GitLab tokens are never sent to the client
HTTP-only session cookies — signed with BETTER_AUTH_SECRET, inaccessible to JavaScript
All server functions authenticated — every API route checks the session before accessing user-specific data

Session History

The /history page keeps a complete record of every session you have run. Each entry captures the task source, provider, duration, cost, and final status.

Filters & Sorting

Source — filter by Trello, GitHub, or GitLab
Status — show only completed, failed, or cancelled sessions
Sort — order by date, cost, or duration

Session Detail View

Click any session to open the detail view. It shows the full event log — you can replay every step the agent took, including file edits, tool calls, and task source updates. For parallel sessions, use the agent filter dropdown to isolate events from a specific agent.

Actions

Delete — permanently remove a session record
Retry — re-launch a failed or partially completed session with the same configuration

Cost Tracking & Analytics

The /analytics page gives you a clear picture of how your AI spend breaks down across sessions, providers, and time.

Summary Cards

Card	Shows
Total Spend	Cumulative API cost across all sessions
Sessions	Number of completed, failed, and total sessions
Tasks Completed	Checklist items and issues resolved by the agent
Tokens Used	Total input and output tokens consumed

Charts

Daily spend chart — bar chart showing cost per day over the selected time range
Provider breakdown — pie chart splitting spend by Claude, OpenAI, and Groq

Monthly Budget

In Settings, set a monthly budget and an alert threshold (e.g. 80%). When your spend crosses the threshold, a warning banner appears on the dashboard. The analytics page shows a progress bar against your configured budget.

Task Dependencies

TaskPilot automatically detects dependency markers in card descriptions and issue bodies. When the agent encounters these markers, it reorders tasks to respect the dependency graph.

Supported Markers

Depends on #12
      Blocked by #7

Both formats are recognized. The #N refers to the card number (Trello) or issue number (GitHub/GitLab) within the same board or project.

How It Works

Tasks are reordered topologically so dependencies are always processed first
In parallel mode, an agent will wait for its dependency to finish before starting
Circular dependencies are detected and flagged — the session log warns you so you can fix the task descriptions

UI Indicators

Cards and issues with dependencies show "Blocked by #N" chips on the dashboard. Blocked cards appear dimmed until their dependencies are resolved.

PR/MR Automation

TaskPilot can automatically create pull requests (GitHub) or merge requests (GitLab) after a session completes. Configure this from Settings > PR Automation.

Configuration Options

Option	Description
Enable	Toggle PR/MR creation on or off globally
Draft mode	Create PRs/MRs as drafts so you can review before merging
Auto-link issues	Automatically reference the source issue in the PR/MR description with closing keywords
Branch pattern	Template for branch names (e.g. `taskpilot/issue-{{number}}`)

Behavior

After a session finishes, the agent's changes are pushed to a new branch and a PR/MR is created automatically
Works with both GitHub (pull requests) and GitLab (merge requests)
For Trello-sourced tasks, the PR URL is attached to the card as a comment
PR/MR descriptions include a summary of what the agent changed and which tasks were completed

Real-Time Updates

TaskPilot uses webhooks to push task source changes to the UI as they happen, so the dashboard stays in sync without manual refreshes.

Webhook Setup by Source

Trello — webhooks are registered automatically when you connect your account. No manual configuration needed.
GitHub — add a webhook in your repository settings pointing to your TaskPilot instance. Select "Issues" and "Pull request" events.
GitLab — add a project webhook in Settings > Webhooks pointing to your TaskPilot instance. Enable "Issues events" and "Merge request events".

Connection Status

The sidebar shows a connection status dot next to each linked source:

Green — webhook active, receiving events
Amber — connected but webhook not configured (polling fallback active)
Gray — source not connected

Polling Fallback

When webhooks are unavailable, TaskPilot falls back to polling. During an active session, the board panel polls every 5 seconds. When idle, polling is disabled to minimize API usage.

What's New

The /updates changelog page tracks every notable change to TaskPilot. Visit it any time to see what has been added, improved, or fixed.

A notification banner appears at the top of the dashboard when there are updates you haven't seen yet
The sidebar shows a badge on the "What's New" link with a count of unread entries
Dismiss the banner or visit the page to mark updates as read