@agentdeploymentco/bishop 0.1.0

package/README.md

@@ -0,0 +1,800 @@
+# Bishop
+
+Bishop puts an agent where your team already works.
+
+Point it at a directory that a coding agent already works in, and the agent becomes something your team can talk to: a Slack thread, an email thread, or both at once. Bishop handles the connection and the mapping between threads and agent sessions.
+
+```
+$ cd path/to/agent
+$ bishop slack setup
+$ bishop
+```
+
+Bishop is an agent gateway: it sits between the places people work and the agents they work with. Today that is Slack and Gmail, one agent, in a single process.
+
+## Requirements
+
+- Node 24 or newer
+- A directory the agent works in, meaning `claude` or `codex` runs there and does something useful
+- At least one interface. For Slack: the [`slack` CLI](https://docs.slack.dev/tools/slack-cli/), logged in with `slack auth login`, unless you set the app up by hand (see [Without the Slack CLI](#without-the-slack-cli)), plus permission to install an app in your workspace. For email: a Google Workspace account, a Google Cloud project, and a Workspace user for the agent.
+
+## Install
+
+```
+$ npm install -g @agentdeploymentco/bishop
+```
+
+That puts `bishop` on your PATH. Bishop always treats the current directory as the agent, so run it from the agent's directory. [In a container](#in-a-container) is the other way to run it.
+
+### From source
+
+The published package is minified and carries no source maps. If you work on Bishop, and so can read its repository, build it instead:
+
+```
+$ git clone https://github.com/Agent-Deployment-Co/bishop.git
+$ cd bishop
+$ npm install
+$ npm run build
+$ npm link          # optional, puts `bishop` on your PATH
+```
+
+Without `npm link`, run it as `node /path/to/bishop/dist/cli.js`.
+
+## Set up an agent
+
+From the agent's directory:
+
+```
+$ bishop slack setup
+```
+
+It asks for an app name, a display name, and a description, defaulting the name to the directory name. Pass them as flags to skip the questions:
+
+```
+$ bishop slack setup --name salesforce-guy \
+    --display-name "Salesforce Guy" \
+    --description "Answers Salesforce admin questions"
+```
+
+`--no-prompt` takes the defaults instead of asking. Bishop assumes it when there's no terminal, so this works in a script.
+
+Setup creates the Slack app, installs it, and writes two files:
+
+```
+.bishop/config.json    configuration, commit this
+.env                   credentials, gitignored for you
+```
+
+It also adds `bishop.db` to `.gitignore`, which `bishop` creates on its first run to hold the thread-to-session mapping.
+
+Then start it:
+
+```
+$ bishop
+```
+
+Invite the bot to a channel, or DM it directly.
+
+### Without the Slack CLI
+
+If you can't install the CLI, or somebody else owns app creation in your workspace, Bishop can adopt an app you set up by hand.
+
+First get the manifest, so the scopes and events are right by construction:
+
+```
+$ bishop slack manifest > manifest.json
+```
+
+Create the app in Slack from that file (**Create New App**, then **From a manifest**), install it to the workspace, then collect two tokens from App Settings: the bot token (`xoxb-`) under OAuth & Permissions, and an app-level token (`xapp-`) with `connections:write` under Basic Information.
+
+```
+$ bishop slack setup --manual
+```
+
+It asks for both tokens, checks them against Slack, and builds the config from what Slack reports. You don't have to type the app ID or name: `auth.test` returns them.
+
+One thing it can't check is which events the app subscribes to. If the agent never answers anything, that's the first place to look.
+
+### Email
+
+Gmail is the second interface. It needs a Google Cloud project, and the agent needs its own Workspace user, say `salesforce-guy@example.com`. That address is what people write to, and its mailbox is what Bishop reads. Don't point this at a person's account.
+
+Then create an OAuth client, once:
+
+1. In the [Google Cloud console](https://console.cloud.google.com/), pick or create a project and **enable the Gmail API**.
+2. Configure the OAuth consent screen with user type **Internal**. This is what lets you skip Google's app verification.
+3. Create an OAuth client ID of type **Desktop app**.
+4. Put both values in `.env`:
+
+```
+BISHOP_GMAIL_CLIENT_ID=...
+BISHOP_GMAIL_CLIENT_SECRET=...
+```
+
+Then authorize the mailbox:
+
+```
+$ bishop gmail setup
+```
+
+A browser opens. Sign in **as the agent's Workspace user**, not as yourself, and approve. Bishop catches the redirect, writes `BISHOP_GMAIL_REFRESH_TOKEN` to `.env`, and tells you which mailbox it reached.
+
+Re-running it later checks the credentials instead of authorizing again, so it doubles as a health check in a deploy script. It exits non-zero when the mailbox can't be reached.
+
+**Set `gmail.allow` before pointing anyone at it.** Without it, every address that can reach the mailbox can use the agent, and a Workspace mailbox can be reached from anywhere.
+
+```json
+{ "gmail": { "allow": ["you@example.com", "@example.com"] } }
+```
+
+#### Moving it to a server
+
+The refresh token isn't tied to the machine you authorized on. Copy three lines to the server's `.env` and start Bishop there:
+
+```
+BISHOP_GMAIL_CLIENT_ID=...
+BISHOP_GMAIL_CLIENT_SECRET=...
+BISHOP_GMAIL_REFRESH_TOKEN=...
+```
+
+To set it up on the server directly instead, run `bishop gmail setup` there. It notices it's over SSH, prints a URL instead of opening one, and asks you to paste back where the browser ended up. The browser lands on a `http://127.0.0.1` address that fails to load, which is expected: the code is in the address bar, and pasting the whole address is enough. `--no-browser` forces that mode anywhere.
+
+#### When it stops working
+
+Google revokes Gmail refresh tokens when the mailbox's password is reset. The agent goes quiet, the log says the token is no longer valid, and `bishop gmail setup` fixes it by authorizing again.
+
+If that isn't acceptable, use domain-wide delegation instead. Nothing about it expires and no person is ever needed again, but it costs more to set up: a service account key, which most organizations now block by default, plus a Workspace super admin to grant the delegation. Set `BISHOP_GMAIL_USER` and `BISHOP_GMAIL_SERVICE_ACCOUNT` instead of the three OAuth variables, and run `bishop gmail setup` to check it. It prints the exact client ID and scope to paste into the admin console when the grant is missing.
+
+Bishop runs whichever interfaces have credentials. Set up both and one process answers Slack and email at once, with separate threads and separate sessions.
+
+### GitHub
+
+An agent that opens pull requests, reads issues, or pushes branches needs a GitHub credential of its own. Without one it borrows whatever login happens to be on the machine, and in a container there is nothing to borrow.
+
+```
+$ bishop github setup
+```
+
+It takes the token from the [`gh` CLI](https://github.com/cli/cli), offering to run `gh auth login` if you aren't logged in, verifies it against GitHub, and writes `GH_TOKEN` to `.env`. From there it reaches the agent's environment, and `gh` picks it up on its own.
+
+The report names the account the token acts as and the scopes it carries, and prints the `gh auth refresh` for any scope the agent needs that's missing. Re-running it checks the token instead of issuing another, so it doubles as a health check in a deploy script. It exits non-zero when GitHub won't accept the token.
+
+**A token from `gh auth login` acts as you, in every repository you can reach.** To limit the agent instead, create a [fine-grained personal access token](https://github.com/settings/personal-access-tokens) scoped to the repositories it should touch, put it in `.env` as `GH_TOKEN`, and run setup to check it. GitHub reports no scopes for a fine-grained token, so setup says what it can't tell you rather than guessing.
+
+git never reads `GH_TOKEN`, so `git push` still asks for a password until the credential helper is installed. Setup says so when it's missing:
+
+```
+$ gh auth setup-git
+```
+
+**`gh auth login` replaces whichever account the `gh` CLI is signed in as.** On a machine where you are signed in as yourself, `--temporary` runs the login in a `gh` configuration directory it creates and deletes, so your own login survives:
+
+```
+$ bishop github setup --temporary
+```
+
+The token still lands in `.env`. Because the temporary directory has no account in it, this always logs in rather than reusing one, and it needs a terminal. A `GH_TOKEN` already in `.env` is checked as usual and no login happens at all.
+
+For a deployment whose secrets live somewhere other than a `.env` file, `--print` writes the credential to stdout as JSON and nothing to disk, with the report and any prompting on stderr:
+
+```
+$ bishop github setup --print
+{"GH_TOKEN":"gho_..."}
+```
+
+`--no-prompt` never offers the login, and fails with the command to run instead. `--temporary` and `--print` combine: log in as the agent, pipe the token into a secret store, leave nothing behind.
+
+## Pointing at a different agent
+
+By default Bishop treats the current directory as both its own home and the agent, so the files above land beside the agent. `--agent` separates the two:
+
+```
+$ 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 exception to reading only is [worktree mode](#worktree-mode), where the agent creates worktrees under `.claude/worktrees/` in its own directory.
+
+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 Slack configuration or losing thread history.
+
+### Pointing at a 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 git@github.com: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.
+
+This is the other half of the split. Point at a directory and its state is yours: Bishop reads it, writes nothing into it, and you pull when you want to. The one thing it removes there is an old thread's worktree, see [Cleaning up after itself](#cleaning-up-after-itself). Point at a repository and Bishop owns the checkout instead, 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, so a quiet week costs one directory.
+
+`current` is for you, not for Bishop. Nothing reads it while a thread runs; it records what the next new thread would start on.
+
+### 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, credentials, or Slack app, which are read from the directory you ran it from and still need a restart to change.
+
+## Cleaning up after itself
+
+A finished conversation leaves things behind: the snapshot it was pinned to, the worktree and branch it edited in, the files people shared in it, and its rows in Bishop's database. A schedule leaves a set every time it fires, which for an hourly one is 24 a day.
+
+Bishop collects them itself, at startup and every six hours after, so a gateway left running for months doesn't fill a disk. Everything a thread left is kept for 30 days past its last turn:
+
+```json
+{
+  "gc": {
+    "maxAgeDays": 30
+  }
+}
+```
+
+A snapshot a thread is still using is kept however old the commit is, and so is `current`. Nothing a live conversation is using is ever touched.
+
+**It deletes what it collects.** A worktree goes with its branch, including work the agent committed there and nobody merged, and a thread that comes back after that starts fresh on the current files. If a thread's work matters, merge it before it ages out, or raise `maxAgeDays`.
+
+**A collected thread stops being one Bishop is listening to.** In a Slack channel, mention the agent to pick it up again; a reply without a mention in a thread that old is ignored. DMs and email are unaffected.
+
+To collect on your own terms, with Bishop stopped or from cron:
+
+```
+$ bishop gc
+$ bishop gc --max-age-days 7
+```
+
+It reads the database and the disk and nothing else, so it needs no credentials.
+
+`bishop slack setup` and `bishop slack manifest` don't take `--agent`. They only deal with Bishop's own directory and the Slack app, and know nothing about any agent.
+
+## Using it over email
+
+Set up a Gmail mailbox for the agent (see [Email](#email)) and the agent has an address. Anyone on its allow list emails it, and the reply arrives in the same thread.
+
+An email thread is an agent session, exactly as a Slack thread is. Reply to the agent's answer and it picks up where it left off.
+
+Email works differently enough to be worth stating:
+
+- **Nothing happens until the turn is over.** No streaming, no progress, no sign the agent is working. Then one plain-text reply arrives with everything it had to say. This makes a long turn fine, which it isn't in Slack.
+- **The reply goes to everyone on the thread.** So Bishop refuses a thread with anyone on it who isn't on the allow list. If you're on the list and copied someone who isn't, it tells you why. If you're not on the list, it sends nothing at all.
+- **Labels are the only progress you get.** Bishop marks each thread `Bishop/Working` while it runs, then `Bishop/Done`, `Bishop/Failed`, or `Bishop/Refused`. Open the mailbox to see what the agent is doing.
+- **Attachments come through.** Bishop downloads what was attached and hands the agent the path, the same as in Slack.
+- **No stop button.** Nothing in email can cancel a turn.
+
+Bishop never answers automated mail: autoresponders, mailing lists, bounces, its own address, or anything Gmail marked spam. It also refuses mail whose sender Gmail's own verdict doesn't clear, without writing back, since the from address is the one thing known to be untrustworthy there. That check reads DMARC rather than a bare SPF or DKIM pass, and only from the topmost `Authentication-Results` header, because a sender can write that header themselves and only Gmail's own copy means anything.
+
+Two rules are worth stating plainly, because both are about mail the agent must never send:
+
+**Bishop only ever writes to an address on the allow list.** Someone not on it gets no reply, not even one explaining why. The thread is labelled `Bishop/Refused` and the reason goes in the log. Without this, pointing the agent at a mailbox that receives ordinary mail means it answers every stranger who writes in.
+
+**Bishop never answers mail that arrived before you pointed it at the mailbox.** It records that moment the first time it connects and refuses anything older, whatever else happens to its polling state. Startup logs the cutoff as `answeringMailAfter`. Restarts still catch up on whatever arrived while it was down, because the cutoff is when it first attached, not when the process started. There is no setting that moves it earlier.
+
+## Using it in Slack
+
+**DM the bot** and every message reaches the agent.
+
+**@-mention it in a channel** to start a thread. Bishop replies in that thread
+and follows the conversation there. It ignores everything else in the channel, including messages in threads it isn't part of.
+
+Each thread is its own agent session with its own history. Two threads are two independent conversations even with the same person, and a thread picks up where it left off, including after Bishop restarts.
+
+**A turn shows its work.** Slack marks the thread as working for as long as the agent is, however long that is, which is also the stop button. Everything the agent writes lands as its own message as it writes it, and the tools it calls in between share a card that says what it is doing now. When the run of tool calls ends, the card becomes a line saying how many it used. The turn closes with the answer and a line saying how long it took, or how long it ran before you stopped it.
+
+**Turn it down.** A thread showing every tool call is a thread that's hard to read when you already trust the agent. Send `` `! verbosity medium` `` to drop the tool card, or `` `! verbosity low` `` to leave only the answer. Send `` `! verbosity` `` to see where a thread stands, and `` `! verbosity default` `` to put it back. It applies to the turn that's running, so you can quiet one mid-flight. `slack.verbosity` in the config sets where every thread starts, and Slack always marks the thread as working whatever the level.
+
+**Commands go to Bishop, not the agent.** Anything whose whole message is code opening with `! ` is a command: Bishop runs it, answers in the thread, and the agent is never told about either. `` `! help` `` lists them, and any of them takes `--help`. What follows the `!` has to look like a command name, so code and pasted output reach the agent as they always did.
+
+**It doesn't answer every message in a busy thread.** In a thread where more than one other person is talking, the agent can leave a message alone when it wasn't for the agent, the way anyone else in the thread would. Slack still shows it thinking for a moment, the way somebody starts typing and then doesn't send. It always answers a message that @-mentions it, and always answers in a thread where you're the only other person talking, so a DM and a thread between you and the agent are unchanged.
+
+**Write while it's working.** A message sent mid-turn gets an :hourglass_flowing_sand: and waits, rather than starting a second turn in the same conversation. When the turn ends, everything waiting goes to the agent as one prompt, with who wrote each one attached. Edit or delete a waiting message and the agent sees the change: what it gets is what the thread says at the moment it is sent.
+
+**Share files with it.** Attach a file to a message, with or without a caption, and the agent gets it: Bishop downloads it and hands over the path. Screenshots included, so "look at this" and an image works. There is no restriction on type; what the agent can do with a `.parquet` is up to the agent. Files over 100MB reach it as a name and a note saying they were too large, which `files.maxMb` changes.
+
+**It can open a file shared before it arrived.** Tag the agent into a thread that already has files in it and it is told what was shared, then downloads the ones it needs. Nothing is fetched on the way in, so tagging it into a thread with forty screenshots in it costs nothing.
+
+**Mentions work both ways.** The agent reads mentions of other people as names rather than as Slack's user ids, and when it writes `@name` Bishop turns it into a real mention that notifies them. Other apps count: an agent can mention the bot beside it in a channel. A name that matches nobody, or more than one account, stays as plain text. `@here`, `@channel`, and `@everyone` are never converted, so an agent can't wake a workspace.
+
+**It can talk to another agent, in a thread you started.** Pull two agents into the same thread and they can address each other, and the one you are talking to is told which messages came from another agent rather than a person. Neither can start the exchange: a bot's message is answered only in a thread that already has a session, so a bot can't DM the agent or open a thread with it. Apps that post under a name rather than an account, like an incoming webhook, are never answered at all. And an exchange between them is capped at three turns in a row by default, after which Bishop says it's holding off and waits for someone to say something. A turn another agent drew can't use Bishop's own tools either, so it can't leave a schedule behind. Set `slack.maxBotTurns` to change the cap, or to `0` to have the agent never answer another bot.
+
+In a DM, Slack shows a stop button for as long as the turn runs. Pressing it cancels the agent mid-turn.
+
+Slack caps messages near 4000 characters, so Bishop splits longer answers. Slack also doesn't render tables and handles nested lists badly, so agent output written for a terminal will sometimes look wrong in a thread.
+
+## Scheduled prompts
+
+Bishop can run a prompt on a clock and post the answer where you say, only when the agent has something to say.
+
+```
+bishop schedules add \
+  --name "CI check" \
+  --cron "0 9 * * 1-5" \
+  --to "#ops" \
+  --prompt "Check CI on main. If nothing is broken, answer <no-output>."
+```
+
+`--to` takes `#channel` or `@person` for Slack, or an email address for Gmail, and never an id: Bishop resolves it once, when you add the schedule, and shows it back the same way. Adding a Slack destination needs three scopes (`channels:read`, `groups:read`, `im:write`) that an app installed before this existed won't have, so run `bishop slack setup` again if it says so.
+
+```
+bishop schedules list          # everything scheduled here, in your own time zone
+bishop schedules disable <id>  # stop it firing, keep it
+bishop schedules enable <id>   # start it again, from now
+bishop schedules rm <id>       # remove it
+```
+
+What to expect:
+
+- **Silence is the normal outcome.** Bishop posts nothing when the agent answers `<no-output>` or says nothing at all. `NOTHING TO REPORT` still works, so a prompt written before this doesn't have to change. Tell the agent in the prompt what is worth reporting; that criterion is yours, not Bishop's.
+- **Nothing streams.** A scheduled turn is invisible while it runs, on Slack as much as on email, because Bishop can't unsay a report it turns out not to want. There is no way to stop one mid-turn.
+- **Every firing is a fresh session.** The agent doesn't remember the last one, so tell it to write down anything it needs to carry over.
+- **`--cron` is five fields**, read in `--tz` (defaults to this machine's zone), and no more often than every five minutes. `@daily` and friends work.
+- **Nothing fires while Bishop is stopped, and nothing catches up.** A firing missed while it was down is skipped, and the log says so. A firing whose previous run is still going is skipped too.
+- **A failure is never silent.** Bishop posts to the destination on the first failed run, records the reason in `schedules list`, and after five failures in a row turns the schedule off and says so. Re-enable it with `bishop schedules enable`.
+- **A schedule stops when its author loses access.** Bishop re-checks the allow list at every firing, so removing someone stops what they scheduled.
+
+Schedules live in `bishop.db`, not in a config file, so `bishop schedules list` is the only way to see what the agent will do tomorrow.
+
+### Asking the agent for one
+
+You can also just ask, in a thread or an email:
+
+> @agent send me a report every morning at 9am in #ops, and stay quiet if there's nothing to say
+
+The agent writes the schedule itself, and Bishop wakes up and delivers it. Leave the destination out and it posts back into the conversation you asked in.
+
+Slack refuses a channel the app isn't in, Gmail refuses an address that isn't on `gmail.allow`, and you'll be told so in the thread rather than finding out at nine tomorrow. You can ask by email for something to land in Slack; it's the `#ops` that decides where it goes, not where you asked from.
+
+Two limits the command line doesn't have, both because the agent is picking rather than you:
+
+- **It won't start DMing someone who isn't on `slack.allow`**, and won't send mail at all unless `gmail.allow` is set. Posting in a channel is fine, since the app had to be invited there. Use `bishop schedules add` to aim somewhere the recipient hasn't opted into.
+- **Twenty schedules per person.** Ask for a twenty-first and it'll tell you to remove one first.
+
+What the agent can *see* is narrower. It lists and removes schedules you created, plus any that post into the conversation you're in, and nothing else, so asking it won't name private channels you aren't in. `bishop schedules list` still shows everything, with `by slack:U123…` naming who asked for each.
+
+## Configuration
+
+`.bishop/config.json` holds everything except credentials. Setup writes it, and you can edit it by hand.
+
+```json
+{
+  "slack": {
+    "workspace": "acme",
+    "app": {
+      "id": "A09XXXXXXXX",
+      "name": "salesforce-guy",
+      "displayName": "Salesforce Guy",
+      "description": "Answers Salesforce admin questions"
+    },
+    "allow": [
+      "hayes.davis@agentdeployment.co",
+      "revops",
+      "@sales-managers"
+    ]
+  },
+  "gmail": {
+    "allow": ["hayes.davis@agentdeployment.co", "@agentdeployment.co"],
+    "pollSeconds": 20
+  },
+  "agent": {
+    "harness": "claude",
+    "model": "claude-sonnet-5",
+    "effort": "high"
+  }
+}
+```
+
+Every block is optional, and an interface runs when its credentials are set rather than when its block is here. `gmail` takes `allow`, `pollSeconds`, `labelPrefix`, and `markRead`; its `allow` is addresses and `@domain` entries, and an entry that is neither stops startup.
+
+`slack` takes `allow`, `maxBotTurns`, and `verbosity`, plus the `workspace` and `app` fields setup writes.
+
+`agent` takes `harness`, `model`, `effort`, `worktrees`, `options`, and `harnesses`. The last two are alternatives: `options` for a config that runs one harness, `harnesses` for one that switches.
+
+Every key is checked at startup, so a typo fails with the path to it rather than being ignored. The one exception is `agent.options`, which is passed through to the harness unvalidated.
+
+### Which agent runs
+
+`agent.harness` picks the SDK. `claude` is the default and runs the Claude Agent SDK; `codex` runs OpenAI's Codex SDK.
+
+```json
+{
+  "agent": {
+    "harness": "codex"
+  }
+}
+```
+
+`--harness` overrides it for one run, and an unsupported name fails at startup naming the ones that exist:
+
+```
+$ bishop --harness codex
+$ bishop --harness gemini
+unknown harness "gemini"; supported: claude, codex
+```
+
+Bishop manages no model credentials either way. Each harness authenticates however its own CLI does in that directory, so make `claude` or `codex` work there first. For Codex that means `codex login`, or `CODEX_API_KEY` in the environment or `.env`.
+
+`OPENAI_API_KEY` is deliberately not read, because `codex` doesn't read it either. With only `OPENAI_API_KEY` set and no login, `codex` sends no credential at all and the request comes back `401 Missing bearer`. Picking it up here would invent a credential path Codex doesn't have, and on a machine with a working `codex login` it would override that login and move billing to the API key without saying so.
+
+Bishop warns at startup when it can find neither a `CODEX_API_KEY` nor a login, since the first turn would otherwise fail on authentication with nothing to explain it. The startup check can't catch that itself: it stops before any model call, which is what makes it free. Otherwise the log names the credential it found.
+
+A session id belongs to the harness that issued it, so changing this leaves running threads unable to resume. Bishop notices, logs it, and starts each thread a fresh session on its next message rather than failing the turn. Nothing else is lost.
+
+Codex threads read differently in one way that shows: what its tool cards say is vaguer, because a command comes through as a raw shell line and nothing else, which Bishop won't put in a thread.
+
+### Model and effort
+
+Every harness has a model and a reasoning level, so both sit at the top of `agent` rather than inside `agent.options`:
+
+```json
+{
+  "agent": {
+    "harness": "codex",
+    "model": "gpt-5.6-codex",
+    "effort": "high"
+  }
+}
+```
+
+Both are free strings, passed to the harness as written. The names belong to the harness and change with it, so Bishop doesn't check them: `claude` takes `claude-sonnet-5` and `low` through `max`, `codex` takes `gpt-5.6-codex` and `modelReasoningEffort`'s levels.
+
+Nothing checks the value before the first turn, including the startup check, which stops before any model call. A name the harness doesn't know surfaces in a thread instead, differently by harness. Codex fails the turn with the API's own complaint about the field. Claude answers a bad model with the agent saying in prose that the model is wrong, and ignores an effort level it doesn't recognize. So an effort typo under Claude is silent: check the log line at startup, which names the model and effort Bishop passed.
+
+`--model` and `--effort` override the config for one run:
+
+```
+$ bishop --harness claude --model claude-opus-5 --effort high
+```
+
+Each harness maps them onto its own option, which is `model` and `effort` under Claude, `model` and `modelReasoningEffort` under Codex. Setting the same thing again in `agent.options` loses to these, and startup logs a warning naming the key it overrode. That way a flag never does nothing silently.
+
+### Switching between harnesses
+
+`agent.options` is written in one harness's vocabulary, so a config meant to run either one keeps a block per harness:
+
+```json
+{
+  "agent": {
+    "harness": "claude",
+    "worktrees": true,
+    "effort": "high",
+
+    "harnesses": {
+      "claude": {
+        "options": { "maxTurns": 30 }
+      },
+      "codex": {
+        "model": "gpt-5.6-codex",
+        "options": { "sandboxMode": "danger-full-access" }
+      }
+    }
+  }
+}
+```
+
+`bishop` runs Claude with its block, and `bishop --harness codex` runs Codex with its own model and sandbox setting. Nothing written for one follows the other.
+
+A block takes `model`, `effort`, and `options`, and nothing else. `model` and `effort` layer over the ones beside `harness`, so `effort` above applies to both harnesses and Codex adds a model. `options` doesn't layer: it replaces `agent.options` outright, since merging two objects written in different vocabularies would splice one harness's keys into the other's call.
+
+That leaves `agent.options` as the options for whichever harness has no block of its own, which is what keeps a config that never switches harness exactly as it was. Set both for the same harness and startup warns that the block wins. Switch to a harness with no block and startup warns that it is being handed options meant for the other one, since the harness that doesn't own them ignores what it doesn't recognize and says nothing.
+
+A harness name Bishop doesn't run fails at startup rather than being ignored, so a misspelled block can't quietly do nothing.
+
+### Who can use the agent
+
+`allow` takes usernames, emails, and group names in one list, and Bishop works out which is which. A leading `@` is optional. Groups expand to their members, and Bishop refreshes the list every few minutes so a membership change lands without a restart.
+
+Every message is checked, not just the one that starts a thread, so someone who isn't allowed can't join a conversation another person started. They get a reply only they can see.
+
+Another app is an entry like any other: list it by name and the agent will answer it, subject to the same limits on a bot-only exchange described in [Using it in Slack](#using-it-in-slack). This is the setting that decides which apps can reach the agent, and it matters more than it did: without a list, any app posting in a thread someone started can draw a turn, and what it posts is text nobody in the thread wrote. Set `slack.maxBotTurns` to `0` to keep every one of them out.
+
+Leave `allow` out and anyone who can reach the bot can use the agent. Bishop warns at startup when that's the case.
+
+An entry matching two different things, like a name that's both a person and a group, stops startup and says which candidates it found. An entry matching nothing logs a warning and Bishop keeps running, so a departed colleague's email doesn't take the agent down.
+
+### Agent options
+
+`agent.options` is passed to the agent harness. Under Claude that is the Agent SDK's own options object, not a settings file: anything from [Claude Code's settings reference](https://code.claude.com/docs/en/settings-reference) goes in the nested `settings` object, which is shaped like a `.claude/settings.json`. A settings key written at the top level is dropped by the SDK without a word, so put it a level down:
+
+```json
+{
+  "agent": {
+    "options": {
+      "maxTurns": 30,
+      "settings": {
+        "permissions": { "allow": ["Bash(python3:*)"] }
+      }
+    }
+  }
+}
+```
+
+These layer over the agent's own settings files rather than replacing them, so a project that sets `model` in `.claude/settings.json` keeps it unless `agent.options` names `model` too. [`agent.model` and `agent.effort`](#model-and-effort) sit above `agent.options` in turn, and a config that switches harness puts its options in [a block per harness](#switching-between-harnesses) instead.
+
+Bishop sets a few options itself and ignores them here: `cwd`, `resume`, `systemPrompt`, `abortController`, `sessionId`, `forkSession`, and `canUseTool`. Setting one logs a warning naming it. They decide which agent runs, which conversation it continues, and how Bishop tells the agent who it's talking to.
+
+Bishop sets two defaults, both overridable. `permissionMode: "auto"`, because nothing in Slack can answer a permission prompt and an agent needing approval for a tool reports itself blocked instead of doing the work; override it in `agent.options` if you want something stricter. And `settings.autoMemoryEnabled: false`, because auto memory writes to `~/.claude/projects/<agent-directory>/memory`, outside the agent's own repository: it doesn't travel when you deploy the agent somewhere else, and a remote agent's directory changes with every commit, so the memory of the last one is orphaned. Turn it back on with:
+
+```json
+{
+  "agent": {
+    "options": {
+      "settings": { "autoMemoryEnabled": true }
+    }
+  }
+}
+```
+
+That key belongs under `settings` and nowhere else. The harness ignores it at the top of `agent.options`, so Bishop warns at startup if you put it there.
+
+`hooks` and `settings` merge instead of being replaced or ignored. Your hooks run alongside the one [worktree mode](#worktree-mode) installs, so setting `hooks` can't switch that off, and your `settings` object keeps Bishop's defaults for the keys it doesn't name. Pointing `settings` at a settings *file* instead opts out of both defaults, which Bishop warns about.
+
+#### Under the Codex harness
+
+`agent.options` takes Codex's own fields instead:
+
+```json
+{
+  "agent": {
+    "harness": "codex",
+    "options": {
+      "sandboxMode": "danger-full-access",
+      "additionalDirectories": ["/srv/data"]
+    }
+  }
+}
+```
+
+Bishop's defaults are `approvalPolicy: "never"`, `sandboxMode: "workspace-write"`, `networkAccessEnabled: true`, and `skipGitRepoCheck: true`. Nothing in Slack can answer an approval prompt, so an agent that asks for one stalls the turn. The sandbox is the compensation: writes stay inside the working directory, and network access stays on because an agent that can't push, install, or fetch fails at something in most threads. Override any of them here.
+
+Bishop sets `workingDirectory` and `developer_instructions` itself and ignores them here, for the same reasons as above.
+
+`config` and `configOverrides` reach Codex's own `--config` mechanism, which is how anything in `config.toml` can be set per-agent. Bishop uses `config.developer_instructions` for the principal, so a `config` object you set is merged rather than replaced.
+
+### Worktree mode
+
+Threads share one directory, so two people directing a coding agent in two threads write the same files. Turn that off:
+
+```json
+{
+  "agent": {
+    "worktrees": true
+  }
+}
+```
+
+Each thread now works in its own git worktree, named `bishop-<team>-<channel>-<thread>`, and stays in it for every later message. It lives in `.claude/worktrees/` at the root of the repository the agent is in, which is the agent directory itself unless you pointed `--agent` at a git URL; there Bishop's own checkout layout puts it in `.bishop/agents/<slug>/mirror.git/.claude/worktrees/`. `git worktree list` always says.
+
+How it gets there depends on the harness, because only one of them can be told to move itself:
+
+- **Claude** creates the worktree the first time the agent decides to edit a file, so a thread that only asks questions never gets one. Bishop names it, tells the agent to enter it, and refuses edits in the shared checkout until it has. The branch is the worktree name prefixed with `worktree-`.
+- **Codex** has no equivalent tool, so Bishop creates the worktree itself and starts the session inside it. Every thread gets one whether or not it edits anything, and the branch is the worktree name exactly. Nothing depends on the agent cooperating.
+
+Either way the agent commits on that branch and says which one it is.
+
+A worktree outlives the thread that made it, and Bishop collects it a month after the thread's last message, along with its branch. See [Cleaning up after itself](#cleaning-up-after-itself). To take one sooner: under Claude the harness locks each one while its session holds it, and the lock outlives the process, so removing one takes two commands:
+
+```
+$ git worktree list
+$ git worktree unlock .claude/worktrees/bishop-T1-C1-1712345678-123456
+$ git worktree remove .claude/worktrees/bishop-T1-C1-1712345678-123456
+```
+
+Add `--force` to `remove` to discard uncommitted changes in it. Check `git -C <worktree> status` first: that's where a thread's unfinished work is.
+
+A new worktree holds only tracked files, so `node_modules` and anything else your repository ignores is missing. Symlink what the build needs:
+
+```json
+{
+  "agent": {
+    "worktrees": true,
+    "options": {
+      "settings": {
+        "worktree": {
+          "symlinkDirectories": ["node_modules"],
+          "baseRef": "head"
+        }
+      }
+    }
+  }
+}
+```
+
+Bishop sets `baseRef` to `head` so a worktree branches from wherever the agent directory is now. Set it to `fresh` to branch from `origin/<default-branch>` instead. Everything else the harness offers here, including `sparsePaths` for a large monorepo, works the same way. That block is Claude's; under Codex, Bishop always branches from `HEAD` and there is nothing to configure.
+
+Under Claude, Bishop refuses `Edit`, `Write`, and `NotebookEdit` in the shared directory until the agent has entered its worktree, and tells the agent why. Bash is not checked, since a command's target can't be read off its text. So this keeps threads out of each other's way; it isn't a sandbox, and an agent determined to write outside its worktree can. Under Codex the session starts in the worktree, so nothing has to be refused, and `sandboxMode` is what limits where it can write.
+
+**When the agent directory isn't a git repository**, there's nothing to isolate. Bishop warns at startup and says so once in each thread, then edits the directory directly.
+
+### Shared files
+
+Bishop downloads what people attach and saves it under `.bishop/files`, one directory per thread, collected with everything else that thread left behind. The agent reads it from disk, so any file type works.
+
+A file shared earlier in the conversation is named to the agent rather than downloaded, and the agent fetches the ones it wants with a tool. That keeps being tagged into a busy thread cheap, and it means the agent can go back for a file it was told about turns ago. A reference only works in the conversation the file was shared in.
+
+```json
+{
+  "files": {
+    "maxMb": 100
+  }
+}
+```
+
+The default is 100. A file over the limit isn't refused: the agent is told its name and that it was too large, so it can say so. There is no restriction on type and won't be.
+
+**Slack needs the `files:read` scope**, which is new. An app set up before this has to be reinstalled to grant it, and until then Bishop warns at startup and the agent sees a note in place of each file. Run `bishop slack manifest` for the current manifest, or reinstall from App Settings. Gmail needs nothing new.
+
+### Credentials
+
+`.env` holds the Slack tokens, written by setup:
+
+```
+BISHOP_SLACK_BOT_TOKEN=xoxb-...
+BISHOP_SLACK_APP_TOKEN=xapp-...
+```
+
+Add `ANTHROPIC_API_KEY` if the agent should use a specific key. Without one, the agent authenticates however `claude` does on that machine, usually an existing login. Bishop logs which of the two it used at startup.
+
+Anything else in `.env` reaches the agent's environment too, which is how `GH_TOKEN` from [`bishop github setup`](#github) gets there.
+
+## Running it for real
+
+Bishop is one process that logs JSON to stdout and errors to stderr, so any process supervisor works. It needs only outbound access to Slack, since it uses Socket Mode. No public URL, no inbound firewall rule.
+
+```
+$ BISHOP_LOG_LEVEL=info bishop
+```
+
+`BISHOP_LOG_LEVEL=debug` adds tool activity and every routing decision. Pipe through `npx pino-pretty` to read it by eye.
+
+At startup Bishop checks that the agent can launch, resolves the allow list, and connects to Slack, failing with a specific message if any of those doesn't work.
+
+### As a systemd service
+
+A unit file keeps Bishop running across crashes and reboots on a Linux host:
+
+```
+[Unit]
+Description=Bishop gateway for <agent>
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=<user>
+WorkingDirectory=/path/to/agent
+Environment=BISHOP_LOG_LEVEL=info
+ExecStart=/path/to/node /path/to/bishop/dist/cli.js --agent /path/to/agent
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Point `ExecStart` at an absolute path to `node`, not the bare command. systemd doesn't source `.bashrc` or `.profile`, so a version installed through nvm isn't on `PATH` for the service even though it is for you in a login shell. `which node` finds the real path; symlink it somewhere stable like `~/.local/bin` so the unit survives a node upgrade without an edit. Installed from npm, the script it runs is `<npm root -g>/@agentdeploymentco/bishop/dist/cli.js`.
+
+```
+$ sudo systemctl enable --now bishop.service
+$ journalctl -u bishop -f
+```
+
+**Editing the unit file needs no sudo, applying it always does.** `chown` the unit to the service's own user (`sudo chown <user> /etc/systemd/system/bishop.service`) so an edit is a normal file write, then scope `sudoers` to exactly the two commands a change needs: `daemon-reload` and `restart bishop.service`. That is the smallest grant that lets a deployment change its own `ExecStart` without a root shell.
+
+```
+<user> ALL=(root) NOPASSWD: /usr/bin/systemctl daemon-reload, /usr/bin/systemctl restart bishop.service
+```
+
+**Switching `--agent` from a local path to a git URL with `--auto-update`, replace the flag, don't append it.** `ExecStart` is a backslash-continued multi-line value, and the old `--agent /path` line loses its trailing `\` when a new one gets pasted below it. systemd then ends the directive at that line, and the new `--agent` line below becomes a bare, invalid line in `[Service]`. `systemctl status` catches half of this ("unit file changed on disk, run daemon-reload") but not the syntax error, so read the file back after editing rather than trusting the diff you meant to make.
+
+**A restart kills whichever turn asked for it, when Bishop is asked to reconfigure itself.** An agent that edits its own unit file and runs `systemctl restart` takes down the process running that same turn. It comes back clean, since session and thread state live in Bishop's own working directory rather than the agent's, so the conversation resumes on the next message. But the response that triggered the restart cuts off mid-stream, which reads as a crash to whoever is waiting on it unless they're told to expect it. Some harnesses also refuse this outright: Claude Code's own permission model blocks a session from editing a file outside its project directory or restarting the service that's running it, so a human ends up applying the unit change and the restart by hand either way.
+
+**A fresh `--auto-update` snapshot has no git identity.** Each commit gets its own directory under `.bishop/agents/<slug>/snapshots/`, cloned straight from the bare mirror, and none of them inherit a `user.name`/`user.email` set locally in an old checkout. Set it globally for the service's user once (`git config --global user.name ...`) rather than per snapshot, or every commit the agent makes fails with "Author identity unknown."
+
+### In a container
+
+`ghcr.io/agent-deployment-co/bishop` runs Bishop on Debian with Node 24, for `linux/amd64` and `linux/arm64`. The image is the agent's shell as well as Bishop's, so it carries git, `gh`, ripgrep, jq, curl, ssh, and python3 alongside both harness SDKs. `uv` and `uvx` are there too, with CPython 3.14 already installed and on `PATH` as `python3.14`, since Debian's `python3` is externally managed and won't let anything install into it.
+
+Two directories to persist. `/data` is the working directory, holding everything Bishop writes:
+
+```
+/data/.bishop/config.json    configuration
+/data/.bishop/agents/        cloned agents, when --agent is a git URL
+/data/bishop.db              the thread-to-session mapping
+```
+
+`/home/node` is the second, holding what the harnesses write: their logins, and the session transcripts they resume from. Bishop resumes a thread by handing back the session id it recorded in `bishop.db`, so a home directory that dies with the container leaves every existing thread asking for a transcript the harness no longer has. Mount it or lose every conversation on the next deploy.
+
+Credentials go in the environment rather than a `.env` file:
+
+```
+$ docker run -d --name bishop \
+    -v bishop-data:/data -v bishop-home:/home/node \
+    -e BISHOP_SLACK_BOT_TOKEN -e BISHOP_SLACK_APP_TOKEN \
+    -e ANTHROPIC_API_KEY \
+    -e GIT_CONFIG_COUNT=2 \
+    -e GIT_CONFIG_KEY_0=user.name -e GIT_CONFIG_VALUE_0="Agent" \
+    -e GIT_CONFIG_KEY_1=user.email -e GIT_CONFIG_VALUE_1="agent@example.com" \
+    ghcr.io/agent-deployment-co/bishop \
+    --agent https://github.com/you/your-agent.git --auto-update
+```
+
+The entrypoint is `bishop`, so arguments after the image are its flags, and any other command works the same way: `docker run --rm -v bishop-data:/data ghcr.io/agent-deployment-co/bishop gc`.
+
+Set a git identity, as above, or the agent can't commit what it does in a worktree. `GIT_CONFIG_COUNT` reaches every snapshot and worktree Bishop creates, which a `git config` run in one directory doesn't.
+
+Bishop runs as uid 1000 and needs to write both volumes. On Kubernetes that means a `fsGroup` in the pod's security context, or volumes already owned by 1000.
+
+Tags: `latest` and `sha-<commit>` from `main`, plus `<version>` and `<major>.<minor>` from a `v*` git tag. `bishop --version` reads `package.json`, so a release tag has to bump it in the same commit or the image reports a version its tag disagrees with.
+
+Setup commands that need a browser or a terminal (`bishop slack setup`, `bishop gmail setup`) are meant to be run on a laptop. Carry the tokens they produce to the container as environment variables, and the `.bishop/config.json` they write into the volume.
+
+## Troubleshooting
+
+**"--agent directory doesn't exist"** or **"is not a directory"** means the path is wrong. Bishop checks it before anything else, because the harness reports a bad directory as a native binary failing to launch.
+
+**"The Claude agent couldn't start"** means the harness didn't launch. Check that
+`claude` works in that directory first. Note that a wrong `ANTHROPIC_API_KEY` passes this check and fails on the first real message, since only a live call tests a key.
+
+**The agent says it's blocked on permissions.** Something needs approval that
+`auto` mode declined. Add an allow rule under `agent.options.settings.permissions.allow`.
+
+**The bot doesn't answer in a channel.** It only replies to mentions and to
+threads it's already in. Confirm it's in the channel and that you mentioned it.
+
+**The bot doesn't answer at all** and the log shows a refusal. The sender isn't
+on the `allow` list.
+
+**The agent never answers, and nothing appears in the log.** If you set the app up by hand, check its Event Subscriptions. Bishop can't see them, and an app subscribed to nothing looks identical to an idle one.
+
+**Setup says the app kept a `(local)` suffix.** The `slack` CLI's login expires
+after 12 hours, which stops Bishop from correcting the app name. Run `slack auth login` again, or rename the app in Slack.
+
+**You can't find what a thread changed.** In worktree mode the work is on that thread's branch, not in the agent directory. `git worktree list` shows every one, and `git branch --list 'worktree-bishop-*'` shows the branches.
+
+**A build or test fails inside a worktree.** A fresh worktree has only tracked files, so `node_modules` and anything else the repository ignores isn't there. Add it to `agent.options.settings.worktree.symlinkDirectories`.
+
+**The agent says it can't edit a file.** In worktree mode Bishop refuses writes in the shared directory. The agent is told to call `EnterWorktree` first, and normally does it unprompted. If the agent directory isn't a git repository, that can't work, and Bishop says so in the thread.
+
+**Sessions get confused.** Delete `bishop.db` to make every thread start fresh.
+It holds only the thread-to-session mapping.
+
+## What this version doesn't do
+
+- One agent per directory, one process. No agent registry.
+- Slack and Gmail only. No Teams.
+- No sandboxing between sessions. [Worktree mode](#worktree-mode) keeps concurrent threads out of each other's files, but it's a convention with a guardrail rather than a sandbox, and it needs a git repository. Without it, two threads can write the same file at once.
+- Files come in but don't go out. The agent can read what you attach; it can't attach anything to its answer.
+- No approval flow. Permission decisions are the harness's, and Slack has no way to ask a person.
+- No way to turn Bishop's own tools off. Bishop listens on `127.0.0.1` on an ephemeral port to serve them, authenticated with a credential minted per turn and destroyed when the turn ends. Nothing is reachable from off the machine, but anything running on it can reach the port and will be refused.
+
+Bishop notices neither a revoked Slack app nor a dead socket, so a supervised process can look healthy while receiving nothing. Restart it if the agent goes quiet.
+
+## How setup gets the tokens
+
+Worth knowing if you're wondering why the `slack` CLI is a requirement.
+
+Socket Mode needs an app-level (`xapp-`) token, and no Slack API will mint one. The `slack` CLI does, and hands it to a project it runs. So setup writes a throwaway Slack project, runs it once to collect both tokens, and stops it. The CLI creates that app as a dev app and appends ` (local)` to its name, so setup pushes the intended manifest over it afterward. That changes no permissions and needs no reinstall.
+
+## License
+
+Not yet chosen, and the published package says so: `license` is `UNLICENSED`, which grants nothing. Nobody outside the company should build on it until there are real terms.