Use Skeg from a coding agent¶

Skeg exposes its tools over MCP. A coding agent such as Claude Code or Codex can then check its own changes on a device before it calls the work done. The agent uses a project token: the token names the project, and holding it is the permission.

Set up¶

1. In Skeg, open the project, then Settings → Agent tokens. Create a named token. The secret shows once.
2. Find the runner on the agent's machine. Open Skeg Runner once: it creates a launcher at <home>/.config/skeg/skeg-runner (Windows: <home>\.config\skeg\skeg-runner.bat).
3. Save a device target in Setup, ideally as the project default. The agent drives that target.
4. Add the skeg MCP server. The setup panel next to the token generates the entry for Codex (TOML) and for MCP JSON clients.
5. Restart the client's MCP server. Ask the agent: "Call Skeg's check_setup, then list_plans, and tell me which project you are connected to."

No pairing is needed. start_inspector starts a local runner on the agent's machine with the project token.

Share the config with your team, not the secret¶

Claude Code expands environment variables in a project's .mcp.json (docs). Commit the entry and let each developer export their own SKEG_TOKEN:

{
  "mcpServers": {
    "skeg": {
      "type": "stdio",
      "command": "${SKEG_RUNNER_BIN}",
      "args": ["--mode", "mcp", "--server", "https://api.getskeg.dev"],
      "env": { "SKEG_TOKEN": "${SKEG_TOKEN:-}" }
    }
  }
}

Each developer sets SKEG_RUNNER_BIN to their launcher path and SKEG_TOKEN to their token.

Tell the agent when to verify¶

Put the loop into your repository's agent instructions (AGENTS.md or CLAUDE.md), so every change gets checked:

## Verify on device with Skeg

After a change with visible app behavior, verify it with the `skeg` MCP server:

1. Build and install the app on the default Skeg target. Call `check_setup` first.
2. Behavior should be unchanged: `list_plans`, then `execute_plan` (include_screenshots: false)
   on each plan that visits the changed screens. A failed step is a regression unless the change
   was intended.
3. Behavior changed on purpose: `start_inspector`, then `start_goal` with the goal and one
   observable fact per criterion. Wait with `goal_result`. On `passed`, `promote_goal_run`
   (reset_app: true for Android and iOS targets only: macOS cannot reset, so a reset step there
   fails every replay) and tell me the plan name to review. Then `stop_inspector`.
4. Report the verdict, failed steps or criteria, and the run id. Treat `inconclusive` and
   `infrastructure-error` as "not verified", never as a pass.

Write good criteria¶

• criteria: facts that must hold where the run ends. "The cart badge shows 1."
• intermediate_criteria: facts seen only during the run. "A 'Saved' toast appears." Putting these in criteria fails a correct run.
• One observable fact per criterion. Describe the goal in user terms, not in code terms.
• Reference test data as ${NAME} from an environment (list_environments). The agent never sees the values.

Tools¶

Goal runs and ports need a model key in the MCP server's own environment, for example ANTHROPIC_API_KEY (SKEG_LLM_PROVIDER and SKEG_LLM_MODEL change the provider and model). A model set in Skeg's chat does not reach an external agent.

Fixes¶