Git Channel

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 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.

Request

{ "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.

Response

{
  "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",
        "kind": "text",
        "additions": 1,
        "deletions": 0,
        "hunks": [
          {
            "header": "@@ -1 +1,2 @@",
            "oldStart": 1, "oldCount": 1, "newStart": 1, "newCount": 2,
            "lines": [
              { "kind": "context", "text": "import express", "oldLine": 1, "newLine": 1 },
              { "kind": "add", "text": "import cors", "oldLine": null, "newLine": 2 }
            ]
          }
        ]
      }
    ]
  }
}

Each file has status (added, modified, deleted, renamed) and kind (text, binary, too_large). Text and binary results have additions/deletions and hunks; a binary type change can include text hunks. Each line has kind (add, del, context), text, and oldLine/newLine, with null on a side where the line does not exist. Untracked text larger than 262,144 bytes stays in the change list as too_large. It has a maxBytes limit and no counts or hunks. Other files remain available, and the whole-file revert operation still works. Genuine Git and file-read errors fail the request.

Oversized file

{
  "oldPath": "/dev/null",
  "newPath": "generated/big.txt",
  "displayPath": "generated/big.txt",
  "status": "added",
  "kind": "too_large",
  "maxBytes": 262144
}

`snapshots`

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

Request

{ "channel": "git", "type": "snapshots", "requestId": "req-2", "limit": 50 }

limit is optional, up to 200.

Response

{
  "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.

Request

{ "channel": "git", "type": "restore", "requestId": "req-3", "messageId": "msg-9" }

Response

{ "channel": "git", "type": "restore", "requestId": "req-3", "success": true }

Restore is destructive: it discards file changes and conversation history made after the checkpoint. After a restore the server also pushes a files refresh and a conversation.truncated agent event.

`revertFile`

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

Modified deleted

{
  "channel": "git",
  "type": "revertFile",
  "requestId": "req-4",
  "filePath": "src/index.ts",
  "fileStatus": "modified"
}

Renamed

{
  "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.

Request

{ "channel": "git", "type": "showFile", "requestId": "req-6", "filePath": "src/index.ts", "ref": "HEAD" }

Response

{ "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.

{ "channel": "git", "type": "checkpoint", "messageId": "msg-10" }

API Reference

Projects

Workspaces

Tasks

Environment Variables

Secret Files

Skills

Automations

Agent Profiles

Usage

Profile

Organizations

User Discovery

Pr Reviews

Pull Requests

Push Tokens

Cursor Auth

Claude Code Auth

Slack

Codex Auth

Sentry

Feedback

Notifications

OpenCode Auth

GitHub

Platform API Keys

User Settings

Inference

Billing

Linear

WebSocket

`diff`

`snapshots`

`restore`

`revertFile`

`showFile`

`checkpoint` (server push)

​diff

​snapshots

​restore

​revertFile

​showFile

​checkpoint (server push)

`diff`

`snapshots`

`restore`

`revertFile`

`showFile`

`checkpoint` (server push)