🧠 Cognitally

Sovereign AI Coding Agent Observability & Token Cost Ledger for Linux / Ubuntu
(Formerly TokDash — evolved with Stdio MCP Server & Single-Flight Streaming)

Real-time token throughput, prompt caching, quota tracking, and read-only MCP control plane for AI coding agents.

English | 简体中文

📖 Overview

Cognitally (from Cognitive + Tally) is a local-first, low-overhead desktop observatory, CLI tool, and standard Model Context Protocol (MCP) server for developers using autonomous AI coding tools. It performs passive, zero-leakage local log parsing across 14 mainstream coding agents to provide mathematical certainty into token volume, cache reads, cost provenance, subscription quotas, and project attribution.

Automatic seamless one-time migration is supported from legacy ~/.config/tokdash and ~/.tokei.

Related MCP server: ai-usage-mcp

✨ Features

• 🔌 Read-Only Stdio MCP Server (cognitally --mcp): Native support for the MCP specification (2024-11-05). Claude Code, Cursor, Codex, and OpenCode can query current token consumption, quotas, and costs directly via 6 strictly read-only tools (get_usage, get_cost, get_quota, get_projects, get_models, get_accounting_status).

• ⚡ Single-Flight Refresh & Streaming Engine: Shared flock-protected canonical snapshots prevent redundant concurrent parsing and eliminate memory spikes on live rollouts.

• 🔒 Local-First & Transparent Privacy: Reads local session transcripts and SQLite/JSONL cache files on your disk for passive accounting. No prompts, code, or context logs are uploaded to third-party telemetry servers.

• 📤 Canonical Export (cognitally --export json/csv): Export deterministic, schema-versioned token and cost datasets to JSON or CSV.

• ⚡ Full Token Metrics Breakdown: Distinguishes Prompt Input, Completion Output, and Cache Reads, avoiding cache-token double counting.

• 💰 Configurable Cost Estimation: Uses OpenRouter's model pricing catalog (pricing.json) together with customizable local rate overrides (pricing_overrides.json) for private endpoints, discounts, and explicit pricing provenance.

• 📈 Two-Week Daily Expense Trend: Interactive daily bar chart with per-tool cost breakdowns on hover.

• 🤖 Multi-Agent Quota & Window Limits: Real-time quota countdowns for Antigravity (Google AI Pro), Codex Plus/Pro, Cursor Ultra, and Grok.

• 📂 Workspace & Project Tracking: Aggregates token spend and session counts per code repository and detects local listening ports.

• 🌓 Modern UI & System Tray: Frameless dark/light mode with a native Ubuntu system tray icon, minimize-to-tray behavior, and hotkey toggling.

🛠️ Supported AI Coding Agents

Cognitally passively inspects standard local session logs in read-only mode and does not act as an interception proxy.

Design Note: Cognitally explicitly focuses on these 14 first-class production AI coding agents, ensuring rock-solid ingestion pipelines and strict mathematical reconciliation. Peripheral niche tools are de-emphasized.

🚀 Quick Start

Prerequisites

• Ubuntu / Debian Linux (20.04+)

• Node.js >= 22.12.0

• Python >= 3.10

• npm (Node ≥22.12). pnpm optional if corepack works on your machine

Installation & Launch

# 1. Clone the repository
git clone https://github.com/kamanager2012/tokdash.git
cd tokdash

# 2. Run the automated installer
#    (installs dependencies, builds UI, and creates 'cognitally' CLI + desktop launcher)
chmod +x install.sh
./install.sh

# 3. CLI & Desktop Usage
cognitally --doctor       # Run system & 14-agent health check
cognitally --mcp          # Launch standard Stdio MCP server for Claude Code / Codex / Cursor
cognitally --export json  # Export canonical snapshot to JSON
cognitally --export csv   # Export daily model breakdown to CSV
./start.sh                # Launch frameless Linux desktop observatory

Desktop Launcher: After running install.sh, press Super (Windows key) on Ubuntu, search for Cognitally, and launch it from the application menu.

Development Mode

# Install dependencies
npm install

# Start the Vite development server
npm run dev

# In another terminal, run Electron against the development server
npm start

🤝 Contributing

Contributions, issues, and feature requests are welcome.

Please read the Contributing Guide and Code of Conduct.

📄 License & Acknowledgements

• Licensed under the MIT License.

• Special thanks to @cclank for the original macOS tokei concept.