# composiohq/composio architecture

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

- Interactive diagram: https://gitdiagram.com/composiohq/composio
- Repository: https://github.com/composiohq/composio

## Overview

Composio is a multi-language SDK and CLI for giving AI agents authenticated access to app toolkits. The main workflow is to create a user-scoped session, expose its tools through a provider adapter (or MCP), let an agent discover and execute actions, and return results. Sessions also manage connected accounts, triggers, and files; the CLI offers a shell-based tool workflow. The Python session excerpts show local-versus-backend execution and file operations, while the TypeScript excerpts show session execution, file mounts, and deletion. Other subsystem links reflect README capabilities; unsampled implementation details are not inferred.

Main entry points: [`ts/packages/core/src/models/ToolRouterSession.ts`](https://github.com/composiohq/composio/blob/next/ts/packages/core/src/models/ToolRouterSession.ts) (Tool session), [`python/composio/core/models/tool_router_session.py`](https://github.com/composiohq/composio/blob/next/python/composio/core/models/tool_router_session.py) (Tool session), [`python/composio/core/models/tool_router.py`](https://github.com/composiohq/composio/blob/next/python/composio/core/models/tool_router.py) (Session creation), [`ts/packages/cli/src/commands`](https://github.com/composiohq/composio/tree/next/ts/packages/cli/src/commands) (CLI workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ts["TypeScript SDK"]
  node_ts_session["Tool session"]
  node_ts_files["Session files"]
  node_ts_delete["Session deletion"]
  node_ts_types["Session models"]
  node_ts_telemetry["Telemetry<br/>[Telemetry.ts]"]
end

subgraph group_py["Python SDK"]
  node_py_router["Session creation<br/>[tool_router.py]"]
  node_py_session["Tool session"]
  node_py_files["Session files"]
  node_py_delete["Session deletion"]
  node_py_client["HTTP client<br/>[__init__.py]"]
  node_custom_tools["Custom tools<br/>[custom_tool.py]"]
  node_tool_definitions["Tool schemas<br/>[tools.py]"]
  node_provider_base["Provider base<br/>[base.py]"]
  node_auth["Authentication<br/>[auth_configs.py]"]
  node_accounts["Connected accounts"]
  node_triggers["Triggers<br/>[triggers.py]"]
end

subgraph group_providers["Provider adapters"]
  node_provider_adapters["Framework adapters"]
end

subgraph group_cli["Command line"]
  node_cli["CLI workflows"]
  node_cli_execute["Tool execution"]
  node_cli_search["Tool search"]
end

node_developer(("SDK user"))
node_agent(("AI agent"))
node_backend{{"Composio service"}}

node_developer -->|"creates session"| node_ts_session
node_ts_session -->|"provides tools"| node_agent
node_agent -->|"requests actions"| node_ts_session
node_ts_session -->|"executes remote tools"| node_backend
node_developer -->|"creates session"| node_py_router
node_py_router -->|"creates session"| node_py_session
node_py_session -->|"calls API"| node_py_client
node_py_session -->|"routes local tools"| node_custom_tools
node_py_session -->|"executes remote tools"| node_backend
node_py_session -->|"uses tool models"| node_tool_definitions
node_py_session -->|"wraps tools"| node_provider_base
node_provider_base -->|"adapted by"| node_provider_adapters
node_developer -->|"runs with tools"| node_agent
node_ts_session -->|"mounts files"| node_ts_files
node_ts_session -->|"deletes session"| node_ts_delete
node_ts_files -->|"validates responses"| node_ts_types
node_ts_session -->|"records events"| node_ts_telemetry
node_py_session -->|"manages files"| node_py_files
node_py_router -->|"deletes session"| node_py_delete
node_py_delete -->|"calls API"| node_py_client
node_py_files -->|"calls file API"| node_py_client
node_ts_session -.->|"supports authorization"| node_auth
node_ts_session -.->|"manages connections"| node_accounts
node_developer -.->|"configures triggers"| node_triggers
node_developer -->|"uses shell commands"| node_cli
node_cli -->|"searches tools"| node_cli_search
node_cli -->|"executes tools"| node_cli_execute
node_cli_execute -.->|"runs actions"| node_backend

click node_ts_session "https://github.com/composiohq/composio/blob/next/ts/packages/core/src/models/ToolRouterSession.ts"
click node_ts_files "https://github.com/composiohq/composio/blob/next/ts/packages/core/src/models/ToolRouterSessionFileMount.ts"
click node_ts_delete "https://github.com/composiohq/composio/blob/next/ts/packages/core/src/lib/toolRouterSessionDelete.ts"
click node_ts_types "https://github.com/composiohq/composio/blob/next/ts/packages/core/src/types/ToolRouterSessionFilesMount.types.ts"
click node_ts_telemetry "https://github.com/composiohq/composio/blob/next/ts/packages/core/src/telemetry/Telemetry.ts"
click node_py_router "https://github.com/composiohq/composio/blob/next/python/composio/core/models/tool_router.py"
click node_py_session "https://github.com/composiohq/composio/blob/next/python/composio/core/models/tool_router_session.py"
click node_py_files "https://github.com/composiohq/composio/blob/next/python/composio/core/models/tool_router_session_files.py"
click node_py_delete "https://github.com/composiohq/composio/blob/next/python/composio/core/models/tool_router_session_delete.py"
click node_py_client "https://github.com/composiohq/composio/blob/next/python/composio/client/__init__.py"
click node_custom_tools "https://github.com/composiohq/composio/blob/next/python/composio/core/models/custom_tool.py"
click node_tool_definitions "https://github.com/composiohq/composio/blob/next/python/composio/core/models/tools.py"
click node_provider_base "https://github.com/composiohq/composio/blob/next/python/composio/core/provider/base.py"
click node_provider_adapters "https://github.com/composiohq/composio/tree/next/python/providers"
click node_auth "https://github.com/composiohq/composio/blob/next/python/composio/core/models/auth_configs.py"
click node_accounts "https://github.com/composiohq/composio/blob/next/python/composio/core/models/connected_accounts.py"
click node_triggers "https://github.com/composiohq/composio/blob/next/python/composio/core/models/triggers.py"
click node_cli "https://github.com/composiohq/composio/tree/next/ts/packages/cli/src/commands"
click node_cli_execute "https://github.com/composiohq/composio/blob/next/ts/packages/cli/src/commands/tools/execute/tools.execute.handler.ts"
click node_cli_search "https://github.com/composiohq/composio/blob/next/ts/packages/cli/src/commands/tools/search/tools.search.handler.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_ts_session,node_ts_files,node_ts_delete,node_ts_types,node_ts_telemetry,node_developer toneBlue
class node_py_router,node_py_session,node_py_files,node_py_delete,node_py_client,node_custom_tools,node_tool_definitions,node_provider_base,node_auth,node_accounts,node_triggers toneAmber
class node_provider_adapters toneMint
class node_cli,node_cli_execute,node_cli_search toneRose
class node_agent,node_backend toneIndigo
```

## Components

### TypeScript SDK

- [Tool session](https://github.com/composiohq/composio/blob/next/ts/packages/core/src/models/ToolRouterSession.ts): `ts/packages/core/src/models/ToolRouterSession.ts`
- [Session files](https://github.com/composiohq/composio/blob/next/ts/packages/core/src/models/ToolRouterSessionFileMount.ts): `ts/packages/core/src/models/ToolRouterSessionFileMount.ts`
- [Session deletion](https://github.com/composiohq/composio/blob/next/ts/packages/core/src/lib/toolRouterSessionDelete.ts): `ts/packages/core/src/lib/toolRouterSessionDelete.ts`
- [Session models](https://github.com/composiohq/composio/blob/next/ts/packages/core/src/types/ToolRouterSessionFilesMount.types.ts): `ts/packages/core/src/types/ToolRouterSessionFilesMount.types.ts`
- [Telemetry](https://github.com/composiohq/composio/blob/next/ts/packages/core/src/telemetry/Telemetry.ts): `ts/packages/core/src/telemetry/Telemetry.ts`

### Python SDK

- [Session creation](https://github.com/composiohq/composio/blob/next/python/composio/core/models/tool_router.py): `python/composio/core/models/tool_router.py`
- [Tool session](https://github.com/composiohq/composio/blob/next/python/composio/core/models/tool_router_session.py): `python/composio/core/models/tool_router_session.py`
- [Session files](https://github.com/composiohq/composio/blob/next/python/composio/core/models/tool_router_session_files.py): `python/composio/core/models/tool_router_session_files.py`
- [Session deletion](https://github.com/composiohq/composio/blob/next/python/composio/core/models/tool_router_session_delete.py): `python/composio/core/models/tool_router_session_delete.py`
- [HTTP client](https://github.com/composiohq/composio/blob/next/python/composio/client/__init__.py): `python/composio/client/__init__.py`
- [Custom tools](https://github.com/composiohq/composio/blob/next/python/composio/core/models/custom_tool.py): `python/composio/core/models/custom_tool.py`
- [Tool schemas](https://github.com/composiohq/composio/blob/next/python/composio/core/models/tools.py): `python/composio/core/models/tools.py`
- [Provider base](https://github.com/composiohq/composio/blob/next/python/composio/core/provider/base.py): `python/composio/core/provider/base.py`
- [Authentication](https://github.com/composiohq/composio/blob/next/python/composio/core/models/auth_configs.py): `python/composio/core/models/auth_configs.py`
- [Connected accounts](https://github.com/composiohq/composio/blob/next/python/composio/core/models/connected_accounts.py): `python/composio/core/models/connected_accounts.py`
- [Triggers](https://github.com/composiohq/composio/blob/next/python/composio/core/models/triggers.py): `python/composio/core/models/triggers.py`

### Provider adapters

- [Framework adapters](https://github.com/composiohq/composio/tree/next/python/providers): `python/providers`

### Command line

- [CLI workflows](https://github.com/composiohq/composio/tree/next/ts/packages/cli/src/commands): `ts/packages/cli/src/commands`
- [Tool execution](https://github.com/composiohq/composio/blob/next/ts/packages/cli/src/commands/tools/execute/tools.execute.handler.ts): `ts/packages/cli/src/commands/tools/execute/tools.execute.handler.ts`
- [Tool search](https://github.com/composiohq/composio/blob/next/ts/packages/cli/src/commands/tools/search/tools.search.handler.ts): `ts/packages/cli/src/commands/tools/search/tools.search.handler.ts`

### Other components

- **SDK user**
- **AI agent**
- **Composio service**

## Connections

- SDK user → Tool session: creates session (evidence: `README.md`)
- Tool session → AI agent: provides tools (evidence: `README.md`)
- AI agent → Tool session: requests actions (evidence: `README.md`)
- Tool session → Composio service: executes remote tools (evidence: `README.md`)
- SDK user → Session creation: creates session (evidence: `README.md`)
- Session creation → Tool session: creates session (evidence: `python/composio/core/models/tool_router.py`)
- Tool session → HTTP client: calls API (evidence: `python/composio/core/models/tool_router_session.py`)
- Tool session → Custom tools: routes local tools (evidence: `python/composio/core/models/tool_router_session.py`)
- Tool session → Composio service: executes remote tools (evidence: `python/composio/core/models/tool_router_session.py`)
- Tool session → Tool schemas: uses tool models (evidence: `python/composio/core/models/tool_router_session.py`)
- Tool session → Provider base: wraps tools (evidence: `python/composio/core/models/tool_router_session.py`)
- Provider base → Framework adapters: adapted by (evidence: `README.md`)
- SDK user → AI agent: runs with tools (evidence: `README.md`)
- Tool session → Session files: mounts files (evidence: `ts/packages/core/src/models/ToolRouterSession.ts`)
- Tool session → Session deletion: deletes session (evidence: `ts/packages/core/src/models/ToolRouterSession.ts`)
- Session files → Session models: validates responses (evidence: `ts/packages/core/src/models/ToolRouterSessionFileMount.ts`)
- Tool session → Telemetry: records events (evidence: `ts/packages/core/src/models/ToolRouterSession.ts`)
- Tool session → Session files: manages files (evidence: `python/composio/core/models/tool_router_session.py`)
- Session creation → Session deletion: deletes session (evidence: `python/composio/core/models/tool_router.py`)
- Session deletion → HTTP client: calls API (evidence: `python/composio/core/models/tool_router_session_delete.py`)
- Session files → HTTP client: calls file API (evidence: `python/composio/core/models/tool_router_session_files.py`)
- Tool session → Authentication: supports authorization (evidence: `README.md`)
- Tool session → Connected accounts: manages connections (evidence: `README.md`)
- SDK user → Triggers: configures triggers (evidence: `README.md`)
- SDK user → CLI workflows: uses shell commands (evidence: `README.md`)
- CLI workflows → Tool search: searches tools (evidence: `README.md`)
- CLI workflows → Tool execution: executes tools (evidence: `README.md`)
- Tool execution → Composio service: runs actions (evidence: `README.md`)
