tktop-tui 0.3.0__tar.gz

tktop_tui-0.3.0/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-0.3.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: tktop-tui
+Version: 0.3.0
+Summary: Live htop-style TUI dashboard for AI token consumption across coding agents (OpenCode, Claude Code, Codex, generic JSONL). Python wrapper that launches the tktop TUI via Bun.
+Author: AlexKay28
+License: 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.
+        
+Project-URL: Homepage, https://github.com/AlexKay28/tktop
+Project-URL: Repository, https://github.com/AlexKay28/tktop
+Keywords: cli,tui,ai,llm,tokens,monitoring,htop
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# tktop-tui
+
+Python launcher for **tktop** — the live htop-style TUI dashboard for AI token
+consumption across coding agents (OpenCode, Claude Code, Codex, generic JSONL).
+
+```
+pip install tktop-tui
+tktop
+```
+
+The wheel bundles the TypeScript TUI. On first run it stages the app into
+`~/.local/share/tktop/<version>/`, runs `bun install` there (so read-only
+site-packages are never touched), and execs the TUI under
+[Bun](https://bun.sh) — install it first if you don't have it:
+
+```
+curl -fsSL https://bun.sh/install | bash
+```
+
+Requirements:
+
+- Python ≥ 3.10
+- Bun ≥ 1.1 (for the TUI runtime)
+- network on the very first launch only (to fetch `@opentui/core`)
+
+Features: per-session token/burn-rate table with mouse-clickable column
+sorting, live log-scale scatterplot (colored markers + trails), grouping,
+filtering, sparklines — all read-only, tktop never touches your harnesses.
+
+GitHub: <https://github.com/AlexKay28/tktop>

tktop_tui-0.3.0/README.md

@@ -0,0 +1,30 @@
+# tktop-tui
+
+Python launcher for **tktop** — the live htop-style TUI dashboard for AI token
+consumption across coding agents (OpenCode, Claude Code, Codex, generic JSONL).
+
+```
+pip install tktop-tui
+tktop
+```
+
+The wheel bundles the TypeScript TUI. On first run it stages the app into
+`~/.local/share/tktop/<version>/`, runs `bun install` there (so read-only
+site-packages are never touched), and execs the TUI under
+[Bun](https://bun.sh) — install it first if you don't have it:
+
+```
+curl -fsSL https://bun.sh/install | bash
+```
+
+Requirements:
+
+- Python ≥ 3.10
+- Bun ≥ 1.1 (for the TUI runtime)
+- network on the very first launch only (to fetch `@opentui/core`)
+
+Features: per-session token/burn-rate table with mouse-clickable column
+sorting, live log-scale scatterplot (colored markers + trails), grouping,
+filtering, sparklines — all read-only, tktop never touches your harnesses.
+
+GitHub: <https://github.com/AlexKay28/tktop>

tktop_tui-0.3.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tktop-tui"
+version = "0.3.0"
+description = "Live htop-style TUI dashboard for AI token consumption across coding agents (OpenCode, Claude Code, Codex, generic JSONL). Python wrapper that launches the tktop TUI via Bun."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "AlexKay28" }]
+keywords = ["cli", "tui", "ai", "llm", "tokens", "monitoring", "htop"]
+classifiers = [
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/AlexKay28/tktop"
+Repository = "https://github.com/AlexKay28/tktop"
+
+[project.scripts]
+tktop = "tktop_tui:main"
+
+[tool.setuptools]
+packages = ["tktop_tui"]
+
+[tool.setuptools.package-data]
+# the bundled TUI (staged here by python/sync.sh at build time)
+tktop_tui = ["tui/**/*"]

tktop_tui-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tktop_tui-0.3.0/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-0.3.0/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-0.3.0/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-0.3.0/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-0.3.0/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-0.3.0/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)
+    }
+  }
+}