Install and operate plugins and integrations

This guide shows how to manage built-in agent integrations and Gardn plugins. It assumes that gardn is already available on your PATH.

Use the CLI for integrations on the Coordinator Host. Use Settings > Integrations for Local or saved SSH Execution Hosts. The Local API plugin and integration methods provide structured results for Coordinator Host automation.

Trust boundary: Plugins are not sandboxed. A linked or installed plugin executes as your current user, can read and change anything that user can access, and can launch more processes. A remote plugin's build commands also execute as your current user. Review the repository, the pinned revision, the preview, every command, and every requested pane or action before you continue. Gardn does not review or endorse plugin code.

Manage built-in agent integrations

The built-in integration writes hooks, extensions, or agent configuration entries into the target agent's own configuration area. The supported targets are pi, omp, claude, codex, devin, kimi, droid, copilot, opencode, hermes, qodercli, cursor, and grok.

1. Check what is installed and whether its embedded version is current:

   gardn integration status

   The output includes the target, not installed, current, or outdated, the expected version when applicable, and the path inspected. To print only outdated installed integrations, run gardn integration status --outdated-only.

2. Install one target:

   gardn integration install codex

   Replace codex with one supported target. Install checks agent availability and, for targets with a minimum agent version, reports an error or warning when that check cannot succeed. All targets are supported on both Windows and non-Windows platforms. kimi is the only target with an agent-version probe: an old version fails, while an unavailable or unparsable version adds a warning and continues.

3. Restart the affected agent pane after installing or updating an integration. Existing agent processes do not automatically reload their hook or extension configuration.

4. Remove the Gardn integration when it is no longer needed:

   gardn integration uninstall codex

   Uninstall removes Gardn-managed hook or extension files and removes Gardn-owned entries from supported agent configuration files. It does not uninstall the agent itself. It has no confirmation prompt.

Integration paths are platform-aware. By default, Gardn uses $XDG_CONFIG_HOME/gardn (or ~/.config/gardn) on Unix-like systems and %APPDATA%\\gardn on Windows; GARDN_CONFIG_PATH can select a specific config.toml. Agent-specific environment variables such as CODEX_HOME, CLAUDE_CONFIG_DIR, COPILOT_HOME, KIMI_CODE_HOME, QODER_CONFIG_DIR, and CURSOR_CONFIG_DIR can move the corresponding agent configuration. The command output is the authoritative path.

Managed files: Re-running an integration install rewrites the Gardn-managed hook, extension, or plugin file at its reported path. Do not edit that file to customize behavior; put custom configuration beside it or remove the integration first. A later install or update can overwrite it.

Manage an integration on an SSH Execution Host

1. Save and connect the host in Settings > Connections.
2. Open Settings > Integrations.
3. Change Integration host from Local to the saved connection.
4. Wait for the host inspection to finish. The list shows whether each integration is missing, current, or needs an update on that host.
5. Select Install, Update, or Uninstall for the target.
6. Restart affected agent panes on that host.

Gardn sends the operation to its managed execution worker. The worker reads and writes the selected host's agent configuration. It does not expose the Coordinator Host's Local API socket, profile arguments, or environment to remote agent hooks.

The host selector is client-local. Changing it does not change another attached client's Settings view. If a saved connection is deleted, the selector returns to Local.

The gardn integration CLI and integration.install or integration.uninstall Local API methods do not select an SSH Execution Host. They continue to manage the Coordinator Host only.

Link a local plugin

Linking registers an existing directory; it does not copy the directory and does not run a build command.

gardn plugin link /absolute/path/to/plugin

The directory (or a direct manifest path) must contain a valid gardn-plugin.toml. Use --disabled to register without running its actions or event hooks:

gardn plugin link /absolute/path/to/plugin --disabled

Inspect the registry and manifest warnings with:

gardn plugin list
gardn plugin list --json

The registry is global to the current user rather than scoped to one default or named session. If no server is running, plugin install, plugin uninstall, plugin link, and plugin list read or update that persisted registry directly. Runtime operations—actions, hooks, panes, enable/disable, and plugin unlink—still require a running server.

Enable, disable, or remove the registry entry as needed:

gardn plugin enable PLUGIN_ID
gardn plugin disable PLUGIN_ID
gardn plugin unlink PLUGIN_ID

unlink removes the registry entry and plugin pane attribution, but leaves the local source directory untouched. A running plugin pane is not killed by unlinking; it remains a normal terminal pane. See the plugin manifest reference for the fields Gardn validates.

Install a GitHub plugin

Remote installation accepts only GitHub shorthand in the form owner/repo or owner/repo/subdir/...; URL and SSH forms are rejected. The optional subdirectory selects the manifest root within the checkout.

Use a reviewed, immutable ref in normal operation:

gardn plugin install OWNER/REPO/plugin --ref v1.2.3

--ref is fetched directly from GitHub and the resolved commit is shown in the preview. A branch name is allowed by the CLI but is mutable; pin a tag that your review covers or, preferably, a full commit ID. Do not omit the ref for a trust-sensitive install unless you have deliberately reviewed the repository's current default revision.

The install sequence is:

1. Gardn shallow-fetches the repository, checks out the requested ref (or HEAD when no ref is given), and resolves the checked-out commit.
2. It parses the manifest and prints a preview containing the plugin id, name, version, source, resolved commit, build/action/event/pane/link-handler counts, every command, platform skips, warnings, and any existing plugin that would be replaced.
3. In an interactive terminal it asks Install this plugin? [y/N]. Answering anything other than y cancels before build execution.
4. It runs supported [[build]] commands from the manifest root as your current user. Build commands are direct argv, not a sandbox; they may write files, run network tools, or execute arbitrary code. Each command's stdout and stderr are capped to the last 64 KiB in a failure report.
5. It validates that the build did not change gardn-plugin.toml, then moves the checkout into Gardn's managed plugin data and registers it.

Non-interactive input must use --yes:

gardn plugin install OWNER/REPO/plugin --ref 0123456789abcdef0123456789abcdef01234567 --yes

--yes bypasses both the preview confirmation and the human review gate; it does not make code safer. Use it only in a controlled automation environment that has already inspected the exact source and ref. If an existing plugin with the same id is locally linked, installation stops and asks you to unlink it first. A GitHub plugin can replace an existing GitHub installation; the preview identifies that replacement.

If a build fails, the install is not completed. The error reports the plugin, build index, working directory, argv, exit status, and capped stdout/stderr. A build that edits the manifest also aborts installation.

Run actions and panes

Actions and panes run only while the plugin is enabled and the current platform is supported.

1. List actions, optionally for one plugin:

   gardn plugin action list
   gardn plugin action list --plugin PLUGIN_ID

2. Invoke an action by id. Use the qualified PLUGIN_ID.ACTION_ID form when more than one plugin exposes the same action id:

   gardn plugin action invoke PLUGIN_ID.ACTION_ID

   An invocation receives the current workspace, tab, focused pane, selection, and invocation-source context when those values exist. An action from a disabled plugin is rejected.

3. Open a declared pane entrypoint:

   gardn plugin pane open --plugin PLUGIN_ID --entrypoint ENTRYPOINT_ID --placement overlay

   The supported placements are overlay, split, tab, and zoomed. overlay opens a detached popup owned by the requesting client; only that client can see, focus, or close it, opening another replaces its current popup, and esc closes it. split can use --target-pane PANE_ID and --direction right|down; tab can use --workspace WORKSPACE_ID. --cwd PATH overrides the default plugin-root working directory, and repeated --env KEY=VALUE adds launch environment values.

4. Focus or close a pane by its pane id:

   gardn plugin pane focus PANE_ID
   gardn plugin pane close PANE_ID

Split, tab, and zoomed plugin panes are ordinary session terminal panes. Overlay popups are separate client-owned runtimes and are not visible or addressable from another attached client. Every plugin pane process starts with the plugin root as its default working directory, and Gardn replaces protected identity, path, and context environment keys with the real values. Do not attempt to spoof those values through --env.

Enabled event hooks run automatically for supported workspace, tab, pane, and agent-status lifecycle events. Enabled [[startup]] commands whose platform filter matches run once when the server starts; refreshing manifests does not replay them, so restart the server to run them again. Link handlers dispatch their declared action when a matching pane URL is clicked. Event, startup, and action commands execute asynchronously; inspect their runtime records with:

gardn plugin log list --plugin PLUGIN_ID --limit 200

The log list is bounded and keeps only recent in-memory session records. A failed action or hook does not roll back the workspace change that triggered it.

Uninstall a plugin and understand the data effect

Uninstall by id or by the installed GitHub source shorthand:

gardn plugin uninstall PLUGIN_ID
gardn plugin uninstall OWNER/REPO/plugin

Uninstall removes the registry entry and, for a GitHub installation, deletes the managed checkout after verifying that it is the expected managed path. It does not delete a linked local directory. It also does not remove the per-plugin config and state directories exposed through GARDN_PLUGIN_CONFIG_DIR and GARDN_PLUGIN_STATE_DIR; remove those directories yourself only after checking their contents. Running panes keep running like unlink; their plugin attribution is removed, and no new actions or hooks can start after the plugin is gone.

For a concise failure-oriented workflow, continue with Troubleshoot sessions, agents, integrations, and plugins.