work-session

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface as $, Register } from 'claude-code'
3
4import type { Kickoff, Title, Wrap } from '../types'
5import {
6  cleanTitle,
7  commandName,
8  hasCommand,
9  isFreshStart,
10  kickoffMode,
11  startContext,
12  TITLE_TOOL_DESCRIPTION,
13  wrapReason,
14} from './session'
15import type { KickoffMode } from './session'
16
17const PLUGIN = 'work-session'
18const TOOL = 'set_session_title'
19// Press ids carry the plugin's name: the band is shared with other plugins' Clients.
20const P = {
21  kickoff: `${PLUGIN}:kickoff`,
22  skip: `${PLUGIN}:skip`,
23  wrap: `${PLUGIN}:wrap`,
24  later: `${PLUGIN}:later`,
25} as const
26
27const EMPTY_KICKOFF: Kickoff = { phase: 'none', command: '' }
28const EMPTY_WRAP: Wrap = { phase: 'none', reason: '' }
29const EMPTY_TITLE: Title = { applied: null }
30
31const kickoff = atom({ plugin: 'work-session', key: 'kickoff' } as const, EMPTY_KICKOFF)
32const wrap = atom({ plugin: 'work-session', key: 'wrap' } as const, EMPTY_WRAP)
33const title = atom({ plugin: 'work-session', key: 'title' } as const, EMPTY_TITLE)
34
35let start = 'cws'
36let end = 'ews'
37let mode: KickoffMode = 'band'
38let wrapAt = 75
39
40// Saved state from an older version lacks newer fields: fill defaults on reads and updates.
41const readKickoff = async ($: $): Promise<Kickoff> => ({ ...EMPTY_KICKOFF, ...(await read($, kickoff)) })
42const readWrap = async ($: $): Promise<Wrap> => ({ ...EMPTY_WRAP, ...(await read($, wrap)) })
43const readTitle = async ($: $): Promise<Title> => ({ ...EMPTY_TITLE, ...(await read($, title)) })
44const setKickoff = ($: $, fn: (k: Kickoff) => Kickoff) => update($, kickoff, (x): Kickoff => fn({ ...EMPTY_KICKOFF, ...x }))
45const setWrap = ($: $, fn: (w: Wrap) => Wrap) => update($, wrap, (x): Wrap => fn({ ...EMPTY_WRAP, ...x }))
46const setTitle = ($: $, fn: (t: Title) => Title) => update($, title, (x): Title => fn({ ...EMPTY_TITLE, ...x }))
47
48async function runCommand($: $, name: string): Promise<void> {
49  try {
50    await $.command.run({ command: name, args: '' })
51  } catch (err) {
52    $.ui.log(`${PLUGIN}: could not run /${name}: ${err instanceof Error ? err.message : String(err)}`)
53  }
54}
55
56async function press($: $, id: string): Promise<void> {
57  if (id === P.kickoff) {
58    await setKickoff($, k => ({ ...k, phase: 'started' }))
59    // Not awaited: the command runs once the session is idle, after this press returns.
60    void runCommand($, start)
61  } else if (id === P.skip) {
62    await setKickoff($, k => ({ ...k, phase: 'skipped' }))
63  } else if (id === P.wrap) {
64    await setWrap($, w => ({ ...w, phase: 'started' }))
65    void runCommand($, end)
66  } else if (id === P.later) {
67    await setWrap($, w => ({ ...w, phase: 'dismissed' }))
68  }
69}
70
71export const register: Register = (on, options) => {
72  start = commandName(options?.startCommand, 'cws')
73  end = commandName(options?.endCommand, 'ews')
74  mode = kickoffMode(options?.kickoff)
75  wrapAt = typeof options?.wrapAtPercent === 'number' ? options.wrapAtPercent : 75
76
77  on('session.start', async ($, e, next) => {
78    const result = await next(e)
79    await $.tool.register({
80      name: TOOL,
81      description: TITLE_TOOL_DESCRIPTION,
82      inputSchema: {
83        type: 'object',
84        properties: { title: { type: 'string', description: 'The session title, e.g. "Atlas S12 · Search filters"' } },
85        required: ['title'],
86      },
87      isDeferred: false,
88    })
89    return result
90  })
91
92  // The classic event carries the start's source: only a fresh session is kicked off.
93  on('classic.SessionStart', async ($, e, next) => {
94    const result = await next(e)
95    if (!isFreshStart(e.source)) return result
96    await Promise.all([
97      setKickoff($, () => EMPTY_KICKOFF),
98      setWrap($, () => EMPTY_WRAP),
99      setTitle($, () => EMPTY_TITLE),
100    ])
101    if (mode === 'off' || !hasCommand(await $.command.list(), start)) return result
102    if (mode === 'auto') {
103      await setKickoff($, () => ({ phase: 'started', command: start }))
104      void runCommand($, start)
105    } else {
106      await setKickoff($, () => ({ phase: 'offered', command: start }))
107    }
108    return { ...result, additionalContext: [...(result.additionalContext ?? []), startContext(start)] }
109  })
110
111  // Re-sent with every prompt, so the session keeps the title it was given.
112  on('classic.UserPromptSubmit', async ($, e, next) => {
113    const result = await next(e)
114    const t = await readTitle($)
115    return t.applied ? { ...result, sessionTitle: t.applied } : result
116  })
117
118  on('tool.call', { tool: 'mcp__work-session__set_session_title' }, async ($, e) => {
119    const cleaned = cleanTitle((e as unknown as { title?: unknown }).title)
120    if ('error' in cleaned) return { deny: `${TOOL}: ${cleaned.error}` }
121    await setTitle($, () => ({ applied: cleaned.title }))
122    return { result: `Session title set to "${cleaned.title}"; it shows from the user's next message.` }
123  })
124
125  // Anything the person types instead of pressing 1 means this session needs no kickoff.
126  on('prompt.submit', async ($, e, next) => {
127    if (e.origin?.kind === 'composer' && (await readKickoff($)).phase === 'offered') {
128      await setKickoff($, k => ({ ...k, phase: 'skipped' }))
129    }
130    return next(e)
131  })
132
133  on('command.run', async ($, e, next) => {
134    if (e.command === start) await setKickoff($, k => ({ ...k, phase: 'started' }))
135    if (e.command === end) await setWrap($, w => ({ ...w, phase: 'started' }))
136    // A /rename by hand wins: stop re-sending this mod's title.
137    if (e.command === 'rename') await setTitle($, () => EMPTY_TITLE)
138    return next(e)
139  })
140
141  on('turn.complete', async ($, e, next) => {
142    const result = await next(e)
143    if (e.agentId) return result
144    if ((await readWrap($)).phase !== 'none') return result
145    const reason = wrapReason(await $.session.usage(), wrapAt)
146    if (reason && hasCommand(await $.command.list(), end)) {
147      await setWrap($, () => ({ phase: 'offered', reason }))
148    }
149    return result
150  })
151
152  on('ui.message', { component: 'AbovePrompt' }, async ($, e, next) => {
153    const id = (e.data as { press?: unknown } | null)?.press
154    if (typeof id !== 'string' || !id.startsWith(`${PLUGIN}:`)) return next(e)
155    await press($, id)
156    return {}
157  })
158
159  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
160    // The band's controls need a terminal (Buttons) or the desktop (Clients).
161    if (e.props.hasSurvey || e.props.isWorking) return next(e)
162    if (e.surface !== 'terminal' && e.surface !== 'desktop') return next(e)
163    const [k, w] = await Promise.all([readKickoff($), readWrap($)])
164    const offer =
165      k.phase === 'offered'
166        ? { glyph: '▸', text: `Kick off this session with /${start}`, yes: P.kickoff, yesLabel: `Run /${start}`, no: P.skip, noLabel: 'Skip' }
167        : w.phase === 'offered'
168          ? { glyph: '◐', text: `Time to wrap? ${w.reason}`, yes: P.wrap, yesLabel: `Run /${end}`, no: P.later, noLabel: 'Later' }
169          : null
170    if (!offer) return next(e)
171    const { Box, Text, Button, Client } = $.ui.resolve({ ...e, surface: e.surface })
172    // The terminal draws Buttons for their digit hotkeys; the desktop drops Button
173    // presses from plugin UI, so it gets Client pills posting { press }.
174    const control = (id: string, label: string, hotkey: string) =>
175      e.surface === 'terminal' ? (
176        <Button key={id} label={label} hotkey={hotkey} plain onPress={() => press($, id)} />
177      ) : (
178        <Client key={id} module="./pill.tsx" props={{ id, label, hotkey }} />
179      )
180    const row = (
181      <Box key={PLUGIN} flexDirection="row" gap={2} paddingX={1}>
182        <Text color="suggestion">{offer.glyph}</Text>
183        <Text>{offer.text}</Text>
184        {control(offer.yes, offer.yesLabel, '1')}
185        {control(offer.no, offer.noLabel, '2')}
186      </Box>
187    )
188    // Stacked over what the plugins beneath draw (a desktop status line), not instead of it.
189    const below = await next(e)
190    return (
191      <Box flexDirection="column">
192        {row}
193        {below}
194      </Box>
195    )
196  })
197}
198

1/** Pure decisions behind the hooks: what to offer, when, and what a title may be. */
2
3export type KickoffMode = 'band' | 'auto' | 'off'
4export type StartSource = 'startup' | 'resume' | 'clear' | 'compact' | 'fork'
5
6export const TITLE_MAX = 80
7// A rate limit this used up is worth wrapping before it runs out mid-task.
8export const RATE_LIMIT_WRAP = 90
9
10export function kickoffMode(raw: unknown): KickoffMode {
11  return raw === 'auto' || raw === 'off' ? raw : 'band'
12}
13
14/** A command name as typed in settings: no slash, no spaces; empty when unusable. */
15export function commandName(raw: unknown, fallback: string): string {
16  const name = (typeof raw === 'string' ? raw : fallback).trim().replace(/^\//, '')
17  return /^[\w:.-]+$/.test(name) ? name : ''
18}
19
20export function hasCommand(list: readonly { name: string }[], name: string): boolean {
21  return name !== '' && list.some(c => c.name === name)
22}
23
24/** A fresh working session starts at launch or after /clear; a resume or compact continues one. */
25export function isFreshStart(source: StartSource): boolean {
26  return source === 'startup' || source === 'clear'
27}
28
29/** The title as it will be shown, or why it is refused. */
30export function cleanTitle(raw: unknown): { title: string } | { error: string } {
31  if (typeof raw !== 'string') return { error: 'title must be a string' }
32  const title = raw.replace(/\s+/g, ' ').trim()
33  if (title === '') return { error: 'title is empty' }
34  if (title.length > TITLE_MAX) return { error: `title is ${title.length} characters; keep it under ${TITLE_MAX}` }
35  return { title }
36}
37
38type Usage = {
39  context: { percent?: number; tokens?: number; window: number }
40  rateLimits: readonly { kind: string; percentUsed: number }[]
41}
42
43export function contextPercent(usage: Usage): number | null {
44  const { percent, tokens, window } = usage.context
45  if (typeof percent === 'number') return Math.round(percent)
46  if (typeof tokens === 'number' && window > 0) return Math.round((tokens / window) * 100)
47  return null
48}
49
50/** Why a wrap is worth offering now, worded for the band; null when it is not. */
51export function wrapReason(usage: Usage, atPercent: number): string | null {
52  if (atPercent <= 0) return null
53  const limit = [...usage.rateLimits].sort((a, b) => b.percentUsed - a.percentUsed)[0]
54  if (limit && limit.percentUsed >= RATE_LIMIT_WRAP) return `${limit.kind} limit ${Math.round(limit.percentUsed)}% used`
55  const percent = contextPercent(usage)
56  if (percent !== null && percent >= atPercent) return `context ${percent}% full`
57  return null
58}
59
60/** What the model is told at a fresh start in a project that has the start command. */
61export function startContext(start: string): string {
62  return [
63    `This project kicks off working sessions with /${start}.`,
64    `Once a session's focus is known (after /${start} presents and the user picks what to work on,`,
65    'or once the task is clear), call the set_session_title tool with a short title:',
66    '"<Project> S<n> · <focus>" when the project numbers its sessions (e.g. "Atlas S12 · Search filters"),',
67    'else "<Project> · <focus>". Call it again when the focus changes.',
68  ].join(' ')
69}
70
71export const TITLE_TOOL_DESCRIPTION = [
72  "Sets this session's title, shown in the session list and the terminal tab, so the user can tell sessions apart.",
73  'Call it once the focus of the session is clear, and again when it changes.',
74  'Format: "<Project> S<n> · <focus>" when the project numbers its sessions (e.g. "Atlas S12 · Search filters"),',
75  `else "<Project> · <focus>". Under ${TITLE_MAX} characters.`,
76  'The title appears from the user\'s next message on.',
77].join(' ')
78

1import type { ClientModule } from 'claude-code'
2
3/**
4 * A pressable control drawn as a Client: a click, Enter or Space posts
5 * `{ press: id }` to the hooks module. The desktop app drops Button presses
6 * from plugin UI, while Client messages arrive (claude-mods' desktop rules);
7 * the terminal draws real Buttons instead, for their digit hotkeys.
8 */
9export type PillProps = { id: string; label: string; hotkey: string }
10
11type Local = { hover: boolean }
12
13const Pill: ClientModule<PillProps, Local> = (props, surface) => {
14  const { Box, Text } = surface.elements
15  const state = surface.state ?? { hover: false }
16  // Listeners are set once, on the first draw: each set is a message to the page.
17  if (surface.state === undefined) {
18    const id = props.id
19    surface.onPointer(e => {
20      const cur = surface.state ?? { hover: false }
21      if (e.type === 'leave') {
22        if (cur.hover) surface.setState({ hover: false })
23      } else if (!cur.hover) {
24        surface.setState({ hover: true })
25      }
26      if (e.type === 'down' && (e.button ?? 'left') === 'left') surface.post({ press: id })
27    })
28    surface.onKey(e => {
29      if (e.key === 'return' || e.key === ' ') surface.post({ press: id })
30    })
31    surface.setState(state)
32  }
33  return (
34    <Box flexDirection="row" borderStyle="round" borderColor={state.hover ? 'suggestion' : 'subtle'} paddingX={1}>
35      <Text color="suggestion">{props.hotkey}</Text>
36      <Text>: {props.label}</Text>
37    </Box>
38  )
39}
40
41export default Pill
42

1export type KickoffPhase = 'none' | 'offered' | 'started' | 'skipped'
2export type WrapPhase = 'none' | 'offered' | 'dismissed' | 'started'
3
4export type Kickoff = { phase: KickoffPhase; command: string }
5export type Wrap = { phase: WrapPhase; reason: string }
6/** `applied`: re-sent with every prompt so the session keeps it; null hands titling back to Claude Code. */
7export type Title = { applied: string | null }
8
9declare module 'claude-code' {
10  interface PluginState {
11    'work-session': { kickoff: Kickoff; wrap: Wrap; title: Title }
12  }
13}
14