Choosing the Agent

By default Bishop treats the current directory as both its own home and the agent, so its config, credentials and database land beside the agent. --agent separates the two, and takes a directory or a git URL.

A directory

bishop --agent /srv/agents/salesforce-guy

Bishop's config, credentials, and database stay in the directory you run from. The agent directory is only read, by the agent itself, so its CLAUDE.md and .claude/settings.json govern as always and nothing of Bishop's is written into it.

Bishop never updates a directory you point it at, whether or not it's a git checkout. Pull, branch, and edit it whenever you like. The exceptions are worktree mode, where the agent creates worktrees under .claude/worktrees/ in its own directory, and cleanup, which removes an old thread's worktree.

This is how you swap the agent underneath a running deployment. Point Bishop at a checkout, a worktree, or a release directory, and change which one it points at without touching any interface configuration or losing thread history.

The sandbox needs this split: Bishop's own directory can't be the agent directory with the sandbox on.

A git repository

--agent also takes a git URL, which Bishop clones on startup:

bishop --agent https://github.com/acme/salesforce-guy
bishop --agent https://github.com/acme/salesforce-guy/tree/staging
bishop --agent [email protected]:acme/salesforce-guy.git

GitLab's /-/tree/<branch> form works too, as does any URL git can clone. A bare owner/repo is treated as a local directory, since nothing distinguishes it from a relative path. Bishop uses whatever git credentials the machine already has, so a private repo works if git clone works there.

Point at a repository and Bishop owns the checkout, under .bishop/agents/<owner>-<repo>:

.bishop/agents/acme-salesforce-guy/
├── mirror.git/                bare clone, the only thing a fetch touches
└── snapshots/
    ├── current -> b4c5d6e     what the next new thread starts on
    ├── a1b2c3d/               an older commit, still in use by a thread
    └── b4c5d6e/

A snapshot is one commit, checked out and never rewritten. A thread picks its snapshot on its first message and stays there for good, so a conversation always sees one consistent set of files. Threads on the same commit share a snapshot.

current is for you, not for Bishop. Nothing reads it while a thread runs. It records what the next new thread would start on.

A fresh snapshot has no git identity of its own, so set one for the user Bishop runs as, or every commit the agent makes fails with "Author identity unknown". git config --global works on a host, and the container sets it through the environment.

Picking up a push without restarting

--auto-update checks the remote at the start of every new thread:

bishop --agent https://github.com/acme/salesforce-guy --auto-update

A new thread gets whatever is on the branch now. Threads already going keep their own snapshot, so nobody's conversation changes underneath them. Without the flag, Bishop checks once at startup and every thread that process handles starts on that commit.

Threads waking together share one fetch. If the fetch fails, new threads start on the snapshot Bishop already has and the reason is logged, so an expired credential doesn't take the agent offline.

It doesn't install anything. A commit that changes package.json gets a snapshot with no node_modules, and what to do about that is the agent's business. It also doesn't touch Bishop's own config or credentials, which are read from the directory you ran it from and still need a restart to change.

Commands that don't take an agent

bishop slack setup and bishop slack manifest don't take --agent. They only deal with Bishop's own directory and the Slack app.