# computeruseprotocol/typescript-sdk architecture

> Architecture diagram of the GitHub repository computeruseprotocol/typescript-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/computeruseprotocol/typescript-sdk
- Repository: https://github.com/computeruseprotocol/typescript-sdk

## Overview

CUP is a TypeScript SDK and integration server for AI agents to inspect and operate desktop interfaces. The main workflow creates a session, selects a platform adapter, captures an accessibility tree, and returns a CUP envelope or compact text; callers can then search the captured tree or execute actions against its elements. The graph also includes the CLI and MCP entry points. Platform implementations are shown as distinct capture and action backends; unsampled implementation details and undocumented wiring are omitted.

Main entry points: [`src/actions/executor.ts`](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/executor.ts) (Action executor), [`src/index.ts`](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/index.ts) (Session API), [`src/router.ts`](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/router.ts) (Platform router), [`src/actions/keys.ts`](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/keys.ts) (Key parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["SDK and output"]
  node_session["Session API<br/>[index.ts]"]
  node_format["Envelope and serializers<br/>[format.ts]"]
  node_search["Element search<br/>[search.ts]"]
  node_types["CUP types<br/>[types.ts]"]
end

subgraph group_capture["Tree capture"]
  node_router["Platform router<br/>[router.ts]"]
  node_windows_capture["Windows capture<br/>[windows.ts]"]
  node_macos_capture["macOS capture<br/>[macos.ts]"]
  node_linux_capture["Linux capture<br/>[linux.ts]"]
  node_web_capture["Web capture<br/>[web.ts]"]
end

subgraph group_actions["Action execution"]
  node_executor["Action executor<br/>[executor.ts]"]
  node_handler_contract["Handler contract<br/>[handler.ts]"]
  node_keys["Key parsing<br/>[keys.ts]"]
  node_windows_actions["Windows actions<br/>[windows.ts]"]
  node_macos_actions["macOS actions<br/>[macos.ts]"]
  node_linux_actions["Linux actions<br/>[linux.ts]"]
  node_web_actions["Web actions<br/>[web.ts]"]
end

subgraph group_integrations["Agent interfaces"]
  node_cli["CLI<br/>[cli.ts]"]
  node_mcp_cli["MCP stdio entry<br/>[cli.ts]"]
  node_mcp_server["MCP server<br/>[server.ts]"]
end

node_caller(("SDK caller"))
node_chrome(("Chromium via CDP"))

node_caller -->|"calls"| node_session
node_session -->|"selects adapter"| node_router
node_router -->|"dispatches"| node_windows_capture
node_router -->|"dispatches"| node_macos_capture
node_router -->|"dispatches"| node_linux_capture
node_router -->|"dispatches"| node_web_capture
node_session -->|"builds output"| node_format
node_session -->|"searches tree"| node_search
node_session -->|"executes actions"| node_executor
node_executor -->|"uses contract"| node_handler_contract
node_executor -->|"dispatches"| node_windows_actions
node_executor -->|"dispatches"| node_macos_actions
node_executor -->|"dispatches"| node_linux_actions
node_executor -->|"dispatches"| node_web_actions
node_windows_actions -->|"uses parsing"| node_keys
node_macos_actions -->|"uses parsing"| node_keys
node_linux_actions -->|"uses parsing"| node_keys
node_web_actions -->|"uses parsing"| node_keys
node_cli -->|"selects platform"| node_router
node_cli -->|"formats output"| node_format
node_mcp_cli -->|"starts server"| node_mcp_server
node_mcp_server -->|"calls SDK"| node_session
node_web_capture -->|"connects via CDP"| node_chrome

click node_session "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/index.ts"
click node_router "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/router.ts"
click node_windows_capture "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/platforms/windows.ts"
click node_macos_capture "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/platforms/macos.ts"
click node_linux_capture "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/platforms/linux.ts"
click node_web_capture "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/platforms/web.ts"
click node_format "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/format.ts"
click node_search "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/search.ts"
click node_types "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/types.ts"
click node_executor "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/executor.ts"
click node_handler_contract "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/handler.ts"
click node_keys "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/keys.ts"
click node_windows_actions "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/windows.ts"
click node_macos_actions "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/macos.ts"
click node_linux_actions "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/linux.ts"
click node_web_actions "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/web.ts"
click node_cli "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/cli.ts"
click node_mcp_cli "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/mcp/cli.ts"
click node_mcp_server "https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/mcp/server.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_session,node_format,node_search,node_types toneBlue
class node_router,node_windows_capture,node_macos_capture,node_linux_capture,node_web_capture toneAmber
class node_executor,node_handler_contract,node_keys,node_windows_actions,node_macos_actions,node_linux_actions,node_web_actions toneMint
class node_cli,node_mcp_cli,node_mcp_server toneRose
class node_caller,node_chrome toneIndigo
```

## Components

### SDK and output

- [Session API](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/index.ts): `src/index.ts`
- [Envelope and serializers](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/format.ts): `src/format.ts`
- [Element search](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/search.ts): `src/search.ts`
- [CUP types](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/types.ts): `src/types.ts`

### Tree capture

- [Platform router](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/router.ts): `src/router.ts`
- [Windows capture](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/platforms/windows.ts): `src/platforms/windows.ts`
- [macOS capture](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/platforms/macos.ts): `src/platforms/macos.ts`
- [Linux capture](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/platforms/linux.ts): `src/platforms/linux.ts`
- [Web capture](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/platforms/web.ts): `src/platforms/web.ts`

### Action execution

- [Action executor](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/executor.ts): `src/actions/executor.ts`
- [Handler contract](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/handler.ts): `src/actions/handler.ts`
- [Key parsing](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/keys.ts): `src/actions/keys.ts`
- [Windows actions](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/windows.ts): `src/actions/windows.ts`
- [macOS actions](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/macos.ts): `src/actions/macos.ts`
- [Linux actions](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/linux.ts): `src/actions/linux.ts`
- [Web actions](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/actions/web.ts): `src/actions/web.ts`

### Agent interfaces

- [CLI](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/cli.ts): `src/cli.ts`
- [MCP stdio entry](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/mcp/cli.ts): `src/mcp/cli.ts`
- [MCP server](https://github.com/computeruseprotocol/typescript-sdk/blob/main/src/mcp/server.ts): `src/mcp/server.ts`

### Other components

- **SDK caller**
- **Chromium via CDP**

## Connections

- SDK caller → Session API: calls (evidence: `README.md`)
- Session API → Platform router: selects adapter (evidence: `src/index.ts`)
- Platform router → Windows capture: dispatches (evidence: `src/router.ts`)
- Platform router → macOS capture: dispatches (evidence: `src/router.ts`)
- Platform router → Linux capture: dispatches (evidence: `src/router.ts`)
- Platform router → Web capture: dispatches (evidence: `src/router.ts`)
- Session API → Envelope and serializers: builds output (evidence: `src/index.ts`)
- Session API → Element search: searches tree (evidence: `src/index.ts`)
- Session API → Action executor: executes actions (evidence: `src/index.ts`)
- Action executor → Handler contract: uses contract (evidence: `src/actions/executor.ts`)
- Action executor → Windows actions: dispatches (evidence: `src/actions/executor.ts`)
- Action executor → macOS actions: dispatches (evidence: `src/actions/executor.ts`)
- Action executor → Linux actions: dispatches (evidence: `src/actions/executor.ts`)
- Action executor → Web actions: dispatches (evidence: `src/actions/executor.ts`)
- Windows actions → Key parsing: uses parsing (evidence: `src/actions/windows.ts`)
- macOS actions → Key parsing: uses parsing (evidence: `src/actions/macos.ts`)
- Linux actions → Key parsing: uses parsing (evidence: `src/actions/linux.ts`)
- Web actions → Key parsing: uses parsing (evidence: `src/actions/web.ts`)
- CLI → Platform router: selects platform (evidence: `src/cli.ts`)
- CLI → Envelope and serializers: formats output (evidence: `src/cli.ts`)
- MCP stdio entry → MCP server: starts server (evidence: `src/mcp/cli.ts`)
- MCP server → Session API: calls SDK (evidence: `src/mcp/server.ts`)
- Web capture → Chromium via CDP: connects via CDP (evidence: `README.md`)