Cate

https://github.com/0-ai-ug/cate
Admin
Cate is a desktop application that provides an infinite zoomable canvas where editor panels,...
Tokens:12,995
Snippets:197
Trust Score:5.8
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Clone and Setup Project

Source: https://github.com/0-ai-ug/cate/blob/main/CONTRIBUTING.md

Initializes the local development environment by cloning the repository and installing dependencies.

```bash
git clone https://github.com/<you>/cate.git
cd cate
bun run setup
```

--------------------------------

### Install Cate via Homebrew

Source: https://github.com/0-ai-ug/cate/blob/main/README.md

Use this command to install the Cate application on macOS systems using the Homebrew package manager.

```sh
brew install --cask cate
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/0-ai-ug/cate/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification.

```text
feat: add panel snapping to grid
fix: terminal resize not updating PTY dimensions
```

--------------------------------

### Clone the catalog repository

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-extension/SKILL.md

Use this command to initialize a new extension project within the shared catalog repository structure.

```bash
git clone git@github.com:0-AI-UG/cate-extensions.git
```

--------------------------------

### Available Development Scripts

Source: https://github.com/0-ai-ug/cate/blob/main/CONTRIBUTING.md

Commonly used commands for development, testing, and building the project.

```bash
bun run dev          # dev server with hot reload
bun run typecheck
bun run lint
bun run test         # unit tests (vitest)
bun run test:e2e     # Playwright integration tests
bun run build        # production build
bun run package      # package for distribution (:mac, :win, :linux)
```

--------------------------------

### List panels

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-cli/SKILL.md

Retrieve a list of available panels.

```bash
cate panel list
```

--------------------------------

### Build System Commands

Source: https://github.com/0-ai-ug/cate/blob/main/CLAUDE.md

Standard npm scripts for managing the development lifecycle of the Electron application.

```bash
npm install        # install dependencies
npm run dev        # start dev server with hot reload
npm run build      # production build
npm test           # run vitest suite
```

--------------------------------

### Manage editor and panels

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-cli/SKILL.md

Open files in the editor or manage panel creation and lifecycle.

```bash
cate editor open src/app.tsx:42
cate panel create terminal
cate panel create canvas
cate panel set <id>
cate panel current
cate panel clear
cate panel close <id>
```

--------------------------------

### Configure light theme settings

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-theme/SKILL.md

Set the theme type and editor base for light-mode configurations.

```json
"type": "light"
"editor": { "base": "vs" }
```

--------------------------------

### Locate Cate configuration files

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-theme/SKILL.md

The paths where user themes are stored across different operating systems.

```text
macOS:   ~/Library/Application Support/cate/config.json
Linux:   ~/.config/cate/config.json
Windows: %APPDATA%/cate/config.json
```

--------------------------------

### Run Pre-push Checks

Source: https://github.com/0-ai-ug/cate/blob/main/CONTRIBUTING.md

Executes verification scripts to ensure code quality before pushing changes.

```bash
bun run typecheck
bun run lint
bun run test
bun run build
```

--------------------------------

### Execute browser workflow

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-cli/SKILL.md

Perform a sequence of browser actions including navigation, interaction, and snapshotting.

```bash
cate panel set 1a2b3c4d
cate browser open https://example.com
cate browser snapshot -i
cate browser fill @s1e2 user@example.com
cate browser click @s1e3
cate browser wait --url '**/dashboard'
cate browser snapshot -i
```

--------------------------------

### Manage browser lifecycle and viewports

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-cli/SKILL.md

Control browser tabs and viewport settings.

```bash
cate browser tabs
cate browser new-tab [url]
cate browser select-tab <id>
cate browser close-tab <id>
cate browser viewport desktop
cate browser viewport mobile
cate browser viewport 1024 768
cate browser viewport compact
cate browser resize 640 480
```

--------------------------------

### Set and view current panel

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-cli/SKILL.md

Select a specific panel for the current session or verify the currently selected panel.

```bash
cate panel set 1a2b3c4d
cate panel current
```

--------------------------------

### Cate Host API Reference

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-extension/SKILL.md

Overview of the available methods and properties exposed via the window.cate object for extension development.

```APIDOC
## Cate Host API (window.cate)

### Overview
The `window.cate` object provides the primary interface for extensions. Note that many methods require specific scopes to be declared in the extension manifest.

### Methods
- **cate.version()**: Returns a `Promise<number>` representing the API version.
- **cate.panel.setTitle(title: string)**: Sets the title of the current panel.
- **cate.panel.list()**: Returns a list of panels across all windows.
- **cate.panel.focus(panelId)**: Focuses a specific panel.
- **cate.panel.close(panelId)**: Closes a specific panel.
- **cate.workspace.get()**: Returns workspace information (rootPath, branch, worktree).
- **cate.theme.get()**: Returns current theme information.
- **cate.editor.openFile(path, options)**: Opens a file in the editor.
- **cate.canvas.createPanel(type, options)**: Creates a new panel (browser, editor, or extension).
- **cate.ui.notify(message, level)**: Displays a notification to the user.
- **cate.files.onDrop(cb)**: Registers a callback for file drop events.
- **cate.agent.open({ resume? })**: Starts an agent session.
- **cate.agent.send(sessionId, prompt)**: Sends a prompt to an active agent session.
- **cate.agent.dispose(sessionId)**: Disposes of an agent session.
- **cate.browser.open({ url, panelId? })**: Navigates a panel to a URL.
- **cate.browser.screenshot({ panelId? })**: Takes a screenshot of a panel.
```

--------------------------------

### Manage browser navigation

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-cli/SKILL.md

Open new tabs, navigate within the active tab, or create new panels.

```bash
cate browser open https://second.example
cate browser navigate https://replacement.example
cate browser new-panel https://separate.example
```

--------------------------------

### Minimal extension project structure

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-extension/SKILL.md

The required file layout for a frontend-only extension, including the mandatory manifest file and optional build configuration.

```text
extensions/acme.example/
  manifest.json          # required, see below
  README.md              # first line becomes the catalog description fallback
  package.json           # only if it needs a build: must expose "build" script
  index.html             # or src/ + vite build -> dist/index.html
  src/
    main.ts
    _kit/                # synced copy of the shared UI kit (never edit; see Kit)
    cate-host.d.ts       # typings for window.cate
```

--------------------------------

### Execute browser page commands

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-cli/SKILL.md

Run specific browser commands using native agent-browser argument syntax.

```bash
cate browser snapshot -i --compact
cate browser get text @s1e4
cate browser find role button click
cate browser fill '#email' user@example.com
cate browser press Enter
cate browser scroll down 600
cate browser screenshot --full
cate browser console
cate browser errors
```

--------------------------------

### Create Feature Branch

Source: https://github.com/0-ai-ug/cate/blob/main/CONTRIBUTING.md

Command to create a new branch for development.

```bash
git checkout -b my-feature
```

--------------------------------

### Persistent NDJSON CLI Mode

Source: https://github.com/0-ai-ug/cate/blob/main/research/browser-agent-architecture.md

Demonstrates the persistent NDJSON mode for the browser session CLI, allowing agents to reuse a single process and connection.

```text
cate browser session --stdio
{"id":1,"op":"observe","mode":"viewport"}
{"id":2,"op":"act","action":{"type":"click","ref":"r42-17","intent":"Continue setup"}}
```

--------------------------------

### Define a Cate extension manifest

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-extension/SKILL.md

The manifest.json file serves as the primary configuration for a Cate extension, defining its identity, UI panels, and server-side requirements.

```json
{
  "id": "acme.example",
  "name": "Example",
  "version": "1.0.0",
  "category": "development",
  "description": "One-line catalog description.",
  "frontend": "dist/index.html",
  "panels": [
    { "id": "main", "label": "Example", "icon": "<svg …>…</svg>",
      "defaultSize": { "width": 600, "height": 400 } }
  ],
  "server": { "command": "node dist/server.js", "readyPath": "/health", "portEnv": "PORT" },
  "cateApi": ["storage", "theme"]
}
```

--------------------------------

### Clear panel selection

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-cli/SKILL.md

Return to automatic focused or grouped panel resolution.

```bash
cate panel clear
```

--------------------------------

### Validate theme JSON with AJV

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-theme/SKILL.md

Use the AJV CLI to validate a custom theme file against the project's theme schema.

```bash
npx ajv validate -s theme.schema.json -d mytheme.json
```

--------------------------------

### Cate Host API Surface

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-extension/SKILL.md

The complete set of available methods and properties in the window.cate namespace. Refer to the official .d.ts files for canonical type definitions.

```ts
cate.version(): Promise<number>                    // API version int, feature detection
cate.panel.id: string                              // this panel instance's id (readonly)
cate.panel.setTitle(title: string): Promise<void>
cate.panel.list() => [{ panelId, type, title, focused, filePath?, url? }]  // panels across windows
cate.panel.focus(panelId)                          // reveal/focus a panel
cate.panel.close(panelId)                          // close without revealing first

cate.workspace.get(): Promise<{ rootPath, branch, worktree }>   // branch/worktree may be null
cate.theme.get(): Promise<{ id, type: 'dark'|'light', app, terminal }>

cate.editor.openFile(path, { line?, column? })     // path confined to workspace root
cate.canvas.createPanel(type, {                    // type: 'browser' | 'editor' | 'extension'
  position?: { x, y },                             // omit to follow the user's placement setting
  url?, filePath?,                                 // filePath confined to workspace root
  extensionId?, extensionPanelId? })               // 'extension': panelId required, id defaults to caller
cate.ui.notify(message, level?: 'info'|'warn'|'error')

cate.files.onDrop(cb): () => void                  // cb([{ name, path, text, size?, truncated? }])
                                                   // host reads the files; path may be null (OS drops);
                                                   // text is UTF-8, capped (truncated flags over-cap)

cate.storage.get/set/delete/keys                   // extension-scoped JSON KV
cate.storage.panel.get/set                         // panel-scoped slice, keyed by cate.panel.id
cate.storage.onChange(cb): () => void              // external edits + writes from other panels

cate.agent.open({ resume? }) => { sessionId } | { error }
cate.agent.send(sessionId, prompt) => { text, message } | { error }
cate.agent.dispose(sessionId)                      // no one-shot run: compose open -> send -> dispose
cate.agent.cancel()                                // abort this extension's in-flight turn

cate.browser.open({ url, panelId? }) => { panelId, url }   // point a panel at url (or open one)
cate.browser.reload({ panelId? }) => { ok: true }
cate.browser.screenshot({ panelId? }) => { path }  // host filesystem path (OS temp dir)
cate.browser.snapshot({ panelId? }) => { url, title, refs: [{ ref, role, name, value? }] }
cate.browser.click({ ref, panelId? }) => { ok: true }      // ref from a recent snapshot
cate.browser.type({ ref, text, panelId? }) => { ok: true }
cate.browser.wait({ panelId?, timeoutMs? }) => { url, title, loading: false }  // load settled (cap 8s)
cate.browser.press({ key, ref?, panelId? }) => { ok: true }   // TRUSTED key input (Enter submits)
```

--------------------------------

### Interact with terminal

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-cli/SKILL.md

Read terminal output and send input to the active terminal panel.

```bash
cate panel set 1a2b3c4d
cate terminal read
cate terminal type npm test
cate terminal press enter
```

--------------------------------

### Storage Volume Layout

Source: https://github.com/0-ai-ug/cate/blob/main/plan.md

Recommended separation of root and workspace EBS volumes to isolate system files from durable customer data.

```text
root EBS
  /usr/local/bin/cate-runner
  operating system
  system packages
  disposable caches

workspace EBS
  /home/cate
  /workspace
  repositories
  worktrees
  .cate state
  agent sessions
  user-level tools
```

--------------------------------

### Define a Cate theme schema

Source: https://github.com/0-ai-ug/cate/blob/main/skills/cate-theme/SKILL.md

The structure of a Cate theme JSON object, including app chrome, terminal colors, and editor syntax tokens.

```jsonc
{
  "version": 1,
  "id": "midnight-ember",        // REQUIRED, unique kebab-case slug
  "name": "Midnight Ember",      // REQUIRED, display name
  "type": "dark",                // REQUIRED: "dark" | "light" (drives system light/dark auto-switch + editor base)
  "author": "You",               // optional
  "bootBackground": "#1a1714",   // optional — exact cold-launch window bg (defaults to surface-0)

  "app": {                       // app chrome — see "App colors" below. PARTIAL: omitted keys inherit the base.
    "surface-0": "#1a1714",
    "surface-1": "#221d18",
    "text-primary": "#e7ddd0",
    "text-muted": "#9b9186",
    "border-focus": "#e0683c",
    "focus-blue": "#e0683c",
    "agent-rgb": "224 104 60"
  },

  "terminal": {                  // REQUIRED full xterm palette — ordinary shell output
    "background": "#1a1714", "foreground": "#e7ddd0", "cursor": "#e0683c",
    "selectionBackground": "#3a2f26",
    "black": "#1a1714", "red": "#e0683c", "green": "#8fa86a", "yellow": "#d9a441",
    "blue": "#5f90c4", "magenta": "#b06aa0", "cyan": "#5fa8a8", "white": "#d8cdbf",
    "brightBlack": "#6b6258", "brightRed": "#f0855a", "brightGreen": "#a6c47f",
    "brightYellow": "#e8bd6a", "brightBlue": "#7aa8d6", "brightMagenta": "#c884b8",
    "brightCyan": "#7cc0c0", "brightWhite": "#f4ece1"
  },

  "editor": {                    // REQUIRED Monaco syntax
    "base": "vs-dark",           // "vs" for light themes, "vs-dark" for dark
    "tokens": [                  // syntax rules — foreground is hex WITHOUT the leading #
      { "token": "comment", "foreground": "6b6258", "fontStyle": "italic" },
      { "token": "keyword", "foreground": "e0683c" },
      { "token": "string",  "foreground": "8fa86a" },
      { "token": "constant.numeric", "foreground": "d9a441" },
      { "token": "type",    "foreground": "5f90c4" },
      { "token": "entity.name.function", "foreground": "b06aa0" }
    ],
    "colors": {                  // optional Monaco IColors (# prefixed)
      "editor.background": "#1a1714",
      "editor.foreground": "#e7ddd0"
    }
  }
}
```

--------------------------------

### Define RuntimeConnection type

Source: https://github.com/0-ai-ug/cate/blob/main/plan.md

Defines the structure for cloud-based runtime connections, ensuring they remain secret-free.

```ts
type RuntimeConnection =
  | ExistingConnections
  | {
      kind: 'cloud'
      runtimeId: string
      cloudWorkspaceId: string
      region: string
      remotePath: '/workspace'
    }
```

--------------------------------

### Define Agent Observation Structure

Source: https://github.com/0-ai-ug/cate/blob/main/research/browser-agent-architecture.md

Represents the standard JSON schema for agent observations, including viewport state, element references, and screenshot metadata.

```json
{
  "sessionId": "bs_…",
  "pageId": "tab_…",
  "revision": 42,
  "url": "https://…",
  "title": "…",
  "viewport": {"width": 1180, "height": 720, "scrollX": 0, "scrollY": 640},
  "cursor": {"x": 420, "y": 216, "owner": "agent"},
  "elements": [
    {
      "ref": "r42-17",
      "role": "button",
      "name": "Continue",
      "box": [380, 190, 120, 42],
      "states": []
    }
  ],
  "screenshot": {"path": "…", "changed": true},
  "webmcpTools": [],
  "warnings": []
}
```

--------------------------------

### Define CloudWorkspacePhase type

Source: https://github.com/0-ai-ug/cate/blob/main/plan.md

Defines the lifecycle states for a cloud workspace, keeping VM state and runtime channel connectivity separate.

```ts
type CloudWorkspacePhase =
  | 'provisioning'
  | 'stopped'
  | 'starting'
  | 'running'
  | 'stopping'
  | 'failed'
  | 'deleting'
```
Tokens:
Raw