Next.js AI CLI Agent Workbench

Use this stack when you want a Next.js project prepared for AI-assisted development workflows, local MCP tooling, and generated agent documentation.

npm create better-fullstack@latest my-agent-workbench -- \
  --ecosystem typescript \
  --frontend next \
  --backend self \
  --database sqlite \
  --orm drizzle \
  --auth better-auth \
  --api trpc \
  --ai ai-cli \
  --addons mcp skills \
  --ai-docs claude-md agents-md cursorrules \
  --css-framework tailwind \
  --ui-library shadcn-ui \
  --package-manager bun

What this creates

• A Next.js app with a local fullstack setup.
• SQLite and Drizzle.
• Better Auth.
• AI CLI configuration.
• MCP and Skills add-ons.
• Agent-facing documentation files such as CLAUDE.md, AGENTS.md, or .cursorrules depending on selected flags.

Generated shape

This preset is both an application scaffold and an agent-workflow scaffold. The web app is a normal Next.js fullstack project, while the add-ons create repository context for coding agents and local AI tooling.

Representative shape:

my-agent-workbench/
  bts.jsonc
  AGENTS.md
  CLAUDE.md
  .cursorrules
  app/
  components/
  lib/
    auth/
    db/

The exact documentation files depend on --ai-docs claude-md agents-md cursorrules. The command shown asks for all three so different agent tools can find project guidance in their preferred format.

How the AI pieces fit

--ai ai-cli selects AI CLI support. --addons mcp skills adds local agent capabilities around MCP and skills. --ai-docs controls which repository instruction files are generated.

Use those pieces for different jobs:

Example agent instruction

Agent-facing docs should be concrete. Prefer project rules that can be followed and verified:

## Verification

After editing authentication, run the smallest auth-related test or typecheck.
Do not run broad workspace commands unless the change crosses package boundaries.

## Project boundaries

Database access belongs in server-only modules.
Client components should call typed API helpers instead of importing Drizzle code.

Keep these docs current when architecture changes. Stale agent instructions are worse than no instructions because they confidently route future work to the wrong files.

Example application model

The app side remains a normal Better Fullstack TypeScript stack. A small SQLite table might look like this:

import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";

export const agentRun = sqliteTable("agent_run", {
  id: text("id").primaryKey(),
  goal: text("goal").notNull(),
  status: text("status").notNull(),
  createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
});

Use application tables for product data, not for storing secrets. MCP credentials, provider tokens, and AI service keys should live in environment variables or provider-specific secure storage.

When to choose it

Choose this when the repository itself should be easy for coding agents to understand and modify. It is useful for teams standardizing agent workflows, MCP tools, and generated project context.

Compatibility notes

• This preset uses a TypeScript Next.js app with --backend self, so Next.js owns the server boundary.
• --addons mcp skills are development-workflow additions. They do not replace app authentication, database, or API choices.
• --ai-docs claude-md agents-md cursorrules intentionally generates multiple instruction formats for different tools.
• SQLite is convenient for local workbench-style projects. Use PostgreSQL if the workbench becomes a multi-user production product with shared state.

Deployment notes

Deploy the Next.js app like a normal fullstack application: configure Better Auth secrets, app URL, and database settings. Treat AI provider keys, MCP credentials, and any tool tokens as server-side secrets.

Agent docs usually belong in source control. Local credentials, generated logs, and machine-specific MCP config usually do not. Review generated ignore files before committing.

Troubleshooting

• If an AI tool ignores the repository guidance, confirm it reads the generated filename you selected with --ai-docs.
• If MCP tools are unavailable, verify the local MCP setup and whether the consuming agent has been pointed at it.
• If scaffolded addon setup prompts during scripted runs, use explicit flags like this guide does so defaults are deterministic.
• If the app works locally but auth fails after deploy, check the same Better Auth URL and cookie settings you would inspect in any Next.js stack.

Tradeoffs

This stack is more opinionated than a minimal Next.js starter. If you only need a product app without agent tooling, use Next.js with Drizzle and Better Auth.

The extra files are valuable when humans and agents repeatedly work in the repo. They are overhead for a throwaway prototype. If the team will not maintain the instructions, start with the simpler Next.js guide and add AI docs later.

Next steps

• Open the Stack Builder.
• Read the AI agents docs.
• Learn how the Better Fullstack MCP server works.