Agent Workflows
JSON-first and schema-driven workflows for agents, scripts, and automation
Overview
Better-T-Stack now supports a fully JSON-first workflow for agents and automation:
- Raw JSON project creation with
create-json - Raw JSON addon installation with
add-json - Runtime schema introspection with
schema - Local stdio MCP server with
mcp - Structured addon configuration with
addonOptions - Structured database setup configuration with
dbSetupOptions - Safe planning with
--dry-run
If you are automating the CLI from an LLM, CI job, or another tool, start here instead of the interactive prompt flow.
create-json
Create a project from a single JSON payload instead of many flags.
create-better-t-stack create-json --json '{
"projectName": "my-app",
"frontend": ["tanstack-router"],
"backend": "hono",
"runtime": "bun",
"database": "postgres",
"orm": "drizzle",
"api": "trpc",
"auth": "none",
"addons": ["wxt", "mcp"],
"addonOptions": {
"wxt": { "template": "react", "devPort": 5555 },
"mcp": {
"scope": "project",
"servers": ["context7"],
"agents": ["cursor"]
}
},
"install": false
}'This is the best path when:
- Your input already exists as structured data
- You want to avoid shell flag expansion issues
- You need nested addon or database setup options
add-json
Add addons to an existing project with a single JSON payload.
create-better-t-stack add-json --json '{
"projectDir": "./my-app",
"addons": ["skills", "ultracite"],
"addonOptions": {
"skills": {
"scope": "project",
"agents": ["cursor", "codex"],
"selections": [
{
"source": "vercel-labs/agent-skills",
"skills": ["web-design-guidelines"]
},
{
"source": "https://www.evlog.dev",
"skills": ["review-logging-patterns", "analyze-logs"]
}
]
},
"ultracite": {
"linter": "biome",
"editors": ["vscode", "cursor"],
"agents": ["claude", "codex"]
}
},
"dryRun": true
}'Runtime Schema Introspection
Use the CLI itself as the source of truth for current input shapes.
create-better-t-stack schema --name all
create-better-t-stack schema --name cli
create-better-t-stack schema --name createInput
create-better-t-stack schema --name addInput
create-better-t-stack schema --name addonOptions
create-better-t-stack schema --name dbSetupOptionsUseful patterns:
schema --name cli: inspect available commandsschema --name createInput: inspect the full create payloadschema --name addonOptions: inspect nested addon configurationschema --name dbSetupOptions: inspect structured database setup behavior
mcp
Run Better-T-Stack itself as a local MCP server over stdio:
npx create-better-t-stack@latest mcpInstall it into supported agent configs with add-mcp:
npx -y add-mcp@latest "npx -y create-better-t-stack@latest mcp"Exposed tools:
bts_get_stack_guidancebts_get_schemabts_plan_projectbts_create_projectbts_plan_addonsbts_add_addons
This is the best path when an MCP-capable client should scaffold or modify Better-T-Stack projects without shelling out to a prompt-driven CLI flow.
Recommended MCP workflow:
- Call
bts_get_stack_guidanceif the user's request is ambiguous. - Call
bts_get_schemafor the exact input shape you need. - Build a full explicit stack config.
- Call
bts_plan_projectbeforebts_create_project. - For MCP execution, use
install: falsewhen creating projects. - Call
bts_plan_addonsbeforebts_add_addons.
For project creation, the MCP tools now expect a full explicit config, not a partial payload. That means the agent should provide all major stack choices such as:
frontendbackendruntimedatabaseormapiauthpaymentsaddonsexamplesdbSetupwebDeployserverDeploygitpackageManagerinstall
Important field rules:
frontendmeans app surfaces, not styling choices.addonsmust be an explicit array. Use[]when none are requested.examplesmust be an explicit array. Use[]when none are requested.dbSetup,webDeploy, andserverDeployshould be explicit even when the answer isnone.git,install, andpackageManagershould always be set explicitly.installshould usually befalseforbts_create_project, because dependency installation can exceed common MCP client timeouts. Runnpm install,pnpm install, orbun installseparately after scaffolding.- If a request is still ambiguous after reading the guidance, the agent should resolve that ambiguity before calling
bts_plan_project.
If you scaffold a project with the mcp addon, Better-T-Stack itself is now one of the recommended MCP servers. The addon installs it through add-mcp with a package runner command so the generated config does not rely on a globally installed CLI:
npx -y add-mcp@latest "npx -y create-better-t-stack@latest mcp"For Bun projects, the generated config uses the equivalent bunx create-better-t-stack@latest mcp server command inside add-mcp. That means MCP-capable agents inside the generated project can talk back to Better-T-Stack without any extra global install, alongside other recommended docs, framework, and database MCP servers.
Hosted MCP
For clients that can't run a local server, such as claude.ai, ChatGPT, and other web or mobile apps, Better-T-Stack also runs a hosted MCP server:
https://www.better-t-stack.dev/mcpIt uses Streamable HTTP and needs no API key. Add it as a remote or custom connector in your client.
The hosted server validates stacks and previews generated files, but it can't write to your machine. It returns the command to run instead:
bts_get_stack_guidancebts_get_schemabts_plan_project: validates a full explicit config and lists the files it generatesbts_preview_file: returns the contents of one generated filebts_get_create_command: returns thecreate-better-t-stackcommand and a Stack Builder link
It validates with the same compatibility rules as the Stack Builder. An incompatible stack is rejected with the nearest valid values rather than silently changed. addonOptions and dbSetupOptions aren't accepted, because their rules are enforced by the CLI. Use create-json or the local server when you need them.
To create files directly or to add addons to an existing project, use the local mcp server above.
Use it inside your AI agent
Install the Better-T-Stack plugin and your assistant will scaffold and extend projects for you — just ask in plain English, like "create a fullstack app with Next, Hono, Postgres and Better Auth", and it builds a valid stack instead of hand-writing boilerplate.
Claude Code
Add the marketplace and install the plugin:
/plugin marketplace add AmanVarshney01/create-better-t-stack
/plugin install better-t-stack@better-t-stackThen ask for a project in chat, or use the shortcuts:
/better-t-stack:new <description>— scaffold a new project/better-t-stack:add <addons>— add addons to an existing one
Codex
Add the same marketplace from the Codex plugins screen and install Better-T-Stack, then ask for a project in chat.
Prefer just the tools without the plugin? Wire the MCP server into Codex with add-mcp:
npx -y add-mcp@latest "npx -y create-better-t-stack@latest mcp" # choose "codex"Or add it to ~/.codex/config.toml directly:
[mcp_servers.better-t-stack]
command = "npx"
args = ["-y", "create-better-t-stack@latest", "mcp"]opencode
Add the MCP server, then ask for a project in chat:
npx -y add-mcp@latest "npx -y create-better-t-stack@latest mcp" # choose "opencode"Other agents
Any other agent works too, because Better-T-Stack is a CLI underneath:
- MCP-capable agents (Cursor, VS Code, Gemini CLI, Zed, and more) — wire the server with
npx -y add-mcp@latest "npx -y create-better-t-stack@latest mcp"and pick your agent. - CLI-first agents like pi — just ask it to scaffold with Better-T-Stack and it runs the
create-better-t-stackCLI directly.
Structured Addon Options
Prompt-driven addons can be configured up front through addonOptions.
Supported structured addon surfaces include:
wxtfumadocsopentuimcpskillsultracite
When skills is used with the evlog or axiom addon, Better-T-Stack recommends Evlog's agent skills from https://www.evlog.dev: review-logging-patterns and analyze-logs.
Example:
{
"addons": ["wxt"],
"addonOptions": {
"wxt": {
"template": "react",
"devPort": 5555
}
}
}Structured addon options are still persisted in bts.jsonc, but the printed reproducible command now stays on normal CLI flags for consistency. That means deeply nested addon or provider-specific setup options are not fully encoded in the one-line replay command.
Structured Database Setup Options
dbSetupOptions controls how database provisioning behaves in automation.
The supported modes are:
alchemy: provision the selected provider through Alchemyauto: use the provider's automatic setup flowmanual: use an existing database and configure its credentials yourself
Example:
create-better-t-stack create-json --json '{
"projectName": "db-app",
"database": "postgres",
"orm": "drizzle",
"backend": "hono",
"runtime": "bun",
"api": "trpc",
"frontend": ["tanstack-router"],
"dbSetup": "neon",
"dbSetupOptions": {
"mode": "manual"
}
}'Current behavior:
-
When the database-consuming application deploys through Alchemy and the selected setup is Neon, PlanetScale, or Prisma Postgres, provisioning defaults to
alchemy. -
Otherwise, providers with automatic cloud provisioning default to
manualin silent/agent flows:tursoneonprisma-postgressupabasemongodb-atlas
-
Providers that only write local/manual config today are not forced to
manual:d1dockerplanetscale
This keeps agents from accidentally creating cloud resources unless automation explicitly opts into auto, while leaving local or manual-only setups unchanged.
Provider-specific options are intentionally small today:
neon.method,neon.projectName,neon.regionIdprismaPostgres.regionIdturso.databaseName,turso.groupName,turso.installCli
Dry Runs
Use --dry-run to validate inputs and target directories without writing files.
create-better-t-stack --yes --dry-run
create-better-t-stack create-json --json '{"projectName":"my-app","yes":true,"dryRun":true}'
create-better-t-stack add-json --json '{"projectDir":"./my-app","addons":["mcp"],"dryRun":true}'This is especially useful for:
- Planning actions before mutation
- CI validation
- Agent reasoning loops
Programmatic API
The exported create() and add() APIs run in silent mode by default, so they benefit from the same agent-safe behavior as the JSON commands.
See Programmatic API for TypeScript examples.
Stored in bts.jsonc
Better-T-Stack persists structured configuration in bts.jsonc, including:
reproducibleCommandaddonOptionsdbSetupOptions
See bts.jsonc for the file format.