Tasks

Tasks are AI agent processes that run on your server and stream their output to your device in real time. You can start a task from anywhere, monitor it as the agent works, respond to questions and permission prompts, and continue a conversation after the task completes.

Providers

PocketDev supports four agent providers. Each provider has different capabilities and is suited to different kinds of work.

Provider and model are selected when creating a task. Tool paths for each CLI are configured during server setup.

Creating a Task

To start a new task:

1. Tap the + button on the Tasks screen
2. Write your prompt describing what the agent should do
3. Select a provider (Claude, Codex, Copilot, or Shell) and optionally a model
4. Optionally pin files from your repository for focused context
5. Choose a task mode (see below)
6. Tap Start Task

Modes

Default mode gives the agent full execution permissions. It reads files, runs commands, and applies edits automatically as it works.

Plan mode runs the agent with restricted permissions. Instead of making changes, the agent produces a proposed plan — a list of steps it would take — for you to review and approve before anything is executed.

Live Stream

While a task is running, output streams to your device over a WebSocket connection. The stream is organized into activity cards grouped by what the agent was doing at each step.

Activity Categories

The result card appears when the agent produces final text output. Reasoning previews (thinking) are shown inline within activity cards.

Task Checklist

When an agent calls TodoWrite (Claude) or update_plan (Codex), the stream displays a collapsible Tasks card showing each to-do item with its current status — pending, in progress, or completed. A slim progress strip also appears below the status bar showing how many items are done out of the total. Both are only shown when the agent actually produces a checklist; tasks that don't use TodoWrite show neither.

Context Limit

When Claude's context window approaches capacity, PocketDev detects the warning in the terminal output and surfaces a prompt asking whether to run /compact. Choosing "Run /compact" sends the command to the Claude session, which summarises the conversation history to free context space and lets the task continue.

Raw Logs

Toggle the raw log view to see unprocessed output lines directly from the agent CLI. Raw logs are what gets stored for history — the structured activity view is rebuilt live from the current session.

Permissions and Questions

The agent may pause mid-task to ask for your approval or input. When this happens, a sheet slides up from the bottom of the task screen with the request.

Request Types

Tap your answer and the agent resumes. If you're away from your device when a permission is needed, you'll receive a push notification so you can respond.

Steering a Running Task

While a task is running you can interact with it directly from the task detail screen without stopping or restarting it.

Quick Commands (Claude)

A row of one-tap command buttons appears at the bottom of the screen when a Claude task is active. Tapping a button sends the command directly to the Claude session:

Steering Input

A text field labelled Steer the agent… is shown for all running tasks. Type a message and tap send to inject it as raw input into the agent's session. Use this to redirect the agent mid-task — for example to refocus it on a different file or correct a misunderstanding — without killing and restarting.

Multi-Turn Conversations

Claude and Codex tasks support continuation. After a task completes, you can send a follow-up message and the agent will resume the same session, retaining full context from the previous exchange.

When a task has more than one turn, the prompt card is replaced by a conversation view showing all turns — your messages and the assistant's responses — as a familiar chat thread. Each new turn is tracked and stored for history alongside the original task.

Continuation is not available for Copilot or Shell tasks.

Debug Tools

When a task fails, a debug button appears in the task status bar. Tapping it opens the debug sheet, which inspects the task's output logs and your server's tool configuration to pre-select the most likely cause of failure.

Auth Repair

If the agent CLI is not authenticated — expired token, logged out, or revoked credentials — the debug sheet will pre-select the auth issue and walk you through re-authenticating without going through the full tool install wizard again.

Task History

Completed tasks are listed on the Tasks screen. Raw logs are cached locally on your device for fast access. If the local cache is missing (for example after reinstalling the app), logs are fetched from the server on demand.

Structured activity data — activity cards, conversation history, result text — is only available for the current live session. Historical task viewing always uses the raw log feed.

Wire Protocol Reference

Tasks use a WebSocket connection between your device and the PocketDev agent. Commands are messages your device sends to the server; events are messages the server sends back.

Commands

Events