Edit the site
Make my first edit
Turn on the element picker, click the thing you mean, and say what you want. → A tour of the editor · Writing prompts that workUndo something, or go back to this morning
Four different ways back, and they are genuinely different tools. → Review, undo and versionsPublish only some of my changes
Every page in the publish dialog has its own checkbox. → Publishing your changesStop repeating “keep it in our voice” on every request
→ The editorial briefGet started as a developer
See it running in two commands
Boot a real nine-page site and the editor, with no API key and no repository. → Try the demoAdd it to a Next.js site I already have
→ Add Avocado to your site · Manual setupUnderstand the model before writing any code
Pages, blocks, props, operations, sessions, snapshots. The mental model that everything else builds on. → Core Concepts · How It Works · ArchitectureBring in your own site
Hand the integration to your coding agent (Claude Code, Cursor, Codex)
The recommended path. Your agent already knows your codebase, and the work lands through your normal review flow. → Bring your own coding agentLet the built-in onboarding agent do it
Give the in-editor onboarding agent a URL or GitHub repo. It analyzes, wires the SDK, and registers the site. Early — treat the first pass as a draft. → Onboarding agentRead the integration contract
Every seam the integration has to satisfy, whether you or an agent writes the code. → Integration contract · Next.js integration referenceProve the integration is finished
editableCoverage and panelCoverage grade which declared fields the page actually exposes and whether the property panel is usable. The number is what says you are done.
→ Coverage checks
Connect a CMS
Wire up Contentful, Sanity, or Strapi
All three ship as working examples underexamples/ with bootstrap scripts that generate the content model for you.
→ CMS adapters
Write an adapter for a CMS we don’t ship (Hygraph, Payload, Directus, …)
Two functions:getPages({ perspective }) → PageDoc[] and onPublish(pages, config) → CmsPublishResult. How much sits behind them depends on how far your CMS’s shape is from a PageDoc — a JSON-backed site is almost nothing; a CMS that localises per field and stores list rows as their own documents is the real work.
→ CMS adapters — Writing your own · Field table
Customize what’s editable
Make your own components editable
On a site that already exists, your components are the blocks. Register one with a Zod schema and field metadata, and the AI planner edits it like any other block. → Custom blocks · Block systemDeclare a CMS-backed content model once
One field table derives the Zod schema, the panel metadata, the projection out of your CMS, and the merge back into it. Packs ship for Storyblok and Sanity. → Field tableBrowse the live catalogue of built-in blocks
20 blocks, each with editable props, in a live workspace with viewport switcher. → avocadostudio.dev/components · Built-in blocks referenceUse drag-and-drop instead of (or alongside) chat
Avocado ships a Puck integration that produces the sameBlockInstance model from a visual editor.
→ Puck mode
Drive Avocado from outside the editor
From any MCP client
Avocado bundles an MCP server with 49 tools over stdio or streamable HTTP. Drop in a config snippet and Claude Code, Claude Desktop, Cursor, or any other MCP host can read and edit your site directly. → MCP serverFrom a Jira ticket
Webhook + REST integration that turns ticket comments into chat messages. → Jira integrationDeploy
Self-host with Docker
The supported production path. Docker image + persistent volume + Render / Fly / Railway / DO / Kubernetes. → Docker deploymentDeploy the editor + site to Vercel
Three projects: orchestrator (Docker/Render), editor (Vercel), site (Vercel). → Vercel deployment · Netlify deploymentRun a public playground / demo
Locked-downDEMO_MODE=1 with allow-listed ops, per-IP rate limiting, and no AI image gen.
→ Demo mode
Publish to a custom target (S3, GitLab Pages, …)
ImplementPublishTarget (two methods) and register it. The route handler picks it up automatically.
→ Publishing — Building a custom target
Lock down a production deployment
Two credentials, three gates, and the one surface that stays off unless you turn it on. → Security and accessBack up the drafts that are not published yet
Where the SQLite state lives, what is capped, and what a snapshot restores. → State and backupsTune AI behavior
Use Gemini (or OpenAI, or both) instead of Claude
Set the appropriate API key. The editor’s model picker surfaces any provider with a configured key. → AI Providers & Model RoutingUse cheaper models for routine edits, smarter ones for restructures
Per-tier model env vars (*_MODEL_FAST, *_MODEL_BALANCED, *_MODEL_REASONING, *_MODEL_CODEX).
→ AI Providers — Model tiers
Add a new language to the editor + AI responses
One new dictionary file, three lines of glue, one entry in the orchestrator’sLOCALE_NAMES.
→ Internationalization
Debug
A chat returned the wrong operation (or no operation)
Playbook for investigating prompt failures, wrong ops, and regressions. → Chat troubleshootingSee what the planner is spending in tokens
Per-request token usage telemetry with per-provider breakdown. → Token usage trackingFollow one chat request through its phases
Every chat turn emits phase events, fromreceived through planning and apply to result.
→ Chat telemetry events