johnandersen777.bsky.social/knotless

Switch repository

Loading…

# Agents

`knotless-mcp` is an MCP server. An agent connected to it reads and changes
repositories as your account, with no clone and no checkout. The [MCP tools
reference](../reference/mcp.md) lists what it can do.

## Connect a local client

`knotless-mcp` comes with the [install](getting-started.md#install). Log in
as the account the agent should act as, then add the server to your client:

```sh
knotless login you.bsky.social
claude mcp add knotless -- knotless-mcp   # Claude Code
```

Other clients, such as Claude Desktop (`claude_desktop_config.json`) and
Cursor (`.cursor/mcp.json`), take the same command in their MCP settings:

```json
{ "mcpServers": { "knotless": { "command": "knotless-mcp" } } }
```

omp and Claude Code can instead install `knotless-mcp` with a knotless
skill as a plugin, from
[chadtmiller.com/agent-plugins](https://knotless.dev/chadtmiller.com/agent-plugins):

```sh
/marketplace add https://knotless.dev/chadtmiller.com/agent-plugins.git   # omp
/marketplace install knotless@knotless
/plugin marketplace add https://knotless.dev/chadtmiller.com/agent-plugins.git   # Claude Code
/plugin install knotless@knotless
```

Keep the `.git`: without it, Claude Code fetches the URL as a catalog's
JSON.

The server acts as the account `knotless login` stored last. To pin another
account, set `KNOTLESS_IDENTIFIER` in the server's `env`. Pulls and issues
on public repositories come from `https://knotless.dev`; to read them from
another `knotless-serve` with an index, set `KNOTLESS_APPVIEW` to it.

A client that reads MCP resources opens a pull, an issue, its diff or a
file by a URI like its page's, as `read
mcp://knotless://alice.test/proj/pull/did:plc:…/3abc…/diff` in omp or an
`@` mention in Claude Code. [Resources](../reference/mcp.md#resources)
lists the templates.

## Connect a remote client

Some assistants, such as claude.ai with its custom connectors, connect to a
server rather than start one. They use `/mcp` on a public `knotless-serve`.
A server started with `--public-url` serves `/mcp` to any account, as its
pages let anyone log in:

```sh
knotless-serve --public-url https://knotless.example --index index.db
```

Add `https://knotless.example/mcp` as a connector, `https://knotless.dev/mcp`
for knotless.dev's. The assistant registers itself and sends you to sign in
with your handle at your own PDS. An account taken down on a server with an
index is turned away, and taking one down stops its tokens at their next
use. The server keeps each account's session apart from every other's.
When your PDS ends the login the server holds for you, your assistant asks
you to sign in again, or shows knotless as disconnected: reconnect it.

Each account may have 8 tool calls or resource reads running at once, 2 of
them with a `wait`, and start 120 a minute. A tool call past any of these
answers as a tool error saying to wait, a resource read as an error saying
so. An account that makes no token in 90 days is
forgotten, and connects again by signing in.

## Run many agents at once

A branch is one compare-and-swap. Agents writing straight to the same
branch land one per round trip, and the rest retry. To avoid that, do one
of these:

- Give each agent its own branch, and merge their pulls, or
  [queue](collaborating.md#use-the-merge-queue) them.
- Send commits through the repository's gateway, which queues them per
  branch and lands each queue as one push. Collaborators' commits always go
  through it. The owner's do with `batch` on the MCP `repo_commit` tool, or
  `knotless repo commit --batch`.

[Performance](../reference/performance.md#many-writers-on-one-branch) has
the numbers.