Documentation
Install Headcode through your coding agent, the skills CLI, or by hand. Then point it at your collections and start shipping.
Fast local install
Use this path for a new local project with one shared live/draft version on http://localhost:3000. It is the preferred baseline for coding agents.
Before running Convex or auth commands, agents should ask:
- Does this directory already contain a Next.js/shadcn app?
- Should I use the standard site or adapt an existing design?
- Which Convex project should this app connect to?
- Which local URL should auth use as
SITE_URL? - Which admin emails are allowed?
- Which Resend sender and API key should magic links use?
- Should development test login and MCP bearer tokens be configured now?
bash rm -f app/page.tsx app/layout.tsx pnpm dlx shadcn@latest add headcodecms/headcodecms/headcode pnpm install pnpm convex dev
Keep Convex running until .env.local contains CONVEX_DEPLOYMENT, then run:
bash pnpm dlx @convex-dev/auth
Set the minimum Convex environment:
bash pnpm convex env set ALLOWED_ADMIN_EMAILS "admin@example.com" pnpm convex env set AUTH_RESEND_KEY "re_..." pnpm convex env set AUTH_RESEND_FROM "Headcode <admin@example.com>" pnpm convex env set SITE_URL "http://localhost:3000"
pnpm dlx @convex-dev/auth creates JWT_PRIVATE_KEY and JWKS. If it prints manual steps, complete them before continuing.
Timing matters: run pnpm convex dev first so CONVEX_DEPLOYMENT and generated Convex files exist. Then run pnpm dlx @convex-dev/auth. Then set Convex env values. Run pnpm auth:token only when enabling development test login or MCP bearer tokens.
Start the app with pnpm dev, then open http://localhost:3000 and http://localhost:3000/admin/login.
Development agent login
After normal magic-link login works, browser-based coding agents can use the development-only test login:
bash pnpm auth:token pnpm convex env set HEADCODE_ENABLE_TEST_LOGIN true pnpm convex env set HEADCODE_ADMIN_TEST_EMAIL "codex@example.com" pnpm convex env set HEADCODE_ADMIN_TEST_TOKEN "the-generated-token" pnpm convex env set ALLOWED_ADMIN_EMAILS "admin@example.com,codex@example.com"
Add the matching public values to .env.local:
env NEXT_PUBLIC_HEADCODE_ENABLE_TEST_LOGIN=true NEXT_PUBLIC_HEADCODE_ADMIN_TEST_TOKEN=the-generated-token
Do not enable server-side test-login variables in production.
Future live configuration
For a production deployment with separate draft and live hosts:
env NEXT_PUBLIC_HEADCODE_VERSION=auto NEXT_PUBLIC_HEADCODE_DRAFT_HOSTS=preview.example.com,draft.example.com NEXT_PUBLIC_SITE_URL=https://www.example.com
MCP write access uses ALLOWED_MCP_TOKENS in both Convex and the Next.js environment. Readonly MCP access uses READONLY_MCP_TOKENS in both environments and can query content, but write tools return an admin-approval message instead of updating content. Use separate MCP client names for draft and live hosts, for example headcode-draft and headcode-live.
Install with your coding agent
Drop the install prompt into Claude Code, Cursor, or any MCP-aware agent. The agent reads your package manager, runs the install, and wires up the workspace.
Install Headcode in this repo and wire up an empty workspace called "acme-marketing".
Install a skill
Skills extend Headcode with first-party recipes - image pipelines, redirects, sitemap generation. Install them with one command and the agent picks them up.
claude skill add @headcode/sitemap
Manual installation
Install Headcode from the shadcn registry, then run the Convex setup commands. This is the same path coding agents should use.
rm -f app/page.tsx app/layout.tsx && pnpm dlx shadcn@latest add headcodecms/headcodecms/headcode && pnpm install
Three layers, one source of truth
A typed schema lives in your repo. The runtime exposes that schema as a typed API, an admin UI, and an MCP server. Every consumer reads the same model.
Agents draft, humans publish
Writes land on a draft branch by default. Reviewers see the diff plus the rendered preview, then publish or reject. The same flow applies whether the author is human or agent.
Cached at the edge, revalidated on publish
Published content is cached at the edge. Publishing triggers tag-scoped revalidation so changes propagate in under a second without a full deploy.
Configure your workspace
config.ts is the entrypoint. Declare collections, globals, the preview URL, and any agent capabilities. Everything else is derived from this file.
import { defineConfig } from 'headcode'
export default defineConfig({
workspace: 'acme-marketing',
globals: ['header', 'footer', 'homepage'],
})What you should run next
A short checklist to confirm everything is wired correctly before you invite the rest of the team.
pnpm dlx headcode doctor
Where to go from here
The blog has deeper write-ups on the architecture decisions and the migration guides we hand to teams moving from a legacy CMS. The admin is where you spend your time once Headcode is running.
Stuck? Open the contact page.