Run your first agent

You have a lane ready. Now it is time to run an agent in it. ADE offers two paths depending on the scope of the task.

Two good first paths

Agent Chat (recommended for first run)
Mission (for structured work)

Use Agent Chat when the task is small and you want the fastest iteration loop. Chat is conversational — you describe what you want, the agent makes changes, you review and iterate.

Open the lane chat

Select your lane in the Lanes panel. Click the Chat button in the lane toolbar, or press Cmd+K. A new chat session opens with automatic context injection from the lane’s pack.

Choose a model (optional)

The model selector in the chat header defaults to your configured preferred model. Click it to switch models for this session. If you set up Anthropic, Claude Sonnet is a good default for a first task.

Send one narrow task

Start with something small and easy to review. Type your task description and press Enter. The agent receives your message along with the injected context and begins working immediately.See suggested first prompt below.

Watch the agent work

As the agent processes your request, you will see:

Text responses explaining what it plans to do
Tool call blocks showing file reads, writes, and terminal commands in expandable cards
A progress indicator in the chat header showing token usage

Tool calls that take more than a few seconds show a spinner with elapsed time. Click to expand and see partial output as it streams.

Review the diff

After the agent finishes, switch to the Files view (or stay in the lane’s center pane) to inspect what changed. ADE shows a side-by-side diff of every modified file.If the changes look good, you can commit directly from the Files view or ask the agent to commit for you.

If the agent asks a question, a question modal appears in the chat. Read the options, select your answer, and the agent continues. This is ADE’s AskUserQuestion flow — the agent pauses cleanly instead of guessing when it needs your input.

Use a Mission when the task needs a formal plan, parallel workers, validation, or a stronger audit trail. Missions are overkill for a first test — but if you want to see ADE’s full orchestration, here is how.

Open Missions

Click Missions in the left sidebar. Click + New Mission.

Set a goal

Write a clear, specific goal. The planner agent uses this to generate a structured execution plan.Example: “Add a REST endpoint GET /api/health that returns { status: 'ok' } with a corresponding test.”

Choose launch mode

Select Supervised for your first mission. This pauses for your approval before the agent starts executing — so you can review the plan before any code is written.

Review the plan

The planner generates a step-by-step execution plan. Review the steps, lane assignments, and estimated cost. Click Approve to proceed or Edit to adjust.

Monitor execution

Workers execute the plan. The Mission Run panel shows:

Live status of each step (queued, running, completed, failed)
Terminal output from each worker
File changes and tool call logs

When all steps complete, the mission enters validation.

Review results

Check the Artifacts tab for test reports, code changes, and summaries. Create a PR from the mission’s result lane if the work looks good.

First prompt to try

For your first agent task, use something narrow enough to verify the full loop but broad enough to exercise the core workflow:

Add a GET /health endpoint that returns { "status": "ok" } and add one test for it.

Other good first prompts:

"Add a TypeScript type for UserPreferences with name (string), theme (light | dark), and notifications (boolean)."
"Write a utility function that validates email addresses and add 3 unit tests for it."
"Update the README with a Getting Started section that explains how to install dependencies and run the dev server."

What to expect during your first session

Context injection: ADE prepends the Lane Pack before the agent sees your message — so the agent already knows the project structure, lane intent, and recent file state. Tool calls: The agent reads files, writes code, and runs commands via ADE CLI tools. Each call appears as an expandable block in chat. No per-call permissions required in the default config. Session recording: Every message and tool call is captured in the session transcript, viewable in the History tab. Interrupting: Press Escape or click Stop at any time. The agent reports partial results and the conversation continues.

After your first task

Once you have verified the result:

Review the diff

Open the Files view scoped to your lane. Check every changed file. The side-by-side diff makes it easy to spot issues.

Commit the changes

If the changes look correct, commit them. You can:

Ask the agent: “Commit these changes with a descriptive message”
Use the git operations bar at the bottom of the Files view
Use the terminal in the lane to run git commit manually

Create a PR (optional)

Ask the agent: “Create a PR for this work” — or use the lane’s PR action in the right inspector. ADE pre-fills the PR title and description from the Lane Pack.

Troubleshooting your first run

The agent is not responding

Check that at least one AI provider is configured and verified in Settings > AI Providers. A green indicator means the provider is ready. If the provider shows a red indicator, verify your API key.

The agent made changes to the wrong files

Verify you are in the correct lane — check the lane selector in the chat header. If the agent is in the Primary Lane, it writes to your main working directory. Create a Worktree Lane for agent-driven tasks.

The agent's changes do not compile or tests fail

This is normal for a first run, especially on complex codebases. The Lane Pack may not have captured all relevant context. Try:

Tell the agent what failed: “The tests are failing with this error: [paste error]”
The agent will read the error and attempt a fix
If it still fails, provide more context about your project’s testing setup

The session is taking very long

Check the token usage indicator in the chat header. If the agent is consuming tokens but not producing visible output, it may be reading large files. Press Escape to interrupt, then try a more focused prompt.

Next steps

Key Concepts

Understand every core concept in ADE: Lanes, Packs, Missions, the CTO, Automations, and more.

Chat Capabilities

See the full list of what the chat agent can do — file operations, git, PRs, missions, and more.

Missions

Learn how to configure multi-step missions with planning, validation, and cost tracking.

Multi-Agent Setup

Run parallel agents across multiple lanes and monitor them from the Workspace Graph.

Welcome

Setup

Documentation Index

​Two good first paths

​First prompt to try

​What to expect during your first session

​After your first task

​Troubleshooting your first run

​Next steps

Key Concepts

Chat Capabilities

Missions

Multi-Agent Setup

Two good first paths

First prompt to try

What to expect during your first session

After your first task

Troubleshooting your first run

Next steps