tktop-tui 0.3.0__py3-none-any.whl

tktop_tui/__init__.py

@@ -0,0 +1,72 @@
+"""tktop-tui: Python launcher for the tktop TUI.
+
+`pip install tktop-tui` gives you the `tktop` command. The wheel bundles the
+TypeScript TUI (src/ + bin/); on first run it is staged into a user cache dir
+(~/.local/share/tktop/<version>) where `bun install` fetches its JavaScript
+dependencies, then the TUI is exec'd under Bun. Read-only site-packages are
+never touched.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from importlib.resources import as_file, files
+from pathlib import Path
+
+VERSION = "0.3.0"
+HOMEPAGE = "https://github.com/AlexKay28/tktop"
+
+
+def find_bun() -> str | None:
+    """Locate bun on PATH or in its default install location."""
+    found = shutil.which("bun")
+    if found:
+        return found
+    default = Path.home() / ".bun" / "bin" / "bun"
+    return str(default) if default.is_file() and os.access(default, os.X_OK) else None
+
+
+def stage_tui() -> Path:
+    """Copy the bundled TUI into a per-version cache dir (once per version)."""
+    base = Path.home() / ".local" / "share" / "tktop" / VERSION
+    marker = base / ".installed"
+    if marker.is_file():
+        return base
+    if base.exists():
+        shutil.rmtree(base)
+    base.parent.mkdir(parents=True, exist_ok=True)
+    src = files("tktop_tui").joinpath("tui")
+    with as_file(src) as src_path:
+        shutil.copytree(src_path, base)
+    marker.write_text("staged\n")
+    return base
+
+
+def main() -> None:
+    bun = find_bun()
+    if not bun:
+        print("tktop: bun is required but not installed.", file=sys.stderr)
+        print("  install it with: curl -fsSL https://bun.sh/install | bash", file=sys.stderr)
+        print(f"  project: {HOMEPAGE}", file=sys.stderr)
+        raise SystemExit(1)
+
+    tui = stage_tui()
+
+    # fetch JS dependencies once per staged version (needs network on first run)
+    if not (tui / "node_modules").is_dir():
+        pkg = json.loads((tui / "package.json").read_text())
+        pkg.pop("devDependencies", None)  # @types/bun is not needed at runtime
+        pkg.get("scripts", {}).pop("prepublishOnly", None)
+        (tui / "package.json").write_text(json.dumps(pkg))
+        r = subprocess.run([bun, "install", "--production"], cwd=tui)
+        if r.returncode != 0:
+            print("tktop: bun install failed (network reachable?).", file=sys.stderr)
+            raise SystemExit(1)
+
+    os.execv(bun, [bun, "run", str(tui / "src" / "index.ts"), *sys.argv[1:]])
+
+
+if __name__ == "__main__":
+    main()

tktop_tui/tui/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AlexKay28
+
+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.

tktop_tui/tui/bin/tktop

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# tktop launcher — runs the TUI via Bun.
+# Resolves the repo root from this script's own location, so the shim works
+# from ~/.local/bin (symlinked anywhere) and survives repo moves.
+set -eu
+
+REPO_ROOT="$(cd "$(dirname "$(readlink -f "$0")")/.." && pwd)"
+export PATH="$HOME/.bun/bin:$PATH"
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "tktop: bun is required but not installed." >&2
+  echo "  install it with: curl -fsSL https://bun.sh/install | bash" >&2
+  exit 1
+fi
+
+exec bun run "$REPO_ROOT/src/index.ts" "$@"

tktop_tui/tui/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "tktop",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "Live htop-style TUI dashboard for AI token consumption across harnesses (OpenCode, Claude Code, Codex, generic JSONL)",
+  "keywords": [
+    "cli",
+    "tui",
+    "tokens",
+    "llm",
+    "ai",
+    "monitoring",
+    "opentui",
+    "htop"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/AlexKay28/tktop.git"
+  },
+  "bin": {
+    "tktop": "bin/tktop"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "tktop": "bun run src/index.ts",
+    "dump": "bun run src/dump.ts",
+    "typecheck": "bun check",
+    "prepublishOnly": "bun run typecheck"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.8.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

tktop_tui/tui/src/adapters/claude-code.ts

@@ -0,0 +1,143 @@
+/**
+ * Claude Code adapter — additive parsing of JSONL files under ~/.claude/projects.
+ * Auto-activates when ~/.claude exists. See docs/ADR-003 for caveats.
+ */
+import { existsSync } from "node:fs"
+import { homedir } from "node:os"
+import type { Adapter, SessionInfo, TokenCounts } from "../types"
+import { JsonlTail } from "./jsonl-tail"
+
+interface Acc {
+  id: string
+  title: string
+  directory: string
+  model: string
+  tokens: TokenCounts
+  cost: number
+  timeCreated: number
+  timeUpdated: number
+}
+
+function newAcc(id: string): Acc {
+  return {
+    id,
+    title: "",
+    directory: "",
+    model: "-",
+    tokens: { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 },
+    cost: 0,
+    timeCreated: 0,
+    timeUpdated: 0,
+  }
+}
+
+export class ClaudeCodeAdapter implements Adapter {
+  readonly harness = "claude-code"
+  lastError: string | null = null
+
+  private root: string
+  private tail: JsonlTail
+  private accs = new Map<string, Acc>()
+  private started = false
+
+  constructor(root?: string) {
+    this.root = root ?? `${homedir()}/.claude/projects`
+    this.tail = new JsonlTail(`${this.root}/**/*.jsonl`)
+  }
+
+  available(): boolean {
+    return existsSync(this.root)
+  }
+
+  private sid(obj: any, path: string): string {
+    if (obj.sessionId) return String(obj.sessionId)
+    const m = path.match(/([0-9a-f-]{36})(?:\.jsonl)?$/i)
+    if (m?.[1]) return m[1]
+    return path
+  }
+
+  poll(): SessionInfo[] {
+    try {
+      if (!this.started) {
+        this.tail.refreshFiles()
+        this.started = true
+      } else if (this.accs.size === 0 || Math.random() < 0.05) {
+        // occasionally re-scan for new project files
+        this.tail.refreshFiles()
+      }
+
+      this.tail.read((obj, path) => this.onLine(obj, path))
+
+      const out: SessionInfo[] = []
+      for (const [sid, a] of this.accs) {
+        out.push({
+          key: `${this.harness}:${sid}`,
+          harness: this.harness,
+          id: sid,
+          title: a.title || (a.directory ? a.directory.split("/").filter(Boolean).pop() || sid.slice(0, 12) : sid.slice(0, 12)),
+          directory: a.directory,
+          model: a.model || "-",
+          archived: false,
+          tokens: a.tokens,
+          cost: a.cost,
+          timeCreated: a.timeCreated || a.timeUpdated,
+          timeUpdated: a.timeUpdated,
+        })
+      }
+      this.lastError = null
+      return out
+    } catch (e) {
+      this.lastError = (e as Error).message
+      return []
+    }
+  }
+
+  private onLine(obj: any, path: string): void {
+    if (!obj || typeof obj !== "object") return
+    const sid = this.sid(obj, path)
+    let acc = this.accs.get(sid)
+    if (!acc) {
+      acc = newAcc(sid)
+      this.accs.set(sid, acc)
+    }
+
+    const ts = obj.timestamp ? (typeof obj.timestamp === "number" ? obj.timestamp : Date.parse(obj.timestamp)) : 0
+    if (ts > acc.timeUpdated) acc.timeUpdated = ts
+    if (acc.timeCreated === 0 || (ts > 0 && ts < acc.timeCreated)) acc.timeCreated = ts
+    if (obj.cwd) acc.directory = String(obj.cwd)
+
+    if (obj.type === "summary" && obj.summary) {
+      if (!acc.title) acc.title = String(obj.summary)
+      return
+    }
+
+    const msg = obj.message
+    if (!msg || typeof msg !== "object") return
+
+    if (obj.type === "user" && !acc.title) {
+      const c = msg.content
+      const text =
+        typeof c === "string"
+          ? c
+          : Array.isArray(c)
+            ? (c.find((p: any) => p?.type === "text")?.text ?? "")
+            : ""
+      if (text) acc.title = text.replace(/\s+/g, " ").slice(0, 80)
+      return
+    }
+
+    if (obj.type === "assistant") {
+      if (msg.model) acc.model = String(msg.model)
+      const u = msg.usage
+      if (u && typeof u === "object") {
+        acc.tokens.input += u.input_tokens ?? 0
+        acc.tokens.output += u.output_tokens ?? 0
+        acc.tokens.cacheRead += u.cache_read_input_tokens ?? 0
+        acc.tokens.cacheWrite += u.cache_creation_input_tokens ?? 0
+        // some history formats fold reasoning into output; record if present
+        acc.tokens.reasoning += u.reasoning_tokens ?? 0
+      }
+      if (typeof obj.costUSD === "number") acc.cost += obj.costUSD
+    }
+  }
+}

tktop_tui/tui/src/adapters/codex.ts

@@ -0,0 +1,131 @@
+/**
+ * Codex CLI adapter — cumulative token_count events in
+ * ~/.codex/sessions JSONL files ("latest" semantics). See docs/ADR-003.
+ */
+import { existsSync } from "node:fs"
+import { homedir } from "node:os"
+import type { Adapter, SessionInfo, TokenCounts } from "../types"
+import { JsonlTail } from "./jsonl-tail"
+
+interface Acc {
+  id: string
+  title: string
+  directory: string
+  model: string
+  tokens: TokenCounts
+  cost: number
+  timeCreated: number
+  timeUpdated: number
+}
+
+function newAcc(id: string): Acc {
+  return {
+    id,
+    title: "",
+    directory: "",
+    model: "-",
+    tokens: { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 },
+    cost: 0,
+    timeCreated: 0,
+    timeUpdated: 0,
+  }
+}
+
+export class CodexAdapter implements Adapter {
+  readonly harness = "codex"
+  lastError: string | null = null
+
+  private root: string
+  private tail: JsonlTail
+  private accs = new Map<string, Acc>()
+  private started = false
+
+  constructor(root?: string) {
+    this.root = root ?? `${homedir()}/.codex/sessions`
+    this.tail = new JsonlTail(`${this.root}/**/*.jsonl`)
+  }
+
+  available(): boolean {
+    return existsSync(this.root)
+  }
+
+  poll(): SessionInfo[] {
+    try {
+      if (!this.started) {
+        this.tail.refreshFiles()
+        this.started = true
+      } else if (Math.random() < 0.05) {
+        this.tail.refreshFiles()
+      }
+      this.tail.read((obj, path) => this.onLine(obj, path))
+
+      const out: SessionInfo[] = []
+      for (const [sid, a] of this.accs) {
+        out.push({
+          key: `${this.harness}:${sid}`,
+          harness: this.harness,
+          id: sid,
+          title: a.title || sid.slice(0, 12),
+          directory: a.directory,
+          model: a.model || "-",
+          archived: false,
+          tokens: { ...a.tokens },
+          cost: a.cost,
+          timeCreated: a.timeCreated || a.timeUpdated,
+          timeUpdated: a.timeUpdated,
+        })
+      }
+      this.lastError = null
+      return out
+    } catch (e) {
+      this.lastError = (e as Error).message
+      return []
+    }
+  }
+
+  private onLine(obj: any, path: string): void {
+    if (!obj || typeof obj !== "object") return
+    const payload = obj.payload
+
+    // session id: prefer payload.session_meta.id, else file stem
+    let sid: string | null = null
+    if (payload?.type === "session_meta" && payload.id) sid = String(payload.id)
+    if (!sid) {
+      const m = path.match(/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i)
+      if (m?.[1]) sid = m[1]
+    }
+    if (!sid) return
+
+    let acc = this.accs.get(sid)
+    if (!acc) {
+      acc = newAcc(sid)
+      this.accs.set(sid, acc)
+    }
+
+    const ts = obj.timestamp ? (typeof obj.timestamp === "number" ? obj.timestamp : Date.parse(obj.timestamp)) : 0
+    if (ts > acc.timeUpdated) acc.timeUpdated = ts
+    if (acc.timeCreated === 0 || (ts > 0 && ts < acc.timeCreated)) acc.timeCreated = ts
+
+    const p = payload ?? {}
+    if (p.cwd) acc.directory = String(p.cwd)
+    if (p.model) acc.model = String(p.model)
+
+    if (p.type === "token_count") {
+      const info = p.info ?? p
+      // cumulative totals: overwrite, never sum
+      const total = info.total_token_usage ?? info.totalTokenUsage ?? info.usage
+      if (total && typeof total === "object") {
+        const pick = (...names: string[]): number => {
+          for (const n of names) if (typeof total[n] === "number") return total[n]
+          return 0
+        }
+        acc.tokens.input = pick("input_tokens", "inputTokens", "input")
+        acc.tokens.cacheRead = pick("cached_input_tokens", "cachedInputTokens", "cache_read", "cached")
+        acc.tokens.output = pick("output_tokens", "outputTokens", "output")
+        acc.tokens.reasoning = pick("reasoning_output_tokens", "reasoning_tokens", "reasoningOutputTokens", "reasoning")
+      }
+    } else if (p.type === "turn_context" && p.model) {
+      acc.model = String(p.model)
+    }
+  }
+}

tktop_tui/tui/src/adapters/generic-jsonl.ts

@@ -0,0 +1,170 @@
+/**
+ * Generic JSONL adapter — operator-declared sources via
+ * ~/.config/tktop/adapters.json. See docs/ADR-003 for the config schema.
+ */
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import type { Adapter, SessionInfo, TokenCounts } from "../types"
+import { JsonlTail } from "./jsonl-tail"
+
+/** Resolve dotted path "a.b.c" against an object; undefined when missing. */
+function dig(obj: any, path: string | undefined): any {
+  if (!path) return undefined
+  let cur = obj
+  for (const seg of path.split(".")) {
+    if (cur == null || typeof cur !== "object") return undefined
+    cur = cur[seg]
+  }
+  return cur
+}
+
+function toTime(v: any): number {
+  if (v == null) return 0
+  if (typeof v === "number") return v < 1e12 ? v * 1000 : v
+  const t = Date.parse(String(v))
+  return Number.isNaN(t) ? 0 : t
+}
+
+export interface GenericSourceConfig {
+  harness: string
+  glob: string
+  sessionId?: string
+  model?: string
+  title?: string
+  directory?: string
+  timeUpdated?: string
+  usage?: string
+  tokens?: Partial<Record<keyof TokenCounts, string>>
+  cost?: string
+  mode?: "additive" | "latest"
+}
+
+interface Acc {
+  id: string
+  model: string
+  title: string
+  directory: string
+  tokens: TokenCounts
+  cost: number
+  timeUpdated: number
+}
+
+export function loadGenericConfig(path?: string): GenericSourceConfig[] {
+  const p = path ?? `${homedir()}/.config/tktop/adapters.json`
+  if (!existsSync(p)) return []
+  try {
+    const raw = JSON.parse(readFileSync(p, "utf8"))
+    return Array.isArray(raw?.sources) ? (raw.sources as GenericSourceConfig[]) : []
+  } catch {
+    return []
+  }
+}
+
+export class GenericJsonlAdapter implements Adapter {
+  lastError: string | null = null
+
+  readonly harness: string
+  private tail: JsonlTail
+  private accs = new Map<string, Acc>()
+  private additive: boolean
+  private started = false
+
+  constructor(private cfg: GenericSourceConfig) {
+    this.harness = cfg.harness || "generic"
+    this.tail = new JsonlTail(cfg.glob)
+    this.additive = (cfg.mode ?? "additive") === "additive"
+  }
+
+  available(): boolean {
+    this.tail.refreshFiles()
+    return this.tail.filePaths.length > 0
+  }
+
+  poll(): SessionInfo[] {
+    try {
+      if (!this.started) {
+        this.tail.refreshFiles()
+        this.started = true
+      } else {
+        this.tail.refreshFiles() // cheap enough for operator-defined source counts
+      }
+      this.tail.read((obj, path) => this.onLine(obj, path))
+
+      const out: SessionInfo[] = []
+      for (const [sid, a] of this.accs) {
+        out.push({
+          key: `${this.harness}:${sid}`,
+          harness: this.harness,
+          id: sid,
+          title: a.title || sid.slice(0, 12),
+          directory: a.directory,
+          model: a.model || "-",
+          archived: false,
+          tokens: { ...a.tokens },
+          cost: a.cost,
+          timeCreated: a.timeUpdated,
+          timeUpdated: a.timeUpdated,
+        })
+      }
+      this.lastError = null
+      return out
+    } catch (e) {
+      this.lastError = (e as Error).message
+      return []
+    }
+  }
+
+  private onLine(obj: any, path: string): void {
+    if (!obj || typeof obj !== "object") return
+    const sid = String(dig(obj, this.cfg.sessionId) ?? path)
+    let acc = this.accs.get(sid)
+    if (!acc) {
+      acc = {
+        id: sid,
+        model: "",
+        title: "",
+        directory: "",
+        tokens: { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 },
+        cost: 0,
+        timeUpdated: 0,
+      }
+      this.accs.set(sid, acc)
+    }
+
+    if (this.cfg.model) {
+      const m = dig(obj, this.cfg.model)
+      if (m != null) acc.model = String(m)
+    }
+    if (this.cfg.title && !acc.title) {
+      const t = dig(obj, this.cfg.title)
+      if (t != null) acc.title = String(t).replace(/\s+/g, " ").slice(0, 80)
+    }
+    if (this.cfg.directory) {
+      const d = dig(obj, this.cfg.directory)
+      if (d != null) acc.directory = String(d)
+    }
+    const ts = toTime(dig(obj, this.cfg.timeUpdated))
+    if (ts > acc.timeUpdated) acc.timeUpdated = ts
+
+    const usage = this.cfg.usage ? dig(obj, this.cfg.usage) : obj
+    if (usage && typeof usage === "object") {
+      const map = this.cfg.tokens ?? {}
+      const keys: (keyof TokenCounts)[] = ["input", "output", "reasoning", "cacheRead", "cacheWrite"]
+      for (const k of keys) {
+        const field = map[k] ?? k
+        const v = dig(usage, field as string)
+        if (typeof v === "number") {
+          if (this.additive) acc.tokens[k] += v
+          else acc.tokens[k] = v
+        }
+      }
+    }
+    if (this.cfg.cost) {
+      const c = dig(obj, this.cfg.cost)
+      if (typeof c === "number") {
+        if (this.additive) acc.cost += c
+        else acc.cost = c
+      }
+    }
+  }
+}