> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Code Review

> An agent reviews a pull request from context scattered across the pull request, its issue, CI and the code, and can comment but never merge or push. Mirage sets up a managed virtual terminal for the task.

![mirage](https://docs.mirage.strukto.ai/logo/light.svg)
![mirage](https://docs.mirage.strukto.ai/logo/dark.svg)

When a pull request opens, an agent reviews it the way a teammate would. It
reads the pull request and the issue it fixes, looks at the code around the
change, checks the tests and CI, and posts a review comment on the pull request
with a confidence score, a diagram of the change, and notes on the lines that
need one.

A review is reads and writes over scattered context, a pull request, its
issue, CI and the code around the change, and that is the work Mirage is
built for. The agent reaches all of it from one terminal, with fewer tokens
than calling the same services as MCP tools
([VFS-Bench 1.0](https://agentvfs.org/benchmark/vfs-bench-1)). It is also a
task with clear boundaries, one repository to read and one pull request to
comment on, so a managed terminal suits it best. Here it runs as an
[in-process terminal](https://docs.mirage.strukto.ai/home/examples/in-process-terminal.md) on a Mirage
server, without a VM or sandbox.

## Setup

> [card] Files
>
> `/repo`, a clone of the repository in memory, read-only. `/workspace` for the review the agent writes.

> [card] CLIs
>
> [`gh`](https://docs.mirage.strukto.ai/python/cli/gh) calls GitHub with a token the Mirage server holds. [`git`](https://docs.mirage.strukto.ai/python/cli/git) clones the repository.

> [card] Policy
>
> A [session profile](https://docs.mirage.strukto.ai/home/configuration/session.md) and `guard.py` let the agent run only review commands. It can comment, never merge.

You need the `mirage` CLI and a GitHub token, `GITHUB_TOKEN`, that can read
the repository and comment on its pull requests.
[GitHub](https://docs.mirage.strukto.ai/home/setup/github.md) says how to create one.

> [accordion] Installation
>
> The policy runs on [Monty](https://docs.mirage.strukto.ai/home/policy/scripts.md#runtimes), a small sandboxed
> Python interpreter:
>
> > [tab] pip
> >
> > ```bash theme={null}
> > pip install 'mirage-ai[monty]'
> > ```
>
> > [tab] npm
> >
> > ```bash theme={null}
> > npm install -g @struktoai/mirage-cli @pydantic/monty
> > ```

> [accordion] workspace.yaml
>
> `workspace.yaml` mounts `/repo` and `/workspace` in memory, installs `gh` and
> `git`, and defines the `reviewer` profile every agent terminal gets:
>
> ```yaml workspace.yaml theme={null}
> mounts:
>   /repo:
>     vfs: ram
>     mode: write
>   /workspace:
>     vfs: ram
>     mode: write
>
> clis:
>   gh:
>     cli: gh
>     machine: in_process
>     config:
>       token: {from: env, key: GITHUB_TOKEN}
>       repo: sindresorhus/ky
>   git:
>     cli: git
>     machine: in_process
>
> profiles:
>   reviewer:
>     cwd: /repo
>     mounts:
>       /repo:
>         mode: read
>     commands:
>       allow: [cd, pwd, echo, ls, cat, head, tail, grep, sed, awk, wc, sort, uniq, find, jq, git, gh pr view, gh pr diff, gh pr checks, gh issue view, gh pr comment]
>     policy:
>       pre_command:
>         - {script: ./guard.py}
> ```
>
> * `mounts` in the profile makes `/repo` read-only for the agent. The clone
>   below runs in the default session, which has no profile.
> * `commands.allow` is the whole list of what the agent can run. `rm`, `mv`
>   and `curl` are not on it. Of `gh`, it has the four commands that read a
>   pull request, its issue and CI, and `gh pr comment` to post the review.
>   `gh pr merge`, `gh pr edit` and `gh api` are refused.

> [accordion] guard.py
>
> An allow rule matches the start of a command, so `gh pr comment` alone
> would also let the agent pick another repository with `-R` or delete a
> comment with `--delete-last`. `guard.py` sees the command after the shell
> has expanded it, and accepts a comment only in one form:
>
> ```python guard.py theme={null}
> def pre_command(ctx):
>     words = [w["text"] for w in ctx["words"]]
>     if words[:3] != ["gh", "pr", "comment"]:
>         return None
>     if len(words) == 6 and words[3].isdigit() and words[4:] == ["--body-file", "/workspace/review.md"]:
>         return None
>     return {"kind": "deny", "reason": "comment only as gh pr comment N --body-file /workspace/review.md"}
> ```

Create the workspace, clone ky into `/repo` at the commit pull request 880
merged as, and open a terminal for the agent under the `reviewer` profile:

```bash theme={null}
export GITHUB_TOKEN=<your token>
mirage daemon restart
mirage workspace create workspace.yaml --id review
export MIRAGE_WORKSPACE=review
mirage shell -c 'git clone -q https://github.com/sindresorhus/ky.git /repo && git -C /repo checkout -q --detach 0bda554d448c1b57c17a5c18114432c02465d467'
mirage workspace session create -s agent -p reviewer
```

The local server reads `GITHUB_TOKEN` when it starts, so `mirage daemon
restart` stops a server that started without it. To review your own
repository, change the clone's URL and commit, and the `repo` of `gh` in
`workspace.yaml`.

## Example

The agent reviews
[pull request 880](https://github.com/sindresorhus/ky/pull/880) of
[ky](https://github.com/sindresorhus/ky), a small HTTP client on GitHub. The
pull request fixes how `ky.extend()` replaces an `AbortSignal`.

These are the commands the agent runs, in the `agent` terminal Setup
created, which starts in `/repo`. Your agent sends each one with
`mirage shell -s agent`, or through [MCP](https://docs.mirage.strukto.ai/home/access/mcp.md), the
[HTTP API](https://docs.mirage.strukto.ai/home/access/http.md), [RPC](https://docs.mirage.strukto.ai/home/access/rpc.md) or [SSH](https://docs.mirage.strukto.ai/home/access/ssh.md).

**1. Read the pull request and its issue**

`gh` reads GitHub with the token the Mirage server holds.

```bash theme={null}
gh pr view 880 --json title,state,closingIssuesReferences …
gh issue view 879 --json body --jq .body | grep null
```

The pull request is merged and fixes issue #879, which says `undefined` and `null` should both reset the signal.

**2. Read the code around the change**

The repository is a read-only clone at `/repo`, so `sed` reads it like any file.

```bash theme={null}
sed -n 312,317p source/utils/merge.ts
```

The fix handles `undefined`, but a `null` still keeps the parent's signal.

**3. Check the tests and CI**

```bash theme={null}
gh pr diff 880 | grep "^+test("
gh pr checks 880 … | sort | uniq -c
```

Three new tests, none for `null`. All 6 checks pass.

**4. Write and post the review**

The agent writes a score, a diagram of the change and a note on `merge.ts:228` to `/workspace/review.md`, then posts it.

```bash theme={null}
gh pr comment 880 --body-file /workspace/review.md
```

The review is a comment on the pull request, the one write the profile allows.

**5. Everything else is refused**

The profile and `guard.py` are checked before each command, and `/repo` is read-only. Each prints `Permission denied` or the file system's error, and the reason:

| The agent runs | Reason |
| - | - |
| `rm -rf /repo/source` | rm is not allowed |
| `echo hi >> /repo/readme.md` | Read-only file system |
| `gh pr merge 880` | gh pr merge is not allowed |
| `gh pr comment 880 -R other/repo --body-file /workspace/review.md` | comment only as gh pr comment N --body-file /workspace/review\.md |
| `curl https://example.com` | curl is not allowed |

> [accordion] Full commands
>
> Each line runs in the agent's terminal with `mirage shell -s agent`.
>
> ````bash theme={null}
> mirage shell -s agent -c 'gh pr view 880 --json title,state,closingIssuesReferences --jq ".title, .state, .closingIssuesReferences[0].number"'
> mirage shell -s agent -c 'gh issue view 879 --json body --jq .body | grep null'
> mirage shell -s agent -c 'sed -n 312,317p source/utils/merge.ts'
> mirage shell -s agent -c 'gh pr diff 880 | grep "^+test("'
> mirage shell -s agent -c 'gh pr checks 880 --json bucket --jq ".[].bucket" | sort | uniq -c'
> mirage shell -s agent -c 'cat > /workspace/review.md' <<'MD'
> ## Confidence score: 4/5
>
> Safe to merge. `replaceOption(signal)` and `signal: undefined` now drop the
> signals an instance inherits. One gap: `signal: null`, which #879 also
> names, still keeps them.
>
> ```mermaid
> flowchart TD
>     A["extend({signal: value})"] --> B{"replaceOption(...) or undefined?"}
>     B -- yes --> C["drop inherited signals"]
>     B -- no --> D{"an AbortSignal?"}
>     C --> D
>     D -- yes --> E["add it to the signals"]
>     D -- no --> F["merge as a plain option"]
>     E --> G["AbortSignal.any(signals)"]
>     F --> G
> ```
>
> **P2, `source/utils/merge.ts:228`:** clear the signals on `null` too, and
> add a test.
> MD
> mirage shell -s agent -c 'gh pr comment 880 --body-file /workspace/review.md'
> ````

See [Session Profiles](https://docs.mirage.strukto.ai/home/configuration/session.md) for the rules a profile
takes, and [Policy](https://docs.mirage.strukto.ai/home/policy/overview.md) for checks a list cannot express.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.