> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nagare.smtdfc.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin Overview

> How Nagare plugins work, plugin package structure, features (permissions), and how to install and manage plugins.

Plugins extend Nagare with new tools, new chat channels (like Telegram), or custom system prompts. Each plugin is **an independent process** launched by the gateway, communicating with the gateway via IPC:

* Linux/macOS: Unix socket `~/.nagare/nagare-plugin.sock`.
* Windows: named pipe `\\.\pipe\nagare-plugin`.

You can write plugins in [Go](https://docs.nagare.smtdfc.net/en/plugins/go-sdk.md) or [Rust](https://docs.nagare.smtdfc.net/en/plugins/rust-sdk.md).

## Project structure

```text theme={null}
my-plugin/
├── metadata.json
├── go.mod            # or Cargo.toml
└── main.go           # or src/main.rs
```

### metadata.json

```json theme={null}
{
  "package_name": "com.example.hello",
  "name": "Hello plugin",
  "version": "1.0.0",
  "api_version": "1",
  "author": "Your Name",
  "features": ["plugin_tool"]
}
```

| Field | Required | Description |
| - | - | - |
| `package_name` | Yes | Unique identifier. Only letters, numbers, `_`, `.`, `-`; must start and end with a letter or number; cannot contain `..` or slashes. |
| `name` | Yes | Display name. |
| `version` | Yes | Plugin version. |
| `api_version` | Yes | Plugin API version, currently `"1"`. |
| `author` | Yes | Author name. |
| `features` | No | List of plugin features required (see below). |
| `bin` | No | OS-to-relative-path map to the executable file. `nagare plugin build` fills this field automatically. |

### Feature (permission)

Plugins can only use the functionality they declare in `features`:

| Feature | Allows |
| - | - |
| `plugin_tool` | Register new tools and tool categories. |
| `chat` | Open chat channels, send messages, receive responses, and send approval results. |
| `model_provider` | Read the list of model providers. |
| `system_prompt` | Insert or delete the plugin's system prompt. |

## Build a plugin package

In the plugin directory, run:

```bash theme={null}
nagare plugin build
```

This command:

1. Reads and validates `metadata.json`.
2. Builds the executable: `go build` if `go.mod` exists, or `cargo build --release` if `Cargo.toml` exists. The directory must not contain both.
3. Computes the SHA-256 checksum of the executable.
4. Packages everything into `<package_name>.nagare_plugin`.

To sign the package, add `--sign`. See [Plugin Signing](https://docs.nagare.smtdfc.net/en/plugins/signing.md).

## Managing plugins

Go to **Settings → Plugins**:

| Action | Description |
| - | - |
| **Install Plugin** | Web UI: upload the `.nagare_plugin` file (optionally with the `.sig` signature file). Desktop app: enter the absolute path to the package. |
| Enable / Disable | Start or stop the plugin process. |
| Update | Upload a new version of the package. Existing chat sessions are preserved. |
| Status | View PID, CPU usage, and memory usage of the plugin. |
| Uninstall | Remove the plugin. |

During installation, you may receive a warning if the package is **unsigned** or **unverified**. See [Plugin Signing](https://docs.nagare.smtdfc.net/en/plugins/signing.md#installation-warnings).

## Runtime environment

The gateway verifies the executable checksum before every launch. If it does not match, the plugin is marked as failed and other plugins continue running normally.

Plugins inherit the gateway's environment variables, plus:

| Variable | Value |
| - | - |
| `NAGARE_PLUGIN_CONNECT_CODE` | Code used when handshaking with the gateway. |
| `NAGARE_PLUGIN_SOCKET_PATH` | Path to the IPC socket/pipe. |
| `NAGARE_PLUGIN_LOG_FILE` | `~/.nagare/logs/plugins/<package_name>.log` |
| `NAGARE_PLUGIN_CONFIG_DIR` | `~/.nagare/configs/plugins/<package_name>` |
| `NAGARE_PLUGIN_DATA_DIR` | `~/.nagare/data/plugins/<package_name>` |

SDKs read these variables automatically.

## Chat messages

With the `chat` feature, plugins receive agent responses as JSON chunks. Each chunk has a `type` field:

| `type` | Content |
| - | - |
| `TEXT_MESSAGE` | Text snippet (`content`). |
| `APPROVAL_REQUEST_MESSAGE` | Tool approval request (`requestID`, `title`). |
| `AGENT_ERROR_MESSAGE` | Error (`code`, `error`). |
| `AGENT_STARTED_MESSAGE`, `AGENT_COMPLETED_MESSAGE` | Agent started, agent completed. |
| `TOOL_CALL_MESSAGE`, `TOOL_RESULT_MESSAGE` | Tool call and result. |
| `REASONING_MESSAGE` | Model reasoning content. |

The built-in Telegram plugin is a complete example. See the source code at [plugins/telegram](https://github.com/smtdfc/nagare/tree/main/plugins/telegram).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.