> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Your Coding Agent

> Build and run your software factory from the coding agent you already use, without leaving your IDE or terminal.

Your coding agent is where you already think, plan, and ship. Overcut meets you there. Connect Claude Code, Cursor, Codex, or any MCP-capable agent to your Overcut account, and it becomes the front door to your software factory: the same agent that edits your code can connect your Git provider, register repositories, design and publish workflows, and check on runs, all in conversation and all headless.

That changes how the platform fits into your day:

* **Stay in your agent.** No context switch to a web app to set things up. Describe what you want automated and let the agent do the configuration, with you approving each meaningful step.
* **Build the factory from your IDE.** The agent reads the repository in front of you (stack, test commands, CI, contribution rules) and proposes workflows that fit it, then tailors, dry-runs, and publishes them.
* **Monitor without leaving.** Ask the agent why a run failed, what a workflow is waiting on, or what triggered last night, and it queries Overcut for the answer.
* **Scale the same way.** Everything the agent does runs as you, inside your workspace's permissions, secrets, approvals, and audit trail. Repeat it across every repository your team owns.

One command sets this up. The rest of this page walks through it.

You need:

* Node.js 20 or newer
* An Overcut account, or permission to create one during sign-in
* A supported coding agent installed on your machine
* A local checkout of the repository you want to set up

## Install and sign in

<Steps>
  <Step title="Run the setup command" icon="terminal">
    From a terminal, run:

    ```sh theme={"dark"}
    npx overcut init
    ```

    The CLI opens your browser to sign in (or sign up) if you have no session, then detects the coding agents installed on your machine and connects them to Overcut.

    For an SSH or headless session, run `npx overcut login --no-browser` first and follow the printed URL and code.
  </Step>

  <Step title="Choose a workspace" icon="building">
    If you belong to more than one workspace, the CLI asks `Which workspace should be the current one?` and confirms `Current workspace: <name>`.
  </Step>

  <Step title="Choose a coding agent" icon="robot">
    If several agents are detected, the CLI asks `Which coding agent should get the Overcut MCP server?` Pick one or **All detected**. It then prints each configured host.
  </Step>

  <Step title="Verify" icon="user-check">
    ```sh theme={"dark"}
    npx overcut whoami
    ```

    Shows the signed-in user, current workspace, and server.
  </Step>
</Steps>

<Note>
  The web app offers the same command: select **Connect your coding agent** in the sidebar footer, or the **Build with your agent** card, to copy it.
</Note>

## Set up a repository with your agent

<Steps>
  <Step title="Open the repository" icon="folder-open">
    Start (or restart) your connected coding agent inside the local repository you want to configure.
  </Step>

  <Step title="Start guided setup" icon="comments">
    Ask the agent:

    > Set up Overcut for this repo.

    The agent loads Overcut's setup guide and inspects the repository: Git remote, default branch, language, package manager, test and lint commands, CI configuration, and contribution files.
  </Step>

  <Step title="Choose the project" icon="folder-tree">
    The agent uses the single project in a new workspace, asks you to choose when several exist, or offers to create one.
  </Step>

  <Step title="Connect the provider" icon="plug">
    If the repository's Git provider is not connected yet, the agent gives you a link to connect it in the web app. Complete the authorization in the browser. Never give credentials or secrets to the agent.
  </Step>

  <Step title="Register the repository" icon="code-branch">
    The agent finds the matching remote repository, registers it, and activates it. It asks before registering an uncertain match. Code indexing stays off; enable it separately if you want it. See [Repositories](/docs/get-started/repositories).
  </Step>

  <Step title="Choose and test a workflow" icon="flask">
    The agent proposes one to three workflows that fit the repository. Pick one. The agent installs and tailors it, runs it as a draft, and summarizes the result.
  </Step>

  <Step title="Approve publishing" icon="circle-check">
    The agent publishes the workflow and activates its triggers only after you agree, then tells you what will trigger it and where to see runs.
  </Step>
</Steps>

<Warning>
  Review every change the agent proposes. Destructive actions (delete, deactivate, discard) are refused by Overcut until the agent asks for your agreement and retries with confirmation.
</Warning>

If the workspace already has repositories and active workflows, the agent summarizes them and asks what you want to add instead of repeating setup.

## Manage the connection

Rerun the agent connection at any time, for example after installing a new coding agent:

| Goal                                                  | Command                                 |
| ----------------------------------------------------- | --------------------------------------- |
| Reconnect detected agents                             | `npx overcut mcp`                       |
| Configure a specific agent                            | `npx overcut mcp --host claude-code`    |
| Configure every detected agent without a prompt       | `npx overcut mcp --all`                 |
| Print the configuration block instead of writing it   | `npx overcut mcp --print`               |
| Configure and launch the agent (Claude Code or Codex) | `npx overcut mcp --host codex --launch` |

Supported agents include Claude Code, Cursor, Codex, Windsurf, VS Code, Zed, and Gemini CLI. The CLI writes to the agent's **user-level** configuration only, so the connection works across all your repositories and is never committed with a project.

Each connected agent gets its own API token, named for the agent and machine. Rerunning `overcut mcp` rotates it. `overcut logout` ends your terminal session, revokes the tokens created on this machine, and removes the Overcut entry from each agent's configuration. Tokens also appear under **Workspace Settings → Security → API Tokens**, where you can revoke them.

<Warning>
  The configuration printed by `--print` contains a bearer token with your permissions. Treat it like a password: never paste it into chat, commit it, or save it in a project-level file.
</Warning>

### CI and scripts

Create a general-purpose token for automation with `npx overcut token create <name>` (printed once; manage with `token list` and `token revoke <id>`). Set it as `OVERCUT_API_TOKEN` and no login is needed. Add `--json` to any command for machine-readable output.

### On-premises deployments

Pass your server's GraphQL URL with `--url`, or set `OVERCUT_API_URL`:

```sh theme={"dark"}
npx overcut init --url https://overcut.example.com/graphql
```

## Troubleshooting

* **No agent detected:** run `npx overcut mcp --host <name>`, or use `--print` and add the block to your agent's user-level MCP configuration.
* **The agent cannot see Overcut:** restart the agent after configuration and check `npx overcut whoami`.
* **CLI login or the MCP endpoint is unavailable on an on-premises server:** ask your administrator to enable it or upgrade the deployment. For CI, use `OVERCUT_API_TOKEN`.

## Related

* [Overcut Skills](/docs/quick-starts/overcut-skills): installable `SKILL.md` guidance for agents, including the direct GraphQL API skill.
* [MCP Servers](/docs/reference/mcp-servers): give agents running inside Overcut access to third-party tools. This is different from the connection described here.