---
title: "Run an agent on your repository"
description: "Give Panolayer Agent a task in your codebase, follow its work, and review the result before bringing it into your branch. You stay in control of what gets merged."
url: https://panolayer.com/docs/running-agents
type: HOW-TO
updated: 2026-10-20
---

# Run an agent on your repository

Give Panolayer Agent a task in your codebase, follow its work, and review the result before bringing it into your branch. You stay in control of what gets merged.

Last updated 2026-10-20

<a id="before-you-start"></a>

## Before you start

This guide uses the Twitter example, `twitter-starter`, to build a feature: sharing a giant emoji with text underneath. You’ll describe what you want directly to the agent, follow its work, and review the finished result. You can use the same workflow for another feature or a bug you want to fix.

- Install Panolayer, sign in, and open the **Twitter Clone** example. See [Install and set up Panolayer](/docs/getting-started) if you haven’t opened a repository yet.
- Use **Panolayer Agent**, which is built in. You can also use any other supported agent, which you need to install before using. See [Supported agents](/docs/agents) for setup.

You’ll finish with a reviewed change recorded in your local Git history. Pushing it to a remote is a separate step.

<a id="start-agent"></a>

## Start Panolayer Agent

1. Open **My Agents** in the sidebar.
2. Click the **+** button next to **Monitor Agents** to open the agent menu.
3. Select **Panolayer Agent** for this walkthrough.

The menu includes Panolayer Agent and the agents you’ve installed. You can choose any of them to fix a bug or build code.

![Twitter example My Agents page with the plus button beside Monitor Agents and its menu open, showing Panolayer Agent and installed coding agents.](/docs/running-agents/01-agent-picker.png "Click + beside Monitor Agents, then choose Panolayer Agent or another agent you’ve installed.")

**Panolayer Agent works like the coding agents you already use.** Ask it to build a feature, fix a bug, or answer a question about your code. Type your request into **Chat with your codebase or build something…** and continue the conversation as you work.

**Starting from an issue?** In **Issues**, choose **Fix** and select **Panolayer Agent**. Panolayer carries the issue’s context into the task. Follow the [first-bug walkthrough](/docs/first-bug) for that route.

<a id="give-it-a-task"></a>

## Give it a task with a clear result

Describe what’s wrong or what you want to build, what should happen when it works, and anything the agent should preserve. Name a file or function when you know it.

For the Twitter example, use the same request shown in the screenshot:


```text
add a new feature where you can share a giant emoji with text underneath
```

Enter your request into the message box, then click the send arrow.

![Panolayer Agent in the Twitter example with the request to add a giant emoji with text underneath entered in the message box, ready to send.](/docs/running-agents/03-feature-prompt.png "Describe the feature you want to build. This request asks for a giant emoji with text underneath.")

Panolayer Agent can use the code map to find the relevant functions and relationships as it works. You can refer to the behavior you care about even when you don’t know every filename.

If the agent asks a question, answer it in the same conversation. If you need to narrow the task, state the specific result you want.

<a id="follow-the-work"></a>

## Follow the work without giving up your workspace

When Panolayer Agent starts a coding run, its progress appears in the conversation. The coding work happens in an isolated **Git worktree**: a separate checkout where the agent can edit and test the code while your main workspace stays available.

### Watch the task in the conversation

The run card shows the task and its current activity while the agent builds the giant-emoji feature. You can follow its progress and see the files and commands it’s using as it works.

### Open the run for more detail

Choose **Open** on the right-hand side of the card to see the run’s activity. In **Stream**, select an activity to inspect the command and its output in the right-hand panel. Use **Back to agent** to return to the conversation.

![Add Giant Emoji With Caption run opened in Stream, showing live activity and a selected command with its output in the right-hand panel.](/docs/running-agents/04-feature-run-details.png "Open shows the Add Giant Emoji With Caption task in progress. Selecting an entry lets you inspect what ran and what it returned.")

### See when the run is complete

When the work finishes, the card updates to **Subagent run complete**. The **Done** banner summarizes the checks and the number of files changed. You can still choose **Open** to inspect the completed run.

![Panolayer Agent conversation showing the giant-emoji task as Subagent run complete, with a Done banner, passed checks, 16 files changed, and an Open button.](/docs/running-agents/05-feature-run-complete.png "The completed giant-emoji task appears in the conversation, with its result and changed-file evidence ready to review.")

You can keep working and return to the run later. Use **Monitor Agents** for an overview when you have more than one agent working. Several agents can work on the same repository in separate worktrees; review how their changes fit together before merging them.

**Keep a follow-up tied to its task.** Use the run reference shown in your conversation when you send a follow-up, so it’s clear which task you mean.

<a id="review-verification"></a>

## Review the verification result

Review the changed code alongside the verification result before merging. See [Review changes and commit](/docs/changes) for the full guide to reviewing an agent’s changes.

When the agent requests a merge, read the verification summary: **Rules passed**, **Verification runs**, and **Files changed**. Review any new failures separately from issues that were already present.

![Panolayer Agent ready-to-merge dialog for the giant-emoji feature, showing 110 of 121 rules passed, one verification run, 16 files changed, and the expanded Details summary.](/docs/running-agents/06-feature-review-merge.png "The giant-emoji feature is finished and awaiting your approval to merge. Details explains what changed and how the agent checked it.")

In this run, the summary shows **110 of 121 rules passed**, **1 verification run**, and **16 files changed**. It identifies **11 pre-existing failures** separately and reports no new failures, warnings, or unchecked rules. Your totals will depend on your task.

Open **Details** to investigate the result further. See [Understand a verification result](/docs/verification-results) for the summary fields and statuses.

Check the behavior in the running app when the task calls for it. For this example, try creating a post with a giant emoji and text underneath, then check that ordinary text posts still work as expected.

<a id="merge-when-ready"></a>

## Merge when you’re ready

You decide what moves from the agent’s worktree into your branch. Choose **Not now** to keep reviewing. Once you’re satisfied with the changes and results, confirm the target branch and choose **Merge into main** for the Twitter sample.

The **Merged into main** confirmation shows a commit ID. This workflow records the change in local Git history, so you don’t need to commit that same change again.

Open **Changes** and find the commit in **History**. Check for unexpected uncommitted edits. If your repository has a remote and you want to share the commit, use **Git → Push**.

You’ve given an agent a task, followed its work, reviewed the result, and decided what reaches your branch.

## Continue learning

- [Review changes and commit](/docs/changes)

- [Understand a verification result](/docs/verification-results)

- [Supported agents](/docs/agents)
