> ## 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 Lua agent kit

> Install the Lua agent kit in Claude Code, Codex, Cursor, or any coding agent, sign in outside the transcript, and build, test, and release an agent with a production gate

After this guide, your coding agent has the Lua agent kit installed. Every agent gets the Lua skills, which teach it to build, test, and release agents with `lua-cli`. Claude Code, Codex, and Cursor also get the `lua-agent-builder` plugin: 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](https://docs.heylua.ai/build-with-ai/docs-mcp.md). In Claude Code the plugin adds 20 slash commands and five subagents. It drives the same `lua` CLI you would run by hand, so [Build with a coding assistant](https://docs.heylua.ai/build-with-ai/overview.md) applies, and every command is visible in the session. The source is at [github.com/lua-ai-global/agent-kit](https://github.com/lua-ai-global/agent-kit).

*Verified against agent kit 2.0.0-beta.0 and lua-cli 3.58.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`).
* A coding agent such as Claude Code or Codex, and a Lua account at [admin.heylua.ai](https://admin.heylua.ai).

**1. Install the kit**

> [tab] Claude Code
>
> Add the marketplace and install the plugin, then start a new `claude` session.
>
> ```bash theme={null}
> claude plugin marketplace add lua-ai-global/agent-kit
> claude plugin install lua-agent-builder@lua-ai
> ```
>
> Inside a running session the same commands are `/plugin marketplace add lua-ai-global/agent-kit` and `/plugin install lua-agent-builder@lua-ai`, followed by `/reload-plugins`.

> [tab] Codex
>
> Add the marketplace and install the plugin.
>
> ```bash theme={null}
> codex plugin marketplace add lua-ai-global/agent-kit
> codex plugin add lua-agent-builder@lua-ai
> ```
>
> Then open Codex, run `/hooks`, and trust the Lua hooks. Until you do, the production gate is not active in Codex.

> [tab] Cursor
>
> Add the marketplace with Cursor's `agent` CLI. Use the full URL, and be signed in to Cursor.
>
> ```bash theme={null}
> agent plugin marketplace add https://github.com/lua-ai-global/agent-kit
> ```
>
> Then open `/plugins` in `agent`, or **Customize** in the Cursor app, and install `lua-agent-builder`.

> [tab] Any other agent
>
> Install the skills for every coding agent on your machine (GitHub Copilot, Gemini CLI, OpenCode, Amp, and more).
>
> ```bash theme={null}
> npx skills add lua-ai-global/agent-kit
> ```
>
> These agents have no hook that can stop a command, so the skills never run a production command themselves. They print it for you to run.

If you used the earlier Claude Code plugin from `lua-ai-global/claude-code-lua-plugin`, remove it first with `/plugin uninstall lua-agent-builder@claude-code-lua-plugin`.

The steps below use the Claude Code slash commands. In other agents, ask for the same thing in plain words, for example "check my Lua setup".

**2. 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`.

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

**3. Sign in**

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.

**4. Verify**

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 <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 (`lua push agent` stages the persona); 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](https://docs.heylua.ai/ship/releasing.md)). To upgrade, run `claude plugin marketplace update lua-ai` (or `codex plugin marketplace upgrade lua-ai`) and install the plugin again; for the skills, run `npx skills update`.

## 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. From plugin 1.14.0 a third, `lua-ui`, is the public catalog of the `@lua-ai-global/ui` components at `https://ui.lua.dev/mcp`; the plugin checks a component's props there before it writes a web app's pages ([Look and theme](https://docs.heylua.ai/build/apps/routes-and-pages.md#look-and-theme)). 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

> [accordion] 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`.

> [accordion] /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.

> [accordion] 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 [agent kit repository](https://github.com/lua-ai-global/agent-kit).

## Next steps

> [card] [Build with a coding assistant](https://docs.heylua.ai/build-with-ai/overview.md)
>
> The rules the plugin's subagents follow, for any other assistant.

> [card] [Add the docs MCP server](https://docs.heylua.ai/build-with-ai/docs-mcp.md)
>
> The same docs server for Claude, Cursor, and Windsurf.

> [card] [Release an agent to production](https://docs.heylua.ai/ship/releasing.md)
>
> Push, agent version, promote, and rollback, and why a bare `lua deploy skill` is undone by the next promote.

> [card] [Automate releases in CI](https://docs.heylua.ai/ship/ci-and-automation.md)
>
> The non-interactive flags and exit codes behind every slash command.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.