# Composio Patterns

> Canonical conventions for running batch workflows through the Composio MCP server. Use when authoring or modifying commands or agents that call Composio tools — the Workbench sandbox, Multi-Execute batching, and the local usage counter.

- Skill: `kinginyellows/composio-patterns` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kinginyellows/composio-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kinginyellows/composio-patterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kinginyellows (https://skillmd.com/u/kinginyellows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kinginyellows/composio-patterns

---


# Composio Integration Patterns

## What It Does

Reference conventions for yellow-composio plugin -- tool patterns, batch
processing, usage tracking, graceful degradation, and security rules.

## When to Use

Use when authoring or modifying commands or agents that call Composio tools --
the Workbench sandbox, Multi-Execute batching, and the local usage counter.

## Usage

Reference the sections below as preloaded context; start with the Overview
for the three-prefix tool discovery order.

## Overview

Composio is a managed tool integration platform providing 1,000+ toolkits and
11,000+ actions via a single MCP server. In yellow-plugins, Composio is an
**optional accelerator** -- all workflows must function without it. Tools are
discovered via ToolSearch and may appear under one of three prefixes,
checked in priority order:

1. `mcp__plugin_yellow-composio_composio-server__*` -- bundled by this
   plugin (preferred, requires both `userConfig` values to be set).
2. `mcp__claude_ai_composio__*` -- Claude.ai native Composio integration
   (legacy, still supported).
3. `mcp__composio-server__*` -- manual `claude mcp add` setup
   (legacy / migration path).

## Tool Reference

### Meta Tools (Always Available in Composio Session)

| Tool | Slug | Purpose |
|------|------|---------|
| Search Tools | `COMPOSIO_SEARCH_TOOLS` | Discover tools, get schemas, check connection status |
| Get Schemas | `COMPOSIO_GET_TOOL_SCHEMAS` | Full parameter schemas for specific tools |
| Multi-Execute | `COMPOSIO_MULTI_EXECUTE_TOOL` | Run up to 50 tools in parallel |
| Manage Connections | `COMPOSIO_MANAGE_CONNECTIONS` | OAuth flow, API key auth for apps |
| Remote Workbench | `COMPOSIO_REMOTE_WORKBENCH` | Persistent Python sandbox (Jupyter-style) |
| Remote Bash | `COMPOSIO_REMOTE_BASH_TOOL` | Bash commands in the sandbox |

### Additional Meta Tools

| Tool | Purpose |
|------|---------|
| `COMPOSIO_CREATE_PLAN` | Generate execution plans for complex tasks |
| `COMPOSIO_WAIT_FOR_CONNECTIONS` | Pause for user auth completion |
| `COMPOSIO_LIST_TOOLKITS` | List all available toolkits with filters |
| `COMPOSIO_EXECUTE_AGENT` | Execute complex multi-step workflows |
| `COMPOSIO_GET_TOOL_DEPENDENCY_GRAPH` | Related/parent tool discovery |

### App-Specific Tools

Follow `{TOOLKIT}_{ACTION}` naming (e.g., `GMAIL_SEND_EMAIL`,
`GITHUB_CREATE_ISSUE`). Discovered at runtime via `COMPOSIO_SEARCH_TOOLS` --
never hardcode app-specific tool slugs.

## Workbench Batch Processing Pattern

Use `COMPOSIO_REMOTE_WORKBENCH` when processing 10+ items, handling large API
responses, or performing data transformation that would consume excessive
context tokens.

### When to Use

- Fetching and classifying 10+ items (Linear issues, semgrep findings, etc.)
- Aggregating results from multiple API calls
- Data transformation, filtering, and summarization
- Any operation where raw response data would overwhelm context

### Session Lifecycle

1. **Get session_id** from `COMPOSIO_SEARCH_TOOLS` response (`session.id`)
2. **Execute code** via `COMPOSIO_REMOTE_WORKBENCH` with `session_id`
3. **State persists** across calls within the same session
4. **Each operation creates its own session** (no reuse across workflow steps
   in v1 -- avoids state leakage)

### Built-in Helpers

Available inside `COMPOSIO_REMOTE_WORKBENCH` code:

| Helper | Purpose |
|--------|---------|
| `run_composio_tool(slug, args)` | Execute any Composio tool; returns `(response, error)` |
| `invoke_llm(query)` | Call LLM for classification/summarization (max 200K chars) |
| `upload_local_file(*paths)` | Upload files to cloud storage; returns download URL |
| `proxy_execute(method, endpoint, toolkit)` | Direct API calls when no tool exists |
| `web_search` | Search the web for data enrichment |
| `smart_file_extract` | Extract text from PDFs, images, documents |

### Parallelism Pattern

```python
from concurrent.futures import ThreadPoolExecutor

items = [...]  # list of items to process
results = []

def process_item(item):
    response, error = run_composio_tool("TOOL_SLUG", {"arg": item})
    return {"item": item, "result": response, "error": error}

with ThreadPoolExecutor(max_workers=10) as executor:
    results = list(executor.map(process_item, items))
```

### Context Window Management

Use `sync_response_to_workbench=true` on `COMPOSIO_MULTI_EXECUTE_TOOL` to save
large responses to the remote sandbox instead of returning them inline. Then
process via `COMPOSIO_REMOTE_WORKBENCH` or `COMPOSIO_REMOTE_BASH_TOOL`.

### Chunked Execution for Large Batches

Workbench has a **hard 4-minute timeout** per execution. For batches exceeding
this:

1. Split work into chunks of N items (start with N=20, adjust based on
   per-item processing time)
2. Execute each chunk in a separate Workbench call
3. State persists across calls within the same session_id
4. Aggregate results across chunks after all complete

### Remote File Path Warning

Paths returned from Workbench (e.g., `/home/user/.code_out/response.json`) are
**REMOTE** -- they exist only in the sandbox. Never use them as local file
paths. To get data out of the sandbox, return it inline from the Python code or
use `upload_local_file()` for large artifacts.

## Multi-Execute Pattern

`COMPOSIO_MULTI_EXECUTE_TOOL` runs up to 50 independent tool calls in parallel.

### Rules

- Use valid tool slugs from `COMPOSIO_SEARCH_TOOLS` -- never invent slugs
- Ensure ACTIVE connections for all toolkits being called
- Only batch logically independent operations (no ordering dependencies)
- Do not pass dummy or placeholder values

### Workflow

```text
COMPOSIO_SEARCH_TOOLS -> COMPOSIO_MANAGE_CONNECTIONS (if needed) -> COMPOSIO_MULTI_EXECUTE_TOOL
```

## Usage Tracking Convention

### Schema

`.claude/composio-usage.json`:

```json
{
  "version": 1,
  "created": "ISO8601",
  "updated": "ISO8601",
  "thresholds": {
    "daily_warn": 200,
    "monthly_warn": 8000
  },
  "periods": {
    "YYYY-MM": {
      "total": 0,
      "by_tool": { "TOOL_SLUG": 0 },
      "by_day": { "YYYY-MM-DD": 0 }
    }
  }
}
```

### Counter Increment

Consuming commands should increment the counter after each Composio tool
execution using this pattern:

```bash
USAGE_FILE=".claude/composio-usage.json"
LOCK_FILE="${USAGE_FILE}.lock"
# Caller must set TOOL_SLUG before sourcing (e.g., TOOL_SLUG="COMPOSIO_REMOTE_WORKBENCH")
: "${TOOL_SLUG:?TOOL_SLUG is required}"
TODAY=$(date -u +%Y-%m-%d)
MONTH=$(date -u +%Y-%m)

do_increment() {
  if jq --arg tool "$TOOL_SLUG" --arg day "$TODAY" --arg month "$MONTH" '
    .updated = (now | todate) |
    .periods[$month] //= {"total": 0, "by_tool": {}, "by_day": {}} |
    .periods[$month].total += 1 |
    .periods[$month].by_tool[$tool] = ((.periods[$month].by_tool[$tool] // 0) + 1) |
    .periods[$month].by_day[$day] = ((.periods[$month].by_day[$day] // 0) + 1)
  ' "$USAGE_FILE" > "${USAGE_FILE}.tmp"; then
    mv "${USAGE_FILE}.tmp" "$USAGE_FILE"
  else
    rm -f "${USAGE_FILE}.tmp"
    return 1
  fi
}

if [ -f "$USAGE_FILE" ]; then
  if command -v flock >/dev/null 2>&1; then
    touch "$LOCK_FILE"
    ( flock -x 200; do_increment ) 200>"$LOCK_FILE"
  else
    do_increment
  fi
fi
```

Increment **post-execution** (after confirmed success), not pre-execution.

### Threshold Checking

- Warn at 80% of `monthly_warn` (approaching threshold)
- Warn when projected monthly usage exceeds `monthly_warn`
- Display prominent warning when actual usage reaches `monthly_warn`
- Check daily count against `daily_warn` threshold
- Never hard-block -- the user owns their budget

## Graceful Degradation Pattern

All consuming plugins must detect Composio availability at runtime and fall back
silently when absent.

### Detection (Pattern A -- ToolSearch Probe)

```text
1. ToolSearch("COMPOSIO_REMOTE_WORKBENCH")
2. If not found: skip Composio path, use existing local approach
3. If found: proceed with Composio-accelerated path
4. If Composio call fails at runtime: fall back to local approach,
   note degradation briefly
```

This matches the pattern used by `review:pr` for ruvector/morph detection and
by debt scanners for ast-grep detection.

### Consumer Integration Pattern

Consuming plugins embed Composio detection inline in their command markdown
(not via cross-plugin `skills:` preloading -- no such mechanism exists).
Pattern:

```markdown
### Step N: Composio acceleration (optional)

1. Call ToolSearch("COMPOSIO_REMOTE_WORKBENCH"). If not found, skip to Step N+1.
2. [Composio-accelerated operation here]
3. Increment usage counter (see composio-patterns skill for bash snippet)
4. If Composio call fails: fall back to [existing local approach], note
   degradation briefly.
```

## Error Handling Catalog

| Error | Recovery |
|-------|----------|
| ToolSearch: no Composio tools | Silent skip, use local codepath |
| Tool call: network timeout | Retry once after 2s, then fallback to local |
| Tool call: 401 Unauthorized | Log warning, fallback to local, suggest `/composio:setup` |
| Tool call: 429 Rate Limited | Wait `Retry-After` header seconds, retry once, then fallback |
| Workbench: 4-minute timeout | Log warning, reduce batch size, fallback to local |
| Connection not ACTIVE | Log warning, suggest `COMPOSIO_MANAGE_CONNECTIONS` |
| MCP server not configured | Run `/composio:setup` |
| Usage counter missing | Run `/composio:setup` |
| Usage counter corrupted | Run `/composio:setup` to reset |

## Security Notes

- **Remote execution**: Workbench executes Python code on Composio's remote
  infrastructure. Do not send sensitive file contents, credentials, private
  keys, or proprietary algorithms. Use Workbench for data processing and API
  orchestration, not as a trusted execution environment.
- **API key stored in system keychain**: When the bundled MCP path is used,
  the `composio_api_key` `userConfig` value is stored in the OS keychain
  (`sensitive: true`) and sent as the `X-API-Key` header on every request.
  Never echo, log, or transmit the value. Legacy `mcp__claude_ai_composio__*`
  and `mcp__composio-server__*` paths use Claude Code's native or manual
  credential management instead.
- **HTTPS-only MCP URL (advisory)**: `composio_mcp_url` MUST start with
  `https://` — Claude Code sends the API key as the `X-API-Key` header to
  whatever URL is configured, so a non-HTTPS URL leaks the credential in
  cleartext. Format is not enforced at the schema level (the Claude Code
  remote validator does not support `userConfig.<key>.pattern`); the bundled
  `hooks/check-mcp-url.sh` SessionStart hook prints a warning if the URL is
  non-HTTPS, but it cannot block the MCP server from attaching first. Treat
  the warning as a "reconfigure now" signal: open `/plugin`, set the URL to
  an `https://mcp.composio.dev/*` value, and restart the session.
- **Content fencing**: Wrap all Composio responses in `--- begin/end ---`
  delimiters per repository convention.
- **Data transmission**: Tool call parameters and Workbench code are sent to
  Composio's cloud servers. Review what data is included before execution.
- **Sandbox isolation**: Composio's sandbox isolation details (containerization,
  tenant separation) are not publicly documented. Enterprise tier offers
  VPC/on-prem deployment for stricter requirements.

## Composio Pricing Reference

| Plan | Executions/Month | Price |
|------|-----------------|-------|
| Free / Hobby | 10,000 | $0 |
| Starter | 100,000 | $119/month |
| Growth | 2,000,000 | $229/month |
| Enterprise | Custom | Custom |

Overage: $0.249 per 1,000 additional calls. Premium tools cost ~3x standard.