# Launching Agents
Stop copy-pasting task descriptions into ChatGPT. Stop re-explaining context every time you want AI help. With Valdr, you click **Launch** and an agent picks up the task with everything it needs: description, acceptance criteria, linked requirements, checklist state, and project context. **You don't prompt. You delegate.**

All agent sessions run locally within your workspace and are recorded for inspection.

{{< thumbcard src="/images/ui/tasks/task-agent-sessions-tab.png" alt="Agent Sessions tab with launcher and session history" caption="7 sessions across multiple providers—launch more, compare results, and know exactly what happened" >}}

## What this page covers

- Where to launch agents
- Launcher presets (one-click configurations)
- Full configuration options
- Session monitoring and comparison
- Best practices for task, review, and audit workflows

## Two launch points: speed or control

### Quick launch (Overview sidebar)

From the task sidebar, you're always one click away:

1. Select a preset
2. Click **Launch**
3. Work on something else

The agent inherits everything. No prompting, no copy-paste, no context re-establishment. **This is what "delegation" actually means.**

### Full control (Agent Sessions tab)

Need to tweak settings for this specific run? The Agent Sessions tab gives you the complete launcher:

- See all past sessions before launching another
- Configure every parameter inline
- Compare provider/model performance before choosing

Use this when you want to experiment with different models or adjust reasoning effort.

## Launcher presets: your playbook

Launcher presets are pre-configured agent setups that encode your best practices. Instead of configuring from scratch every time, **you codify what works once and reuse it consistently**.

### What presets capture

| Setting | What it controls |
|---------|------------------|
| **Provider** | AI backend (Anthropic, Codex, Ollama) |
| **Model** | Specific model within provider |
| **Temperature** | Creativity vs. consistency |
| **Reasoning effort** | How much the model "thinks" |
| **Worktree** | Whether to provision an isolated git branch |

### Example presets

- **Coder – Anthropic** — Claude for implementation tasks
- **Codex SDK** — OpenAI's Codex for code-heavy work
- **Ollama Local** — On-premise execution for sensitive codebases

Each shows its provider icon so you can identify them at a glance.

> [!TIP]
> **Reusable configs:** Create presets in [Settings > Provider Packs](../../settings/) for your specific workflows. Once configured, launching agents is always consistent—no recreating settings, no "how did I configure that last time?" questions.

## Configuration deep dive

When you need precise control, every parameter is at your fingertips:

### Agent handle

The registered agent identity (`@documentation-author`, `@code-reviewer`):

- Determines which system prompts load
- Links to agent capabilities and permissions
- Defines the "personality" and expertise of the session

### Role

What function the agent performs on this task:

| Role | Purpose | When to use |
|------|---------|-------------|
| **task** | Implement the work | Initial development |
| **reviewer** | Evaluate and provide feedback | After implementation |
| **auditor** | Verify compliance and quality | Before sign-off |

**The role shapes how the agent approaches the task.** A reviewer reads code critically; a task agent writes it confidently.

### Provider and Model

Choose your AI backend and specific model:

- **Codex SDK** — GPT-5.1 Codex for code generation
- **Anthropic** — Claude Opus 4 for complex reasoning
- **Ollama** — Local models (Llama, Mistral) for air-gapped environments

Different tasks benefit from different models. Run a complex architecture spike on Opus; run a simple bug fix on a local model. **You're not locked in—you choose the right tool for each job.**

### Temperature

Control the creativity-consistency tradeoff:

| Range | Behavior | Best for |
|-------|----------|----------|
| `0.0-0.3` | Deterministic, focused | Code implementation |
| `0.4-0.7` | Balanced | General tasks |
| `0.8-1.0` | Creative, varied | Brainstorming, documentation |

Default: `0.2` for code tasks. **Predictable output beats surprising output when shipping features.**

### Reasoning effort

How much "thinking" the model does before responding:

- **low** — Quick responses, less deliberation
- **medium** — Balanced (default)
- **high** — Thorough reasoning, better for complex problems

Bump to **high** for architectural decisions or tricky bugs. Keep at **medium** for routine tasks.

### Instructions

Add context specific to this run:

- Clarify ambiguous requirements
- Specify coding conventions
- Request particular approaches
- Point out edge cases to consider

**Instructions compound with the task description.** The agent sees both—use instructions for "this session only" guidance.

### Worktree

Toggle isolated git branches:

| Setting | What happens |
|---------|--------------|
| **Enabled** | Agent gets its own branch, commits freely, generates clean diffs |
| **Disabled** | Agent works in main workspace |

With worktree enabled, agents can:

- Make commits without touching your main branch
- Generate diffs for easy review
- Create pull requests when done

**This is how you isolate reviewable changes.** Worktrees keep agent changes off your active branch while you inspect them. They are a workflow boundary, not an OS sandbox.

## What happens when you click Launch

{{% steps %}}

### Session spins up

Valdr creates a session with:

- Unique session ID (ULID format)
- Task context loaded automatically
- Agent prompts assembled from registry
- Worktree provisioned (if enabled)

### Agent executes

The agent works through the task:

- Reads description and acceptance criteria
- Executes tools (file operations, shell commands)
- Generates code, reviews, or audits
- Updates progress visible in real-time

### Session closes

When finished:

- Status changes to "Closed"
- Duration and token usage logged
- Session appears in history
- Task can move to next status

{{% /steps %}}

**You don't babysit.** Launch, work on something else, come back to results.

## Session history: full visibility into what agents did

Every session is recorded. No black boxes, no "what did the AI do?" mysteries.

### Session card at a glance

Each session shows:

- **Session ID** — Click for full transcript
- **Role badge** — task, reviewer, or auditor
- **Status** — Running (green pulse) or Closed (checkmark)
- **Provider** — Which AI backend
- **Duration** — Total execution time
- **Time** — When it ran

### Expand for details

Click the chevron to see:

- Full session ID
- Token breakdown (input, output, cached)
- Tool call count
- Commands executed

### Full session view

Click **View session** to open the complete [Agent Sessions](../../agent-sessions/) detail page—full transcript, every tool call, complete local audit trail.

## Session comparison: optimize your agent strategy

The analytics panel answers: "Which provider/model works best for this kind of task?"

### Metrics you can compare

| Tab | What it shows |
|-----|---------------|
| **Tokens** | Input, output, cached (spot cost drivers) |
| **Tools** | Tool call frequency |
| **Commands** | Shell commands executed |
| **Duration** | Time comparison |

### Group by Provider, Model, or Role

Segment the chart to understand patterns:

- **Provider** — Is Codex faster than Anthropic for this task type?
- **Model** — Does Opus outperform Sonnet enough to justify the cost?
- **Role** — How do reviewer sessions compare to task sessions?

**This is how you build intuition.** Run experiments, see results, adjust your presets.

## Workflows that ship

### Task implementation (the common path)

1. Open task, verify description and acceptance criteria look right
2. Select your **task** preset (e.g., "Coder – Anthropic")
3. Click **Launch**
4. Work on something else or watch in real-time
5. When closed, review the output
6. Launch a **reviewer** session to verify

**Time to first agent result: under 30 seconds.**

### Code review (quality gate)

1. After task session completes, click **Launch** again
2. Select a **reviewer** preset
3. The reviewer sees the task context AND the changes made
4. Review feedback appears in the Reviews tab with structured findings

**Catch issues before they ship.** Reviewer agents don't rubber-stamp—they find real problems.

### Quality audit (compliance check)

1. Before marking a task Done, launch an **auditor** session
2. Auditor verifies against acceptance criteria
3. Structured pass/fail assessment with specific findings

**Prove your work meets the spec.** Auditable, documented, defensible.

## When things go wrong

### Session won't start

- Check provider configuration in Settings
- Verify API keys are set
- Ensure agent handle exists in registry

### Session runs too long

- Use a smaller model for simple tasks
- Add clearer instructions to focus the agent
- Reduce max tokens if output is unnecessarily verbose

### Output quality is poor

- Bump reasoning effort to **high**
- Add more specific instructions
- Try a more capable model
- Review and improve the task description itself

**The fix is usually context.** Better input = better output.

## The result: delegation that actually works

Traditional AI assistance means you do the work of prompting, context-gathering, and result-wrangling. With Valdr agent launching:

- **Context is automatic** — No copy-paste, no re-explaining
- **Configuration is reusable** — Presets encode your best practices
- **Execution is observable** — Every session logged, every action traceable
- **Iteration is safe** — Worktrees isolate experiments from production

This is the difference between "using AI" and **operating AI at scale**.

## Next steps

- **[Agent Sessions](../../agent-sessions/)** — Deep dive into session management
- **[Settings > Provider Packs](../../settings/)** — Create custom launcher presets
- **[Agents](../../agents/)** — Manage your agent registry

**Launch your first agent now.** Open a task, select a preset, click Launch. In 30 seconds you'll see why developers don't go back to copy-pasting into ChatGPT.