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.

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 (Claude provider)
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

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