collab

1// ABOUTME: The collab plugin's hooks: project keys, the read guard, inbox polling, the pane,
2// ABOUTME: and listening for replies, all over the collab MCP server the manifest declares.
3
4import { atom, read, update } from 'claude-code'
5import type { EngineInterface, Register, ToolCallResult } from 'claude-code'
6
7import type { Inbox, PaneView, Filing, Thread, ThreadRead } from '../types'
8import { arrivals, listenPrompt, readPrompt, sentToast, statusText, threadsTitled, toastText } from './inbox'
9import { hasOldServer, hasOldStatusLine, leftoverText } from './leftovers'
10import { oneLine } from './pane'
11import { projectKey, projectName } from './projects'
12import { sessionSection } from './prompt'
13import { answerOf, CollabError } from './server'
14import { listView, threadView } from './view'
15import type { Action, PaneElements } from './view'
16
17// The plugin's own server, as Claude calls its tools.
18const COLLAB = 'mcp__plugin_collab_collab__'
19
20const POLL_MS = 30_000
21// Long enough after start for the session's MCP servers to have connected.
22const LEFTOVER_CHECK_MS = 15_000
23const PANE = 'collab'
24const LIST: PaneView = { screen: 'list', selected: null, expanded: [], error: null }
25
26const listening = atom({ plugin: 'collab', key: 'listening' } as const, [] as string[])
27const inbox = atom({ plugin: 'collab', key: 'inbox' } as const, { threads: [], error: null, checked: false } as Inbox)
28// The person's archived threads, once they open the pane's Archived group.
29const archived = atom({ plugin: 'collab', key: 'archived' } as const, null as Thread[] | null)
30const pane = atom({ plugin: 'collab', key: 'pane' } as const, LIST)
31const NO_FILING: Filing = { autoFile: false, known: [] }
32const filing = atom({ plugin: 'collab', key: 'filing' } as const, NO_FILING)
33
34/** This session's project key, read afresh: `/cd` can move the session. */
35const here = async ($: EngineInterface) => projectKey(await $.session.repo(), await $.session.root())
36
37/** Calls a collab tool through Claude Code's own connection, so the person's sign-in carries over. */
38const call = async ($: EngineInterface, tool: string, args: Record<string, unknown> = {}): Promise<any> => {
39  const connected = await $.mcp.connect('collab')
40  if (!connected.isConnected) throw new CollabError(connected.message)
41  let result
42  try {
43    result = await $.mcp.call(connected.server, tool, args)
44  } catch (error) {
45    // Claude Code refusing the call (a permission rule, auto mode) is a failed call to show the
46    // person, not a fault in the plugin.
47    throw new CollabError(error instanceof Error ? error.message : String(error))
48  }
49  return answerOf(result)
50}
51
52/** Every thread in the person's inbox, page by page. */
53const fetchInbox = async ($: EngineInterface, includeArchived = false): Promise<Thread[]> => {
54  const threads: Thread[] = []
55  let cursor: string | undefined
56  do {
57    const page = await call($, 'check_inbox', { include_archived: includeArchived, ...(cursor && { cursor }) })
58    threads.push(...page.threads)
59    cursor = page.next_cursor
60  } while (cursor !== undefined)
61  return threads
62}
63
64// A thread id as check_inbox gives it. The server also reads other spellings of the same id
65// (uppercase, braces, no hyphens), which the guard would fail to match, so only this one is taken.
66const THREAD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
67const NOT_A_THREAD_ID = 'Give the thread id exactly as check_inbox gives it (lowercase, with hyphens).'
68
69/** A thread of the person's, archived or not, or undefined when they have no such thread. */
70const findThread = async ($: EngineInterface, threadId: string): Promise<Thread | undefined> =>
71  (await fetchInbox($, true)).find(t => t.thread_id === threadId)
72
73/**
74 * Files each unfiled thread under its suggested project, when that's a project opened on this
75 * machine; anything else stays a suggestion, so nothing is filed where the person never looks.
76 */
77const autoFile = async ($: EngineInterface, threads: Thread[], known: readonly string[]): Promise<Thread[]> => {
78  const filed: Thread[] = []
79  for (const thread of threads) {
80    const suggested = thread.suggested_project
81    if (thread.projects.length > 0 || suggested === null || !known.includes(suggested)) {
82      filed.push(thread)
83      continue
84    }
85    try {
86      await call($, 'set_projects', { thread_id: thread.thread_id, projects: [suggested] })
87      filed.push({ ...thread, projects: [suggested], suggested_project: null })
88    } catch (error) {
89      if (!(error instanceof CollabError)) throw error
90      filed.push(thread)
91    }
92  }
93  return filed
94}
95
96/** Checks the inbox once; see poll. */
97const pollOnce = async ($: EngineInterface) => {
98  const before = await read($, inbox)
99  const key = await here($)
100  let threads: Thread[]
101  try {
102    threads = await fetchInbox($)
103  } catch (error) {
104    if (!(error instanceof CollabError)) throw error
105    await update($, inbox, last => ({ ...last, error: error.message }))
106    $.ui.status(statusText(before.threads, key, error.message))
107    return
108  }
109  const { autoFile: isAutoFiling, known } = await read($, filing)
110  if (isAutoFiling) threads = await autoFile($, threads, known)
111  await update($, inbox, () => ({ threads, error: null, checked: true }))
112  $.ui.status(statusText(threads, key, null))
113  // The first check has nothing to compare with: what already waits is no news.
114  if (!before.checked) return
115  const fresh = arrivals(before.threads, threads)
116  for (const thread of fresh) $.ui.toast(toastText(thread))
117  const listened = await read($, listening)
118  const heard = fresh.map(t => t.thread_id).filter(id => listened.includes(id))
119  if (heard.length > 0) void $.prompt.submit({ text: listenPrompt(heard) })
120}
121
122let isPolling = false
123let isPollWanted = false
124
125/**
126 * Checks the inbox: updates the status entry, raises a toast for each thread with a new message
127 * addressed to the person, and hands replies in threads this session listens to to Claude. A
128 * check asked for while one runs runs after it, so the pane always ends up current.
129 */
130const poll = async ($: EngineInterface) => {
131  if (isPolling) {
132    isPollWanted = true
133    return
134  }
135  isPolling = true
136  try {
137    do {
138      isPollWanted = false
139      await pollOnce($)
140    } while (isPollWanted)
141  } finally {
142    isPolling = false
143  }
144}
145
146/** Checks the inbox from a timer, where nothing would hear a failure but the debug log. */
147const checkInbox = ($: EngineInterface) =>
148  poll($).catch(error => $.ui.log(`collab: inbox check failed: ${error}`, { to: 'debug' }))
149
150const loadArchived = async ($: EngineInterface) => {
151  const all = await fetchInbox($, true)
152  await update($, archived, () => all.filter(t => t.archived))
153}
154
155/** Checks the inbox after the person changed something, and the archived threads if shown. */
156const refresh = async ($: EngineInterface) => {
157  await poll($)
158  if ((await read($, archived)) !== null) await loadArchived($)
159}
160
161const startListening = ($: EngineInterface, threadId: string) =>
162  update($, listening, ids => (ids.includes(threadId) ? ids : [...ids, threadId]))
163
164const stopListening = ($: EngineInterface, threadId: string) => update($, listening, ids => ids.filter(id => id !== threadId))
165
166const COMMAND_HELP =
167  '/collab opens or closes the pane. /collab listen [part of a title] listens here for replies; ' +
168  '/collab unlisten [part of a title] stops.'
169
170/** The thread a title's words name, or what to tell the person when they name none or several. */
171const threadTitled = async ($: EngineInterface, words: string): Promise<Thread | string> => {
172  const matches = threadsTitled(await fetchInbox($, true), words)
173  if (matches.length === 1) return matches[0]!
174  if (matches.length === 0) return `No thread’s title contains “${words}”.`
175  return `Several threads match “${words}”: ${matches.map(t => `“${oneLine(t.title)}”`).join(', ')}. Give more of the title.`
176}
177
178/**
179 * Answers `/collab listen` and `/collab unlisten`. Listening is the person's to turn on: a bare
180 * listen means the thread Claude last sent to from this session, a bare unlisten every thread.
181 */
182const listenCommand = async ($: EngineInterface, isStarting: boolean, words: string, lastSent: string | undefined): Promise<string> => {
183  try {
184    if (!isStarting && words === '') {
185      await update($, listening, () => [])
186      return 'Stopped listening here.'
187    }
188    let chosen: Thread | string
189    if (words !== '') chosen = await threadTitled($, words)
190    else if (lastSent === undefined)
191      return 'Nothing sent from this session yet. Give part of the thread’s title (/collab listen retention), or press Listen here in /collab.'
192    else chosen = (await findThread($, lastSent)) ?? 'The thread this session last sent to is no longer in your inbox.'
193    if (typeof chosen === 'string') return chosen
194    const title = oneLine(chosen.title)
195    if (isStarting) {
196      await startListening($, chosen.thread_id)
197      return `Listening here for replies in “${title}”.`
198    }
199    if (!(await read($, listening)).includes(chosen.thread_id)) return `This session wasn’t listening to “${title}”.`
200    await stopListening($, chosen.thread_id)
201    return `Stopped listening here to “${title}”.`
202  } catch (error) {
203    if (error instanceof CollabError) return `Couldn't look up your threads: ${error.message}`
204    throw error
205  }
206}
207
208const THREAD_TOOLS = { markRead: 'mark_read', markUnread: 'mark_unread', archive: 'archive_thread', unarchive: 'unarchive_thread' }
209
210/** Reads more of the thread the pane shows, before or after what it has. */
211const page = async ($: EngineInterface, direction: 'before' | 'after') => {
212  const view = await read($, pane)
213  if (view.screen !== 'thread' || view.read === null) return
214  const shown = view.read
215  const edge = direction === 'before' ? shown.messages[0]?.id : shown.messages[shown.messages.length - 1]?.id
216  if (edge === undefined) return
217  const more: ThreadRead = await call($, 'read_thread', { thread_id: view.threadId, format: 'json', [direction]: edge })
218  const merged: ThreadRead =
219    direction === 'before'
220      ? { ...shown, messages: [...more.messages, ...shown.messages], earlier: more.earlier }
221      : { ...shown, messages: [...shown.messages, ...more.messages], later: more.later }
222  await update($, pane, v => (v.screen === 'thread' && v.threadId === view.threadId ? { ...v, read: merged } : v))
223}
224
225/** Carries out what the person pressed in the pane; a failure shows there. */
226const perform = async ($: EngineInterface, action: Action) => {
227  try {
228    switch (action.kind) {
229      case 'select':
230        await update($, pane, v =>
231          v.screen === 'list' ? { ...v, selected: v.selected === action.threadId ? null : action.threadId, error: null } : v,
232        )
233        return
234      case 'expand': {
235        const view = await read($, pane)
236        if (view.screen !== 'list') return
237        const isOpening = !view.expanded.includes(action.group)
238        const expanded = isOpening ? [...view.expanded, action.group] : view.expanded.filter(g => g !== action.group)
239        await update($, pane, v => (v.screen === 'list' ? { ...v, expanded } : v))
240        if (isOpening && action.group === 'archived') await loadArchived($)
241        return
242      }
243      case 'view': {
244        const threadId = action.threadId
245        await update($, pane, (): PaneView => ({ screen: 'thread', threadId, read: null, error: null }))
246        const shown: ThreadRead = await call($, 'read_thread', { thread_id: threadId, format: 'json' })
247        await update($, pane, v => (v.screen === 'thread' && v.threadId === threadId ? { ...v, read: shown } : v))
248        // Viewing marks the thread read, as Claude reading it does.
249        await refresh($)
250        return
251      }
252      case 'back':
253        await update($, pane, () => LIST)
254        return
255      case 'earlier':
256        await page($, 'before')
257        return
258      case 'later':
259        await page($, 'after')
260        return
261      case 'readWithClaude':
262        void $.prompt.submit({ text: readPrompt(action.threadId) })
263        return
264      case 'setProjects':
265        await call($, 'set_projects', { thread_id: action.threadId, projects: action.projects })
266        await refresh($)
267        return
268      case 'markRead':
269      case 'markUnread':
270      case 'archive':
271      case 'unarchive':
272        await call($, THREAD_TOOLS[action.kind], { thread_id: action.threadId })
273        await refresh($)
274        return
275      case 'listen':
276        if ((await read($, listening)).includes(action.threadId)) await stopListening($, action.threadId)
277        else await startListening($, action.threadId)
278        return
279      case 'autoFile':
280        await update($, filing, s => ({ ...s, autoFile: action.on }))
281        await $.store.set('autoFile', action.on)
282        return
283    }
284  } catch (error) {
285    if (!(error instanceof CollabError)) throw error
286    const message = error.message
287    await update($, pane, v => ({ ...v, error: message }))
288  }
289}
290
291/**
292 * The thread a send went to, or undefined when it didn't go; unless this session listens to that
293 * thread, a toast says how to.
294 */
295const noteSend = async ($: EngineInterface, e: { title?: unknown }, sent: ToolCallResult): Promise<string | undefined> => {
296  if (sent.deny !== undefined || sent.isError === true || sent.text === undefined) return undefined
297  const threadId = JSON.parse(sent.text)?.thread_id
298  if (typeof threadId !== 'string' || !THREAD_ID.test(threadId)) return undefined
299  if (!(await read($, listening)).includes(threadId)) {
300    const title = typeof e.title === 'string' ? e.title : (await findThread($, threadId))?.title
301    $.ui.toast(sentToast(title === undefined ? undefined : oneLine(title)))
302  }
303  return threadId
304}
305
306/** Shows the commands that remove the old server entry and status line, when either is found. */
307const checkLeftovers = async ($: EngineInterface) => {
308  const tools = (await $.tool.list()).map(t => t.name)
309  const configDir = (await $.env.get('CLAUDE_CONFIG_DIR')) ?? `${await $.env.get('HOME')}/.claude`
310  const settingsText = await $.fs.read(`${configDir}/settings.json`).catch(() => '')
311  const text = leftoverText(hasOldServer(tools), hasOldStatusLine(String(settingsText)))
312  if (text !== undefined) $.ui.log(text)
313}
314
315export const register: Register = on => {
316  // The session section as Claude last received it in this conversation.
317  let carriedSection: string | undefined
318  // The thread Claude last started or sent to from this session, for a bare /collab listen.
319  let lastSent: string | undefined
320
321  on('session.start', async ($, e, next) => {
322    carriedSection = undefined
323    await $.command.register({
324      name: 'collab',
325      description: 'Open or close the collab pane; /collab listen [title] hears replies here, /collab unlisten stops',
326    })
327    // Remembers that this project is opened on this machine, for filing and auto-filing.
328    const key = await here($)
329    const stored = await $.store.get('projects')
330    const known = Array.isArray(stored) ? stored.filter((p): p is string => typeof p === 'string') : []
331    if (!known.includes(key)) known.push(key)
332    await $.store.set('projects', known)
333    const isAutoFiling = (await $.store.get('autoFile')) === true
334    await update($, filing, () => ({ autoFile: isAutoFiling, known }))
335    void checkInbox($)
336    $.clock.after(LEFTOVER_CHECK_MS, () =>
337      void checkLeftovers($).catch(error => $.ui.log(`collab: leftover check failed: ${error}`, { to: 'debug' })),
338    )
339    $.clock.every(POLL_MS, () => void checkInbox($))
340    return next(e)
341  })
342
343  for (const tool of ['start_thread', 'send_message']) {
344    on('tool.call', { tool: `${COLLAB}${tool}` }, async ($, e, next) => {
345      // A send whose project can't be worked out still goes, unfiled.
346      const sentFrom = await here($).catch(() => undefined)
347      const sent = await next(sentFrom === undefined ? e : { ...e, sent_from: sentFrom })
348      // Nothing after the send may fail the hook: the message has gone, and a failed hook would
349      // report it as not sent.
350      const threadId = await noteSend($, e as { title?: unknown }, sent).catch(error => {
351        $.ui.log(`collab: after the send: ${error}`, { to: 'debug' })
352        return undefined
353      })
354      if (threadId !== undefined) lastSent = threadId
355      return sent
356    })
357  }
358
359  // Keeps a session from reading threads filed under other projects: reading marks a thread
360  // read everywhere, so it would stop waiting where it belongs.
361  on('tool.call', { tool: `${COLLAB}read_thread` }, async ($, e, next) => {
362    const { thread_id, format } = e as { thread_id?: unknown; format?: unknown }
363    if (format === 'json') {
364      return {
365        deny:
366          'Read threads with the default text format: it tags what other people wrote as ' +
367          "untrusted data. format \"json\" is for the collab plugin's pane.",
368      }
369    }
370    if (typeof thread_id !== 'string' || !THREAD_ID.test(thread_id)) return { deny: NOT_A_THREAD_ID }
371    let found: Thread | undefined
372    try {
373      found = await findThread($, thread_id)
374    } catch (error) {
375      if (error instanceof CollabError) return { deny: `collab: couldn't check where this thread is filed: ${error.message}` }
376      throw error
377    }
378    const key = await here($)
379    if (found === undefined || found.projects.length === 0 || found.projects.includes(key)) return next(e)
380    return {
381      deny:
382        `Not read: your person filed this thread under ${found.projects.map(projectName).join(', ')}, ` +
383        `not this session's project (${projectName(key)}). Tell them which project it belongs to, ` +
384        'and offer to move it here, or to file it here as well, with set_projects if they want it read here.',
385    }
386  }).catch(() => ({ deny: "collab: couldn't check where this thread is filed, so it wasn't read." }))
387
388  on('command.run', { command: 'collab' }, async ($, e) => {
389    const args = e.args.trim()
390    const [word = ''] = args.split(/\s+/)
391    if (word === 'listen' || word === 'unlisten') {
392      return { text: await listenCommand($, word === 'listen', args.slice(word.length).trim(), lastSent) }
393    }
394    if (word !== '') return { text: COMMAND_HELP }
395    const isOpen = (await $.ui.panes()).some(p => p.id === PANE)
396    if (isOpen) await $.ui.close({ id: PANE })
397    else await $.ui.open({ id: PANE, title: 'collab', closeOnEscape: true })
398    return {}
399  })
400
401  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
402    const elements = $.ui.resolve(e) as PaneElements
403    const model = {
404      inbox: await read($, inbox),
405      archived: await read($, archived),
406      here: await here($),
407      filing: await read($, filing),
408      listening: await read($, listening),
409      now: await $.clock.now(),
410    }
411    const view = await read($, pane)
412    const act = (action: Action) => void perform($, action)
413    return view.screen === 'list' ? listView(elements, model, view, act) : threadView(elements, model, view, act)
414  })
415
416  // The session section reaches Claude as context beside the person's prompt: in Team and
417  // Enterprise organizations, Claude Code's security default skips a user-installed plugin's
418  // prompt.compose and prompt.context hooks. It rides along when it changes, and again once the
419  // conversation starts over or is compacted.
420  on('prompt.submit', async ($, e, next) => {
421    const text = sessionSection(await here($), await read($, listening))
422    if (text === carriedSection) return next(e)
423    const entered = await next({ ...e, context: [...(e.context ?? []), text] })
424    if (!('drop' in entered)) carriedSection = text
425    return entered
426  })
427
428  on('session.compact', async ($, e, next) => {
429    const compacted = await next(e)
430    if (e.trigger !== 'precompute' && e.agentId === undefined && !('skip' in compacted)) carriedSection = undefined
431    return compacted
432  })
433}
434

1// ABOUTME: What the plugin makes of the inbox: the status entry, which threads gained a message for
2// ABOUTME: the person, which threads /collab listen means, and the words for toasts and prompts.
3
4import type { Thread } from '../types'
5import { projectName } from './projects'
6
7// Other projects the status entry names; the rest are counted together, to keep it short.
8const NAMED_PROJECTS = 2
9
10/**
11 * `4 waiting: 1 here · 1 lunch-menu · 1 elsewhere · 1 unfiled`, with the failure when the
12 * last check failed; none when quiet. Each thread counts once: here when filed here, else under
13 * the first project it's filed in. Other projects are named busiest first, ties going to the most
14 * recently active, since check_inbox lists those first. Claude Code shows it under the plugin's name.
15 */
16export const statusText = (threads: readonly Thread[], here: string, error: string | null): string | undefined => {
17  const waiting = threads.filter(t => t.waiting_on_you)
18  const waitingHere = waiting.filter(t => t.projects.includes(here)).length
19  const unfiled = waiting.filter(t => t.projects.length === 0).length
20  const others = new Map<string, number>()
21  for (const thread of waiting) {
22    const project = thread.projects[0]
23    if (project !== undefined && !thread.projects.includes(here)) others.set(project, (others.get(project) ?? 0) + 1)
24  }
25  const busiest = [...others].sort(([, a], [, b]) => b - a)
26  const named = busiest.slice(0, NAMED_PROJECTS)
27  const elsewhere = busiest.slice(NAMED_PROJECTS).reduce((sum, [, count]) => sum + count, 0)
28  const places = [
29    ...(waitingHere > 0 ? [`${waitingHere} here`] : []),
30    ...named.map(([project, count]) => `${count} ${projectName(project)}`),
31    ...(elsewhere > 0 ? [`${elsewhere} elsewhere`] : []),
32    ...(unfiled > 0 ? [`${unfiled} unfiled`] : []),
33  ]
34  const parts = waiting.length === 0 ? [] : [`${waiting.length} waiting: ${places.join(' · ')}`]
35  if (error !== null) parts.push(`inbox check failed: ${error}`)
36  return parts.length === 0 ? undefined : parts.join(' · ')
37}
38
39/** The threads with more messages addressed to the person than at the last check. */
40export const arrivals = (before: readonly Thread[], after: readonly Thread[]): Thread[] => {
41  const had = new Map(before.map(t => [t.thread_id, t.unread_to_you]))
42  return after.filter(t => t.unread_to_you > (had.get(t.thread_id) ?? 0))
43}
44
45/** How people are named in a line: their address without the domain. */
46export const personName = (email: string): string => email.split('@')[0] ?? email
47
48export const toastText = (thread: Thread): string =>
49  `${thread.latest_from === null ? 'new message' : personName(thread.latest_from)} in “${thread.title}” · /collab to open`
50
51/** The toast after Claude sends, saying how to hear the reply here. */
52export const sentToast = (title: string | undefined): string =>
53  `Sent${title === undefined ? '' : ` to “${title}”`} · /collab listen to hear the reply here`
54
55/** The threads `/collab listen <words>` means: those titled exactly that, else those whose title contains it, any case. */
56export const threadsTitled = (threads: readonly Thread[], words: string): Thread[] => {
57  const wanted = words.trim().toLowerCase()
58  const exact = threads.filter(t => t.title.trim().toLowerCase() === wanted)
59  return exact.length > 0 ? exact : threads.filter(t => t.title.toLowerCase().includes(wanted))
60}
61
62/**
63 * The prompt that hands Claude replies in threads this session listens to. It names threads by
64 * id only: a plugin's prompt reads as the person's request, and titles are other people's words.
65 */
66export const listenPrompt = (threadIds: readonly string[]): string =>
67  `A reply addressed to me arrived in the collab ${threadIds.length === 1 ? 'thread' : 'threads'} ` +
68  `this session listens to: ${threadIds.join(', ')}. Read ${threadIds.length === 1 ? 'it' : 'each'} ` +
69  'with read_thread and summarize it.'
70
71/** The prompt "Read with Claude" submits; by id only, as listenPrompt. */
72export const readPrompt = (threadId: string): string =>
73  `Read the collab thread ${threadId} with read_thread and summarize it.`
74

1// ABOUTME: Recognizes what the plugin replaces — the old collab server entry and the old status
2// ABOUTME: line wrapper — and words the commands that remove them.
3
4// The old server's tools, as Claude Code named them.
5const OLD_SERVER_TOOL = /^mcp__collab__(check_inbox|send_message|start_thread|read_thread)$/
6
7export const hasOldServer = (toolNames: readonly string[]): boolean => toolNames.some(name => OLD_SERVER_TOOL.test(name))
8
9/** Whether a settings file's status line is the old collab wrapper (~/.config/collab/statusline.sh). */
10export const hasOldStatusLine = (settingsText: string): boolean => {
11  try {
12    const command = JSON.parse(settingsText)?.statusLine?.command
13    return typeof command === 'string' && command.includes('/.config/collab/statusline.sh')
14  } catch {
15    return false
16  }
17}
18
19/** One transcript line with the commands to run, or undefined when nothing is left over. */
20export const leftoverText = (oldServer: boolean, oldStatusLine: boolean): string | undefined => {
21  const commands = [
22    ...(oldServer ? ['claude mcp remove collab -s user'] : []),
23    ...(oldStatusLine ? ['python3 "$HOME/.config/collab/install.py" uninstall'] : []),
24  ]
25  if (commands.length === 0) return undefined
26  return `collab: the collab plugin replaces your earlier collab setup. Remove it by running: ${commands.join(' && ')}`
27}
28

1// ABOUTME: What the collab pane shows: threads grouped by project, each row's parts, a color per
2// ABOUTME: author, message bodies made safe to draw, and the choices for filing a thread.
3
4import type { Thread } from '../types'
5import { personName } from './inbox'
6import { projectName } from './projects'
7
8export type Group = { id: string; title: string; threads: Thread[]; waiting: number }
9
10export type Choice = { value: string; label: string }
11
12// What a surface refuses or someone could hide text with: control characters, and the
13// invisible and direction-changing format characters.
14const HIDDEN = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/g
15const MARKDOWN_MAX = 10_000
16const CUT_NOTE = '\n\n… (cut here: read it with Claude for the rest)'
17
18const byWaitingThenLatest = (a: Thread, b: Thread) =>
19  Number(b.waiting_on_you) - Number(a.waiting_on_you) || b.last_activity.localeCompare(a.last_activity)
20
21const group = (id: string, title: string, threads: Thread[]): Group => ({
22  id,
23  title,
24  threads: [...threads].sort(byWaitingThenLatest),
25  waiting: threads.filter(t => t.waiting_on_you).length,
26})
27
28/**
29 * The pane's groups: this project, unfiled, each other project the person filed threads under
30 * (a thread filed under several shows in each), then archived, whose threads load on demand.
31 */
32export const groupThreads = (threads: readonly Thread[], archived: readonly Thread[] | null, here: string): Group[] => {
33  const others = [...new Set(threads.flatMap(t => t.projects))]
34    .filter(key => key !== here)
35    .sort((a, b) => projectName(a).localeCompare(projectName(b)))
36  return [
37    group('here', 'This project', threads.filter(t => t.projects.includes(here))),
38    group('unfiled', 'Unfiled', threads.filter(t => t.projects.length === 0)),
39    ...others.map(key => group(`project:${key}`, projectName(key), threads.filter(t => t.projects.includes(key)))),
40    group('archived', 'Archived', [...(archived ?? [])]),
41  ]
42}
43
44/** Other people's text as one plain line: nothing hidden, no line breaks. */
45export const oneLine = (text: string): string =>
46  text.replace(HIDDEN, ' ').replace(/\s+/g, ' ').trim()
47
48const pad = (n: number) => String(n).padStart(2, '0')
49const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
50const DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
51
52/** When something happened, in local time: the time today, the weekday this week, else the date. */
53export const when = (iso: string, now: number): string => {
54  const at = new Date(iso)
55  const today = new Date(now)
56  if (at.toDateString() === today.toDateString()) return `${at.getHours()}:${pad(at.getMinutes())}`
57  if (now - at.getTime() < 6 * 24 * 3600_000) return DAYS[at.getDay()] ?? ''
58  return `${MONTHS[at.getMonth()]} ${at.getDate()}`
59}
60
61/** What a thread's row shows beside its mark: the title, who wrote last, what's new, and when. */
62export type Row = { title: string; by: string | null; count: string | null; time: string }
63
64export const rowParts = (thread: Thread, now: number): Row => ({
65  title: oneLine(thread.title),
66  by: thread.latest_from === null ? null : personName(thread.latest_from),
67  count: thread.unread > 0 ? `${thread.unread} new` : null,
68  time: when(thread.last_activity, now),
69})
70
71/** Theme colors for telling people apart in a thread; they follow the person's light or dark theme. */
72export const AUTHOR_COLORS = ['suggestion', 'success', 'merged', 'claude', 'permission', 'planMode'] as const
73
74/** A person's color in a thread, by their place among its participants. */
75export const authorColor = (author: string, participants: readonly string[]): (typeof AUTHOR_COLORS)[number] => {
76  const place = participants.indexOf(author)
77  const index = place >= 0 ? place : participants.length
78  return AUTHOR_COLORS[index % AUTHOR_COLORS.length]!
79}
80
81/**
82 * A message body as markdown the pane can draw: nothing hidden, and cut to what fits. No link can
83 * form, since a link's text can disguise where it goes: brackets, angle brackets and backslashes
84 * are escaped, so a link shows as written, its real address included.
85 */
86export const bodyMarkdown = (body: string): string => {
87  const shown = body.replace(HIDDEN, '').replace(/[\\[\]<]/g, '\\$&')
88  return shown.length <= MARKDOWN_MAX ? shown : shown.slice(0, MARKDOWN_MAX - CUT_NOTE.length) + CUT_NOTE
89}
90
91/**
92 * Where a thread can be filed: projects known on this machine, then ones seen in the inbox, then
93 * the projects it's filed under to remove. Names, or keys where two projects share a name.
94 */
95export const fileChoices = (thread: Thread, known: readonly string[], inbox: readonly Thread[]): Choice[] => {
96  const seen = [...known, ...inbox.flatMap(t => t.projects), ...inbox.flatMap(t => t.suggested_project ?? [])]
97  const toAdd = [...new Set(seen)].filter(key => !thread.projects.includes(key))
98  const all = [...toAdd, ...thread.projects]
99  const label = (key: string) =>
100    all.filter(other => projectName(other) === projectName(key)).length > 1 ? key : projectName(key)
101  return [
102    ...toAdd.map(key => ({ value: `add:${key}`, label: `File in ${label(key)}` })),
103    ...thread.projects.map(key => ({ value: `remove:${key}`, label: `Remove from ${label(key)}` })),
104  ]
105}
106

1// ABOUTME: Project keys: which project a session is in, as a key the server stores and shares,
2// ABOUTME: and the short name people see for one.
3
4import type { SessionRepo } from 'claude-code'
5
6// The server's own check on git keys (migration 006): recipients see them, so only a bare,
7// normalized host/path ever leaves this machine.
8const GIT_KEY = /^git:[a-z0-9.-]+(:[0-9]+)?(\/[a-z0-9._~-]+)+$/
9const KEY_MAX = 500
10
11const URL_REMOTE = /^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]*@)?([^/]*)(\/.*)?$/i
12const SCP_REMOTE = /^(?:[^@/:]+@)?([^/:]+):(.*)$/
13
14/**
15 * The key everyone's copy of a repository shares, from its origin remote: the scheme, user and
16 * trailing `.git` and `/` dropped, scp form (`host:path`) made `host/path`, all lowercase. Null for
17 * a remote with no host, such as a local path, or one that doesn't reduce to a plain host/path.
18 */
19const gitKey = (remote: string): string | null => {
20  const text = remote.trim()
21  const url = URL_REMOTE.exec(text)
22  const scp = url ? null : SCP_REMOTE.exec(text)
23  const [host, path] = url ? [url[1], url[2] ?? ''] : scp ? [scp[1], `/${scp[2]}`] : [null, '']
24  if (host === null) return null
25  const bare = path.replace(/\/+/g, '/').replace(/\/$/, '').replace(/\.git$/i, '')
26  const key = `git:${host}${bare}`.toLowerCase()
27  return GIT_KEY.test(key) && key.length <= KEY_MAX ? key : null
28}
29
30/**
31 * The session's project key: `git:` and the normalized origin remote, or else `dir:` and the
32 * repository's main working tree (the same from any worktree), or else the session's root.
33 */
34export const projectKey = (repo: Pick<SessionRepo, 'root' | 'remote'> | null, root: string): string => {
35  if (repo === null) return `dir:${root}`
36  return (repo.remote === null ? null : gitKey(repo.remote)) ?? `dir:${repo.root}`
37}
38
39/** What people see for a project: the repository's name, or the folder's. */
40export const projectName = (key: string): string => {
41  const path = key.slice(key.indexOf(':') + 1)
42  return path.split('/').filter(Boolean).pop() ?? '/'
43}
44

1// ABOUTME: The collab plugin's notes to Claude for this session: this session's project, and how to
2// ABOUTME: handle threads filed here, unfiled, and elsewhere, and listening for replies.
3
4import { projectName } from './projects'
5
6export const sessionSection = (key: string, listening: readonly string[]): string => `\
7# collab in this session
8This session's collab project is "${projectName(key)}", project key \`${key}\`. Use this key as \
9given; never run git to work it out. Each check_inbox row lists the projects your person filed \
10the thread under (\`projects\`, empty when unfiled) and, for an unfiled one, \`suggested_project\`; \
11take other projects' keys from there.
12
13- **What's waiting:** when your person asks, call check_inbox and group the threads waiting on \
14them: filed here, unfiled, and filed under other projects (by name). Read and summarize the \
15waiting ones filed here. List unfiled ones with their suggested project and ask before reading \
16them, unless one clearly belongs here. Never read ones filed only under other projects; say where \
17they belong.
18- **Filed elsewhere:** read_thread is refused for a thread filed only under other projects. Say \
19which project it belongs to, and offer to move it here, or to file it here as well, with \
20set_projects (it replaces the whole list) if your person wants it read here.
21- **Filing:** after handling an unfiled thread that clearly belongs to this project, offer in one \
22line to file it here with set_projects.
23- **Listening:** only your person turns it on, with /collab listen or Listen here in the /collab \
24pane; don't offer it after sending, since the collab plugin says how. If they ask you to listen \
25for a reply, tell them to type /collab listen. When a reply arrives in a thread this session \
26listens to, the collab plugin asks you to read and summarize it.
27
28This session ${listening.length === 0 ? 'listens to no threads' : `listens to threads ${listening.join(', ')}`}.`
29

1// ABOUTME: Reading the collab server's answers: each tool answers JSON in a text block, or an
2// ABOUTME: error result whose text says why.
3
4import type { McpToolResult } from 'claude-code'
5
6/** The server refused or failed the call; the message says why. */
7export class CollabError extends Error {}
8
9/** A tool's JSON answer; throws CollabError for an error result. */
10export const answerOf = (result: McpToolResult): any => {
11  const text = result.content.map(block => block.text ?? '').join('')
12  if (result.isError) throw new CollabError(text.replace(/^Error: /, ''))
13  return JSON.parse(text)
14}
15

1// ABOUTME: Draws the collab pane: the list of threads by project with each thread's actions, and
2// ABOUTME: one thread's messages. Every button answers with an Action for the hooks to carry out.
3
4import type { BoxProps, ButtonProps, ElementConstructor, MarkdownProps, SelectProps, TextProps } from 'claude-code'
5
6import type { Inbox, Message, PaneView, Filing, Thread, ThreadRead } from '../types'
7import { personName } from './inbox'
8import { authorColor, bodyMarkdown, fileChoices, groupThreads, oneLine, rowParts, when } from './pane'
9import { projectName } from './projects'
10
11/** The elements the pane draws with; Select is missing on surfaces that have none. */
12export type PaneElements = {
13  Box: ElementConstructor<BoxProps>
14  Text: ElementConstructor<TextProps>
15  Button: ElementConstructor<ButtonProps>
16  Markdown: ElementConstructor<MarkdownProps>
17  Select?: ElementConstructor<SelectProps>
18}
19
20export type Action =
21  | { kind: 'select'; threadId: string }
22  | { kind: 'expand'; group: string }
23  | { kind: 'view'; threadId: string }
24  | { kind: 'back' }
25  | { kind: 'earlier' }
26  | { kind: 'later' }
27  | { kind: 'readWithClaude'; threadId: string }
28  | { kind: 'setProjects'; threadId: string; projects: string[] }
29  | { kind: 'markRead' | 'markUnread' | 'archive' | 'unarchive'; threadId: string }
30  | { kind: 'listen'; threadId: string }
31  | { kind: 'autoFile'; on: boolean }
32
33export type Model = {
34  inbox: Inbox
35  archived: Thread[] | null
36  here: string
37  filing: Filing
38  listening: string[]
39  now: number
40}
41
42type Act = (action: Action) => void
43
44// Groups the person opens to see; this project and unfiled are always open.
45const COLLAPSIBLE = (id: string) => id !== 'here' && id !== 'unfiled'
46
47const isReadableHere = (thread: Thread, here: string) => thread.projects.length === 0 || thread.projects.includes(here)
48
49const people = (emails: readonly string[]) => emails.map(personName).join(', ')
50
51const addressedTo = (to: string) =>
52  to === 'everyone' || to.startsWith('nobody') ? to : people(to.split(', '))
53
54/** The buttons for one thread, in the list or its own view. */
55const threadActions = (E: PaneElements, thread: Thread, model: Model, act: Act, inList: boolean) => {
56  const { Box, Button } = E
57  const id = thread.thread_id
58  const isListening = model.listening.includes(id)
59  const isHereOnly = thread.projects.length === 1 && thread.projects[0] === model.here
60  const choices = fileChoices(thread, model.filing.known, [...model.inbox.threads, ...(model.archived ?? [])])
61  return (
62    <Box flexDirection="row" flexWrap="wrap" columnGap={1} paddingLeft={2}>
63      {inList && <Button key={`view:${id}`} label="View" onPress={() => act({ kind: 'view', threadId: id })} />}
64      {isReadableHere(thread, model.here) && (
65        <Button key={`claude:${id}`} label="Read with Claude" onPress={() => act({ kind: 'readWithClaude', threadId: id })} />
66      )}
67      {!isHereOnly && (
68        <Button key={`here:${id}`} label="Move here" onPress={() => act({ kind: 'setProjects', threadId: id, projects: [model.here] })} />
69      )}
70      {inList && E.Select !== undefined && choices.length > 0 && (
71        <E.Select
72          key={`file:${id}`}
73          label="File in…"
74          options={choices}
75          onSelect={value => {
76            const [how, ...rest] = value.split(':')
77            const key = rest.join(':')
78            const projects = how === 'add' ? [...thread.projects, key] : thread.projects.filter(p => p !== key)
79            act({ kind: 'setProjects', threadId: id, projects })
80          }}
81        />
82      )}
83      {thread.waiting_on_you ? (
84        <Button key={`read:${id}`} label="Mark read" onPress={() => act({ kind: 'markRead', threadId: id })} />
85      ) : (
86        <Button key={`unread:${id}`} label="Mark unread" onPress={() => act({ kind: 'markUnread', threadId: id })} />
87      )}
88      {thread.archived ? (
89        <Button key={`unarchive:${id}`} label="Unarchive" onPress={() => act({ kind: 'unarchive', threadId: id })} />
90      ) : (
91        <Button key={`archive:${id}`} label="Archive" onPress={() => act({ kind: 'archive', threadId: id })} />
92      )}
93      <Button
94        key={`listen:${id}`}
95        label={isListening ? 'Stop listening' : 'Listen here'}
96        onPress={() => act({ kind: 'listen', threadId: id })}
97      />
98    </Box>
99  )
100}
101
102export const listView = (E: PaneElements, model: Model, view: Extract<PaneView, { screen: 'list' }>, act: Act) => {
103  const { Box, Text, Button } = E
104  const waiting = model.inbox.threads.filter(t => t.waiting_on_you).length
105  const error = view.error ?? model.inbox.error
106  return (
107    <Box flexDirection="column">
108      <Text bold>
109        <Text color="claude">collab</Text>
110        {' · '}
111        {waiting === 0 ? <Text dimColor>nothing waiting</Text> : <Text color="warning">{`${waiting} waiting`}</Text>}
112        <Text dimColor> · here: {projectName(model.here)}</Text>
113      </Text>
114      {error !== null && <Text color="error">collab: {oneLine(error)}</Text>}
115      <Button
116        key="autofile"
117        plain
118        dimColor
119        label={`Auto-file into projects opened here: ${model.filing.autoFile ? 'on' : 'off'}`}
120        onPress={() => act({ kind: 'autoFile', on: !model.filing.autoFile })}
121      />
122      {groupThreads(model.inbox.threads, model.archived, model.here).map(group => {
123        const isOpen = !COLLAPSIBLE(group.id) || view.expanded.includes(group.id)
124        const count = group.id === 'archived' && model.archived === null ? '' : ` · ${group.waiting > 0 ? `${group.waiting} waiting` : group.threads.length}`
125        return (
126          <Box key={`group-box:${group.id}`} flexDirection="column" marginTop={1}>
127            {COLLAPSIBLE(group.id) ? (
128              <Button key={`group:${group.id}`} plain label={`${isOpen ? '▾' : '▸'} ${group.title}${count}`} onPress={() => act({ kind: 'expand', group: group.id })} />
129            ) : (
130              <Text bold color="suggestion">
131                {group.title} · {group.threads.length}
132              </Text>
133            )}
134            {isOpen && (
135              <Box key={`threads:${group.id}`} flexDirection="column" rowGap={1}>
136              {group.threads.map(thread => {
137                const id = thread.thread_id
138                const row = rowParts(thread, model.now)
139                const isChosen = view.selected === id
140                return (
141                  <Box
142                    key={isChosen ? `chosen:${id}` : `row:${group.id}:${id}`}
143                    flexDirection="column"
144                    {...(isChosen && { borderStyle: 'round', borderColor: 'suggestion' })}
145                  >
146                    {/* The title has a line to itself and the rest one line under it, each wrapping
147                        whole: pieces side by side squeeze into columns a few letters wide. */}
148                    <Box key={`title:${id}`} flexDirection="row" columnGap={1}>
149                      <Box flexShrink={0}>
150                        <Text color={thread.waiting_on_you ? 'warning' : 'subtle'}>{thread.waiting_on_you ? '●' : '○'}</Text>
151                      </Box>
152                      <Button
153                        key={`thread:${id}`}
154                        plain
155                        label={row.title}
156                        onPress={() => act({ kind: 'select', threadId: id })}
157                      />
158                    </Box>
159                    <Box key={`details:${id}`} paddingLeft={2}>
160                      <Text>
161                        {row.by !== null && <Text dimColor>{`${row.by} · `}</Text>}
162                        {row.count !== null && (thread.waiting_on_you ? <Text color="warning">{row.count}</Text> : <Text dimColor>{row.count}</Text>)}
163                        <Text dimColor>{`${row.count !== null ? ' · ' : ''}${row.time}`}</Text>
164                      </Text>
165                    </Box>
166                    {thread.projects.length === 0 && thread.suggested_project !== null && (
167                      <Box flexDirection="row" flexWrap="wrap" columnGap={1} paddingLeft={2}>
168                        <Text dimColor>suggested:</Text>
169                        <Text color="suggestion">{projectName(thread.suggested_project)}</Text>
170                        <Button
171                          key={`suggest:${id}`}
172                          label="File there"
173                          onPress={() => act({ kind: 'setProjects', threadId: id, projects: [thread.suggested_project!] })}
174                        />
175                      </Box>
176                    )}
177                    {isChosen && threadActions(E, thread, model, act, true)}
178                  </Box>
179                )
180              })}
181              </Box>
182            )}
183          </Box>
184        )
185      })}
186    </Box>
187  )
188}
189
190const messageView = (E: PaneElements, message: Message, participants: readonly string[], now: number) => {
191  const { Box, Text, Markdown } = E
192  if (message.kind !== 'message') {
193    return (
194      <Text key={`message:${message.id}`} dimColor>
195        {when(message.at, now)} · {oneLine(message.body)}
196      </Text>
197    )
198  }
199  const color = authorColor(message.author, participants)
200  return (
201    <Box
202      key={`message:${message.id}`}
203      flexDirection="column"
204      marginTop={1}
205      paddingX={1}
206      borderStyle="round"
207      borderColor={color}
208      borderDimColor={!message.unread}
209    >
210      <Box flexDirection="row" columnGap={1}>
211        <Text bold color={color}>{personName(message.author)}</Text>
212        <Text dimColor>
213          → {addressedTo(message.to ?? '')} · {when(message.at, now)}
214        </Text>
215        {message.unread && <Text bold color="warning">new</Text>}
216      </Box>
217      {message.deleted ? <Text dimColor>(deleted)</Text> : <Markdown text={bodyMarkdown(message.body)} />}
218    </Box>
219  )
220}
221
222export const threadView = (E: PaneElements, model: Model, view: Extract<PaneView, { screen: 'thread' }>, act: Act) => {
223  const { Box, Text, Button } = E
224  const thread = [...model.inbox.threads, ...(model.archived ?? [])].find(t => t.thread_id === view.threadId)
225  const read: ThreadRead | null = view.read
226  return (
227    <Box flexDirection="column">
228      <Box flexDirection="row" flexWrap="wrap" columnGap={1}>
229        <Button key="back" label="Back" onPress={() => act({ kind: 'back' })} />
230        {thread !== undefined && threadActions(E, thread, model, act, false)}
231      </Box>
232      {view.error !== null && <Text color="error">collab: {oneLine(view.error)}</Text>}
233      {read === null ? (
234        view.error === null && <Text dimColor>Loading…</Text>
235      ) : (
236        <Box flexDirection="column" marginTop={1}>
237          <Text bold>{oneLine(read.title)}</Text>
238          <Text dimColor>with {people(read.participants)}</Text>
239          {read.earlier > 0 && <Button key="earlier" plain label={`Earlier messages (${read.earlier})`} onPress={() => act({ kind: 'earlier' })} />}
240          {read.messages.map(message => messageView(E, message, read.participants, model.now))}
241          {read.later > 0 && <Button key="later" plain label={`Later messages (${read.later})`} onPress={() => act({ kind: 'later' })} />}
242        </Box>
243      )}
244    </Box>
245  )
246}
247

1// ABOUTME: The collab plugin's state contract: the session's inbox, the threads it listens to,
2// ABOUTME: and what the pane shows, declared under the plugin's name in PluginState.
3
4/** One row of check_inbox, as the server returns it. */
5export type Thread = {
6  thread_id: string
7  title: string
8  created_by: string
9  participants: string[]
10  unread: number
11  unread_to_you: number
12  waiting_on_you: boolean
13  last_activity: string
14  archived: boolean
15  marked_unread: boolean
16  projects: string[]
17  suggested_project: string | null
18  latest_from: string | null
19}
20
21/**
22 * The latest inbox check: the person's threads (archived ones left out), why the last check
23 * failed if it did, and whether any check has succeeded yet.
24 */
25export type Inbox = { threads: Thread[]; error: string | null; checked: boolean }
26
27/** One message or membership change in read_thread's JSON form. */
28export type Message = {
29  id: number
30  kind: string
31  author: string
32  to: string | null
33  reply_to: number | null
34  at: string
35  unread: boolean
36  deleted: boolean
37  body: string
38}
39
40/** read_thread's JSON form: the thread and a run of its messages, with how many lie either side. */
41export type ThreadRead = {
42  thread_id: string
43  title: string
44  created_by: string
45  participants: string[]
46  messages: Message[]
47  earlier: number
48  later: number
49}
50
51/**
52 * What the pane shows: the list (which thread's actions are open, which collapsed groups are
53 * open) or one thread; with the last action's failure, if it failed.
54 */
55export type PaneView =
56  | { screen: 'list'; selected: string | null; expanded: string[]; error: string | null }
57  | { screen: 'thread'; threadId: string; read: ThreadRead | null; error: string | null }
58
59/** This machine's filing settings: whether to auto-file, and the projects opened here. */
60export type Filing = { autoFile: boolean; known: string[] }
61
62declare module 'claude-code' {
63  interface PluginState {
64    collab: {
65      inbox: Inbox
66      listening: string[]
67      archived: Thread[] | null
68      pane: PaneView
69      filing: Filing
70    }
71  }
72}
73