How Disco Parrot works
A worked example from intent to a merged pull request. The same shape every run takes, narrated on a real change.
This page walks through one run end to end. The example is a small change you might give an AI agent on a real engineering team: add a CSV export to a reporting page. You will see what happens in the product, what the agent does, where you approve, and what gets recorded. The mechanics are the same for changes that are larger or smaller.
Before you start
A run in Disco Parrot needs three things to exist for it to do anything: a project (the work lives in one), a repository connected to that project (the agent works against a real codebase), and a sandbox profile (the disposable environment the run uses, with the runtime, image, and tools chosen up front). For this page, assume the workspace has all three and your team already uses them daily.
The shape of a run
A run is the unit of work from a chat or a flow that produces a change. It starts as intent and ends as a pull request your team reviews. Here is what happens between the two.
1. Write the intent
You open SDLC, click into Initiatives, and write a new one. The title is "CSV export on the reporting page." The body is two sentences: "Add a Download as CSV button to /reports. Use the same date range as the page filter." You leave the rest of the fields blank.
You click the Continue in Chat button at the top of the initiative. A chat panel opens on the right, and the agent reads the initiative body, the plans that already live underneath it, the test cases linked to those plans, the bugs in the workspace, and the attachments you have put on the record. That set of records gets materialized into the agent's sandbox as files at chat start, which is how the agent has context that includes your team's work and not just the codebase. You tell the agent: "Break this into plans." It comes back with three: one for the server endpoint, one for the front-end button and download trigger, one for a small test case.
The plans appear on the initiative's Plans tab as real records, each one with its own owner, status, and acceptance criteria. They are tagged with an editSource:"ai" mark on the version history so anyone reading them later can see they were authored by the agent.
2. Launch the flow
You pick the first plan. From the action launcher on the plan detail page you choose the Quick SDLC flow. The launcher shows the flow's parameters (you accept the defaults), the sandbox profile the run will use, and an oversight mode picker.
The sandbox profile decides where the run lives: which AI runtime, which image, which repos are mounted, which tools are reachable, and a resource class. Three classes ship today (a small one for planning and reading, a medium one for builds and tests, and a large one for heavier integration work). The profile your admin set as the project default is selected up front, and you can change it before launching if a profile better fits the work.
The oversight modes are Supervised and Autonomous. Supervised pauses at every checkpoint the flow defines and waits for your decision. Autonomous runs the same steps without pausing for intermediate approvals, records every decision the agent makes in the transcript, and lets you go do something else while it works. Autonomous requires a permission your admin grants, since it changes the trust model on a given run. You leave it on Supervised.
You click Launch. The chat panel widens into a flow run view. The run has four steps: Create Plan, Implement, Verify, and Create PR.
3. Watch the agent work
The Plan step runs first. The agent re-reads the initiative and the surrounding code in the sandbox, expands the plan with implementation steps, and writes the plan back as a real plan record. Sub-second updates land in the run timeline as the agent's tool calls fire.
The Implement step runs next. The agent edits a few files in the sandbox: a new endpoint in the reporting module, a new button on the front end, a small download utility. Each edit shows up in the run's transcript with the file path and the before-and-after fragment. The agent does not touch your real repository, only the sandbox copy of it.
The Verify step runs after. The agent runs the test suite in the sandbox, exercises the new endpoint, confirms the download works, and writes a structured result. The result includes a readyForPr field the next step uses as its gate.
4. Approve at the checkpoint
The run pauses. The Verify step is complete and the Create PR step is waiting on you. The run view shows the verify result, the files the agent touched, and three controls: Approve, Reject, Skip. You can leave a comment on any decision.
You read the verify summary, click Approve, and the Create PR step runs. The agent commits the changes to a branch named pr/<your-user-id>/<timestamp>, opens a pull request on GitHub with the plan summary in the body, authored as your GitHub identity. A link to the PR appears on the plan record.
If you had clicked Reject, the run would have stopped and the sandbox would have been destroyed. Skip would have advanced past the step without running it. The choice is recorded on the step either way.
5. Review the PR in GitHub
A real PR opens against your default branch. The team reviews it in GitHub the way they always have. Reviewer comments and approvals come back into Disco Parrot through a webhook, attach to the plan as review findings, and show up in the in-app PR review panel where the agent's own self-review findings already live. From that panel you can dispatch a follow-up flow that picks up the unresolved findings, edits a new commit in a fresh sandbox tied to the same PR branch, and pushes the fix. The convergence runs up to three iterations before pausing for a human; if the reviewer's note was already addressed, the next pass marks the finding resolved and the run finishes.
When the PR is approved, the merge happens through GitHub. GitHub stays the merge authority, end of story.
6. Read what got recorded
Three records cover every step.
- Who acted: user, ai, or system
- What changed on which record
- A year of retention by default
- Every chat, Flow run, and background task
- Agent messages, tool calls, file edits with before-and-after
- Where it ran: sandbox, profile, runtime, repo, branch
- The whole record at every meaningful save
- Restore is non-destructive
- Carries the edit source on each version
The tenant audit log carries the high-level entries: every record that was created or edited, every checkpoint decision, every credential lease that was minted and revoked. The Sessions index carries the full transcript of the chat and the flow run: every assistant message, every tool call, every file edit with the before-and-after text. The plan and the initiative carry their own version history where every version is a non-destructive snapshot you can restore to.
A reviewer arriving at the PR a week later can read the initiative, read the plan, open the run's transcript, see the agent's decisions, and tell from the AI badge which fields the agent wrote and which fields a person edited. The structure was built for the day after the PR ships, not just the day the run finished.
What if the agent gets stuck
A flow has a few honest answers built in. A step that finishes but cannot continue marks itself blocked (the verify step decided the change was not ready) and the run pauses with the reason visible. A step can fall back to a different step instead of failing the run. A run can be cancelled at any time and the sandbox is destroyed; nothing partial leaks into your repository. A long-running flow that pauses for a checkpoint can be sent to the background and you will get a notification when it needs you again. The product was built on the assumption that a long agent run is normal, and that a person managing several at once needs the same control they have over one.
Where the work lives between runs
Most teams spend their day in the SDLC area where the records live. The agent shows up there too: in the chat panel on a record, in the flow runs from the action launcher, in the background tasks that finish overnight. The Command Center on the right is one click away with the live state of every chat and run you have in flight.
The Platform area is where the agent itself is shaped: which models to use, what the agent's instructions are, which tools it can reach, which sandbox profiles your team works in. Most users land there once a quarter to check a setting an admin already configured.
Settings is where the workspace is run: members, teams, roles, the audit log, plan and usage.
The point of the three areas is that the structure of your day doesn't change when you bring an agent into it. You are still in SDLC, still on a record, still moving work through statuses. The agent is one more participant on the same team, working on the same records, leaving the same kind of trail you would.