Overview

Relevant source files

executor is a local-first execution environment and integration layer for AI agents README.md1-5 It provides a unified tool catalog, shared across different agents (such as Cursor, Claude Code, or custom scripts), handling complex tasks like authentication, tool discovery, and human-in-the-loop approvals README.md19-60 Instead of granting agents broad shell access, executor exposes a typed TypeScript runtime where agents call tools.* functions within a sandboxed environment README.md80-97

Mental Model

The system operates as a local control plane that manages the lifecycle of tools and their execution README.md16-112

Sources: Users connect external systems via protocols like MCP, OpenAPI, GraphQL, or Google Discovery README.md60-61
Catalog: executor indexes these sources into a searchable, typed namespace README.md83-97
Execution: Agents run code (via CLI executor call or MCP execute) that interacts with the tools object README.md101-131
Interaction: If an execution pauses for auth or approval, it can be resumed via the CLI or Web UI README.md114-134

System Architecture

The following diagram maps high-level conceptual components to their corresponding code entities within the monorepo.

Code Entity Mapping

Sources: bun.lock31-162 apps/cli/src/main.ts58-84 apps/cli/package.json25-36 apps/cloud/package.json35-52

Core Components

Component	Role	Code Reference
CLI (`executor`)	Primary entry point for `call`, `web`, and `mcp` commands.	apps/cli/package.json5-7 README.md122-138
Web UI	React-based dashboard for managing sources and tools.	packages/react/package.json2-24 README.md14-17
Platform SDK	Core abstractions for tool catalogs, backends, and secret management.	apps/cli/package.json31 apps/cloud/package.json51
Plugin System	Protocol-specific adapters (MCP, OpenAPI, GraphQL, etc.).	apps/cloud/package.json44-47 README.md60-61
Kernel Runtimes	Sandboxed environments, primarily QuickJS (WASM-based).	apps/cli/src/main.ts16-37 apps/cli/package.json30-35

Monorepo Organization

The project is a Bun Workspace using Turbo for task orchestration bun.lock4-30

apps/: End-user entry points: the CLI (apps/cli), local server/web, Desktop app (apps/desktop), and Cloud platform (apps/cloud) bun.lock31-167
packages/: Core logic including the sdk, execution engine, runtime-quickjs, and various plugin-* packages (e.g., plugin-mcp, plugin-openapi) AGENTS.md107-122
examples/: Reference code for using the SDK and building custom integrations examples/all-plugins/package.json1-20
tools/: Internal development tools, including custom oxlint rules AGENTS.md18-106
notes/: Contains design documents and internal architectural discussions.
.agents/skills/: Contains coding guides and skill definitions for AI agents working on the codebase.

Monorepo Logic Flow

Sources: bun.lock31-184 AGENTS.md107-122

Distribution and Releases

The executor CLI is distributed as a standalone NPM package README.md12 The release process is managed via Changesets bun.lock8-9

Version Management: Changesets handle version bumping and lockfile synchronization bun.lock8-9
Quality Control: Custom oxlint rules, typecheck, and vitest ensure code quality before release AGENTS.md18-20
Native Modules: Native bindings (like libSQL or keyring) are initialized early in the CLI entrypoint to ensure paths are correctly resolved before they are eagerly loaded by dependencies apps/cli/src/main.ts1-3
Sidecar Pattern: The Desktop application manages the CLI binary as a sidecar process apps/desktop/package.json12-20

Next Steps

To install and run the project, see Getting Started.
To understand the monorepo layout and build system, see Repository Structure.
For a deep dive into the internal layers, see Core Architecture (Section 2).

Sources: README.md9-17 apps/cli/src/main.ts1-114 AGENTS.md107-122