RhysSullivan / executor

executor is a local-first execution environment for AI agents. It gives an agent a TypeScript runtime, a discoverable tool catalog, and a single local place to connect external systems such as MCP servers, OpenAPI APIs, and GraphQL APIs. Instead of pasting large MCP manifests into every chat or giving an agent broad shell access, you run code inside and let it call typed functions. Community Join the Discord community: https://discord.gg/eF29HBHwM6 At runtime, behaves like one local product: • a CLI for starting the runtime and executing code • a local API server • a local web UI for connecting sources, inspecting tools, and managing secrets • an MCP endpoint for hosts that want to drive through MCP The current codebase lives in and . Older experiments stay in and . Attribution • Crystian provided the npm package name . • The concept in this project is inspired by Cloudflare's Code Mode announcement. Why this exists is built around a simple idea: agents should work against a structured tool environment instead of guessing at raw HTTP calls, carrying huge MCP definitions in context, or running arbitrary local commands with broad permissions. In practice that means: • sources are connected once and turned into a reusable workspace tool catalog • the agent discovers tools by intent, inspects schemas, and then calls typed functions • secrets and OAuth flows stay in the local runtime and web UI instead of being pasted into chat • human interaction can pause an execution and resume it cleanly Mental model Think of as a local control plane for agent tool use. • You start a local daemon. • You connect sources such as an MCP server, an OpenAPI document, or a GraphQL endpoint. • indexes those sources into a workspace tool catalog. • An agent runs TypeScript against that catalog through or through the MCP bridge. • If a tool needs credentials or user input, execution pauses, opens a local flow, and then resumes. What it does today Connect external tool sources currently supports these source types: • : remote MCP servers, including transport selection for streamable HTTP or SSE • : REST APIs described by an OpenAPI document • : GraphQL endpoints that can be introspected into callable tools The add-source flow can: • probe a URL and infer what kind of source it is • infer likely authentication requirements • prompt for credentials when discovery or connection needs them • start OAuth when a source requires it • persist the source and its indexed tool metadata in the local workspace The web app also includes templates for common providers so you can start from real examples instead of filling every field by hand. Run agent code against tools The main CLI workflow is . The runtime expects the agent to use the built-in discovery workflow: A few important rules shape the execution model: • write TypeScript, not raw shell pipelines • use , not direct • discover first when the exact tool path is not known • inspect schemas before calling complex tools Handle credentials and user interaction When a source or tool needs human input, can pause the execution and create an interaction record. That interaction may ask you to: • open a secure local credential page • complete an OAuth flow in the browser • respond to a structured elicitation from a tool host • resume a paused execution from the CLI This is the core human-in-the-loop behavior that lets keep secrets and approvals outside the agent's raw context. Inspect the connected tool model The web UI is not just a setup surface. It is also where you can inspect what learned from a source. For each source you can: • browse its tool tree • search for tools by intent • inspect input and output schemas • view generated manifests, definitions, and raw source documents when available • edit source settings and authentication details Quick start If you want to use this a package distribution, install it via npm: Then either tell your agent to use the CLI or to open the web UI and copy the MCP CLI install command. Then you can run the CLI as . If you are working from this repository locally, the easiest path is: That starts the local runtime. The default base URL is: From there: • Open the web UI in your browser. • Add a source from . • If needed, store credentials in . • Run TypeScript with . If you are using a packaged distribution, the command name is simply instead of . Core CLI commands accepts code in three ways: • inline as a positional argument • from • from standard input with Examples: If an execution pauses, resume it with: Adding a source There are two main ways to add a source. In the web UI Use the Add Source flow to: • paste a URL • run discovery • review the inferred kind, namespace, transport, and auth • connect the source • complete credential or OAuth setup if required This is the easiest path for most users. From inside an execution The runtime also exposes , which lets an agent add a source from code. Examples: For HTTP-style sources, can drive the credential flow for you. How execution works At a high level, every execution follows the same loop: • resolves the current local installation and workspace. • It builds a tool catalog from built-in tools plus all connected workspace sources. • It runs your TypeScript inside the configured sandbox runtime. QuickJS is the default, and can set . • Tool calls are dispatched through rather than directly from your code. • If a tool needs interaction, the run pauses and records a pending interaction. • Once the interaction is resolved, the execution continues and eventually completes or fails. Example: This gives you a stable surface for agent automation: • the agent sees a coherent catalog • connected sources become reusable namespace-based tools • auth stays attached to sources and secret material • the runtime can track execution state instead of losing it inside a one-shot prompt Web UI overview The React web app is served from the same local serv…