@sejuneoh/aitop 0.0.0-stage → 0.21.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SejuneOh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# ⣠⣴⣾ aitop
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@sejuneoh/aitop)](https://www.npmjs.com/package/@sejuneoh/aitop)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/SejuneOh/aitop/blob/main/LICENSE)
+
+**`top` for your AI coding agents.** A read-only terminal monitor that shows every Claude Code, Codex CLI and Antigravity CLI session on your machine in one live screen: what each one is doing, which ones are waiting for you, and how many tokens they used.
+
+- **Live status** of every session and its subagents: thinking, running a tool, waiting for you, idle
+- **Waiting alerts**: blocked sessions jump to the top, with optional bell, desktop notification or hook command
+- **Tokens and cost** per session and for today / last 7 days, at public API list prices
+- **Changed files and diffs** per session and per prompt
+- **Read-only**: no network, no ports, no dependencies. It only reads the session logs each CLI already writes
+
+> The interface text is currently in Korean. Keys and options work the same everywhere.
+
+## Install
+
+Requires Node.js 22+ on Linux, macOS or WSL.
+
+```bash
+npm install -g @sejuneoh/aitop
+aitop
+```
+
+## Usage
+
+```
+aitop            live screen
+aitop --all      include sessions that ended in the last 24 hours
+aitop --json     print a snapshot as JSON and exit
+aitop --doctor   check which tools and logs aitop can see
+aitop --help     all options
+```
+
+Keys: `↑↓` select · `n` next session to check · `/` search · `s` sort · `g` group · `p` pin · `f` changed files · `?` help · `q` quit
+
+Settings can also go in `~/.config/aitop/config.json`. See `aitop --help` or the [detailed manual (Korean)](https://github.com/SejuneOh/aitop/blob/main/docs/README.ko.md).
+
+## License
+
+[MIT](https://github.com/SejuneOh/aitop/blob/main/LICENSE)

package/bin/aitop.mjs

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { budgetDayOption, configJson, configText, resolveConfig } from '../src/config.mjs';
+import { notifyOptions } from '../src/notify.mjs';
+import { mask, setAmbiguous, stripControl } from '../src/text.mjs';
+
+const KNOWN = new Set(['-h', '--help', '-v', '--version', '--once', '--all', '--json', '--doctor', '--bell', '--show-requests', '--print-config', '--no-bell', '--no-all', '--no-show-requests', '--debug', '--no-debug', '--color-blind', '--no-color-blind']);
+const THEMES = ['light', 'dark'];
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+// --notify, --no-notify, --on-waiting, --no-on-waiting 은 notifyOptions 한 곳에서 해석한다. 여기서는 명령줄에서 준 값만 본다.
+const cliArgs = process.argv.slice(2);
+const cli = notifyOptions(cliArgs);
+if (cli.error) {
+  process.stderr.write(`aitop: ${cli.error}\n`);
+  process.exit(2);
+}
+// --budget-day <usd>, --budget-day=<usd>, --no-budget-day 는 budgetDayOption 이 꺼낸다.
+const budget = budgetDayOption(cli.rest);
+if (budget.error) {
+  process.stderr.write(`aitop: ${budget.error}\n`);
+  process.exit(2);
+}
+// --theme light, --theme=light 처럼 값을 받는 옵션은 따로 꺼낸다.
+const argv = budget.rest;
+let theme = null;
+const rest = [];
+for (let i = 0; i < argv.length; i++) {
+  const m = /^--theme(?:=(.*))?$/.exec(argv[i]);
+  if (!m) rest.push(argv[i]);
+  else theme = m[1] ?? (argv[i + 1]?.startsWith('-') ? '' : (argv[++i] ?? ''));
+}
+const args = new Set(rest);
+
+// 옵션 > 환경 변수 > 설정 파일 > 기본값. 잘못된 --theme 값은 아래에서 모르는 옵션으로 알린다.
+// --bell 과 --no-bell 처럼 켜고 끄는 옵션은 뒤에 준 쪽을 따른다.
+const flag = (name) => {
+  const on = rest.lastIndexOf(`--${name}`);
+  const off = rest.lastIndexOf(`--no-${name}`);
+  return on < 0 && off < 0 ? undefined : on > off;
+};
+// notify 는 --notify 가 뒤에 오면 true, --no-notify 가 뒤에 오면 false, 둘 다 없으면 정하지 않은 것이다.
+const notifyFlag = cli.notify ? true : notifyOptions(cliArgs, { notify: true }).notify ? undefined : false;
+// onWaiting 은 --on-waiting 이 뒤에 오면 그 명령, --no-on-waiting 이 뒤에 오면 null(끔), 둘 다 없으면 정하지 않은 것이다.
+const onWaitingFlag = cli.onWaiting ?? (notifyOptions(cliArgs, { onWaiting: 'x' }).onWaiting === null ? null : undefined);
+const config = resolveConfig({ flags: { theme: THEMES.includes(theme) ? theme : undefined, colorBlind: flag('color-blind'), bell: flag('bell'), showRequests: flag('show-requests'), all: flag('all'), debug: flag('debug'), notify: notifyFlag, onWaiting: onWaitingFlag, budgetDay: budget.value } });
+const opt = Object.fromEntries(Object.entries(config.values).map(([k, v]) => [k, v.value]));
+// 알림은 설정 파일 값(onWaiting 은 권한 검사를 통과한 것만)을 깔고 명령줄 옵션이 덮는다.
+const fromFile = (k) => (config.values[k].source === 'file' ? config.values[k].value : undefined);
+const alerts = notifyOptions(cliArgs, { notify: fromFile('notify'), onWaiting: fromFile('onWaiting') });
+// 화면 모듈과 표식 모듈은 불러올 때 테마·아이콘을 고르므로 그 전에 넘긴다.
+if (opt.theme) process.env.AITOP_THEME = opt.theme;
+process.env.AITOP_COLOR_BLIND = opt.colorBlind ? '1' : '0';
+if (config.values.icons.source === 'file') process.env.AITOP_ICONS = opt.icons;
+// 폭이 모호한 기호를 2칸으로 셀지는 글자 폭 계산(text.mjs)이 쓴다. 화면 모듈은 그릴 때마다 이 값을 본다.
+setAmbiguous(opt.ambiguous);
+const { BRAND, userVarsSeq } = await import('../src/brand.mjs');
+const { keysText } = await import('../src/help.mjs');
+const { debug, initLog, logPath } = await import('../src/log.mjs');
+
+// 실시간 화면에 들어간 뒤에는 restore 가 터미널을 되돌리고 훅을 끝낸다. 그 전에는 할 일이 없다.
+let restore = () => {};
+process.on('unhandledRejection', (reason) => {
+  debug('aitop', 'unhandledRejection', reason);
+  try {
+    restore();
+  } catch {}
+  const why = reason instanceof Error ? reason.message : String(reason);
+  process.stderr.write(`aitop: 처리되지 않은 오류로 끝냅니다 (${stripControl(mask(why)).slice(0, 200)})\n`);
+  process.exit(1);
+});
+
+const HELP = `${BRAND.logo} aitop - 터미널에서 Claude Code · Codex · Antigravity · Gemini 세션을 실시간으로 본다
+
+  aitop            실시간 화면
+  aitop --once     현재 상태를 한 번 출력하고 끝낸다
+  aitop --all      종료된 세션(24시간 이내)도 함께 본다
+  aitop --json     세션 목록과 사용량 합계를 JSON 으로 한 번 출력한다 (--all 과 함께 쓸 수 있다)
+  aitop --doctor   Claude · Codex · Antigravity · Gemini 기록과 실행 중인 프로세스, 설정 파일을 점검한다 (--json 과 함께 쓸 수 있다)
+  aitop --bell     응답 대기 세션이 새로 생기면 터미널 벨을 울린다
+  aitop --notify   응답 대기 세션이 새로 생기면 데스크톱 알림을 띄운다 (notify-send · osascript, 없으면 건너뜀)
+  aitop --on-waiting <명령>  응답 대기 세션이 새로 생기면 /bin/sh -c 로 명령을 실행한다 (내 권한으로 실행, 10초 제한)
+                   세션 정보는 환경변수로만: AITOP_TOOL AITOP_PROJECT AITOP_SESSION_ID AITOP_CWD AITOP_WAITING_FOR
+  aitop --show-requests  응답 대기 요청 전체를 상세 패널·--json 에 보인다 (AITOP_SHOW_REQUESTS=1). 비밀값 가림은 최선일 뿐이라 명령 속 비밀값이 보일 수 있다
+  aitop --budget-day <달러>  하루 예산. 헤더에 오늘 $12.30/$50 처럼 보이고, 오늘 끝 예상 비용(오늘 + 최근 속도 × 자정까지, 늘 API 환산)이
+                   80% 를 넘으면 '예상 $45', 100% 를 넘으면 '예상 $60!' 로 알린다 (AITOP_BUDGET_DAY, 설정 파일 budgetDay)
+  aitop --theme light|dark  밝은 배경 / 어두운 배경 색 (없으면 COLORFGBG 로 고른다)
+  aitop --color-blind  적록 색약용 색. 응답 대기·돈·경고·diff 를 노랑·파랑 계열로 가른다 (AITOP_COLOR_BLIND=1, 설정 파일 colorBlind). --theme 과 함께 쓴다
+  aitop --no-bell · --no-all · --no-show-requests · --no-notify · --no-on-waiting · --no-budget-day · --no-debug · --no-color-blind  설정 파일에서 켠 값을 이번 실행만 끈다
+  aitop --debug    디버그 로그를 남긴다 (AITOP_DEBUG=1, 설정 파일 debug). 기록 형식이 바뀌어 값이 빌 때 원인 확인용
+                   ${logPath()} (1MB 넘으면 .1 로 하나만 남김, 오류 이름·파일 이름만 쓰고 비밀값은 가림)
+  aitop --print-config  설정 값마다 값과 출처(flag/env/file/default), 설정 파일 위치를 보인다 (--json 과 함께 쓸 수 있다)
+  aitop --version  설치된 버전을 보인다
+
+  AITOP_ICONS=plain  창 제목의 Nerd Font 아이콘과 WezTerm 탭 값을 끈다 (ascii 면 로고도 ASCII)
+  AITOP_AMBIGUOUS=wide  ·, →, ─, ● 같은 폭이 모호한 기호를 2칸으로 그리는 터미널(동아시아 폭 설정)용. 표·상자 기호를 1칸 기호로 바꿔 줄이 밀리지 않게 한다 (설정 파일 ambiguous)
+
+  설정 파일: ${config.path}
+    예) { "theme": "light", "icons": "plain", "bell": true, "notify": true, "onWaiting": "say 대기", "budgetDay": 50, "ambiguous": "wide", "hideIdleTools": false }
+    hideIdleTools: 실행 중 세션이 없고 7일 동안 쓰지 않은 도구를 헤더 아래 도구 줄에서 숨긴다 (기본 true, false 면 늘 셋 다)
+    onWaiting 은 파일 소유자가 나이고 그룹·다른 사용자가 쓸 수 없을 때(chmod 600)만 받는다.
+    옵션 > 환경 변수 > 설정 파일 순서로 정한다. 잘못된 값은 무시하고 --doctor 에 알린다.
+
+${keysText().replace(/^/gm, '  ')}
+  실시간 화면에서 ? 를 누르면 지금 화면의 키부터 보인다`;
+
+if (theme === '') {
+  process.stderr.write(`aitop: --theme 값이 없습니다 (light 또는 dark)\n`);
+  process.exit(2);
+}
+const unknown = [...args].filter((a) => !KNOWN.has(a));
+if (theme != null && !THEMES.includes(theme)) unknown.push(`--theme ${theme}`);
+if (unknown.length) {
+  process.stderr.write(`aitop: 모르는 옵션 ${unknown.join(' ')}\n\n${HELP}\n`);
+  process.exit(2);
+}
+if (args.has('-h') || args.has('--help')) {
+  console.log(HELP);
+  process.exit(0);
+}
+if (args.has('-v') || args.has('--version')) {
+  console.log(VERSION);
+  process.exit(0);
+}
+if (args.has('--print-config')) {
+  console.log(args.has('--json') ? JSON.stringify(configJson(config), null, 2) : configText(config));
+  process.exit(0);
+}
+
+// 디버그 로그는 켰을 때만 파일을 만든다. --help·--version·--print-config 처럼 바로 끝나는 경우에는 만들지 않는다.
+const log = initLog({ enabled: opt.debug, version: VERSION });
+if (opt.debug && !log.on) process.stderr.write(`aitop: 디버그 로그를 열 수 없어 끕니다 (${log.path})\n`);
+
+// 파이프나 파일로 받을 때는 색 코드를 넣지 않는다. 화면 모듈이 불러올 때 NO_COLOR 를 읽으므로 그 전에 정한다.
+const forced = process.env.FORCE_COLOR != null && !['', '0', 'false'].includes(process.env.FORCE_COLOR);
+if (!process.stdout.isTTY && !forced && !process.env.NO_COLOR) process.env.NO_COLOR = '1';
+
+// 받는 쪽(| head 등)이 먼저 닫으면 조용히 끝낸다.
+process.stdout.on('error', (err) => process.exit(err.code === 'EPIPE' ? 0 : 1));
+// 다 쓴 뒤에 끝낸다 (파이프로 넘길 때 64KB 넘는 출력이 잘리지 않게).
+const printAndExit = async (text) => {
+  await new Promise((resolve) => process.stdout.write(text + '\n', resolve));
+  process.exit(0);
+};
+
+// 알림은 실시간 화면에서만 동작한다.
+if ((cli.notify || cli.onWaiting) && (args.has('--once') || args.has('--json') || args.has('--doctor') || !process.stdout.isTTY)) {
+  process.stderr.write('aitop: --notify, --on-waiting 은 실시간 화면에서만 동작한다 (--once·--json·--doctor·파이프 출력에서는 무시)\n');
+}
+
+const { checkTools, doctorText, toolsJson } = await import('../src/doctor.mjs');
+if (args.has('--doctor')) {
+  const result = { ...checkTools(), config: configJson(config), log: { on: log.on, path: log.path } };
+  await printAndExit(args.has('--json') ? JSON.stringify({ version: VERSION, ...result, tools: toolsJson(result.tools) }, null, 2) : doctorText(result, VERSION));
+}
+
+const { collect } = await import('../src/collect.mjs');
+const { render, filterSessions, animating } = await import('../src/ui.mjs');
+const { arrange } = await import('../src/order.mjs');
+const { frameTimer } = await import('../src/frames.mjs');
+const { flushCache } = await import('../src/cache.mjs');
+const { toJson } = await import('../src/json.mjs');
+const { createAttention, updateAttention, markSeen, nextAttention, windowTitle, createWaitWatch, takeNewlyWaiting, attentionCounts } = await import('../src/attention.mjs');
+const { createNotifier } = await import('../src/notify.mjs');
+const { onKey, fixFocus } = await import('../src/keys.mjs');
+
+// 요청 전체 보기는 기본으로 꺼 둔다. 켜지 않으면 상세 패널에도 --json 에도 나가지 않는다.
+const showRequests = opt.showRequests;
+// settings: 도움말(?)에 보이는 지금 설정 값.
+const settings = { budgetDay: opt.budgetDay, notify: Boolean(alerts.notify), onWaiting: Boolean(alerts.onWaiting), debug: log.on, configPath: config.path };
+const view = { showRequests, budgetDay: opt.budgetDay, hideIdleTools: opt.hideIdleTools, settings, data: null, selectedId: null, showDetail: 'auto', showEnded: opt.all, frame: 0, filter: '', searching: false, help: false, focus: null, filePath: null, diffScroll: 0, tab: 'now', costMode: 'api', sort: 'default', group: 'none', pins: [] };
+const once = args.has('--once') || args.has('--json') || !process.stdout.isTTY;
+// 실시간 화면에서 한 번 갱신할 때 읽는 기록 양과 시간. 큰 기록은 여러 번에 나눠 읽어서 키 입력이 막히지 않게 한다.
+const TICK_BUDGET = 24 * 1024 * 1024;
+const TICK_MS = 60;
+// 덜 읽은 기록이 있으면 1초를 기다리지 않고 이만큼 쉰 뒤 이어 읽는다 (그 사이 키 입력과 그리기가 돈다).
+const CATCH_UP_MS = 15;
+// 처음 읽는 동안은 캐시를 자주 저장해, 도중에 끝내도 읽은 만큼은 남게 한다.
+const LOADING_FLUSH_MS = 3000;
+
+const attention = createAttention();
+let tools = null;
+// --bell · --notify · --on-waiting: 실시간 화면에서만, 첫 갱신에서 이미 응답 대기인 세션은 알리지 않는다.
+const bell = opt.bell;
+const waitWatch = createWaitWatch();
+const notifier = !once && (alerts.notify || alerts.onWaiting) ? createNotifier(alerts) : null;
+
+function refresh() {
+  const data = collect({ showEnded: view.showEnded, selectedId: view.selectedId, budgetBytes: once ? Infinity : TICK_BUDGET, budgetMs: once ? Infinity : TICK_MS });
+  if (!data.sessions.some((s) => s.id === view.selectedId)) {
+    view.selectedId = arrange(data.sessions, view).sessions[0]?.id ?? null;
+    view.focus = null;
+    view.tab = 'now';
+  }
+  updateAttention(attention, data.sessions, view.selectedId);
+  data.sessions = data.sessions.map((s) => (attention.unseen.has(s.id) ? { ...s, unseen: true, phase: { kind: 'unseen', text: '완료 · 확인 전' }, plain: s } : s));
+  // 도구별 점검은 기록 폴더를 훑으므로 30초에 한 번만 한다.
+  if (!tools || Date.now() - tools.at > 30_000) tools = { at: Date.now(), result: checkTools() };
+  data.tools = tools.result;
+  view.data = data;
+  if (!once && (bell || notifier)) {
+    const fresh = takeNewlyWaiting(waitWatch, data.sessions);
+    if (fresh.length && bell) process.stdout.write('\x07');
+    notifier?.fire(fresh);
+  }
+  if (view.filter) keepSelectionVisible();
+  fixFocus(view);
+}
+
+function select(id) {
+  if (id !== view.selectedId) {
+    view.focus = null;
+    view.tab = 'now';
+  }
+  view.selectedId = id;
+  markSeen(attention, id);
+}
+
+if (once) {
+  refresh();
+  flushCache();
+  const size = (v) => (Number(v) > 0 ? Math.floor(Number(v)) : 0);
+  const W = process.stdout.columns || size(process.env.COLUMNS) || 140;
+  const H = process.stdout.rows || size(process.env.LINES) || 40;
+  await printAndExit(args.has('--json') ? JSON.stringify(toJson(view.data, VERSION, { showRequests, budgetDay: opt.budgetDay }), null, 2) : render(view, W, H).join('\n'));
+}
+
+const out = process.stdout;
+const stdin = process.stdin;
+let last = '';
+let lastTitle = '';
+// 스피너처럼 움직이는 표시가 있을 때만 120ms 마다 다시 그린다. 없으면 데이터 갱신·키 입력·창 크기 변경 때만 그린다.
+const frames = frameTimer({
+  ms: 120,
+  animating: () => animating(view),
+  onFrame: () => {
+    view.frame++;
+    draw();
+  },
+});
+
+function draw() {
+  frames.sync();
+  view.rows = out.rows;
+  const frame = render(view, out.columns, out.rows).join('\r\n');
+  const title = windowTitle(view.data?.sessions ?? [], BRAND.tab);
+  if (title !== lastTitle) {
+    lastTitle = title;
+    out.write(`\x1b]0;${title}\x07`);
+    // WezTerm 탭 제목에서 읽을 수 있게 같은 수를 user var 로도 내보낸다.
+    if (BRAND.userVars) out.write(userVarsSeq(attentionCounts(view.data?.sessions ?? [])));
+  }
+  if (frame === last) return;
+  last = frame;
+  out.write('\x1b[?2026h\x1b[H' + frame + '\x1b[?2026l');
+}
+
+function enterScreen() {
+  // 창 제목을 저장해 두었다가 끝낼 때 되돌린다 (지원하지 않는 터미널은 무시한다).
+  out.write('\x1b[22;0t\x1b[?1049h\x1b[?25l\x1b[2J');
+  lastTitle = '';
+  stdin.setRawMode(true);
+  stdin.resume();
+  last = '';
+}
+
+function leaveScreen() {
+  out.write('\x1b[0m\x1b[?25h\x1b[?1049l\x1b[23;0t' + (BRAND.userVars ? userVarsSeq(null) : ''));
+  if (stdin.isTTY) stdin.setRawMode(false);
+}
+
+restore = () => {
+  notifier?.killAll();
+  leaveScreen();
+  flushCache();
+};
+
+function quit() {
+  notifier?.killAll();
+  leaveScreen();
+  flushCache();
+  process.exit(0);
+}
+
+enterScreen();
+draw();
+process.on('SIGINT', quit);
+process.on('SIGTERM', quit);
+process.on('SIGHUP', quit);
+process.on('SIGQUIT', quit);
+process.on('SIGCONT', () => {
+  enterScreen();
+  draw();
+});
+process.on('uncaughtException', (err) => {
+  debug('aitop', 'uncaughtException', err);
+  notifier?.killAll();
+  leaveScreen();
+  try {
+    flushCache();
+  } catch {}
+  console.error(err);
+  process.exit(1);
+});
+out.on('resize', () => {
+  last = '';
+  out.write('\x1b[2J');
+  draw();
+});
+
+// 화면에 그린 순서 그대로 (정렬·묶기 반영). ↑↓ 와 n 이 이 순서를 따른다.
+const visible = () => arrange(filterSessions(view.data?.sessions ?? [], view.filter), view).sessions;
+
+function move(delta) {
+  const list = visible();
+  if (!list.length) return;
+  const i = Math.max(0, list.findIndex((s) => s.id === view.selectedId));
+  goTo(list[Math.min(list.length - 1, Math.max(0, i + delta))]);
+}
+
+function goTo(next) {
+  if (!next) return;
+  select(next.id);
+  // 아직 본문을 읽지 않은 종료 세션을 고르면 다음 갱신을 기다리지 않고 바로 읽는다. 그 밖에는 전체 갱신 없이 화면만 바꾼다.
+  if (next.lazy) return refresh();
+  if (next.unseen) view.data.sessions = view.data.sessions.map((s) => (s.id === next.id ? s.plain : s));
+}
+
+function keepSelectionVisible() {
+  const list = visible();
+  if (list.length && !list.some((s) => s.id === view.selectedId)) select(list[0].id);
+}
+
+stdin.setEncoding('utf8');
+const act = {
+  quit,
+  refresh,
+  move,
+  next: () => goTo(nextAttention(attention, visible(), view.selectedId)),
+  keepVisible: keepSelectionVisible,
+};
+
+stdin.on('data', (key) => {
+  onKey(view, key, act);
+  draw();
+});
+
+let lastFlush = 0;
+function tick() {
+  refresh();
+  const more = view.data?.more;
+  if (more ? Date.now() - lastFlush > LOADING_FLUSH_MS : Date.now() - lastFlush > 15_000) {
+    flushCache();
+    lastFlush = Date.now();
+  }
+  draw();
+  setTimeout(tick, more ? CATCH_UP_MS : 1000);
+}
+
+setTimeout(tick, 30);

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@sejuneoh/aitop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.21.2",
+  "description": "터미널에서 Claude Code · Codex · Antigravity · Gemini 세션과 토큰을 실시간으로 보는 읽기 전용 모니터",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "aitop": "bin/aitop.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "homepage": "https://github.com/SejuneOh/aitop#readme",
+  "bugs": "https://github.com/SejuneOh/aitop/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SejuneOh/aitop.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node bin/aitop.mjs",
+    "test": "node --test test/*.test.mjs",
+    "test:e2e": "node --test test/e2e/*.e2e.mjs"
+  }
+}

package/src/attention.mjs

@@ -0,0 +1,70 @@
+// "끝났는데 아직 안 본" 세션 추적. aitop 메모리에만 두고 파일에는 쓰지 않는다.
+// 작업 중(busy·shell)이던 세션이 대기(idle)로 바뀌었는데 그때 선택돼 있지 않았으면 확인 전으로 본다.
+
+export function createAttention() {
+  return { prev: new Map(), unseen: new Set() };
+}
+
+export function updateAttention(state, sessions, selectedId) {
+  const ids = new Set();
+  for (const s of sessions) {
+    ids.add(s.id);
+    const before = state.prev.get(s.id);
+    // 상태를 기록 수정 시각으로 추측한 세션(statusGuessed)은, 작업이 아닌 줄이 붙어도 잠깐 작업 중으로 보이므로 확인 전으로 치지 않는다.
+    if (s.id === selectedId || s.status === 'busy' || s.status === 'shell' || !s.live) state.unseen.delete(s.id);
+    else if ((before === 'busy' || before === 'shell') && s.status === 'idle' && !s.statusGuessed) state.unseen.add(s.id);
+    state.prev.set(s.id, s.status);
+  }
+  for (const id of state.prev.keys()) if (!ids.has(id)) state.prev.delete(id);
+  for (const id of state.unseen) if (!ids.has(id)) state.unseen.delete(id);
+}
+
+export function markSeen(state, id) {
+  state.unseen.delete(id);
+}
+
+// 다음에 봐야 할 세션: 지금 선택한 세션은 빼고, 그 다음 것부터 한 바퀴 돌며 응답 대기 → 확인 전 순서로 찾는다.
+// 선택이 목록에 없으면(검색으로 가려짐 등) 맨 위부터 찾는다.
+export function nextAttention(state, sessions, selectedId) {
+  const at = sessions.findIndex((s) => s.id === selectedId);
+  const ordered = at < 0 ? sessions : [...sessions.slice(at + 1), ...sessions.slice(0, at)];
+  return ordered.find((s) => s.status === 'waiting') ?? ordered.find((s) => state.unseen.has(s.id)) ?? null;
+}
+
+// 응답 대기(◆)와 확인 전(●) 수.
+export function attentionCounts(sessions) {
+  return { waiting: sessions.filter((s) => s.live && s.status === 'waiting').length, unseen: sessions.filter((s) => s.unseen).length };
+}
+
+// 창 제목: 맨 앞 아이콘(탭 사이에서 aitop 을 찾게) + 응답 대기·확인 전 수. 예: 󰚩 (2◆ 1●) aitop
+export function windowTitle(sessions, icon = '') {
+  const { waiting, unseen } = attentionCounts(sessions);
+  const marks = [waiting && `${waiting}◆`, unseen && `${unseen}●`].filter(Boolean);
+  return (icon ? icon + ' ' : '') + (marks.length ? `(${marks.join(' ')}) aitop` : 'aitop');
+}
+
+// 새로 응답 대기가 된 세션 목록. seen 은 지난번 응답 대기 세션 id 집합이며 여기서 갱신한다.
+export function freshWaiting(seen, sessions) {
+  const now = sessions.filter((s) => s.live && s.status === 'waiting');
+  const fresh = now.filter((s) => !seen.has(s.id));
+  seen.clear();
+  for (const s of now) seen.add(s.id);
+  return fresh;
+}
+
+// 벨: 새로 응답 대기가 된 세션이 있을 때만 true.
+export function newlyWaiting(seen, sessions) {
+  return freshWaiting(seen, sessions).length > 0;
+}
+
+// --bell · --notify · --on-waiting 이 함께 쓰는 감시. 첫 갱신에서 이미 응답 대기인 세션은 알리지 않는다.
+export function createWaitWatch() {
+  return { seen: new Set(), ready: false };
+}
+
+export function takeNewlyWaiting(watch, sessions) {
+  const fresh = freshWaiting(watch.seen, sessions);
+  const ready = watch.ready;
+  watch.ready = true;
+  return ready ? fresh : [];
+}

package/src/brand.mjs

@@ -0,0 +1,30 @@
+// aitop 표식: 로고, 창·탭 아이콘, WezTerm 탭용 user var.
+// AITOP_ICONS 로 고른다.
+//   (없음)  로고 ⣠⣴⣾, 탭 아이콘은 Nerd Font 로봇(U+F06A9), WezTerm user var 를 내보낸다
+//   plain   Nerd 아이콘과 user var 를 끈다. 탭 아이콘은 로고의 마지막 막대 ⣾
+//   ascii   로고를 >_ai 로, 탭 아이콘 없음, user var 없음 (점자를 못 그리는 환경용)
+// 로고의 점자 글자는 동아시아 폭이 N 이라 한글 터미널에서도 늘 1칸이다.
+
+export function iconMode(env = process.env) {
+  return env.AITOP_ICONS === 'plain' || env.AITOP_ICONS === 'ascii' ? env.AITOP_ICONS : 'full';
+}
+
+export function brand(mode = iconMode()) {
+  if (mode === 'ascii') return { mode, logo: '>_ai', tab: '', userVars: false };
+  return {
+    mode,
+    logo: '⣠⣴⣾',
+    tab: mode === 'plain' ? '⣾' : '\u{F06A9}',
+    userVars: mode === 'full',
+  };
+}
+
+export const BRAND = brand();
+
+// WezTerm 탭 제목(format-tab-title)에서 pane.user_vars 로 읽는 값. 다른 터미널은 모르는 OSC 를 무시한다.
+// counts 가 null 이면 값을 지운다 (aitop 을 끝낼 때).
+export function userVarsSeq(counts) {
+  const set = (name, value) => `\x1b]1337;SetUserVar=${name}=${Buffer.from(value).toString('base64')}\x07`;
+  if (!counts) return set('aitop', '') + set('aitop_waiting', '') + set('aitop_unseen', '');
+  return set('aitop', '1') + set('aitop_waiting', String(counts.waiting)) + set('aitop_unseen', String(counts.unseen));
+}

package/src/budget.mjs

@@ -0,0 +1,29 @@
+// 하루 예산(budgetDay): 오늘 비용에 최근 지출 속도 × 로컬 자정까지 남은 시간을 더해 오늘 끝의 비용을 어림한다.
+// 예산은 화면의 비용 기준(c 키)과 상관없이 늘 API 정가 환산으로 본다. 그래서 화면과 --json 의 단계가 같다.
+// 예상이 예산의 CAUTION 배 이상이면 'caution', 예산 이상이면 'warn'.
+
+export const CAUTION = 0.8;
+// 자정 뒤 이만큼이 지나기 전에는 속도를 믿지 않고 예상 = 오늘 비용.
+export const MIN_TODAY_MS = 15 * 60_000;
+
+// 지금부터 로컬 자정까지 남은 시간 (시간 단위).
+export function hoursToMidnight(now = Date.now()) {
+  const d = new Date(now);
+  const midnight = new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1).getTime();
+  return Math.max(0, (midnight - now) / 3600_000);
+}
+
+export const levelOf = (projected, day) => (projected >= day ? 'warn' : projected >= day * CAUTION ? 'caution' : 'ok');
+
+// usage: collect 의 사용량. recentToday 는 최근 1시간 중 오늘(로컬 자정 이후) 몫과 그 구간 길이(ms)다 (recentTodayOf).
+// 속도 = 그 몫을 시간당으로 늘린 값. 값이 없거나, 아직 집계 중이거나, 자정 뒤 15분이 안 됐으면 예상 = 오늘 비용.
+// 예산이 없거나 사용량이 없으면 null.
+export function projectBudget(usage, day, { now = Date.now() } = {}) {
+  if (!(typeof day === 'number' && day > 0) || !usage?.today) return null;
+  const r = usage.loading == null && usage.recentToday?.ms >= MIN_TODAY_MS ? usage.recentToday : null;
+  const spent = usage.today.cost ?? 0;
+  const perHour = r ? (r.cost ?? 0) / (r.ms / 3600_000) : 0;
+  const projected = spent + perHour * hoursToMidnight(now);
+  const unknown = Boolean(usage.today.unknown || r?.unknown);
+  return { day, spent, projected, unknown, level: levelOf(projected, day) };
+}