Composio x Pi Extension

Pi package that installs a Pi extension for Composio-backed runtime and trigger-authoring tools.

Install

Install the published npm package with Pi:

pi install npm:composio-x-pi

For a pinned version:

pi install npm:[email protected]

During development, install from a local checkout:

cd /path/to/composio-x-pi
bun install
pi install /path/to/composio-x-pi

Try the extension for one Pi run without adding it to settings:

pi -e /path/to/composio-x-pi/src/index.ts

After editing an installed local checkout, use /reload inside Pi.

Publishing

This package is intended to be installed through Pi's npm package source, so releases should be published to npm under the composio-x-pi package name:

bun run test
bun run typecheck
bun run build
npm publish

Setup

No setup is required by default. The agent provisions a Composio identity for you on first tool use via the composio_signup tool. When a Composio tool fails with a missing-credentials error, the model is instructed to call composio_signup, which talks to https://agents.composio.dev/api/signup and writes the returned credentials to ~/.composio/anonymous_user_data.json (mode 0600).

If you already have a Composio API key, you can override the auto-provisioned signup credentials:

/composio-init

The command prompts for your key and stores it in ~/.pi/agent/extensions/composio-x-pi.json with file mode 0600. You can also pass the key as an argument (/composio-init <key>), but the interactive prompt avoids leaving the key in chat history.

Credential precedence:

1. COMPOSIO_API_KEY environment variable
2. /composio-init stored API key
3. composio_signup anonymous credentials

To later hand the auto-provisioned organization over to a human admin, either run /composio-claim <email> or ask the agent to call the composio_claim tool. Composio sends a 24-hour single-use invite to that email.

Optional environment variables:

• COMPOSIO_USER_ID — defaults to default when omitted.

Commands

• /composio-init — securely prompt for and store the Composio API key used by this extension.
• /composio-claim <email> — hand the auto-provisioned Composio org to a human admin (sends a 24-hour invite to the email).

Tools

All tools are registered by default:

• composio_debug_info
• composio_signup
• composio_claim
• composio_search_tools
• composio_get_tool_schemas
• composio_execute_tool
• composio_manage_connections
• composio_multi_execute_tool
• composio_remote_bash_tool
• composio_remote_workbench
• composio_list_trigger_types
• composio_get_trigger_type_schema
• composio_create_trigger
• composio_list_triggers
• composio_delete_trigger
• save_automation_definition

The multi-execute and remote-workbench tools are thin meta-tool wrappers: pass the raw JSON arguments expected by the corresponding COMPOSIO_* meta tool/schema.

Automation JSON handoff

save_automation_definition writes automation metadata for the host application to read.

By default it writes to Pi's global Composio automation handoff file:

~/.config/pi/composio-automations.json

Set PI_COMPOSIO_AUTOMATIONS_JSON to override the global handoff path. Passing filePath to the tool still writes a specific JSON file for that call.

The file contains a JSON array of automation definitions and the tool upserts by triggerId.

Local scripts

• bun test
• bun run test:e2e
• bun run typecheck
• bun run build
• bun run test:integration
• bun run test:e2e:signup
• bun run dev:pi

bun run dev:pi loads the extension from src/index.ts through Pi's embedding API.

Verification

Automated checks before handoff or release:

bun run test
bun run test:e2e
bun run typecheck
bun run build

bun run test:e2e is deterministic: it loads src/index.ts through Pi's SDK in an isolated HOME sandbox, verifies registered tools/commands, executes non-network tools, and exercises /composio-init without contacting Composio.

Live signup e2e (depends on the external agents.composio.dev service):

bun run test:e2e:signup

Integration test with real Composio credentials/config:

COMPOSIO_API_KEY_TEST=...
COMPOSIO_TEST_TRIGGER_SLUG=...
COMPOSIO_TEST_TRIGGER_CONFIG_JSON='...'
# Optional: bind to a known active connected account/alias/word id.
COMPOSIO_TEST_ACCOUNT=ca_...
bun run test:integration

Manual Pi smoke test:

1. Start Pi with the local extension:

   pi -e ./src/index.ts

2. Ask the agent to run any Composio tool; it will call composio_signup automatically on first use. Or run /composio-init to store an existing Composio API key.
3. Run composio_debug_info and confirm runtime plus authoring tools are listed (and apiKeySource is "signup", "stored", or "env" depending on setup).
4. Run composio_list_trigger_types and composio_get_trigger_type_schema for a known trigger.
5. Create a test trigger with composio_create_trigger.
6. Confirm it appears via composio_list_triggers.
7. Save the automation handoff with save_automation_definition.
8. Confirm ~/.config/pi/composio-automations.json (or PI_COMPOSIO_AUTOMATIONS_JSON) contains the expected automation and the host app can read it.
9. Clean up with composio_delete_trigger.

Webhook/ngrok delivery verification belongs to the host app: start the app receiver, expose it through ngrok, create/configure the Composio trigger for that URL, cause a real event, and confirm the app receives it.