Creating Tasks

A task is a unit of work executed by an AI agent. When you create a task, CoderFlow launches an isolated container, runs the agent with your instructions, and captures the results for your review.

Tasks vs. Objectives

You can create tasks in two ways:

• Direct tasks: Create and launch immediately when you know exactly what needs to be done. Best for simple, well-defined work.

• Tasks from objectives: Launch a task from an existing objective. Best when requirements need refinement, work is complex, or you expect multiple iterations. The objective serves as the parent record, tracking all tasks launched from it.

For straightforward fixes or small changes, direct tasks are efficient. For larger initiatives where you'll iterate on requirements, start with an objective and launch tasks from it.

Writing Instructions

Instructions tell the agent what you want to accomplish. Clear, specific instructions lead to better results.

Best Practices

• Be specific: Instead of "fix the bug," describe the symptom, expected behavior, and relevant files
• Include context: Reference related code, error messages, or test failures
• Break down complex work: Large tasks should be decomposed into logical steps
• Specify constraints: Note performance requirements, style guides, or compatibility needs
• Define success criteria: What does "done" look like? What tests should pass?

Example

Instead of:

"Fix the login issue"

Try:

"Users clicking the login button on /auth/login see a spinning loader that never resolves. The expected behavior is a redirect to /dashboard after successful authentication. Check the authentication service for timeout issues—recent logs show 504 errors from the identity provider."

Attachments

Attach files and screenshots to provide additional context.

Supported Types

• Images: Screenshots, mockups, diagrams (PNG, JPG, GIF, WebP)
• Code files: Source code, configuration, logs
• Documents: Text files, markdown, documentation

Attachments are placed in the container where the agent can access them. Reference attachments in your instructions so the agent knows to use them.

Adding Attachments

1. Click Attachments in the task form
2. Select files or paste images from your clipboard
3. Add up to 10 files, 50MB total

Alternatively, drag and drop files directly into the instructions field.

You can also paste screenshots directly into the instructions box using Ctrl+V (Cmd+V on Mac).

Importing from Jira

If your administrator has configured Jira integration, you can create tasks and objectives directly from Jira issues.

In the Web UI, click Import from Jira to search for an issue by key or text. The issue's summary, description, type, status, priority, assignee, and labels are pulled in as context for the agent. You can add additional instructions on top of the imported issue.

From the CLI, use the --jira flag:

coder run <task-type> --jira=PROJ-123

After a task completes, you can post the summary back to the Jira issue as a comment using the Post to Jira button on the task page.

Selecting Agents

Choose which AI agent will work on the task.

Available Agents

• Claude: Strong at complex reasoning and multi-step engineering tasks. Good default for most work.
• Codex: Fast at translating specifications into code. Use for straightforward coding tasks.
• Gemini: Large context window for tasks requiring deep file understanding.
• Bob: IBM's coding agent, tuned for IBM i and enterprise workloads.
• Grok: xAI's Grok Build coding agent, with adjustable effort levels.

Running Multiple Agents

Select multiple agents to run the same task in parallel, creating a task group. Each agent works independently in its own container. You can then compare their approaches and select the best result.

This is especially powerful for complex tasks where different agents might find different solutions.

Skills in Tasks

Tasks automatically inherit the skills assigned to the selected environment. Those skills are injected into the task container at launch, so the agent can invoke them immediately.

If a task needs additional skills, update the environment's skill assignments before launching the task.

Selecting Branches

Whether your environment has one or multiple repositories, you can specify which branch to use for each.

• Default branch: Used unless you select another
• Branch restrictions: Some repositories may be locked to specific branches
• New branches: You can create new branches during the approval step

The agent checks out your selected branches before starting work. During approval, you choose whether to push to the same branch, create a new one, or commit without pushing.

For CLI-created tasks, pass branch overrides with --branch. In multi-repo environments, qualify each branch with the repository name from the environment's Repositories tab:

coder run bug-fix --environment=my-env --branch=web=feature/login-fix
coder run feature --branch api=feature/search --branch ui=feature/search

The CLI also accepts the space-separated form, --branch repo=branch. Repository-qualified values are the safest form for multi-repo environments because the server validates each repository name and rejects overrides for repositories where Allow Branch Selection is disabled.

Running the Task

Once you've entered instructions and selected options:

1. Click Launch Task (or press Ctrl-Enter)
2. Task enters the queue if all agent slots are full
3. Agent starts when a slot is available
4. Live updates appear in the Activity Feed
5. Task completes when the agent finishes
6. Review results and approve, or send follow-up instructions

Task States

• Pending: Created, waiting to be queued
• Queued: Waiting for an available agent slot
• Running: Agent is actively working
• Completed: Agent finished successfully
• Failed: Agent encountered an error
• Staged: Container ready, waiting for you to start the agent

Queue Management

When all slots are occupied, tasks wait in a first-in-first-out queue. Your position is displayed in the UI. Tasks run automatically when slots open.