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

# Git Channel

> Workspace diff, checkpoints, and restoring or reverting agent changes

The `git` channel powers the workspace diff and checkpoint UI: it returns structured diffs, lists the checkpoints the agent creates as it works, and rolls files (and the conversation) back to a checkpoint or reverts a single file. Both the web app and the `aether` CLI use it. See the [WebSocket overview](/api-reference/websocket/overview) for connecting.

Requests carry a `requestId`; responses echo it. Responses are discriminated by `success`, with an `error` string on failure.

## `diff`

Get a structured diff of the workspace.

```json Request theme={null}
{ "channel": "git", "type": "diff", "requestId": "req-1", "mode": "main" }
```

`mode` is optional: `"main"` (default) diffs against the base branch, `"lastCommit"` diffs against the last commit. Untracked files appear as added.

```json Response theme={null}
{
  "channel": "git",
  "type": "diff",
  "requestId": "req-1",
  "success": true,
  "diff": {
    "baseRef": "main",
    "files": [
      {
        "oldPath": "src/index.ts",
        "newPath": "src/index.ts",
        "displayPath": "src/index.ts",
        "status": "modified",
        "isBinary": false,
        "additions": 3,
        "deletions": 1,
        "hunks": [
          {
            "header": "@@ -1,4 +1,6 @@",
            "oldStart": 1, "oldCount": 4, "newStart": 1, "newCount": 6,
            "lines": [
              { "type": "context", "content": "import express", "oldLineNumber": 1, "newLineNumber": 1 },
              { "type": "add", "content": "import cors", "newLineNumber": 2 }
            ]
          }
        ]
      }
    ]
  }
}
```

Each file has `status` (`added`, `modified`, `deleted`, `renamed`), `isBinary`, `additions`/`deletions`, and `hunks`. Each hunk line has `type` (`add`, `remove`, `context`), `content`, and the relevant `oldLineNumber`/`newLineNumber`.

## `snapshots`

List the agent's checkpoints — points in the conversation you can restore to.

```json Request theme={null}
{ "channel": "git", "type": "snapshots", "requestId": "req-2", "limit": 50 }
```

`limit` is optional, up to 200.

```json Response theme={null}
{
  "channel": "git",
  "type": "snapshots",
  "requestId": "req-2",
  "snapshots": [
    { "messageId": "msg-9", "hash": "a1b2c3d", "timestamp": "2026-02-20T10:30:00Z" }
  ]
}
```

## `restore`

Roll the workspace files **and** the conversation back to a checkpoint, identified by its `messageId`. History after that point is truncated.

```json Request theme={null}
{ "channel": "git", "type": "restore", "requestId": "req-3", "messageId": "msg-9" }
```

```json Response theme={null}
{ "channel": "git", "type": "restore", "requestId": "req-3", "success": true }
```

<Warning>
  Restore is destructive: it discards file changes and conversation history made after the checkpoint. After a restore the server also pushes a [`files` `refresh`](/api-reference/websocket/files#refresh) and a [`conversation.truncated`](/api-reference/websocket/agent#other-events) agent event.
</Warning>

## `revertFile`

Revert a single file to its base state. The required fields depend on `fileStatus`.

```json Modified / added / deleted theme={null}
{
  "channel": "git",
  "type": "revertFile",
  "requestId": "req-4",
  "filePath": "src/index.ts",
  "fileStatus": "modified"
}
```

```json Renamed theme={null}
{
  "channel": "git",
  "type": "revertFile",
  "requestId": "req-5",
  "filePath": "src/new-name.ts",
  "fileStatus": "renamed",
  "oldPath": "src/old-name.ts"
}
```

| Field        | Type                                            | Description                             |
| ------------ | ----------------------------------------------- | --------------------------------------- |
| `filePath`   | string                                          | File to revert                          |
| `fileStatus` | `added` \| `modified` \| `deleted` \| `renamed` | Current status of the file              |
| `oldPath`    | string                                          | Required when `fileStatus` is `renamed` |
| `ref`        | string                                          | Optional git ref to revert against      |

The response is `{ requestId, success }`, and the server pushes a `files` `refresh` afterward.

## `showFile`

Read a file's contents at a specific git ref.

```json Request theme={null}
{ "channel": "git", "type": "showFile", "requestId": "req-6", "filePath": "src/index.ts", "ref": "HEAD" }
```

```json Response theme={null}
{ "channel": "git", "type": "showFile", "requestId": "req-6", "success": true, "content": "import express ..." }
```

## `checkpoint` (server push)

When the agent creates a checkpoint, the server pushes a notification with its `messageId`. There is no request for this.

```json theme={null}
{ "channel": "git", "type": "checkpoint", "messageId": "msg-10" }
```