# Plugins

> Add tools the agent can call, slash commands, hooks and skills. Off until you enable them.

A plugin is a folder with a `plugin.json`. It can add **tools** the agent calls, **slash commands**, **hooks** that run around tool calls, and **skills**. Anyone can write one; nothing is compiled into Line.

```text
~/.line/plugins/<name>/          yours, every project
<project>/.line/plugins/<name>/  shipped with a repo
```

## Trust model

<Warning>
Plugins run programs with your permissions. Line keeps them off until you say otherwise.
</Warning>

- A plugin never runs until you enable it (`line plugin enable <name>` or `/plugins enable <name>`). Enabling shows every program it can run.
- Enabling records a fingerprint of **all** the plugin's files. If any file changes, the plugin is disabled until you review and enable it again. A cloned repo can't run code just by shipping `.line/plugins`.
- Plugin tools ask for approval like shell commands, unless the manifest marks them `"read_only": true`.
- Programs run in the project folder, without a shell (argv), with Line's credentials removed from the environment.

## Manifest

```json plugin.json
{
  "name": "guard",
  "version": "0.1.0",
  "description": "What it does",
  "tools": [{
    "name": "deps",
    "description": "Shown to the model",
    "parameters": { "type": "object", "properties": { "path": { "type": "string" } } },
    "read_only": true,
    "timeout_secs": 30,
    "command_unix": ["sh", "${PLUGIN_DIR}/tools/deps.sh"],
    "command_windows": ["powershell", "-NoProfile", "-File", "${PLUGIN_DIR}/tools/deps.ps1"]
  }],
  "commands": [
    { "name": "audit", "description": "…", "prompt": "Review the dependencies. {{args}}" },
    { "name": "status", "description": "…", "run": ["git", "log", "--oneline", "-5"] }
  ],
  "hooks": {
    "session_start": [["sh", "${PLUGIN_DIR}/hooks/context.sh"]],
    "pre_tool": [["sh", "${PLUGIN_DIR}/hooks/block.sh"]],
    "post_tool": [],
    "turn_end": []
  },
  "skills": "skills"
}
```

<ParamField path="tools" type="object[]">
Exposed to the model as `<plugin>__<tool>`. Arguments arrive as JSON on stdin; stdout is the result; a non-zero exit is reported as a failure. Environment: `LINE_PROJECT_DIR`, `LINE_PLUGIN_DIR`, `LINE_TOOL`. Use `command` (all systems) or `command_unix` / `command_windows`: an argv array, or a string run by `sh -c` / PowerShell.
</ParamField>
<ParamField path="commands" type="object[]">
Run as `/<plugin>:<command> [args]` (or `/<command>` when no other plugin uses the name). `prompt` sends a prompt to the agent (`{{args}}` is what you typed after it); `run` executes a program and shows its output.
</ParamField>
<ParamField path="hooks" type="object">
Each hook gets a JSON payload on stdin. `pre_tool` (`{"tool", "arguments"}`): exit code **2** blocks the call and stdout is the reason given to the model. `post_tool` (`{"tool", "arguments", "ok", "summary"}`) and `turn_end` observe. `session_start` runs at the start of each turn; its stdout (up to 4 KB) is added to the agent's context. Hooks time out after 15 seconds.
</ParamField>
<ParamField path="skills" type="string">
A folder of skills that are available while the plugin is enabled.
</ParamField>

## Commands

```bash
line plugin new <name> [--project]                 # scaffold (enabled: you wrote it)
line plugin install <folder | owner/repo[/path]>   # copy into ~/.line/plugins (disabled)
line plugin info <name>
line plugin enable|disable <name>
line plugin remove <name>
line plugin list
```

In the TUI: `/plugins`, `/plugins enable|disable <name>`, `/plugins reload`.