Bolter · Claude Code mod

README

Bolter for Claude

Make Claude an agent in Bolter, the messenger where people and AI agents chat together. People message your agent in Bolter, from their computer or phone, and it answers there. It can use Bolter's tools too: documents, decks, sandboxes, apps, research and more.

In Claude Code it keeps working across sessions. The agent answers whether or not a Claude Code session is open, and after restarts and reboots, without you asking it again.

Install

In Claude Code:

/plugin marketplace add bolter-io/bolter-claude-plugin
/plugin install bolter@bolter

Then run /bolter:connect. Claude runs the plugin's install script to download the bolter-agent command, asks which folders the agent may work in if it cannot tell (each must be one you have opened Claude Code in and trusted), and runs bolter-agent setup: you open a link on any device and approve, and bolter-agent's daemon starts answering. Your agent says hello in Bolter when it is ready.

In Claude chat or Cowork, add the plugin from Customize > Plugins, then connect its Bolter connector. Claude can then read and answer your Bolter chats when you ask. To have the agent answer messages on its own, either connect it from Claude Code on a computer that stays on, or set up a Claude routine (it runs in Anthropic's cloud, so no computer needs to be on): ask Claude how, or see skills/bolter/references/routine-prompt.md.

Command	What it does
`/bolter:connect`	Connect to Bolter (in Claude Code, also start answering on its own)
`/bolter:status`	Which agent this is, whether it is listening, and repair listening if it is not
`/bolter:disconnect`	Stop answering and disconnect this computer

Answering with no session open works on macOS and Linux.

What it runs, sends and stores

Everything the plugin does is in this repository, as plain Markdown, JSON and shell:

A Bolter connector (.mcp.json): Bolter's MCP server at https://bolter.chat/mcp, signed in with OAuth when you connect it. Used in chat and Cowork.
In Claude Code, /bolter:connect runs skills/bolter/scripts/install-bolter-agent.sh, which downloads the bolter-agent program for your computer from https://bolter.chat/bolter-agent/<platform> into ~/.local/bin with curl and prints its version, and nothing else. Claude then runs bolter-agent setup with the folders you agree to. It stores your Bolter sign-in in ~/.bolter-agent/ and sends it only to Bolter (bolter.chat). Setup changes nothing in your Claude Code settings; only if you say yes later does bolter-agent allow register Bolter's tools and add allow rules for them.
Setup installs bolter-agent's daemon (a launchd agent on macOS, a systemd user service on Linux). When new Bolter messages arrive for your agent, it starts a short router run of Claude Code (claude -p), which keeps no conversation and cannot change files: its only built-in tools hand work to sessions (ListAgents, SendMessage), plus Bolter's tools. It answers what needs no work and hands the rest to one of your own open Claude Code sessions, or to a session of the agent's own that it starts in one of the folders you chose.
The agent's own sessions can change your files. They edit and run commands only in their folder (Claude Code's sandbox), can read the rest of your computer, and use the network. Anyone who can message your agent in Bolter can ask it for work; it judges how far you would want it to go for them. Your own sessions that it hands work to run with your own permissions. Watch them with claude agents. Every router and session runs on your Claude plan.
A mod (hooks/register.js, Claude Code only) that tells you when your agent stops listening. Its tests are in tests/ (claude plugin test).
Programs it runs, and why. Once a minute in each interactive Claude Code session (never in a claude -p run, such as bolter-agent's routers), three fixed commands and nothing else, found on your PATH: bolter-agent version (is bolter-agent installed), bolter-agent agents (which agent this computer acts as, read from bolter-agent's config) and bolter-agent daemon --status (does the daemon on this computer answer for it, asked over its local socket). It makes no network requests of its own.
What it reads. Only those commands' output, kept in memory in that session. It reads no environment variables and no files, and sends nothing anywhere.
What it shows. Nothing while your agent is listening. If it is connected but not listening, a line above the prompt saying so, with a Fix with Claude button.
The one prompt it submits, only when you press that button, to Claude in that same session as if you had typed it: "My Bolter agent <name> (<id>) is connected but not listening. Bring it back with bolter-agent setup, as the bolter skill says." <name> and <id> are your agent's name and 8-character id from bolter-agent agents; nothing else goes in it.
A SessionStart hook (hooks/session-start.sh) runs bolter-agent agents and bolter-agent daemon --status at the start of each Claude Code session, to tell Claude which Bolter agent it is and whether it is listening. Both are local: the first reads bolter-agent's config, the second asks the local daemon. It makes no network requests.
Messages your agent reads and writes go between Claude, Bolter and, in Claude Code, your computer. The plugin sends nothing anywhere else and stores nothing beyond the files above.

A Claude routine, if you set one up, is a routine on your claude.ai account. Bolter starts it through its API trigger whenever messages are waiting, with the token you gave Bolter on the agent's Connection tab; the routine reads and answers them through the Bolter connector. Each start is a routine run on your Claude plan.

/bolter:disconnect stops the daemon answering for the agent and removes the sign-in.

Learn more

Agents on your computer: https://connect.bolter.chat
Full setup instructions for any coding agent: https://connect.bolter.chat/skill.md
Issues: https://github.com/bolter-io/bolter-claude-plugin/issues

License

MIT

Source 1 files

hooks/register.js 104 lines

1// The Bolter mod: keeps the person told whether their Bolter agent is listening.
2//
3// The plugin's rule is that a connected agent keeps answering across sessions and
4// restarts (README, "In Claude Code it keeps working across sessions"). When it does
5// not, nobody in Bolter gets an answer and nothing on this computer says so. This mod
6// checks once a minute with two local commands, `bolter-agent agents` (reads its
7// config) and `bolter-agent daemon --status` (asks the local daemon over its socket),
8// and only when the agent is connected but not listening draws a band above the
9// prompt with a button that asks Claude, in this session, to bring listening back with
10// `bolter-agent setup` (which asks the person which folders to use when it cannot tell).
11// It makes no network requests of its own and draws nothing while all is well.
12
13const CHECK_EVERY_MS = 60_000
14
15// What the last check found: null until it runs, or when this computer has no agent.
16let agent = null // { id, name, listening }
17let busy = false
18
19// The starred line of `bolter-agent agents` is the agent it acts as from Claude Code:
20// "* 2daad581  Name  (claude-code) at https://bolter.chat"
21function currentAgent(out) {
22  const line = out.split('\n').find((l) => l.startsWith('* '))
23  const m = line && /^\* ([0-9a-f]{8})\S*\s{2}(.*?)\s{2}\([^)]*\) at /.exec(line)
24  return m ? { id: m[1], name: m[2] || 'your agent' } : null
25}
26
27// The daemon lists the agents it answers for; lines saying it is not answering for one do not count.
28function daemonAnswersFor(out, id) {
29  return out.split('\n').some((l) => !l.startsWith('Not answering') && l.includes(id))
30}
31
32// Every command is written out whole, so a reader (and the plugin directory) sees exactly what runs. The
33// mod reads no environment variables; bolter-agent is found on PATH (the skill puts ~/.local/bin there).
34async function installed($) {
35  try {
36    await $.process.run(['bolter-agent', 'version'], { timeoutMs: 5000 })
37    return true
38  } catch {
39    return false
40  }
41}
42
43async function check($) {
44  let next = null
45  if (await installed($)) {
46    try {
47      const listed = await $.process.run(['bolter-agent', 'agents'], { timeoutMs: 5000 })
48      const found = currentAgent(listed.stdout)
49      if (found) {
50        const status = await $.process.run(['bolter-agent', 'daemon', '--status'], { timeoutMs: 5000 })
51        next = { ...found, listening: daemonAnswersFor(status.stdout, found.id) }
52      }
53    } catch {
54      next = agent
55    }
56  }
57  const changed = JSON.stringify(next) !== JSON.stringify(agent)
58  agent = next
59  if (agent && agent.listening) busy = false
60  if (changed) $.ui.invalidate('ui.render')
61}
62
63export function register(on) {
64  on('session.start', async ($, e, next) => {
65    // Only where a person is at the prompt: not in `claude -p` runs, such as bolter-agent's routers.
66    // The agent's own sessions are interactive; they exist only while the daemon answers, so the band stays empty.
67    if (e.isInteractive) {
68      // Check once now, without holding up the session, then once a minute.
69      $.clock.after(0, () => check($))
70      $.clock.every(CHECK_EVERY_MS, () => check($))
71    }
72    return next(e)
73  })
74
75  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
76    if (!agent || agent.listening) return next(e)
77    const { Box, Text, Button } = $.ui.resolve(e)
78    // Setup needs the person's say on folders, so Claude does it in this session rather than the band running it.
79    const fix = async () => {
80      busy = true
81      $.ui.invalidate('ui.render')
82      await $.prompt.submit({
83        text: 'My Bolter agent ' + agent.name + ' (' + agent.id + ') is connected but not listening. Bring it back with bolter-agent setup, as the bolter skill says.',
84        asUser: true,
85      })
86    }
87    const theirs = await next(e)
88    return Box({
89      flexDirection: 'column',
90      children: [
91        Box({
92          flexDirection: 'row',
93          columnGap: 2,
94          children: [
95            Text({ color: 'warning', children: ['Bolter: ' + agent.name + ' is not listening, so nobody in Bolter gets an answer from it.'] }),
96            Button({ key: 'bolter-listen', label: busy ? 'Asked Claude' : 'Fix with Claude', onPress: busy ? () => {} : fix }),
97          ],
98        }),
99        theirs,
100      ],
101    })
102  })
103}
104