Build with the Claude Code plugin

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. It drives the same lua CLI you would run by hand, so Build with a coding assistant applies, and every command is visible in the session. The source is at 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.

Install the plugin

Add the marketplace and install the plugin from inside a Claude Code session, then reload.

/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.

Run the doctor

/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.

/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.

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.

Verify

In a project directory, /lua-status runs lua status --json --ci and summarizes your sign-in and every primitive’s sync state.

/lua-status

Output

{
  "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 <goal>`	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 <type> [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 <verb>`	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 <env> -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 <type> --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 <topic>`	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 <goal>, /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 <type>, 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 <n> (Release an agent to production). 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_<server>__<tool>.

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

Every lua command asks for permission

The permission rules were not merged. Run /lua-doctor and accept its last step; the rules land in the project’s .claude/settings.json.

/lua-deploy reports that the go-live command was denied

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.

MCP_AUTH_STALE, or Claude Code says you are not signed in

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.

Next steps

Build with a coding assistant

The rules the plugin’s subagents follow, for any other assistant.

Add the docs MCP server

The same docs server for Claude, Cursor, and Windsurf.

Release an agent to production

Push, agent version, promote, and rollback, and why a bare lua deploy skill is undone by the next promote.

Automate releases in CI

The non-interactive flags and exit codes behind every slash command.

Get started

Concepts

Build

Channels

Integrations

Devices

Ship and operate

Marketplace

Build with AI

Examples

Build with the Claude Code plugin

Slash commands

Subagents, hooks, and MCP servers

Safety model

If it isn’t working

Next steps

Build with a coding assistant

Add the docs MCP server

Release an agent to production

Automate releases in CI

​Slash commands

​Subagents, hooks, and MCP servers

​Safety model

​If it isn’t working

​Next steps

Build with a coding assistant

Add the docs MCP server

Release an agent to production

Automate releases in CI

Slash commands

Subagents, hooks, and MCP servers

Safety model

If it isn’t working

Next steps