io.github.henriquepe/lousa
A whiteboard where AI agents draw their explanations as hand-drawn animated diagrams
Open source Open in the app JSON README (API)
About
A whiteboard where AI agents draw their explanations as hand-drawn animated diagrams
Details
- Kind
- MCP servers
- Topic
- Media, design & games
- Publisher
- henriquepe
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1
- Last push
- 2026-08-02T13:15:22Z
- Repository state
- ativo
- Language
- JavaScript
- License
- AGPL-3.0
- Added
- 2026-08-29 04:00:07
- Updated
- 2026-08-29 04:00:07
- Origin id
io.github.henriquepe/lousa
README
# Lousa
**A whiteboard where your AI agent draws its explanations.**
Ask your agent *"explain this visually"* and it sketches an animated, hand-drawn diagram on a live board — instead of another wall of text. Lousa is an MCP server + web viewer: the agent authors a declarative scene (boxes, arrows, cylinders, notes), and the board renders it stroke by stroke, as if someone were drawing it in front of you.
> *Lousa* is Portuguese for the classic school blackboard.
## Why it's different
- **The agent is the artist.** No prompt box, no OCR — your coding agent already has the context and draws through typed MCP tools.
- **Live, incremental drawing.** Follow-ups edit the scene; the open tab animates only what changed, like watching the diagram evolve.
- **Point at things.** Click elements in the viewer to select them, then tell your agent *"improve what I selected"* — it reads your selection through `get_selection` and targets exactly that.
- **Boards expire by default** (12h, sliding) — a whiteboard, not a document graveyard. `ttlHours: 0` keeps a board forever.
## Quick start
Requires [Node.js 18.17+](https://nodejs.org).
```bash
# Claude Code
claude mcp add lousa -- npx -y lousa mcp
# or run the server directly
npx lousa # viewer at http://127.0.0.1:4666
```
Any MCP host works — for stdio configuration use command `npx`, args `["-y", "lousa", "mcp"]`. The stdio endpoint auto-starts the local server, so the viewer is always available. Then ask your agent to *"draw how our auth flow works"* and open the URL it returns.
## MCP tools
| Tool | What it does |
|---|---|
| `create_board` | Creates a board from a scene, returns `{id, url}` |
| `update_board` | Replaces the scene; unchanged elements stay byte-identical so only changes animate |
| `get_board` / `list_boards` | Read boards |
| `get_selection` | What the user selected in the viewer (ids + full elements) |
| `delete_board` | Deletes a board |
The scene is a JSON array of elements — `box`, `ellipse`, `diamond`, `cylinder`, `arrow` (connects ids), `line`, `text`, `note` — rendered with [rough.js](https://roughjs.com). The full schema ships inside the tool definitions; agents need no extra setup.
## Self-hosting a shared server
Run `lousa` on any Node host and point machines at it:
```bash
LOUSA_TOKEN=<secret> HOST=0.0.0.0 npx lousa # server
LOUSA_URL=https://your-host LOUSA_TOKEN=<secret> npx lousa mcp # each client
```
`LOUSA_TOKEN` gates board listing/creation/deletion and `/mcp`; per-board URLs act as capability links. AWS Lambda + S3 deployment is supported out of the box (`lambda.js` handler + `LOUSA_BUCKET` for storage); any HTTPS front (API Gateway, etc.) works.
| Env var | Default | Purpose |
|---|---|---|
| `PORT` / `HOST` | `4666` / `127.0.0.1` | server bind |
| `LOUSA_DATA_DIR` | `~/.lousa/boards` | filesystem board storage |
| `LOUSA_BUCKET` | — | use S3 storage instead of filesystem |
| `LOUSA_TOKEN` | — | require bearer token (header or `?t=`) on global routes and MCP |
| `LOUSA_URL` | — | `lousa mcp` proxies to this remote server |
| `LOUSA_DEFAULT_TTL_HOURS` | `12` | default board expiry |
## Development
```bash
npm install
npm test # node --test
node cli.js # local server
```
## License
[AGPL-3.0](LICENSE) © Henrique Pires