Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
Agent Guide to the Macro App
How an automated agent (driving a real browser via the chrome-devtools MCP server, or
observing via the Grafana MCP server) should operate the Macro web app. Everything here was
verified live against a local stack (just run_local).
| File | Contents |
|---|---|
| login.md | Passwordless login end to end, Mailpit, known crash + recovery |
| navigation.md | Routes, sidebar, command menu, keyboard model, splits |
| documents.md | Creating docs, typing in the editor, AI edit, comments, Word (DOCX) editor, PowerPoint presentations, Figma designs, Photoshop and Illustrator editors, Photoshop and Illustrator documents (AI tools, search), side panel |
| databases.md | Properties, records, kanban boards, saved views, AI questions, live answers |
| forms.md | Forms: create doors, builder (drag and drop, gates), respond route, Responses grid, sharing, polls |
| ai-chat.md | Standalone and doc-scoped AI chat |
| channels.md | Channels: create, invite, message, participants, bots |
| tasks.md | Task list and creation dialog |
| view-tours.md | Desktop feature flyovers, dismissal, targeting, and embedded videos |
| reminders.md | Email snoozing, the reminder command menu, delivery, and safe failure verification |
| home.md | Home and the mobile Notifications inbox |
| email.md | Mail: threads, read state, trash, cached filtering, reminders |
| calendar.md | Calendar views, Scheduling workspace, booking links, events, and invitations in email |
| search.md | Search |
| files.md | Files (Drive) |
| calls.md | Calls, call links, guests, and sharing |
| crm.md | Customers (CRM) |
| pull-requests.md | Pull request review |
| activity.md | Activity |
| notifications.md | Notifications |
| external.md | External tab: linking WhatsApp by QR, adding and sharing external chats, mocking /whatsapp and /external-chats |
| settings.md | Settings sections, including Slack import and team membership |
| onboarding.md | Onboarding resume links, bypass, and setup plan |
| setup-cards.md | Sidebar import and setup cards, the connector import dialog, and permanent dismissal |
| canvas.md | Canvas colors and link paste |
| soup-live-updates.md | Live updates in flat Soup lists |
| ui-conventions.md | Shared UI behavior: list loading, top bars, dialog actions, user cards, information panels |
| browser-technique.md | Generic chrome-devtools MCP lessons learned on this app |
| observability.md | Correlating a UI action to backend traces/logs with the Grafana MCP |
Local stack conventions used in examples: frontend http://localhost:<fe>/app, backend proxy
https://localhost:<be> (checked-in self-signed cert; trust infra/local/certs/ca.pem), Mailpit http://localhost:<mp> (ports come from the --instance;
e.g. the lgtm instance uses 27910 / 27909 / 27908).
For remote browser testing, trust infra/local/certs/ca.pem and open the
printed https://<hostname>:<proxy-port>/app/ URL. The launcher calls hostname
and includes it in both the generated certificate and Vite's allowed hosts.
Caddy forwards frontend assets and HMR to Vite while routing API and backend
WebSockets directly. No Tailscale setup is required; the browser needs network
access to that hostname and port. Plain HTTP on a remote hostname cannot retain
secure login cookies.
Standalone bun run dev uses the same CA and serves HTTPS directly through
Vite. Hosted dev API and WebSocket requests use /__macro_dev/ on the page
origin, with auth cookies scoped to that hostname. Use email-code sign-in; the
hosted Google/SSO redirect allowlist does not include arbitrary hostnames.
Email magic links retain the page's HTTP or HTTPS scheme and port.
On allowed OAuth origins such as https://localhost, standalone Vite uses the
session-code handoff to establish cookies on the local hostname after SSO.
For the standalone marketing site, verify cold product-page navigation with the route module delayed: prerendered content must remain until the page is ready. On mobile, the single hamburger opens and closes navigation; there is no separate caret. Check Escape focus return and keyboard wrapping inside the open menu.
Agent API hosting: chat, routines, preview control, and public MCP share the agent harness service; browser gateway paths remain unchanged. See the service consolidation guide.