--- title: "Work with a coding agent" url: "https://docs.alisx.com/tutorials/work-with-a-coding-agent/" --- # Work with a coding agent In this tutorial you set up a coding agent to drive AlisX for you through the `alis` CLI: install the CLI, hand the agent its manual, let it find and load the skill for the job, and run one define, build and deploy loop with the agent watching the operation. At the end you have an agent that speaks the CLI's JSON contract and knows where it must stop and ask you. It is for builders who already use an agent such as Claude Code, Codex, Gemini CLI or OpenCode. The steps use Claude Code as the example. The commands the agent runs are the same for any agent with a shell. ## 1. Install the CLI Follow [Install the CLI](https://docs.alisx.com/tutorials/install-the-cli.md) through the sign-in step, or let the agent do it. The agent's loop for a fresh machine is documented in `alis docs setup`: install, then call `alis setup status --json` and act on `.next` until `.ready` is `true`. ## 2. Install the agent's Alis Build plugin ```bash title="Terminal" alis setup status --json ``` The `steps` list includes your agent's Alis Build plugin, for example `"name": "Claude Code (Alis Build plugin)"`, with `installed: false` and the `command` that installs it. Install every missing step in one go: ```bash title="Terminal" alis setup install --all --json ``` Steps that need you (for example a package manager's password prompt) come back under `needs_user`; run those yourself. If your agent is not recorded on your build profile yet, tell the CLI: ```bash title="Terminal" alis setup profile --harness claude-code --json alis setup complete --harness claude-code --json ``` Restart the agent so it sees the new PATH and plugin. ## 3. Hand the agent its manual Open your agent in a service folder under `~/alis.build//build//` and give it this first prompt: ```text Run `alis docs` and read it in full. From now on, operate the Alis platform only through `alis` commands with --json, one standalone command at a time. ``` The manual tells the agent the rules it must follow: one JSON object on stdout, progress on stderr, `--async` for long operations, exit code 3 means stop and ask a human. Everything below is what the agent does with that knowledge. The agent can read this documentation too: `https://docs.alisx.com/llms.txt` indexes every page as markdown (see [Documentation for agents](https://docs.alisx.com/reference/docs-for-agents.md)). ## 4. Let the agent see where it is ```bash title="Agent runs" alis context view --json ``` ```json { "organisation": "acme", "product": "shop", "packageId": "acme.shop.orders.v1", "serviceFolder": "/home/me/alis.build/acme/build/shop/orders/v1", "defineFolder": "/home/me/alis.build/acme/define/acme/shop/orders/v1", "environments": [ {"id": "", "displayName": "Development", "production": false, "status": "ACTIVE", "projectId": ""}, {"id": "", "displayName": "Production", "production": true, "status": "ACTIVE", "projectId": ""} ] } ``` Because the working directory is inside the service folder, the agent can omit the package ID on every command. When its tool cannot change directory, it uses `alis --cwd /absolute/path ` instead. Deployment environment ids come from here, never from guessing. ## 5. Let the agent find the skill for the job Ask the agent to add a field to the service's API. Before it edits anything, it searches the skills catalog: ```bash title="Agent runs" alis skills search "add a field to a proto and publish the contract" --json --limit 3 ``` ```json { "queriedSkills": [ {"id": "dbd-add-protos", "displayName": "Initialise Definitions", "description": "Use this skill when …", "version": "1", "source": "USER", "vetVerdict": "PASSED"} ] } ``` It loads the best match and follows it: ```bash title="Agent runs" alis skills load dbd-add-protos --json ``` ```json {"markdown": "# Initialise Definitions\n…"} ``` Skills are loaded live, one at a time, so the agent's context holds only the instructions it needs. If a skill references a file, `alis skills resource ` fetches it. ## 6. Define The agent edits the `.proto` in the define folder, then checks it compiles before committing: ```bash title="Agent runs" alis define --dry-run --json ``` ```json {"valid": true, "diagnostics": [], "git": {"uncommittedFiles": ["orders.proto"], "unpushedCommits": 0}} ``` It commits and pushes, then publishes the contract and installs the generated packages: ```bash title="Agent runs" alis define --json --install ``` ```json {"schemaVersion": 1, "name": "operations/", "done": true, "status": "succeeded", "version": "1.5.0"} ``` ## 7. Build and deploy, asynchronously The agent implements the change, commits and pushes, then starts a build with a deploy attached and returns at once: ```bash title="Agent runs" alis build --json --branch main --deploy -e --async ``` ```json {"schemaVersion": 1, "name": "operations/", "done": false, "status": "running", "next": "alis operations wait operations/ --json"} ``` It runs the `next` command to wait, which blocks efficiently and streams progress on stderr: ```bash title="Agent runs" alis operations wait operations/ --json ``` ```text {"elapsed":"0:04","operation":"operations/","progress":"Building image neurons/orders-v1"} {"elapsed":"2:31","operation":"operations/","progress":"Deploying to Development"} ``` ```json { "schemaVersion": 1, "name": "operations/", "done": true, "status": "succeeded", "version": "1.5.0", "images": [{"path": "."}], "deployments": [{"name": "…/deployments/orders-v1", "state": "RUNNING", "logsUri": "https://…"}] } ``` The agent reads stdout whole: the final JSON is the result, even when the operation fails (then it carries `error`, and `alis logs build|deploy operations/ --json` has the log). It never sleeps in a loop or pipes the output through `tail`. ## 8. Hit the production gate Ask the agent to promote the version to production. It previews first, which is not gated: ```bash title="Agent runs" alis deploy --version 1.5.0 --json -e --plan-only ``` Then it tries the deploy: ```bash title="Agent runs" alis deploy --version 1.5.0 --json -e ``` ```json { "error": { "code": "PRODUCTION_CONFIRMATION_REQUIRED", "message": "…", "retry": "alis deploy --version 1.5.0 --json -e --confirm-production", "agent": "…" } } ``` Exit code 3. This is the moment the agent must stop. It shows you the version, the deployment environment and the retry command, and asks. Only after you say yes does it run the exact `retry`. An agent never adds `--confirm-production` on its own; `--approve` and `--yes` never lift this gate; and approval covers that one deployment only. ## 9. Save the session When the work is done, the agent can save its transcript to your Alis history so that `alis ask` can see it later: ```bash title="Agent runs" alis context push-session --harness claude-code --json ``` The command asks you to confirm before anything leaves the machine. Credentials are masked first. ## What you have - An agent with the Alis Build plugin installed and the CLI manual read. - An agent that resolves context from its working directory, loads skills live, and parses one JSON object per command. - A define, build and deploy loop run with `--async` and `alis operations wait`. - A production gate the agent respects: exit code 3, ask the human, run the exact retry. ## Agents without a shell An agent that cannot run commands, for example one hosted in a browser, reaches the platform through the Alis Build MCP server at mcp.alis.build. It offers SpecIt, server-side RunDefine, RunBuild and RunDeploy, and the skills tools SearchSkills and LoadSkill. The manual's rule: with a shell, use `alis`; without one, use the MCP server, whose skills tools also handle `backend_outdated` from `alis skills`. Next: [Script the CLI with JSON](https://docs.alisx.com/how-to/cli/script-the-cli-with-json.md) for the full contract, and [Agents, skills and the CLI](https://docs.alisx.com/explanation/agents-skills-cli.md) for why it is designed this way.