# How Maxy Works

## The Short Version

Maxy runs on a Raspberry Pi in your home. It uses Claude (Anthropic's AI) as its brain and extends it with plugins — modular capabilities like contacts, Telegram, and memory. Everything stays local: your data, your conversations, your memory graph.

## The Raspberry Pi

Maxy is a server that lives on your local network. It's always on, always available, and accessible:

- **Locally:** `maxy.local:19200` (or the IP address of your Pi)
- **Remotely:** via your personal domain, routed through a Cloudflare tunnel

The Pi runs the web interface, the AI agent, and all the plugin servers. When you send a message, the Pi processes it — not a cloud service.

## The Two Agents

Maxy runs two agents simultaneously:

**Admin agent (you)** — full access to all tools and plugins. This is the agent you interact with at your local or remote URL. It can read and write contacts, send Telegram messages, manage your account, and perform any task you have plugins for. Protected by your PIN.

**Public agent (visitors)** — read-only access. Handles enquiries from people who reach your public URL. It can answer questions about your business and collect waitlist signups, but it cannot access your private data or take actions.

## Plugins

Everything Maxy can do is provided by a plugin. Each plugin is a self-contained package:

- Behaviour instructions (how the agent should act)
- Tools (specific actions the agent can take, exposed via MCP servers)
- Reference documents (detailed knowledge loaded on demand)

Plugins are installed and managed through conversation. You can add marketplace plugins (Stripe, Zapier) or use Maxy's built-in ones (contacts, memory, Telegram).

## Specialist Subagents

Maxy has specialist helpers it can dispatch for specific tasks. You don't need to configure or manage them — Maxy decides when to use them and handles everything automatically. You may see activity like "Dispatching document-specialist..." in the chat timeline when this happens.

| Specialist | What it does |
|-----------|-------------|
| Browser specialist | Automates browser tasks — navigating websites, filling forms, extracting information |
| Memory specialist | Performs focused memory operations — searching, writing, and reindexing your knowledge graph |
| Admin specialist | Handles platform administration — Cloudflare tunnel management, Telegram setup, system configuration |
| Document specialist | Ingests documents and files into your memory graph for searchable storage |
| Researcher | Conducts web research — searching, fetching content, and storing findings in memory |

Specialists are installed during setup and listed when Maxy introduces itself. Some premium plugins add their own specialists (e.g. the writer-craft plugin adds a manuscript reviewer). Specialists installed mid-session become active from the next session.

## Memory

Maxy maintains a graph database (Neo4j) of everything you've told it. People, conversations, preferences, and context are stored as connected nodes. When you ask Maxy something, it searches this graph to retrieve relevant context before responding.

The memory graph is stored on your Pi. It never leaves your network.

## The Web Interface

The web app runs on your Pi on port 19200. It provides:

- **Admin chat** (at `/`) — your primary interface, PIN-protected
- **Public chat** (at `/{agent-name}`) — visitor-facing agents, each with their own URL. On public hostnames, the root path serves the default agent.
- **Telegram bot landing** (at `/bot`)

There is no dashboard, no settings panel, no menus. Everything is done through conversation.

The chat input auto-grows as you type — it expands to fit your message and shrinks back when you delete text. You can also drag the resize handle above the input to set a custom height.
