PluginsEarly
Capabilities
What a plugin may ask for in plugin.toml, the words a person reads before approving it, and what each one allows.
From the plugin interface of gr 0.2.16 (API 0.1, 0.2, 0.3). gr plugin api capabilities prints it on your machine.
A plugin asks for these in plugin.toml. Before anything of it runs, the person installing it reads each one in the words below and grants or refuses it. See Permissions for how that works.
| In plugin.toml | The person reads | What it allows |
|---|---|---|
fs = ["read:workspace"] | "reads the files in your workspace" | fs.read, list, stat and files inside the root, and the line and selection text in the context; never the daemon's folders or ~/.ssh and the like |
fs = ["write:data"] | "keeps files in its own data folder" | fs.writeData in the plugin's own data folder |
exec = ["rg"] | "runs <program> in the sandbox, with your workspace read-only and no network" | exec.run of that program with any arguments; the path is recorded at approval |
net = ["api.github.com", "*.example.com"] | "sends to and reads from <host>" | net.fetch over HTTPS to that host, or one level of subdomain for *.host |
net = ["localhost:8080"] | "talks to a program on this machine at port <port>" | net.fetch over HTTP or HTTPS to that port on this machine |
graph = "read" | "reads your workspace's graph" | graph.node, children, neighbors and search on the root's graph |
agents = "read" | "sees your agents, what they are doing and what they say" | agents.list and get, and (since 0.2) agents.transcript: what an agent and its person said, without tool results or command output |
agents = ["read", "write"] | "writes to your agents: messages and text they will read and may act on" | agents.send, attach of text to a composer, and agents.start's prompt Since API 0.2. |
agents = ["read", "start"] | "starts agents, which costs money: at most 3 every 10 minutes unless you raise it" | agents.start, bounded by agent_starts Since API 0.2. |
clipboard = "write" | "puts text on your clipboard" | $.clipboard.write and the clipboard.write command Since API 0.2. |
terminal = true | "opens terminals that run commands as you, outside the sandbox; each one is shown" | $.terminal.open and close, and open.terminal of its own terminals Since API 0.2. |
docs = "write" | "changes the text of files you have open, each change one undo step" | the edit command, on documents open in the editor Since API 0.2. |
agents = ["tools"] | "offers tools your agents may call; what a tool answers is read by the agent" | [[tools]]: tools offered to the person's agents (Claude Code, Codex, any harness) through Graphide's MCP server, each call a tool event; a plugin without it granted offers none Since API 0.2. |
net = ["any"] | "its server may reach any host" | the network of the plugin's [[mcp]] servers that ask for it (network = true); never a host $.net.fetch reaches. An MCP server is declared in plugin.toml as [[mcp]] name = "<plugin>.<name>", command (a program [allow] exec names, its path recorded at approval), args, network: the daemon starts it for a workspace once an agent's MCP server lists or calls that workspace's tools, in the sandbox with the workspace read-only, a writable folder of its own under the plugin's data folder (its HOME), no network unless it asks and net:any is granted, the five-name environment of exec.run and a memory cap (mcp_memory_mb); its tools join the plugin's own [[tools]] as plugin_<plugin>_<tool> while agents:tools is granted. Its standard error goes to the plugin's log; a crash restarts it with the host's backoff, five in ten minutes switch it off for the session, ten idle minutes stop it, and it stops with its plugin Since API 0.2. |
graph = ["read", "write"] | "changes this workspace's graph: adds, renames, describes, tags, moves and removes nodes; writes are attributed to the plugin and cannot be undone" | graph.create, patch, move and remove, only in the instance's root. Read and write are separate grants; graph = "read" remains valid. Since API 0.2. |
setup = "read" | "reads how your coding agents are set up on this machine: the names and paths of their instructions, skills, hooks, MCP servers and settings, never a key or a token" | setup.read and setup.layer Since API 0.2. |
These docs describe Graphide 0.2.16, the latest release. Something wrong or missing? Tell us onDiscord or at hello@graphide.com.