pane-tools

1import type { EngineInterface, Register } from 'claude-code'
2
3// /mods 하나로 들어가는 모드 허브 — bin/hub.py 가 세션의 컨텍스트·비용 게이지와 bin/ 의 도구 버튼(memo, tetris, pokemon …)을 띄운다.
4// 어디에 띄울지는 사용자가 /config 에서 고른다(userConfig): tmux 패널 · 새 터미널 창 · 사용자 명령(cmux·wezterm·zellij …).
5// 메모는 bin/memo.py 가 받는 세션의 수신함 pane-tools/inbox/<sessionId>.json 에 [{id, text}] 로 쌓고,
6// 받는 세션의 이 mod 가 읽어 $.prompt.submit 으로 넣는다 — 작업 중이면 엔진이 한가해질 때까지 기다렸다 넣는다.
7// 게이지는 각 세션의 이 mod 가 pane-tools/usage/<sessionId>.json 에 적어 둔 값을 허브가 읽는다.
8// 글자는 pane-tools/settings.json 의 lang(허브의 [ 한/EN ] 버튼)을 따른다.
9const SHELLS = new Set(['bash', 'sh', 'zsh'])
10// 게임이 키우기 전 높이를 적어 두는 tmux 패널 옵션 — 게임이 도중에 갈아 끼워져도 다음 도구가 되돌린다
11const HEIGHT_OPT = '@pt_h'
12const TICK_MS = 2000
13
14export type Msg = { id: number; text: string }
15
16// 아직 안 넣은 메시지만, 오래된 순으로 — 기준은 마지막으로 넣은 id ($.fs 에 삭제가 없어 파일을 비우지 못한다)
17export function pending(msgs: Msg[], last: number): Msg[] {
18  return msgs.filter(m => m.id > last).sort((a, b) => a.id - b.id)
19}
20
21export function compose(msgs: Msg[]): string {
22  return msgs.map(m => m.text.trim()).filter(Boolean).join('\n\n')
23}
24
25// 갈아 끼워도 되는 패널인가 — 빈 셸이거나, 이 mod 가 띄운 도구(mark = <플러그인>/bin/)일 때만. 사용자가 돌리는 python 작업은 죽이지 않는다
26export function canReplace(current: string, startCommand: string, mark: string): boolean {
27  return SHELLS.has(current) || startCommand.includes(mark)
28}
29
30export type Opts = { launcher: string; tmuxTarget: string; followPane: string; command: string; feedTarget?: string }
31export type Where = { tmux: boolean; wsl?: string; mac: boolean }
32
33// 셸에 한 덩어리로 넘길 수 있게 작은따옴표로 감싼다
34export const shq = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
35
36// 허브를 어떻게 띄울지 — 실행할 argv 와, 정해진 tmux 패널을 갈아 끼우는 경우 그 패널(slot)
37export function plan(o: Opts, cmd: string, w: Where): { argv: string[]; slot?: string } | { error: 'nocmd' } {
38  const mode = o.launcher === 'tmux' || o.launcher === 'window' || o.launcher === 'command' ? o.launcher : w.tmux ? 'tmux' : 'window'
39  if (mode === 'command') {
40    if (!o.command.includes('{cmd}')) return { error: 'nocmd' }
41    return { argv: ['bash', '-lc', o.command.split('{cmd}').join(shq(cmd))] }
42  }
43  if (mode === 'tmux') {
44    if (o.tmuxTarget) return { argv: ['tmux', 'respawn-pane', '-k', '-t', o.tmuxTarget, `${cmd}; exec bash`], slot: o.tmuxTarget }
45    return { argv: ['tmux', 'split-window', '-h', '-l', '45%', cmd] } // 허브를 닫으면 패널도 닫힌다
46  }
47  if (w.wsl) return { argv: ['wt.exe', '-w', 'new', 'wsl.exe', '-d', w.wsl, '-e', 'bash', '-lc', cmd] }
48  if (w.mac) return { argv: ['osascript', '-e', `tell application "Terminal" to do script ${JSON.stringify(cmd)}`] }
49  return { argv: ['x-terminal-emulator', '-e', 'bash', '-lc', cmd] }
50}
51
52const home = async ($: EngineInterface) => (await $.env.get('HOME')) ?? '/tmp'
53
54// 한/영 — 허브의 [ 한/EN ] 버튼이 적는 설정을 읽는다
55async function L($: EngineInterface, ko: string, en: string) {
56  try {
57    return JSON.parse(await $.fs.read(`${await home($)}/.claude/pane-tools/settings.json`)).lang === 'en' ? en : ko
58  } catch {
59    return ko
60  }
61}
62
63// 허브의 [ 설정 ] 이 같은 파일에 적은 띄울 곳 — /mods 마다 읽어 /config 값보다 먼저 쓴다(다시 불러올 필요 없게)
64const PLACE = ['launcher', 'tmuxTarget', 'followPane', 'command', 'feedTarget'] as const
65export async function prefs($: EngineInterface): Promise<Partial<Opts>> {
66  try {
67    const s = JSON.parse(await $.fs.read(`${await home($)}/.claude/pane-tools/settings.json`))
68    return Object.fromEntries(PLACE.filter(k => typeof s[k] === 'string').map(k => [k, s[k]]))
69  } catch {
70    return {}
71  }
72}
73
74let busy = false
75async function deliver($: EngineInterface) {
76  if (busy) return
77  busy = true
78  try {
79    const sid = await $.session.id()
80    const base = `${await home($)}/.claude/pane-tools/inbox/${sid}`
81    if (!(await $.fs.exists(`${base}.json`))) return
82    let msgs: Msg[]
83    try {
84      msgs = JSON.parse(await $.fs.read(`${base}.json`))
85    } catch {
86      return // 메모장이 쓰는 도중이면 다음 틱에
87    }
88    const key = `last:${sid}`
89    const todo = pending(msgs, ((await $.store.get(key)) as number | undefined) ?? 0)
90    const top = todo.at(-1)?.id
91    if (top === undefined) return
92    const last = ((await $.store.get(key)) as number | undefined) ?? 0
93    // 기준을 먼저 올린다 — 다시 불러온 뒤 타이머가 겹쳐도 두 번 넣지 않게
94    await $.store.set(key, top)
95    const text = compose(todo)
96    // 한가해져 실제로 들어간 뒤에야 확인 파일을 쓴다 — 메모장의 '✓ 전달했습니다' 가 거짓이 되지 않게
97    const r = text ? await $.prompt.submit({ text, asUser: true }) : undefined
98    if (r?.drop !== undefined) {
99      await $.store.set(key, last) // 거절됐으면 되돌려 다음 틱에 다시 넣는다
100      $.ui.toast(`${await L($, '메모를 넣지 못해 다시 시도합니다', 'Could not deliver the memo, retrying')}: ${r.drop}`)
101      return
102    }
103    await $.fs.write(`${base}.ack`, String(top))
104  } finally {
105    busy = false
106  }
107}
108
109// 설정대로 허브를 띄우고, 사용자에게 보일 한 줄을 돌려준다
110async function openHub($: EngineInterface, o: Opts) {
111  const root = $.plugin.root
112  const mark = `${root}/bin/`
113  let cmd = `python3 ${shq(`${root}/bin/hub.py`)} --session ${await $.session.id()}`
114  if (o.followPane) cmd += ` --follow-pane ${shq(o.followPane)}`
115  const where: Where = {
116    tmux: (await $.process.run(['tmux', 'has-session']).catch(() => ({ exitCode: 1 }))).exitCode === 0,
117    wsl: await $.env.get('WSL_DISTRO_NAME'),
118    mac: (await $.process.run(['uname', '-s']).catch(() => ({ stdout: '' }))).stdout.trim() === 'Darwin',
119  }
120  const p = plan(o, cmd, where)
121  if ('error' in p) return L($, '사용자 명령에 {cmd} 자리가 없습니다 — /config 의 pane-tools command 를 확인해 주세요',
122    'The custom command has no {cmd} placeholder — check pane-tools "command" in /config')
123  if (p.slot) {
124    const info = await $.process.run(['tmux', 'display', '-p', '-t', p.slot, '#{pane_current_command}\t#{pane_start_command}'])
125    // 물어보는 것 자체가 실패하면 패널이 바쁜 게 아니라 tmux 에 못 닿은 것 — 소켓 파일이 지워지면 이렇다(2026-10-21 실제로 겪음)
126    if (info.exitCode !== 0) return L($, `tmux 패널 ${p.slot} 에 연결할 수 없습니다: ${info.stderr.trim()} — 패널 이름을 확인하거나, 소켓이 사라졌다면 셸에서 pkill -USR1 -o -x tmux 로 되살리세요.`,
127      `Cannot reach tmux pane ${p.slot}: ${info.stderr.trim()} — check the pane name, or if the socket vanished run pkill -USR1 -o -x tmux.`)
128    const [cur = '', start = ''] = info.stdout.trim().split('\t')
129    if (!canReplace(cur, start, mark)) return L($, `패널 ${p.slot} 에서 ${cur || '다른 프로그램'}이 돌고 있어 열지 않았습니다. 끝낸 뒤 다시 입력해 주세요.`,
130      `Pane ${p.slot} is running ${cur || 'another program'}, so the hub was not opened. Try again when it finishes.`)
131    const h = (await $.process.run(['tmux', 'show', '-pv', '-t', p.slot, HEIGHT_OPT])).stdout.trim()
132    if (h) {
133      await $.process.run(['tmux', 'resize-pane', '-t', p.slot, '-y', h])
134      await $.process.run(['tmux', 'set', '-pu', '-t', p.slot, HEIGHT_OPT])
135    }
136  }
137  const r = await $.process.run(p.argv).catch((e: unknown) => ({ exitCode: 1, stderr: String(e) }))
138  if (r.exitCode !== 0) return `${await L($, '모드 허브를 열지 못했습니다', 'Could not open the mods hub')} (${p.argv[0]}): ${r.stderr.trim()}`
139  return (await L($, '모드 허브를 띄웠습니다.', 'Opened the mods hub.')) + (await openFeed($, o.feedTarget, root))
140}
141
142// 세션 활동 피드를 지정한 tmux 패널에도 — 빈 셸일 때만 띄우고, 이미 피드가 돌면 그대로(스크롤을 잃지 않게), 다른 건 건드리지 않는다
143async function openFeed($: EngineInterface, target: string | undefined, root: string) {
144  if (!target) return ''
145  const info = await $.process.run(['tmux', 'display', '-p', '-t', target, '#{pane_current_command}\t#{pane_tty}'])
146  const [cur = '', tty = ''] = info.stdout.trim().split('\t')
147  if (info.exitCode !== 0 || !SHELLS.has(cur)) return '' // 패널이 없거나 다른 프로그램
148  // respawn 으로 띄운 피드는 겉의 bash -c 가 보여 tmux 가 'bash' 라고 한다 — 그 tty 에 feed.py 가 도는지 직접 본다
149  const ps = await $.process.run(['ps', '-t', tty, '-o', 'args='])
150  if (ps.stdout.includes('feed.py')) return ''
151  const r = await $.process.run(['tmux', 'respawn-pane', '-k', '-t', target, `python3 ${shq(`${root}/bin/feed.py`)}; exec bash`])
152  return r.exitCode === 0 ? L($, ` 피드도 ${target} 에 띄웠습니다.`, ` Also opened the feed in ${target}.`) : ''
153}
154
155// 허브 게이지용 — 컨텍스트·비용·사용 한도를 2초마다, 바뀌었을 때만 적는다.
156// gained: 컨텍스트 토큰이 늘어난 만큼의 누적(압축으로 줄면 무시하고 다시 늘면 또 센다) — pokemon 모드의 경험치.
157// 다시 불러와도 이어지게 $.store 에 두고, 불러온 직후 첫 값은 기준으로만 삼는다(두 번 세지 않게).
158let lastUsage = ''
159let lastTokens: number | undefined
160let gained: number | undefined
161export function grow(prev: number | undefined, now: number | undefined): number {
162  return prev !== undefined && now !== undefined && now > prev ? now - prev : 0
163}
164async function writeUsage($: EngineInterface) {
165  const u = await $.session.usage()
166  const sid = await $.session.id()
167  gained ??= ((await $.store.get(`gain:${sid}`)) as number | undefined) ?? 0
168  const add = grow(lastTokens, u.context.tokens)
169  lastTokens = u.context.tokens ?? lastTokens
170  if (add) {
171    gained += add
172    await $.store.set(`gain:${sid}`, gained)
173  }
174  const text = JSON.stringify({ context: u.context, cost: u.cost?.usd ?? null, rateLimits: u.rateLimits, gained })
175  if (text === lastUsage) return
176  lastUsage = text
177  await $.fs.write(`${await home($)}/.claude/pane-tools/usage/${sid}.json`, text)
178}
179
180export const register: Register = (on, options) => {
181  const o: Opts = {
182    launcher: String(options.launcher ?? 'auto'),
183    tmuxTarget: String(options.tmuxTarget ?? ''),
184    followPane: String(options.followPane ?? ''),
185    command: String(options.command ?? ''),
186    feedTarget: String(options.feedTarget ?? ''),
187  }
188  on('session.start', async ($, e, next) => {
189    // immediate: 작업 중에도 기다리지 않고 바로 연다 (/reload-plugins 처럼)
190    await $.command.register({ name: 'mods', description: '모드 허브 열기 · Open the mods hub (gauges, memo, games)', immediate: true })
191    $.clock.every(TICK_MS, () => {
192      void deliver($)
193      void writeUsage($).catch(() => undefined)
194    })
195    return next(e)
196  })
197
198  on('command.run', { command: 'mods' }, async $ => ({ text: await openHub($, { ...o, ...(await prefs($)) }) }))
199}
200