> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Build with the Claude Code plugin
> Install lua-agent-builder in Claude Code, sign in outside the transcript, and build, test, and release an agent through slash commands with a production gate
After this guide, Claude Code has the `lua-agent-builder` plugin installed: 20 slash commands that wrap `lua-cli`, five subagents, hooks that block any production change until you confirm it, and two MCP servers, a read-only view of your agent on the platform and the [docs](/build-with-ai/docs-mcp). It drives the same `lua` CLI you would run by hand, so [Build with a coding assistant](/build-with-ai/overview) applies, and every command is visible in the session. The source is at [github.com/lua-ai-global/claude-code-lua-plugin](https://github.com/lua-ai-global/claude-code-lua-plugin).
*Verified against lua-agent-builder 1.2.1 and lua-cli 3.33.0.*
**Before you begin**
* Node.js 18 or later. The plugin's hooks and its local MCP server run on Node; the CLI on its own needs only Node 16.
* `lua-cli` 3.33.0 or later (`npm install -g lua-cli`); the plugin's command shapes are verified against that version.
* Claude Code, and a Lua account at [admin.heylua.ai](https://admin.heylua.ai).
Add the marketplace and install the plugin from inside a Claude Code session, then reload.
```text theme={null}
/plugin marketplace add lua-ai-global/claude-code-lua-plugin
/plugin install lua-agent-builder@claude-code-lua-plugin
/reload-plugins
```
If `/lua-doctor` isn't recognized after `/reload-plugins`, start a fresh `claude` session.
`/lua-doctor` checks Node, your package manager, `lua-cli`, and your sign-in, then offers to merge the plugin's permission rules into the project's `.claude/settings.json`.
```text theme={null}
/lua-doctor
```
Accept the merge once per project. Claude Code ignores a plugin's own `permissions` block, so without the merge every read-only `lua` command prompts for permission.
Sign-in never passes through the conversation. `/lua-auth` keeps a credential that already works; for a new sign-in it sends you to your own terminal.
```bash theme={null}
lua auth configure
```
Choose the email option, enter the code the CLI sends you, then pick an organization, agents, and a role. A deny rule and a hook keep the model from running `lua auth configure`, so your email, code, and key never land in the transcript.
In a project directory, `/lua-status` runs `lua status --json --ci` and summarizes your sign-in and every primitive's sync state.
```text theme={null}
/lua-status
```
```json Output theme={null}
{
"auth": {
"authenticated": true,
"source": "renewable session",
…
},
"project": {
"inProject": true,
…
"agentId": "baseAgent_agent_1789214224176_2vta8rnyn",
"agentName": "helpdesk-triage",
"manifest": {
"found": true,
"primitiveCount": 7
}
},
"primitives": [
{
"kind": "skill",
…
"diffs": [
{
"name": "tickets",
"localVersion": "1.0.3",
"serverVersion": "1.0.3",
"status": "synced"
}
]
},
…
],
…
}
```
## Slash commands
Each command collects what it needs in one question, so a build step is one prompt and one answer.
| Command | What it does |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/lua-architect ` | Plans an agent: persona, tools versus integrations, event handling, workflows, build order |
| `/lua-init` | Runs `lua init --ci` for a new, existing, or duplicated agent, with the model chosen from `lua models list` |
| `/lua-new [name]` | Scaffolds a tool, skill, webhook, trigger, job, processor, MCP server, device, device trigger, voice, workflow, or workflow script, registers it, compiles, and tests it |
| `/lua-test [type]` | Runs `lua test --ci` for a skill (one tool), webhook, job, preprocessor, postprocessor, or workflow and hands failures to the debug subagent |
| `/lua-workflow ` | Offline workflow runs with scripted approvals and signals; list, status, watch; start, approve, signal, resume, cancel with one confirmation |
| `/lua-chat` | One message to the sandbox or production agent on a fresh thread (`lua chat --ci -e -m … -t`) |
| `/lua-logs` | Recent execution logs by source and primitive (`lua logs --ci --json`) |
| `/lua-status`, `/lua-sync` | Local versus deployed state for every primitive; pull or push the agent configuration |
| `/lua-env` | Set, list, or delete environment variables; values are never echoed |
| `/lua-integrations` | Discover and manage third-party connections; OAuth connects run in your terminal |
| `/lua-push` | `lua push --ci --force`: a server version, not live, except that `lua push agent` serves the pushed persona at once; never `--auto-deploy` |
| `/lua-deploy` | The gated release: compile, drift check, push, go live, smoke check, and the rollback command |
| `/lua-version` | Agent versions: list, show, diff, status, create; promote routes through `/lua-deploy` |
| `/lua-template` | Marketplace agent templates: create, draft, publish, install, apply, health |
| `/lua-qa` | Conversational QA on isolated threads, offline workflow scenarios, and a log scan, written up as a triage report |
| `/lua-docs ` | Searches this documentation through the docs MCP server |
| `/lua-doctor`, `/lua-auth`, `/lua-update` | Environment check, sign-in guidance, and `npm install -g lua-cli@latest` |
A typical loop is `/lua-architect `, `/lua-init`, `/lua-new skill orders`, `/lua-chat`, `/lua-qa`, `/lua-deploy`. What `/lua-deploy` runs depends on the target: webhooks, jobs, processors, and triggers go live with `lua deploy `, which creates and promotes an agent version scoped to that primitive; a skill on an agent that has agent versions ships as push, `lua version create`, `lua version promote`, because a bare `lua deploy skill` goes live but is reverted by the next promote (on an agent without versions it runs `lua deploy skill`); a persona target is the push itself, since a pushed persona is served at once, and its rollback is `lua deploy persona --set-version ` ([Release an agent to production](/ship/releasing)). To upgrade the plugin, run `/plugin marketplace update claude-code-lua-plugin` and install it again.
## Subagents, hooks, and MCP servers
Five subagents run the longer tasks with a restricted tool set: an architect that plans, a builder that scaffolds and tests any primitive, a debugger that reads exit codes and logs, a deploy pilot that runs the release gate by gate, and a QA agent. They never ask questions; the slash command that spawned them already collected your answer.
Ten hooks run on their own. When a Claude Code session starts they warn when `lua-cli` is older than 3.33.0, detect the project from `lua.skill.yaml`, and probe your sign-in; every prompt is prefixed with the current agent and organization ids. Before each Bash call, `confirm-deploy` blocks bare production verbs, `block-auto-deploy` blocks `--auto-deploy`, `block-auth-configure` blocks a model-run sign-in, and `warn-version-zero` warns on a `--set-version 0.x.y` push that `lua deploy --set-version latest` picks the most recently created version, not the highest number. After a command that made something live, `post-deploy-smoke` sends one message to production on an isolated thread and scans the logs for errors; after `lua compile`, `post-compile-summary` prints how many primitives compiled.
Two MCP servers are registered. `lua-platform` is local and read-only, with five tools: list your agents, inspect one, list a primitive's server versions, see what is live for every primitive and the persona, and tail execution logs; it resolves credentials the way `lua-cli` does. `lua-docs` is the public documentation server. Claude Code names their tools `mcp__plugin_lua-agent-builder___`.
## Safety model
* Production changes need your confirmation. `lua deploy`, the per-primitive `deploy` spellings, `lua persona production deploy`, `lua workflows deploy` and `activate`, `lua version promote`, `lua mcp activate`, and `lua marketplace template publish` and `apply` are blocked by the `confirm-deploy` hook unless they carry the `LUA_DEPLOY_CONFIRMED=1` prefix, which only the deploy flow emits after you confirm once. The hook recognizes every alias the CLI accepts and all three binaries (`lua`, `heylua`, `lua-ai`), refuses shell wrappers and pipes, and wins over any allow rule in your own settings.
* `--auto-deploy` is denied and blocked. A push creates a version that the release step makes live; the persona is the exception, served as soon as it is pushed.
* Credentials stay in your terminal. `lua auth configure`, `lua auth key`, and `lua auth logout` are denied for the model, and `heylua` and `lua-ai` are denied wholesale.
* Deletes, `lua env`, `lua pull`, `lua chat clear`, workflow run control, and activations sit in the `ask` tier, so the permission prompt that shows the exact command is the one confirmation.
* The platform MCP server only reads.
## If it isn't working
The permission rules were not merged. Run `/lua-doctor` and accept its last step; the rules land in the project's `.claude/settings.json`.
A `deny` or `ask` rule in your own settings matches `lua deploy` or a catch-all such as `lua *`. Claude Code evaluates those rules past the `LUA_DEPLOY_CONFIRMED=1` prefix, so they block the confirmed form too; remove the rule. The hook is what guards production.
No credential resolved, or your user session was signed out; signing out of the admin dashboard ends CLI user sessions too. Run `lua auth configure` in your terminal, then `/lua-auth`. If you set `LUA_API_URL`, it must match the environment the session was created for.
The full user guide, with every hook and the exact permission rules, is in the repository's [`docs/USER_GUIDE.md`](https://github.com/lua-ai-global/claude-code-lua-plugin/blob/main/docs/USER_GUIDE.md).
## Next steps
The rules the plugin's subagents follow, for any other assistant.
The same docs server for Claude, Cursor, and Windsurf.
Push, agent version, promote, and rollback, and why a bare `lua deploy skill` is undone by the next promote.
The non-interactive flags and exit codes behind every slash command.