---
title: Plugins
description: Los plugins son pequeñas carpetas que dan nuevas herramientas al agente de programación Lampson, en cualquier lenguaje: consultas a tu base de datos, la API de tu empresa, un deploy.
---
# Plugins

Un **plugin** es una carpeta que le enseña a Lampson una herramienta nueva. Consultar tu base de datos, llamar a la API de tu empresa, ejecutar un despliegue, publicar un mensaje — cualquier cosa que pueda hacer un script, en cualquier lenguaje. Los plugins están **apagados por defecto**: tú enciendes cada uno, y solo entonces el agente puede usar sus herramientas.

> Hasta Lampson 0.2.6 los plugins se llamaban *lámparas* (lamps). Ese nombre ahora es de [lamps.sh](https://lamps.sh) — mira [Plugins y lámparas](#plugins-y-lámparas). Las carpetas viejas siguen funcionando: [qué sigue andando](#antes-se-llamaban-lámparas).

## Encender uno

```
❯ /plugins on postgres
☼ postgres is on — 1 tool available: plugin_postgres_query
```

En la interfaz web, haz clic en el pill **plugins** de la cabecera: una lista de todos los plugins con un interruptor, sus herramientas y un formulario para probar cada una tú mismo. `/plugins off <name>` lo apaga. El agente puede *pedirte* que enciendas un plugin, pero nunca puede hacerlo por su cuenta.

## Anatomía

```
~/lampson/plugins/postgres/      ← global: disponible en todos los proyectos
  plugin.json                    ← el manifiesto
  query.py                       ← el código, en cualquier lenguaje

my-project/.lampson/plugins/…    ← o dentro de un proyecto (súbelo a git y tu equipo lo tiene)
```

`plugin.json`:

```json
{
  "name": "postgres",
  "description": "read-only queries on the dev database",
  "kind": "exec",
  "command": "python query.py",
  "timeout": 30,
  "tools": [
    {
      "name": "query",
      "description": "Run a SELECT and return the rows as JSON.",
      "parameters": {"type": "object", "properties": {"sql": {"type": "string"}}, "required": ["sql"]},
      "readonly": true
    }
  ]
}
```

## Cómo funciona una llamada

Cada vez que el agente usa una herramienta de un plugin, Lampson arranca **un proceso corto** y le pasa la llamada en variables de entorno:

| variable | contenido |
|---|---|
| `PLUGIN_TOOL` | qué herramienta se llamó (`query`) |
| `PLUGIN_ARGS` | sus argumentos, como JSON (`{"sql": "select …"}`) |
| `PLUGIN_DIR` | la carpeta del plugin |
| `PLUGIN_WORKSPACE` | la carpeta del proyecto |

Lo que el script imprima en stdout es el resultado que ve el modelo. Una salida distinta de cero o un timeout se convierten en un error que el modelo puede leer.

```python
# query.py
import os, json, psycopg
tool = os.environ["PLUGIN_TOOL"]
args = json.loads(os.environ.get("PLUGIN_ARGS", "{}"))
if tool == "query":
    with psycopg.connect(os.environ["DEV_DATABASE_URL"]) as db:
        rows = db.execute(args["sql"]).fetchall()
    print(json.dumps(rows, default=str))
```

## Dos tipos

- `"kind": "exec"` — `command` se ejecuta tal cual, desde la carpeta del proyecto. Cualquier lenguaje. Una palabra del comando que nombre un archivo de la carpeta del plugin se resuelve automáticamente (`python query.py` encuentra el `query.py` del plugin). Sin sandbox: el script puede hacer todo lo que puede tu usuario.
- `"kind": "syn"` — un programa en [Synsema](https://synsema.org) (`"entry": "plugin.syn"`). Se ejecuta bajo un **techo de capacidades** tomado de `"caps"` en el manifiesto: el plugin puede hacer exactamente lo que aprobaste al encenderlo, y el código que pida más falla. Ejemplo: `"caps": "file.read=workspace/*,net"`.

Como un plugin `exec` no tiene ese techo, encender cualquier plugin es siempre una decisión humana. Tu código, tus reglas, tu riesgo.

## Permisos

Las herramientas de los plugins siguen el modo de [permisos](/es/docs/permissions): preguntan en `ask`, se ejecutan en `yolo`, se deniegan en `strict`. Las herramientas marcadas con `"readonly": true` también están disponibles para los perfiles de solo lectura (`plan`, `review`, `explore`).

## Deja que el agente escriba uno

«Hazme un plugin que liste los pull requests abiertos con `gh`.» El agente crea la carpeta y el manifiesto dentro de tu proyecto, lo valida (`synsema check` para un plugin Synsema) y te dice que está listo — encenderlo sigue siendo cosa tuya. En el chat web aparece una línea `☼ plugin created` y el pill de plugins parpadea.

## Programar un plugin

Una herramienta de un plugin puede ser el trabajo de una [tarea programada](/es/docs/schedules): «cada mañana, ejecuta `postgres.query` con este SQL y envíame el resultado». Encender el plugin es la autorización.

## El ejemplo

`~/lampson/plugins/example-hello/` viene incluido con Lampson — un plugin Synsema con una herramienta, `greet`. Copia la carpeta, renómbrala y ya tienes un punto de partida.

## Plugins y lámparas

Son dos cosas distintas, a propósito:

- Un **plugin** es local, tuyo y de tu repo: cualquier lenguaje, sin distribución, sin techo salvo que lo escribas en Synsema. Rápido de hacer; confías tú.
- Una **lámpara** ([lamps.sh](https://lamps.sh)) es una unidad portable de capacidad: un manifiesto que declara exactamente qué puede tocar el código, un runtime que lo hace cumplir y audita cada comprobación, versionada por tag de git, descargada desde un hub y usable por *cualquier* agente MCP — Claude Code, Cursor, Lampson…

Para usar lámparas en Lampson: instala el CLI, `lamp add <ref>`, habilítala y añade `lamp mcp` como [servidor MCP](/es/docs/mcp). Sus herramientas llegan con su techo escrito en la descripción.

## Antes se llamaban lámparas

Si usabas lámparas en Lampson antes de 0.2.7, hoy no se rompe nada:

- Las carpetas `.lampson/lamps/<name>/` se siguen descubriendo (marcadas como *carpeta vieja* en la interfaz y en `/plugins`); si falta `plugin.json` se lee `lamp.json`.
- El estado de encendido en `.lampson/lamps.json` se lee hasta que exista `.lampson/plugins.json`.
- Los scripts siguen recibiendo `LAMP_TOOL`, `LAMP_ARGS`, `LAMP_DIR` y `LAMP_WORKSPACE` junto a los nombres nuevos; un plugin Synsema puede conservar `require env("LAMP_*")`.
- Las tareas programadas guardadas con `"type": "lamp"` siguen corriendo; `/lamps` es un alias de `/plugins`.
- Las carpetas globales que pusiste en `~/lampson/lamps/` se mueven a `~/lampson/plugins/` la primera vez que ejecutas Lampson.

Es un puente, no un segundo formato: renombra la carpeta a `.lampson/plugins/`, el manifiesto a `plugin.json` y lee las variables `PLUGIN_*`.