Skip to main content

Documentation index: llms.txt. This page is also available as markdown: append .md to this URL or send Accept: text/markdown.

Set Up Your Agent

This page is written for your AI agent to follow. You start it with one prompt, and the agent tells you what it did and anything it needs from you.

For You: Start the Agent​

Open your agent in your Coalesce Workspace folder, or in any folder if you don't have a Workspace yet, and paste:

Read https://docs.coalesce.io/docs/get-started/set-up-your-agent.md and follow the instructions to set yourself up for Coalesce.

The agent never asks you to paste a token or password into the chat. When a step needs a secret, it gives you a command to run yourself.

What it changes on your machine:

  • Installs the Coalesce platform skills for your agent.
  • Adds Transform MCP to your agent's MCP settings, if you run the command it gives you.
  • Nothing in your warehouse or your Coalesce Environments.

For the Agent: Instructions​

Follow these steps in order. Stop and report if a step fails twice.

Ground Rules​

  • Never print, log, or ask the user to paste a token, password, or private key. When a step needs one, give the user a command to run in their own terminal.
  • Don't run coa deploy, coa refresh, or any MCP tool that starts, retries, or cancels a run, or that creates, updates, or deletes a Project or Environment, unless the user asks for it in this conversation.
  • Don't create or change coa profiles or credentials without the user's yes.
  • Work only in development schemas. If a Storage Location points at a schema whose name suggests production, stop and ask.

Step 1: Find Coalesce Desktop and coa​

Check for ~/.coalesce/desktop/agent.json (on Windows, %USERPROFILE%\.coalesce\desktop\agent.json).

  • Found: Coalesce Desktop is running with a Workspace open. Use its bundled CLI, ~/.coalesce/desktop/coa (Windows: coa.cmd), for every coa command. Read ~/.coalesce/desktop/AGENTS.md for how to run it.
  • Not found: Desktop creates this file only while it has a Workspace open. Ask the user to install and launch Coalesce Desktop and open their Workspace folder, then check again. If they don't want Desktop, use a coa on the PATH.

Run coa --version and note the version for your report. If Desktop's bundled CLI prints 0.0.0-ci, report the Coalesce Desktop app version instead.

Step 2: Install the Coalesce Platform Skills​

The platform skills teach you how to author Nodes, structure pipelines, and use coa correctly.

claude plugin marketplace add Coalesce-Software-Inc/coalesce-platform-skills
claude plugin install coalesce-platform-skills@coalesce

Then ask the user to run /reload-plugins, or restart the session.

Confirm the coalesce-pipelines skill is available. If it is already installed, update it instead of reinstalling. In Claude Code, run claude plugin marketplace update coalesce, then claude plugin update coalesce-platform-skills.

Step 3: Connect Transform MCP​

Transform MCP gives you run history, job status, and deployed Environments. It acts with the user's own Coalesce permissions, so it can also start runs: the ground rules above apply.

  1. Ask the user which Coalesce URL they sign in to, for example https://app.coalescesoftware.io.

  2. Ask the user to export their token as COALESCE_ACCESS_TOKEN in their own shell, then give them this command to run in their own terminal, with their host filled in. Do not run it yourself, and never ask for the token:

    claude mcp add --transport http --scope user coalesce-transform "https://<APP_HOST>/api/v1/mcp" --header 'Authorization: Bearer ${COALESCE_ACCESS_TOKEN}'

    Then ask the user to run /mcp or restart the session, so the new server loads.

    For other agents, link the user to Connect to Transform MCP instead.

  3. When the user confirms, list the Projects in their organization to verify the connection.

Skip this step if the user says they only build locally.

Step 4: Check the Workspace​

Run this step only if the current folder contains data.yml.

  1. Run coa doctor. It checks config, authentication, and warehouse access, and names the profile it used. Confirm that profile is the one the user expects.
  2. Run coa validate to check the Workspace structure.
  3. If workspace.yml is missing, ask the user to run coa init in the Workspace folder to set their Storage Locations. workspace.yml holds personal settings, so it isn't committed and a fresh clone doesn't have it.

If the folder has no data.yml, tell the user it isn't a Coalesce Workspace yet and point them to Build Your First Pipeline With Your Agent.

Step 5: Report Back​

Reply to the user with this table, then one line on what to do next.

CheckResult
Coalesce DesktopFound, or not found
coa versionThe version from Step 1
Platform skillsInstalled, updated, or failed
Transform MCPConnected, skipped, or waiting on the user
coa doctorPassed, failed with the reason, or no Workspace
coa validatePassed, failed with the reason, or no Workspace
ProfileThe profile name coa doctor reported

If anything failed, give the exact error and the one step the user should take.