Plugin Overview

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 or Rust.

Project structure

my-plugin/
├── metadata.json
├── go.mod            # or Cargo.toml
└── main.go           # or src/main.rs

metadata.json

{
  "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:

nagare plugin build

This command:

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

To sign the package, add --sign. See Plugin Signing.

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.

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.

Getting started

User guides

Plugin development

Reference

Plugin Overview

Project structure

metadata.json

Feature (permission)

Build a plugin package

Managing plugins

Runtime environment

Chat messages

​Project structure

​metadata.json

​Feature (permission)

​Build a plugin package

​Managing plugins

​Runtime environment

​Chat messages

Project structure

metadata.json

Feature (permission)

Build a plugin package

Managing plugins

Runtime environment

Chat messages