executor

https://github.com/user-attachments/assets/11225f83-e848-42ba-99b2-a993bcc88dad

The integration layer for AI agents. One catalog for every tool, shared across every agent you use.

Ask DeepWiki

Quick start

npm install -g executor
executor install
executor web

This installs the local background service and opens the web UI. From there, add your first source and start using tools.

Use as an MCP server

Point any MCP-compatible agent (Cursor, Claude Code, OpenCode, etc.) at Executor to share your tool catalog, auth, and policies across all of them.

executor mcp

Example mcp.json for Claude Code / Cursor:

{
  "mcpServers": {
    "executor": {
      "command": "executor",
      "args": ["mcp"]
    }
  }
}

Use with Pi

Pi does not include a built-in MCP client. To use Executor from Pi, install the community bridge:

pi install git:github.com/gvkhosla/pi-executor-mcp@v0.2.0

Reload Pi, then verify the bridge:

/reload
/executor-status

After that, ask Pi to search, inspect, and call tools through Executor.

Add a source

If you can represent it with a JSON schema, it can be an integration. Executor has first-party support for OpenAPI, GraphQL, MCP, and Google Discovery — but the plugin system is open to any source type.

Via the web UI

Run executor web, go to Add Source, paste a URL, and Executor will detect the type, index the tools, and handle auth.

Via the CLI

executor call executor openapi addSource '{
  "spec": "https://petstore3.swagger.io/api/v3/openapi.json",
  "namespace": "petstore",
  "baseUrl": "https://petstore3.swagger.io/api/v3"
}'

Use baseUrl when the OpenAPI document has relative servers entries (for example "/api/v3").

Use tools

Agents discover and call tools through a typed TypeScript runtime:

// discover by intent
const matches = await tools.discover({ query: "github issues", limit: 5 });

// inspect the schema
const detail = await tools.describe.tool({
  path: matches.bestPath,
  includeSchemas: true,
});

// call with type safety
const issues = await tools.github.issues.list({
  owner: "vercel",
  repo: "next.js",
});

Use tools via the CLI:

executor tools search "send email"
executor call --help
executor call github --help
executor call github issues --help
executor call cloudflare --help --match dns --limit 20
executor call github issues create '{"owner":"octocat","repo":"Hello-World","title":"Hi"}'
executor call gmail send '{"to":"alice@example.com","subject":"Hi"}'

executor call, executor resume, and executor tools ... commands auto-start a local daemon if needed. If the default port is busy, the CLI will pick an available local port and track it automatically.

If an execution pauses for auth or approval, resume it:

executor resume --execution-id exec_123

CLI reference

executor install                    # install/start the durable background service
executor web                        # open the running web UI
executor web --foreground           # start a temporary foreground runtime + web UI
executor daemon run                 # start persistent local daemon in background
executor daemon status              # show daemon status
executor daemon stop                # stop daemon
executor daemon restart             # restart daemon
executor mcp                        # start MCP endpoint
executor call <path...> '{"k":"v"}' # invoke a tool by path segments
executor call <path...> --help      # browse namespaces/resources/methods
executor call <path...> --help --match "<text>" --limit <n> # narrow huge namespaces
executor resume --execution-id <id> # resume paused execution
executor tools search "<query>"     # search tools by intent
executor tools sources              # list configured sources + tool counts
executor tools describe <path>      # show tool TypeScript/JSON schema

Developing locally

bun install
bun dev

The dev server starts at http://127.0.0.1:4788.

Tests

bun run test       # unit + integration suites
bun run test:e2e   # full-stack e2e: boots the cloud and self-host apps and drives them

The browser e2e scenarios need Playwright's Chromium once per machine: bunx playwright install chromium.

Community

Join the Discord: https://discord.gg/eF29HBHwM6

Learn more

Visit executor.sh to learn more.

Attribution

• Thank you to Crystian for providing the npm package name executor.

References

As part of my coding process, I give my agent access to references to other codebases to understand patterns and how other people have implemented systems.

A non exhaustive list of references are:

• Better Auth - Storage adapter reference
• Effect - General code patterns
• OpenCode - Plugin system reference
• OpenClaw - Plugin system reference
• Emdash - Plugin system reference
• Pi - Plugin system reference

It's encouraged also that you can use this codebase as a reference to understand how it's implemented