Agent plugins

Agent plugins let an existing coding agent create and operate Sprites without replacing the agent itself. Unless a section says otherwise, the agent stays on your machine and sends remote work to Sprites through the hosted MCP server.

Before you begin

• Install the coding agent you want to use. Check its section below for any version or runtime requirements.
• Have a Fly.io account with access to the intended Sprites organization.
• For OAuth-based plugins, have a browser available for authorization. For Pi, create a Sprites API token and use the storage method in its setup instructions.
• For Herdr, authenticate the Sprites CLI and review the agent login handoff described below.

Run plugin installation commands on your local machine, not inside a Sprite. Keep API tokens out of prompts and committed configuration files.

Codex

The Sprites plugin for Codex adds the hosted MCP server and Sprites workflow guidance.

Install Sprites from the Codex plugin marketplace. On first use, follow the plugin’s browser authentication flow, choose the intended Fly.io organization, and review the connector access policy.

For local installation from a checkout of the repository:

git clone https://github.com/superfly/sprites-codex-plugin.git
cd sprites-codex-plugin
codex plugin marketplace add .

Restart Codex, open its plugin directory, choose the Sprites marketplace, and install Sprites. Then ask:

List my Sprites.

An empty list still confirms that authentication succeeded. Your local Codex workspace and a Sprite’s filesystem remain separate.

Cursor

Install Sprites from the Cursor Marketplace. The Sprites plugin for Cursor bundles the hosted MCP server and Sprites workflow guidance. Cursor starts browser OAuth on the first Sprites request.

Verify it by asking:

List my Sprites.

If you only need the MCP tools, you can add the server directly to ~/.cursor/mcp.json or a project’s .cursor/mcp.json:

{
  "mcpServers": {
    "sprites": {
      "url": "https://sprites.dev/mcp"
    }
  }
}

The direct MCP entry does not include the plugin’s bundled workflow guidance.

Antigravity

Install the Sprites plugin for Antigravity from GitHub:

agy plugin install https://github.com/superfly/sprites-antigravity-plugin

Open /mcp, authenticate the sprites server in your browser, and use restricted connector access unless the workflow intentionally needs organization-wide control. Verify the connection with:

/sprites:list

The plugin also provides commands for creating Sprites, running commands, managing checkpoints and services, and cleaning up environments.

Grok Build

Install and enable the Sprites plugin for Grok Build:

grok plugin install superfly/sprites-grok-plugin --trust
grok plugin enable sprites

Reload plugins with /plugins and r, or restart Grok. Then run /sprites-status or ask Grok to list your Sprites and complete browser OAuth.

An empty Sprite list means the connection is authenticated. For a fuller check, run /sprites-smoke; it lists Sprites, creates a test Sprite, runs a command, and asks before destroying it.

The --trust flag lets the plugin start its MCP connection. Review the repository before installing it, and prefer the restricted OAuth policy unless Grok needs access to every Sprite in the organization.

DeepSeek Harness

The Sprites bundle for DeepSeek Harness requires Node.js 20.19 or newer and the DeepSeek Harness developer preview.

Install the bundle into the built-in Web profile, then start that profile:

npx @deepseek-ai/dsh plugin --profile web add github:superfly/sprites-deepseek-plugin
npx @deepseek-ai/dsh --profile web

Complete browser OAuth on the first connection. If the initial tool synchronization times out while you authorize, finish the browser flow and restart Harness once.

Verify the installed composition:

npx @deepseek-ai/dsh --profile web --dump-config

The output should include dsh-sprites-plugin, sprites-mcp, and sprites-skill-filesystem. The bundle uses mcp-remote because Harness’s current remote HTTP transport does not complete MCP OAuth itself; you do not need a Sprites API token.

Then ask Harness to list your Sprites and check that the tool returns successfully. The configuration dump confirms installation; it does not by itself confirm an authenticated connection.

OpenCode

The Sprites plugin for OpenCode supports OpenCode 1.18.23 or newer and OpenCode 2 beta.

Source installation for now

The package @flydotio/sprites-opencode-plugin is not currently published to npm. Clone the repository and use the checkout path instead of the package name until it is published.

git clone https://github.com/superfly/sprites-opencode-plugin.git

For OpenCode 1, add the absolute package URL to opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["file:///absolute/path/to/sprites-opencode-plugin"]
}

OpenCode 2 uses the plugins key and accepts either a path or a file:// URL. Restart OpenCode after changing the configuration.

Run /sprites-status or ask OpenCode to list your Sprites. If the browser does not open, start authorization explicitly:

opencode mcp auth sprites

Use opencode2 mcp auth sprites for OpenCode 2. No Sprites CLI or pasted API token is required.

Pi

The Pi extension for Sprites requires Node.js 24 or newer. It is not published to npm, so install it directly from GitHub:

pi install git:github.com/superfly/pi-sprites

Set the Sprites token in the environment that launches Pi:

export SPRITES_TOKEN='...'

SPRITE_TOKEN is also accepted. The token stays in the local Pi process and is not copied into remote commands or the Sprite.

Select or create a Sprite, then bootstrap the workspace:

/sprite list
/sprite new pi-my-project
/sprite-bootstrap

While a Sprite is selected, Pi’s normal file and shell tools operate in the remote workspace. Use /sprite-local to return them to your local machine.

Herdr

The Sprites plugin for Herdr, listed in the Herdr plugin marketplace, runs a coding agent inside a persistent Sprite controlled from a local Herdr pane. Each agent pane gets its own Sprite. Unlike the hosted-MCP plugins above, the agent itself runs remotely.

On your local machine, install Herdr 0.9.0 or newer, Node.js 22 or newer, Git, and the Sprites CLI. The CLI must support exec --tty, sessions, checkpoint create, restore, and api.

Authenticate and install the plugin; no npm install or build step is required:

sprite login
herdr plugin install superfly/herdr-sprites-plugin
herdr plugin config-dir sprites

Create config.json in the directory printed by the last command, replacing the organization placeholder:

{
  "org": "your-sprites-organization",
  "agent": "claude"
}

Choose claude, codex, or opencode for agent.

Agent authentication is separate

By default, the plugin hands off an available local Claude or Codex login to the Sprite. Those credentials remain in the Sprite and its checkpoints and use your provider account. To sign in manually instead, add "auth": "none" to config.json before creating a Sprite. This does not revoke credentials already transferred. OpenCode requires manual authentication. See agent login handoff for supported credential sources and limitations.

From a Git worktree in Herdr, launch the configured agent. For a new project, run git init first; no commit is required.

herdr plugin action invoke start-agent --plugin sprites

The new split pane shows setup progress followed by the agent terminal. Sign in there if needed. A setup-launched response only means setup started; check the pane and run Info to confirm the Sprite mapping and remote session, or see setup errors:

herdr plugin action invoke info --plugin sprites

To bring remote edits back, stop the agent before pulling:

herdr plugin action invoke stop --plugin sprites
herdr plugin action invoke pull --plugin sprites

The initial upload includes eligible uncommitted worktree files but excludes local Git history, ignored files, and common credential files. Review source files for embedded secrets before uploading. Changes are not automatically synchronized: Pull refuses overlapping local edits, and Reconnect does not upload new local changes. See worktree transfer for exclusions and size limits.

Stop preserves the Sprite and checkpoints; it does not delete them. See the plugin actions for reconnecting and confirmed cleanup.

Cortex Code

Cortex Code has a focused guide because its plugin includes Snowflake-specific workflows, long-running task support, and explicit authorization steps. Continue with Cortex Code.

If setup gets stuck

• OAuth fails or repeats: see authentication troubleshooting.
• An expected Sprite is missing: check the selected organization and connector access policy. A successful empty list is different from an authentication error; see Sprite visibility.
• A package cannot be found: check the integration’s source-installation notice above before trying another package with a similar name.