tktop 0.1.0__tar.gz

tktop-0.1.0/.env.example

@@ -0,0 +1,23 @@
+# Claude data directory (default: ~/.claude)
+# TKTOP_CLAUDE_DIR=~/.claude
+
+# LLM provider: ollama | anthropic | vertex | openai
+TKTOP_LLM_PROVIDER=ollama
+
+# Ollama settings
+TKTOP_OLLAMA_HOST=http://localhost:11434
+TKTOP_OLLAMA_MODEL=llama3
+
+# Anthropic settings (if using anthropic provider)
+# TKTOP_ANTHROPIC_API_KEY=sk-ant-...
+# TKTOP_ANTHROPIC_MODEL=claude-sonnet-4-6
+
+# Vertex AI settings (if using vertex provider)
+# TKTOP_VERTEX_PROJECT=my-project
+# TKTOP_VERTEX_REGION=us-central1
+# TKTOP_VERTEX_MODEL=claude-sonnet-4-6
+
+# OpenAI-compatible settings (if using openai provider)
+# TKTOP_OPENAI_BASE_URL=https://api.openai.com/v1
+# TKTOP_OPENAI_API_KEY=sk-...
+# TKTOP_OPENAI_MODEL=gpt-4o

tktop-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install tooling
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]" build
+
+      - name: Lint
+        run: ruff check src tests
+
+      - name: Security scan
+        run: bandit -r src/tktop/ -q
+
+      - name: Test
+        run: pytest -q
+
+      - name: Build distributions
+        run: python -m build

tktop-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

tktop-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# OS
+.DS_Store
+Thumbs.db
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment
+.env
+.env.*
+.devbox/
+
+# Build
+build/
+dist/
+out/
+
+# Dependencies
+node_modules/
+vendor/
+__pycache__/
+*.pyc
+
+# Binaries
+*.exe
+*.dll
+*.so
+*.dylib
+
+# Logs
+*.log
+
+# Python
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# PyInstaller
+*.spec
+
+# Don't ignore .env.example
+!.env.example

tktop-0.1.0/AGENTS.md

@@ -0,0 +1,60 @@
+# Codex Repository Instructions
+
+## Project
+
+`tktop` is a Python 3.13+ Textual TUI for monitoring token usage, cost, tools,
+and drift in coding-agent sessions. The current adapter reads Claude Code
+session metadata and JSONL transcripts from `~/.claude`.
+
+## Source Of Truth
+
+- Product and architecture specification: `docs/specs/2026-06-08-tktop-design.md`
+- Historical implementation record: `docs/plans/2026-06-08-tktop.md`
+- User-facing setup and usage: `README.md`
+
+The implementation record documents how the current code was built. Do not
+replay its completed tasks or embedded commit steps. For new work, inspect the
+current code and tests first, then update the specification when behavior or
+architecture changes.
+
+## Repository Layout
+
+- `src/tktop/adapter/`: coding-agent session adapters
+- `src/tktop/metrics/`: data models, aggregation, pricing, and drift detection
+- `src/tktop/llm/`: analysis prompts and provider integrations
+- `src/tktop/tui/`: Textual application, screens, widgets, and styles
+- `tests/`: unit and integration tests with local fixtures
+
+## Development Commands
+
+```bash
+make install
+make test
+make lint
+make security
+make check
+make run
+```
+
+Run focused tests while iterating, then run `make check` before committing.
+`make audit` performs the optional dependency vulnerability scan.
+
+## Engineering Conventions
+
+- Preserve the adapter and provider protocols when adding implementations.
+- Keep blocking file or network work out of the Textual UI event loop.
+- Handle malformed or missing external session data gracefully.
+- Add or update tests for behavior changes.
+- Keep Ruff compatibility with Python 3.13 and the configured 100-character
+  line length.
+- Never commit API keys, `.env`, local session data, or generated build output.
+- Do not modify files under `.git/`; local hooks are not portable project
+  configuration.
+
+## Documentation
+
+- Keep Claude-specific names when they describe supported product behavior,
+  model IDs, environment variables, or the Claude Code data format.
+- Keep agent workflow instructions vendor-neutral and compatible with Codex.
+- Use `docs/specs/` for current design documentation and `docs/plans/` for
+  implementation plans or historical execution records.

tktop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 K Hari Sankar
+
+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-0.1.0/Makefile

@@ -0,0 +1,34 @@
+.PHONY: install run test lint security audit check binary clean release
+
+install:
+	pip install -e ".[dev]"
+
+run:
+	python -m tktop.cli
+
+test:
+	pytest -v
+
+lint:
+	ruff check src/ tests/
+
+security:
+	bandit -r src/tktop/ -q
+
+audit:
+	pip-audit
+
+check: lint security test
+	@echo "✅ All checks passed."
+
+binary:
+	pyinstaller --onefile --name tktop --paths src src/tktop/cli.py --add-data "src/tktop/tui/styles.tcss:tktop/tui"
+	@echo "✅ Binary at dist/tktop ($(du -h dist/tktop | cut -f1))"
+
+clean:
+	rm -rf build/ dist/ *.egg-info src/*.egg-info *.spec
+	find . -type d -name __pycache__ -exec rm -rf {} +
+
+release:
+	@test -n "$(VERSION)" || (echo "VERSION is required, for example: make release VERSION=0.1.1"; exit 1)
+	python3 scripts/release.py "$(VERSION)"

tktop-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: tktop
+Version: 0.1.0
+Summary: Token monitor for coding agents — like htop for AI spend
+Project-URL: Homepage, https://github.com/chanilharisankar/tktop
+Project-URL: Repository, https://github.com/chanilharisankar/tktop
+Project-URL: Issues, https://github.com/chanilharisankar/tktop/issues
+Author: Harisan Sankar
+License: MIT License
+        
+        Copyright (c) 2026 K Hari Sankar
+        
+        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.
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: textual>=1.0.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: watchfiles>=0.21.0
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7.0; extra == 'dev'
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: pip-audit>=2.7.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tktop
+
+Token monitor for coding agents. Like `htop` for your AI spend.
+
+## Features
+
+- **Live dashboard** — real-time token usage breakdown (input/output/cache)
+- **Token flow graph** — sparkline showing output tokens per turn
+- **Tool stats** — see which tools consume the most calls
+- **Drift detection** — 9 algorithms detecting loops, thrashing, runaway sessions
+- **Cost tracking** — per-session cost estimates by model
+- **Turn drill-down** — inspect individual turns with token split and content preview
+- **LLM analysis** — on-demand optimization suggestions via Ollama/Anthropic/Vertex AI/OpenAI
+
+## Install
+
+```bash
+# From PyPI
+pip install tktop
+
+# Upgrade to the latest release
+pip install -U tktop
+```
+
+## Usage
+
+```bash
+tktop              # launch interactive session list
+```
+
+### Keybindings
+
+| Key | Action |
+|-----|--------|
+| `↑/↓` or `j/k` | Navigate |
+| `enter` | Select / drill-down |
+| `a` | Run LLM analysis |
+| `r` | Refresh |
+| `escape` | Back |
+| `q` | Quit |
+
+## Supported Agents
+
+- [x] Claude Code
+- [x] Codex
+- [ ] Cursor (planned)
+- [ ] Aider (planned)
+
+## LLM Analysis
+
+Copy `.env.example` to `.env` and configure:
+
+```bash
+cp .env.example .env
+# Edit .env with your provider settings
+```
+
+Supported providers: `ollama` (default), `anthropic`, `vertex`, `openai`
+
+## Development
+
+```bash
+make install  # install in dev mode
+make test     # run tests
+make clean    # clean build artifacts
+```
+
+Local development still uses an editable install:
+
+```bash
+pip install -e ".[dev]"
+```
+
+For maintainers, a versioned release can be prepared with:
+
+```bash
+make release VERSION=0.1.1
+```
+
+### Devbox
+
+If you have the Devbox CLI installed, you can bootstrap the repo with:
+
+```bash
+devbox shell
+```
+
+On first entry, the shell creates `.venv`, installs `.[dev]`, and activates the
+environment for the session.
+
+License: MIT. See [LICENSE](LICENSE).
+
+Repository instructions for Codex are in [`AGENTS.md`](AGENTS.md). The current
+design is documented in
+[`docs/specs/2026-06-08-tktop-design.md`](docs/specs/2026-06-08-tktop-design.md).

tktop-0.1.0/README.md

@@ -0,0 +1,95 @@
+# tktop
+
+Token monitor for coding agents. Like `htop` for your AI spend.
+
+## Features
+
+- **Live dashboard** — real-time token usage breakdown (input/output/cache)
+- **Token flow graph** — sparkline showing output tokens per turn
+- **Tool stats** — see which tools consume the most calls
+- **Drift detection** — 9 algorithms detecting loops, thrashing, runaway sessions
+- **Cost tracking** — per-session cost estimates by model
+- **Turn drill-down** — inspect individual turns with token split and content preview
+- **LLM analysis** — on-demand optimization suggestions via Ollama/Anthropic/Vertex AI/OpenAI
+
+## Install
+
+```bash
+# From PyPI
+pip install tktop
+
+# Upgrade to the latest release
+pip install -U tktop
+```
+
+## Usage
+
+```bash
+tktop              # launch interactive session list
+```
+
+### Keybindings
+
+| Key | Action |
+|-----|--------|
+| `↑/↓` or `j/k` | Navigate |
+| `enter` | Select / drill-down |
+| `a` | Run LLM analysis |
+| `r` | Refresh |
+| `escape` | Back |
+| `q` | Quit |
+
+## Supported Agents
+
+- [x] Claude Code
+- [x] Codex
+- [ ] Cursor (planned)
+- [ ] Aider (planned)
+
+## LLM Analysis
+
+Copy `.env.example` to `.env` and configure:
+
+```bash
+cp .env.example .env
+# Edit .env with your provider settings
+```
+
+Supported providers: `ollama` (default), `anthropic`, `vertex`, `openai`
+
+## Development
+
+```bash
+make install  # install in dev mode
+make test     # run tests
+make clean    # clean build artifacts
+```
+
+Local development still uses an editable install:
+
+```bash
+pip install -e ".[dev]"
+```
+
+For maintainers, a versioned release can be prepared with:
+
+```bash
+make release VERSION=0.1.1
+```
+
+### Devbox
+
+If you have the Devbox CLI installed, you can bootstrap the repo with:
+
+```bash
+devbox shell
+```
+
+On first entry, the shell creates `.venv`, installs `.[dev]`, and activates the
+environment for the session.
+
+License: MIT. See [LICENSE](LICENSE).
+
+Repository instructions for Codex are in [`AGENTS.md`](AGENTS.md). The current
+design is documented in
+[`docs/specs/2026-06-08-tktop-design.md`](docs/specs/2026-06-08-tktop-design.md).

tktop-0.1.0/devbox.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/main/.devbox.schema.json",
+  "packages": [
+    "python@3.13",
+    "git",
+    "uv"
+  ],
+  "shell": {
+    "init_hook": "if [ ! -f .venv/.tktop-devbox-ready ]; then\n  python -m venv .venv\n  . .venv/bin/activate\n  python -m pip install --upgrade pip\n  python -m pip install -e \".[dev]\"\n  touch .venv/.tktop-devbox-ready\nfi\n. .venv/bin/activate\n",
+    "scripts": {
+      "check": "make check",
+      "lint": "make lint",
+      "test": "make test"
+    }
+  }
+}