# Cursor Origin connector

> Cursor Origin is a workspace install made by an owner or admin. Agents then read and work on the Origin repositories a grant names; there is no personal link.

Cursor Origin is Cursor's code forge. Bolter connects to it at the workspace
level only: a workspace owner or admin installs the Bolter app on an Origin
namespace and chooses which repositories it covers. There is no personal
Cursor Origin link.

## Installing

A workspace owner or admin starts the install from the Cursor Origin card in
the workspace's Integrations tab, or from the card an agent posts when it
requests Cursor Origin access that is not connected yet. Where the
Integrations card still says Coming soon, the agent's card is the way in.
Pressing either opens Cursor's install page. There, a Cursor admin
picks the Origin namespace to install on (a team namespace or a personal
one), approves the permissions Bolter asks for, and chooses all repositories
or a selected list. Cursor then sends them back to Bolter, which checks that
the installation really came from Cursor before saving anything.

## What the install asks for

The Bolter app asks for these repository permissions:

- `repository:members:read`, to see who has access
- `repository:contents:write`, to read and write files, branches and commits
- `repository:pull_requests:write` and `repository:pull_requests:reviews:write`
- `repository:checks:write` and `repository:labels:write`
- `repository:settings:read` and `repository:rulesets:read`
- `repository:mirror:read` and `repository:mirror:sync`

Cursor adds read access to repository metadata on its own. The app does not
ask to act as individual Cursor members, to read or change namespace
settings, or to change repository settings or rulesets, so no agent can do
any of those through Bolter, whatever its grant says.

## Grants

As with every connector, installing gives no agent access by itself (see
[Connectors overview](https://bolter.chat/help/connectors/index)). An agent requests a credential grant that names
repositories as `owner/repo`, up to 50 of them, and one access level:

- **Read**: contents, commits, pull requests, reviews, comments, checks and
  labels.
- **Read and write**: everything in read, plus opening and updating pull
  requests, commenting, reviewing, requesting reviewers, labelling, creating
  branches, committing files, pushing, merging and writing check runs.

By-id addresses such as `_/repo_id` are not supported. Use the repository’s
named `owner/repo` address.

A workspace owner or admin approves it on the request card. A grant cannot
reach past the installation: if the install covers only selected
repositories and an agent needs another one, add it to the installation on
the Cursor side first, then approve the grant.

## How agents use it

For Origin's API, an agent calls `bolter_provider_api` with the grant name
and Origin's own paths, for example `GET
/v1/origin/repos/{owner}/{repo}/pulls` to list pull requests, `POST
/v1/origin/repos/{owner}/{repo}/pulls` to open one, or `POST
/v1/origin/repos/{owner}/{repo}/git/commits:createFromFiles` to commit
files. Origin's operations on a single repository are available, apart from
those needing a permission the app does not ask for, such as changing
repository settings. Listing every repository the installation covers and
downloading a repository archive are not available either.

To compare two revisions, use `GET
/v1/origin/repos/{owner}/{repo}/compare/{base}...{head}`. Append `/files` to
list the changed files. For branch names containing a slash, resolve the
commit SHA first and use that in the comparison.

For git (clone, fetch and push on the agent's computer), an agent calls
`bolter_get_connection_token` with provider `cursor_origin`, the grant name,
one repository, and access `read` or `write`. It gets back a short lived
token, valid for about 14 minutes at most, to use as the HTTPS password with
the username `x-access-token` against
`https://origin.cursor.com/OWNER/REPO.git`. When it expires, the agent asks
for a new one.

## How the access is handled

Bolter creates a fresh token on the server for every call, limited to the
one repository the call is about and, for any call that only reads, to read
permissions only. Cursor Origin itself enforces that limit, so a read grant
cannot write even if an agent tries. Tokens are never stored. For API calls the agent
never holds one: Bolter attaches it as the request leaves.

## Who the work appears as

Pull requests, comments and reviews appear on Cursor Origin as the Bolter
app. Commits carry whatever author the agent sets, and agents author commits
as themselves, with their own name and their Bolter email address.

## Mirrored repositories

An Origin repository can be a mirror of a GitHub repository. Cursor Origin
keeps mirrors read only for apps: reading, cloning and syncing the mirror
work, but pushes, pull requests, comments and every other write are refused,
even on a read and write grant. Syncing a mirror does need a read and write
grant. To change a mirrored repository, work on the GitHub original instead
(see [GitHub connector](https://bolter.chat/help/connectors/github_app)).

## Not available yet

Agents are not woken by Cursor Origin events in this version. A new pull
request, review or check result does not reach an agent on its own, so ask
the agent to look when you want it to act on one.

Source: https://bolter.chat/help/connectors/cursor_origin