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

# Plugins

> The ArgentOS plugin system — extend agent behavior with argent.plugin.json manifests.

## Overview

Plugins are extensions that modify agent behavior at the runtime level. They can register new tools, inject system prompt context, intercept messages, and hook into the agent lifecycle. Plugins are the lowest-level extension mechanism in ArgentOS.

For a hands-on guide to building your own plugin, see [Building Plugins](/tools/building-plugins).

## Plugin Location

Plugins are discovered from two directories:

```
~/.argentos/extensions/          # Global (user-level)
.argent/extensions/              # Workspace (project-level)
```

Each plugin is a directory containing at minimum an `argent.plugin.json` manifest and an entry point (`index.ts` or `index.js`):

```
~/.argentos/extensions/
├── response-validator/
│   ├── argent.plugin.json
│   └── index.ts
├── atera/
│   ├── argent.plugin.json
│   └── index.ts
└── canvas-docs-enforcer/
    ├── argent.plugin.json
    └── index.ts
```

## Plugin Manifest

Every plugin has an `argent.plugin.json` manifest used for discovery and config validation:

```json theme={null}
{
  "id": "my-plugin",
  "name": "My Plugin",
  "description": "What this plugin does",
  "version": "1.0.0",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string",
        "description": "API key (prefer service-keys.json)"
      }
    }
  },
  "uiHints": {
    "apiKey": { "sensitive": true, "label": "API Key" }
  }
}
```

### Manifest Fields

| Field          | Required | Description                                                  |
| -------------- | -------- | ------------------------------------------------------------ |
| `id`           | Yes      | Unique plugin identifier                                     |
| `configSchema` | Yes      | JSON Schema for plugin config (even if empty)                |
| `name`         | No       | Display name                                                 |
| `description`  | No       | Short summary                                                |
| `version`      | No       | Semver version                                               |
| `uiHints`      | No       | UI hints for config fields (sensitive, labels, placeholders) |
| `kind`         | No       | Plugin kind (e.g., `"memory"`)                               |
| `channels`     | No       | Channel IDs registered by this plugin                        |
| `providers`    | No       | Provider IDs registered by this plugin                       |
| `skills`       | No       | Skill directories to load (relative to plugin root)          |

## Plugin Capabilities

### Tool Registration

Plugins register tools programmatically in their entry point via `api.registerTool()`:

```ts theme={null}
export default function register(api: any) {
  api.registerTool({
    name: "weather_lookup",
    description: "Look up current weather for a location",
    parameters: {
      type: "object",
      properties: {
        city: { type: "string", description: "City name" },
      },
      required: ["city"],
    },
    async execute(_id: string, params: any) {
      const data = await fetchWeather(params.city);
      return { content: [{ type: "text", text: data }] };
    },
  });
}
```

<Tip>
  Tools can be marked as **optional** (opt-in via allowlists):

  ```ts theme={null}
  api.registerTool({ /* ... */ }, { optional: true });
  ```
</Tip>

### System Prompt Injection

Plugins can inject text into the agent's system prompt via the `before_agent_start` hook:

```ts theme={null}
api.on("before_agent_start", async (ctx: any) => {
  ctx.systemPromptSuffix = "When creating documents, always use doc_panel.";
});
```

### Lifecycle Hooks

| Hook                 | When                  | Use Case                              |
| -------------------- | --------------------- | ------------------------------------- |
| `before_agent_start` | Before each agent run | Inject context, nudge agent for setup |

### Service Keys

Plugins can read API keys from `~/.argentos/service-keys.json` (managed via the dashboard) rather than requiring separate configuration. See [Building Plugins](/tools/building-plugins#service-keys) for the full pattern.

## Plugin Allowlist

If `plugins.allow[]` in `argent.json` has entries, only listed plugins are enabled:

```json theme={null}
{
  "plugins": {
    "allow": ["atera", "canvas-docs-enforcer"],
    "entries": {
      "atera": { "enabled": true, "config": { } }
    }
  }
}
```

<Info>
  Non-bundled plugins default to enabled when the allowlist is empty.
</Info>

## Tool Name Conflicts

<Warning>
  When multiple plugins register tools with the same name, the **built-in tool wins**. Plugin tools with conflicting names are skipped silently.
</Warning>

## Managing Plugins

```bash theme={null}
# List installed plugins
argent plugins list

# Enable/disable a plugin
argent plugins enable <name>
argent plugins disable <name>
```

## Related

* [Building Plugins](/tools/building-plugins) — End-to-end guide with service keys, config persistence, and hooks
* [Marketplace](/marketplace) — Browse and install community packages