How a run works

Inside a single turn of a loop: an isolated sandbox, a real coding agent on a dedicated branch, a review it did not grade itself, and a handoff note that makes the next turn cheaper than the last.

Every loop turn runs the same way, whether it was fired by a webhook, a clock, or someone mentioning the goblin directly. This page is what happens between that trigger and the merge request.

1. The trigger lands

TaskGoblin finds or creates the thread for that piece of work — the conversation for one issue, one merge request, one loop — and records the turn as a message in it. A follow-up on work already in flight joins the existing thread rather than starting a fresh one, which is why the goblin never asks you to re-explain.

2. The sandbox comes up

The run gets an isolated cloud container with a checkout of your repository. Sandboxes are persistent and reused across a thread's turns, so a follow-up lands in an environment that already has the repository and the previous turn's state — the goblin resumes instead of starting from an empty box.

Sandboxes are often pre-warmed, which is why a run usually starts working in seconds rather than waiting on a cold container. The cloud sandbox covers isolation, persistence, and self-hosting in depth.

3. It reads before it writes

Before touching code the goblin gathers context: the issue or the diff that triggered it, the thread's history, the handoff note the previous goblin left, and your organisation's conventions. For an event loop, your standing instruction is layered on top of the event's own context.

This is the step that separates a useful change from a plausible one. An agent that can see how the last change was reviewed, and why an earlier approach was reverted, makes better decisions than one starting in an empty room.

4. A real coding agent does the work

Inside the sandbox runs an actual coding agent — Claude Code, Codex, or Gemini, depending on the model account for the run. It has the tools a developer has: it reads and edits files, runs commands, and runs your tests. It is not autocompleting a diff, it is working the problem.

5. Branch, commit, push, merge request

The goblin follows the workflow your team already uses:

  1. It works on a dedicated branch — 142-taskgoblin for issue 142 on GitLab or GitHub, proj-123-taskgoblin for a Jira key — never your default branch.
  2. It commits, signing its work so the trail is legible, and pushes the branch.
  3. It opens a merge request (GitLab) or pull request (GitHub) and reports the link back where the work started.

A run triggered on an existing merge request is the exception: it pushes to that MR's own branch rather than opening a competing one.

Because the output is a branch and a merge request, review is exactly what it already is for human contributions. Nothing merges without your say-so.

6. It reports where you are already looking

Throughout the run the goblin talks back through the surface the work belongs to: activity on a Linear issue, inline comments on a merge request, a self-updating card in Slack or Teams. You do not watch a terminal, and there is no separate dashboard you have to remember to open.

7. It writes down what happened

The last thing a goblin does — after the reply is sent, never before it — is record a handoff note: what it learned, what it decided, what is still open. The next turn reads that first.

This is why a loop compounds instead of repeating. See The brain.

Secrets stay out of the agent

The goblin never sees your credentials. Git access inside the sandbox is provisioned per organisation at run time — a GitLab OAuth token or a freshly minted GitHub installation token — and injected into the environment around the agent rather than handed to it as something to read. It can use the access it needs to clone and push without your secrets ever entering its context or its transcript.

That token is for git transport only. Comments, reviews, and issue updates go through TaskGoblin's own integrations so they post as the goblin rather than as you.

When something goes wrong

A run that fails does not disappear. The goblin reports back plainly on the surface you triggered it from, the failure is recorded on the run, and the handoff note carries the wall it hit so the next turn does not rediscover it. A run that never got a sandbox — one blocked by an empty credit balance, for instance — is never billed.

Where to go next