---
name: worktable-setup
description: Set up Worktable for a user or connect their agent to an existing workspace. Use for installation, connection, and optional skills setup; preserve existing workspaces and unrelated client configuration.
---

# Set up Worktable

## Find existing setup

Check available Worktable tools and, on the intended host, `command -v worktable`.
If the CLI exists, inspect `worktable status` and `worktable paths`. For Desktop
or Cloud, use the user's existing workspace and **Settings → Agents**.
Do not install another workspace merely because the agent lacks a connection.

Establish where Worktable should run and where the agent runs. Respect the
user's choice of Desktop, CLI, self-hosted service, or Cloud. If that choice is
missing, explain the relevant options and resolve it before installing.

## Install when needed

Each option has a documented installation page:

- CLI on macOS or Linux: [CLI install](https://docs.worktable.dev/start/install/)
- Desktop on macOS: [Desktop](https://docs.worktable.dev/start/desktop/)
- Cloud: [Cloud setup](https://docs.worktable.dev/guides/worktable-cloud/)

For the CLI, ask the user to run the install command from its page on the
intended host and tell you when it finishes. Interactive setup selects a
workspace, run mode, and supported clients. The installer's `--dry-run` flag
previews its downloads and changes. For a non-interactive installation, suggest
[installer flags](https://docs.worktable.dev/reference/installer/) that name the
user's existing or intended workspace and clients, and keep the default local
host unless the user chose remote access.

## Connect the client

On the same computer as a CLI host, use `worktable mcp setup <client>` for
`claude-code`, `codex`, `cursor`, `vscode`, or `opencode`. For a remote agent,
use the command generated by that workspace's **Settings → Agents**.

Cloud clients complete OAuth in the browser. Stop dependent setup while user
sign-in or consent is pending. Browser credentials belong only in the browser
sign-in, not in a document or chat.

The general Worktable plugin connects to Cloud. Local/self-hosted clients need
their own endpoint. OpenClaw and Hermes use their dedicated plugins with pairing,
or Cloud registration (OpenClaw) or sign-in (Hermes). Follow [Connections](https://docs.worktable.dev/agents/connections/)
for these paths; do not overwrite unrelated client configuration.

## Add skills

Check whether the client already receives the Worktable suite through a plugin.
If it does, avoid a duplicate installation. For a local CLI installation:

```sh
worktable skills status
worktable skills install agents
```

Use target `claude` for `~/.claude/skills`, or `agents` for `~/.agents/skills`
when the client supports that shared directory. On a computer that needs only
skills, ask the user to run the skills-only installer from
[Skills](https://docs.worktable.dev/agents/skills/#installation) with the chosen
target.

Inspect existing or modified skills before replacing anything. See
[Skills](https://docs.worktable.dev/agents/skills/) for preview, update, repair,
and removal behavior.

## Verify and finish

Use `worktable doctor` and `worktable mcp test` where the CLI manages the host.
In the agent client, call `worktable_discover` action `state` and verify the
intended workspace. For conversation-only access, use an authorized test message
instead. Report any unavailable or unverified part of setup accurately.

Complete the user's first requested task if one was included. If the request
was only setup, report the connection and how to open Worktable without creating
sample content. Return the selected workspace, connection method, installed
skills, and any user action still required.