Cate IDE Documentation

A Cate extension adds panels to Cate's infinite canvas. Extensions consist of a web frontend and can optionally include a local server process.

Extension Types

• Frontend-only: Static web assets served by Cate. Best for viewers, editors, formatters, or dashboards using cate.storage. No local process or port is required.
• Server-backed: Includes a local server for full OS access (filesystem, processes, network). Cate spawns one server per extension per workspace, and all panels for that extension connect to it (n:1 relationship).

Starting Points

• For published extensions: Clone the catalog repository git@github.com:0-AI-UG/cate-extensions.git and scaffold at extensions/<id>/. This provides access to the shared UI kit and the ./build.sh validation flow.
• For private/workspace-local tools: Scaffold inline in any folder containing a manifest.json. These do not use the shared UI kit and must handle theming manually via cate.theme.get().

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

Cate is an infinite canvas IDE designed for parallel coding agents. Key capabilities include:

• Agent-aware terminals: Supports Claude Code, Codex, Cursor, Grok, OpenCode, and Pi. Terminals report turn start, turn end, and permission prompts, allowing the canvas to show whether an agent is running, finished, or waiting for user input.
• Persistent Agent Sessions: Terminals and scrollback are preserved across restarts, with agents reattached using their own resume commands.
• Git Worktrees: Easily create worktrees and branches from local branches, remote branches, or open PRs to maintain separate, visible workstreams on the canvas.
• Flexible Panel Layouts: Terminals, Monaco editors, browsers, and viewers can be placed on the canvas or docked into tabs/splits. Layouts are persisted per project.
• Integrated Git and Search: Features multi-repo source control, git badges in the file tree, side-by-side diffs, and ripgrep search.
• Agent-callable CLI: A cate CLI is available within Cate terminals, allowing agents to drive a browser panel, read other terminals, open files, and manage panels.
• Remote Development: Supports working on hosts over SSH or WSL. Terminals, git, and search run on the remote host, while editors, browsers, and the canvas remain local.

A minimal frontend-only extension structure typically looks like this:

extensions/acme.example/
  manifest.json          # Required configuration
  README.md              # Fallback for catalog description
  package.json           # Optional: must include a "build" script
  index.html             # Entry point (or dist/index.html if using a build tool)
  src/
    main.ts
    _kit/                # Synced copy of the shared UI kit (do not edit)
    cate-host.d.ts       # Typings for window.cate

Packaging Rule: If a package.json with a build script is present, CI runs npm install and npm run build. If a dist/ directory exists after the build, the published artifact contains only manifest.json and dist/. Otherwise, the entire folder is shipped. manifest.json must always be at the artifact root.

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

Cate Cloud handles two types of credentials for remote workspaces:

Service-minted credentials

Used for services like GitHub App installation tokens. These are minted on demand, have short lifetimes, avoid persistence, and are refreshed through the cate-runner.

User-provided credentials

Used for services like OpenAI, Anthropic, npm, or private registries.

• Authority: The Cate desktop application acts as the credential authority.
• Delivery: Secrets are delivered after a connection is established.
• Storage: Secrets are stored in a root-created tmpfs owned by cate.
• Lifecycle: Secrets are removed when the workspace stops. If a workspace restarts normally, Cate must reconnect and re-inject the credentials.

Security Note: The security model provides tenant isolation. It does not provide isolation between a user's agent and that specific user's credentials; running user code can read credentials intended for that user.

Cate uses a default-deny security model. Any call to cate.* that is not explicitly declared in the cateApi array of your manifest.json will return { error: 'scope-denied' }.

Declaring a bare namespace grants all its sub-scopes (e.g., editor grants editor.read and editor.write).

Available Scopes

Note: There is no terminal scope for extensions. cate.terminal.* is reserved for the first-party cate CLI and will return { error: 'terminal-first-party-only' } for extensions.

If your extension's manifest.json includes a server field, Cate will spawn your server process lazily when the first panel for that (extensionId, workspace) is opened.

Server Requirements:

• Binding: You must bind to the provided HOST (which is 127.0.0.1). Never bind to 0.0.0.0, as this bypasses the token gate and exposes the server to the network.
• Port: Use the provided PORT environment variable.
• Security: You must require the CATE_TOKEN environment variable on every panel connection to ensure the connection is authorized.
• State Management: Multiple panels may share a single server instance. You must route state and events using cate.panel.id. Treat panel open/close events as join/leave operations. Your server should be able to survive panel remounts (e.g., when a user moves a dock) without dropping state.
• Lifecycle: When the last panel closes, Cate provides a ~30s grace window before sending SIGTERM/SIGKILL.

Provided Environment Variables:

• PORT: The free port to listen on.
• HOST: The host address (must be 127.0.0.1).
• CATE_TOKEN: The shared secret for panel connections.
• CATE_API: A token-gated local HTTP/WS endpoint for server-side reverse-API calls and event streams.
• WORKSPACE_ROOT: The root directory of the workspace the server belongs to.

Cate Cloud provides remotely hosted development workspaces using AWS EC2. To use the service effectively, you must distinguish between three core concepts:

• Cloud workspace: The durable identity of your environment, including your filesystem, repositories, worktrees, settings, and billing ownership.
• Workspace run: The specific period of time during which an EC2 instance is actively running.
• Client connection: An active attachment of a Cate desktop client to a workspace.

Lifecycle Behavior Reference:

Note: In v1, disconnecting your client does not stop the workspace. Stopping a workspace performs a normal shutdown and loses process state, but files persist.