Skip to main content
Glama

๐Ÿง  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.

License: MIT Platform MCP 2024-11-05 Electron React TypeScript Tailwind CSS

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.

Agent / Tool

Detection Target

Metrics Tracked

Claude Code

~/.claude/projects/ JSONL logs

Input, Output, Cache Read/Write, Turns & Estimated Cost

Codex CLI

~/.codex/ sessions

Tokens, Reasoning, Cache Reads, Estimated Cost

Grok Build

~/.tokei/ / ~/.cc-switch/

Real API tokens, live quotas, windows & cost

Grok Bot

~/.grok-bot/ / local logs

Bot interaction turns & token throughput

Cursor Composer

~/.config/Cursor/ auth

Monthly plan spend, auto-spend, % used & reset countdown

Antigravity / Gemini CLI

Local process & session store

Google AI Pro 5h rate limits, quotas & per-step tokens

Kimi Code

~/.kimi-code/ protocol logs

Agent turn tokens, model routing & cost

DeepSeek Harness

~/.dsh/ community sessions

JSONL session metrics, model routing & cost

OpenCode

~/.opencode/ storage & SQLite

DeepSeek / local LLM token telemetry & cost

Hermes Agent

~/.hermes/ runtime

Authoritative local ledger, sessions, token throughput

Pi Coding Agent

~/.pi/ agent runs

Tool calls, input/output token counts

GLM Code

~/.zcode/ CLI SQLite database

Zhipu GLM-5 series tokens & session metrics

CodeBuddy / WorkBuddy

~/.codebuddy/ / ~/.workbuddy/

Tencent coding assistant turns & token counts

Qoder

~/.qoder/ workspace & SQLite

Qoder IDE / Work / CLI multi-target tokens & metrics

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides tools for Claude to query local Claude Code token usage and cost data, enabling spend analysis and insights through natural language.
      24 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables local-first tracking of AI token usage and costs from Claude Code and OpenCode, answering queries about tokens, models, sessions, and cost through MCP tools and a CLI, with no network calls.
      124 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides coding agents with pre-flight cost estimation by analyzing local logs to forecast token usage and quota impact before expensive work, exposing tools for remaining quota, per-task cost estimates, and attempt affordability.
      132 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Reads the Claude Code, Codex and OpenCode usage logs already on your machine and reports token totals, per-day and per-hour activity, a per-agent and per-model breakdown, and a year-in-review recap. It makes no network request at all โ€” a test fails if any source file in the package can open a socket.
      4
      14
      MIT