From yellow-composio
Composio MCP tool patterns, Workbench batch processing, Multi-Execute, usage tracking, and graceful degradation conventions. Use when commands or agents need Composio integration context.
npx claudepluginhub kinginyellows/yellow-plugins --plugin yellow-composioThis skill uses the workspace's default tool permissions.
Reference conventions for yellow-composio plugin -- tool patterns, batch
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
Reference conventions for yellow-composio plugin -- tool patterns, batch processing, usage tracking, graceful degradation, and security rules.
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
provided by the user's MCP connector (prefix varies by configuration, e.g.,
mcp__claude_ai_composio__* or mcp__composio-server__*), not bundled by
this plugin.
| 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 |
| 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 |
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.
Use COMPOSIO_REMOTE_WORKBENCH when processing 10+ items, handling large API
responses, or performing data transformation that would consume excessive
context tokens.
COMPOSIO_SEARCH_TOOLS response (session.id)COMPOSIO_REMOTE_WORKBENCH with session_idAvailable 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 |
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))
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.
Workbench has a hard 4-minute timeout per execution. For batches exceeding this:
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.
COMPOSIO_MULTI_EXECUTE_TOOL runs up to 50 independent tool calls in parallel.
COMPOSIO_SEARCH_TOOLS -- never invent slugsCOMPOSIO_SEARCH_TOOLS -> COMPOSIO_MANAGE_CONNECTIONS (if needed) -> COMPOSIO_MULTI_EXECUTE_TOOL
.claude/composio-usage.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 }
}
}
}
Consuming commands should increment the counter after each Composio tool execution using this pattern:
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.
monthly_warn (approaching threshold)monthly_warnmonthly_warndaily_warn thresholdAll consuming plugins must detect Composio availability at runtime and fall back silently when absent.
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.
Consuming plugins embed Composio detection inline in their command markdown
(not via cross-plugin skills: preloading -- no such mechanism exists).
Pattern:
### 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 | 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 |
--- begin/end ---
delimiters per repository convention.| 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.