For coding agents

Start with the installed version

Use this page when helping a user install, configure, or extend Red. Red's built-in coding assistant has its own Agent guide. Find documentation through the documentation index; each guide is also available at its URL with .md appended.

red --version
red --help

This website's release metadata identifies v0.9.1. Compare that with the installed version and read each guide's minimum-version note before applying instructions. Multiple language servers per document and standalone JSON-RPC plugins require Red v0.9.0 or later. Follow installation and update instructions for the user's installation method. red update --check checks availability without replacing the executable.

Identify the configuration layer

Merge changes into existing TOML tables, then run red --check-config. A custom server table replaces its built-in entry as a unit, so preserve required selectors and arguments. See configuration and language support.

Choose the interface

Use terminal commands for installation, package management, and configuration checks; use editor commands for interactive operations. For example, red plugin list runs in a terminal, while :languages reload and :messages run inside Red. Consult the CLI reference and session guide.

Use the documented JSON-RPC or Husk API to develop plugins. Red launches an RPC plugin as a child process and owns its editor resources. The protocol is not a general remote-control endpoint for arbitrary external clients and has no generic host-action escape hatch.

Configure TypeScript, ESLint, and Prettier

Follow the complete TypeScript and ESLint guide, including its recorded compatibility baseline. Keep Red's built-in TypeScript server and register ESLint with overlapping document selectors. Install both server executables on PATH, and install ESLint, TypeScript, and Prettier in the project. ESLint also needs the guide's empty-section workspace/configuration settings.

Retain external Prettier formatting with formatting.provider = "auto" and a language formatter definition. Formatter lookup checks the project's node_modules/.bin before PATH; do not assume language-server startup uses that same lookup. Add formatter definitions for the other language keys if editing JSX or TSX.

Validate the config and restart Red after server-definition changes, then verify hover, completion, diagnostics from both servers, and an ESLint code action. With the guide's sample, changing quotes and pressing Space f should produce formatted with Prettier. Record the observed result, not just a successful config check.

Create and validate a plugin

Start from the complete TypeScript or Python package in the JSON-RPC tutorial, a Markdown outline and table of contents plugin. Red v0.9.0 uses host API 0.19.0 and protocol version 1; these are distinct from Red's application version. Red v0.9.1 exposes host API 0.20.0 and retains support for 0.19.0 packages. Keep example manifests at the earliest API their features require. Use the tutorial's manifest and initialization response together. The TypeScript version needs Node.js 22.18 or later.

red plugin install --path ./markdown-outline
red plugin list

Open a Markdown file in Red, run :Outline, and confirm that the outline panel opens. Listing a package proves installation; invoking its command also exercises process startup and the handshake. If the command does not run, inspect :messages and red.log in Red's configuration directory. On Red v0.9.1 and later, use :plugin-status for the current session's diagnostic details.

For more operations, read the v0.9.0 protocol reference and complete JSON Workbench example. Match those references to the user's release before adopting newer APIs.

Diagnose the failing stage

• Executable: a bare RPC command resolves on PATH; a command containing a path separator resolves inside the package. Arguments are passed without a shell or ~ expansion.
• Manifest and handshake: check API compatibility and ensure returned commands/events match the activation declarations exactly. Wait for initialized before calling host methods.
• Protocol: reserve stdout for newline-delimited JSON-RPC; log to stderr. Keep reading stdin while awaiting host responses.
• Host method: check names and parameters against the protocol. Invalid arguments can return an error while the connection stays active; framing corruption can quarantine the plugin.

On Red v0.9.1 and later, run :plugin-status to inspect the current editor session. Quarantined or starting plugins appear with diagnostic details; a separate red plugin list process cannot report that live state.

Read :messages and red.log in Red's configuration directory. Use red --self-check for bundled-runtime problems and red --check-config for configuration failures. Follow the troubleshooting guide and the relevant tutorial's failure table. Record the version, exact command, observed error, and smallest reproduction before proposing a fix.