KiroStats

Credit usage and session timing for Kiro IDE, as a local MCP server.

No auth, no network, no cloud. Reads Kiro's own session files on disk. Works with Kiro 1.0+ and pre-1.0.

Usage

Type /stats in any Kiro chat.

{
  "credits_used": 84.7983,
  "agent_time": "27m 4s",
  "session_time": "49m 46s",
  "turns": 4,
  "source": "kiro-1.x",
  "session_id": "sess_ec3ae179-3b53-4ee1-a6be-95c67922ebeb",
  "last_turn_credits": 7.2263,
  "last_turn_time": "1m 29s"
}

Related MCP server: MCP Token Tracker

Install

git clone https://github.com/BrennanWebb/KiroStats.git
cd KiroStats
.\install.ps1

The installer locates a Python 3.10+ interpreter, pip-installs the package, registers the server in ~/.kiro/settings/mcp.json, and writes a /stats steering file.

Kiro normally picks up the new server on its own. Restart it if /stats does not respond.

Tool

get_session_stats(layout="auto", workspace_path=None)

Returns credits_used (session total), agent_time, session_time, turns, source, and session_id, plus last_turn_credits / last_turn_time on 1.0+. A note field appears when a caveat applies.

How It Works

Kiro moved session storage between 0.x and 1.0. KiroStats reads both and prefers the newer layout, so a stale globalStorage tree left behind by an upgrade cannot shadow live data.

Kiro 1.0+

An append-only event log under the user home:

~/.kiro/sessions/{workspace-key}/sess_{uuid}/session.json
~/.kiro/sessions/{workspace-key}/sess_{uuid}/messages.jsonl

session.json carries status, createdAt, modelId, and workspacePaths. Credits arrive in messages.jsonl as a usage_summary record, appended when a turn completes:

{"payload": {
  "type": "usage_summary",
  "promptTurnSummaries": [
    {"unit": "credit", "unitPlural": "credits", "usage": 18.5044}
  ],
  "elapsedTime": 387160,
  "status": "success"
}}

That record is what the chat footer renders: 18.5044 and 387160 ms display as Est. Credits Used: 18.5 / Elapsed time: 6m 27s.

Pre-1.0

One JSON blob per agent execution under the extension's globalStorage:

{globalStorage}/kiro.kiroagent/{ws-hash}/{session-hash}/{execution-hash}

Each carries chatSessionId, startTime/endTime, status, and a usageSummary[] of per-response metering entries. KiroStats finds the execution with status == "running" and aggregates its whole chat session.

Limits

Not real-time on 1.0+. Kiro holds the metering stream in memory during a turn and flushes it only at turn completion, so a mid-turn reading covers through the last completed turn. The response says as much in note. Pre-1.0 could see in-flight usage, because the running execution file sat on disk with a partial usageSummary.

Session detection is best-effort. With several Kiro windows mid-turn, more than one session is genuinely in_progress. KiroStats prefers live sessions and tiebreaks on recent activity; pass workspace_path to be exact. Heuristic picks are flagged, and session_id always comes back so you can verify.

Manual Install

pip install -e .
python -c "import sys; print(sys.executable)"

Add to ~/.kiro/settings/mcp.json, using that interpreter path:

{
  "mcpServers": {
    "kiro-stats": {
      "command": "C:\\Path\\To\\python.exe",
      "args": ["-m", "kiro_stats_mcp.server"],
      "disabled": false,
      "autoApprove": ["get_session_stats"]
    }
  }
}

Copy .kiro/steering/stats.md to ~/.kiro/steering/, saved without a BOM — a BOM ahead of the --- breaks front-matter parsing.

Use the absolute interpreter path and -m rather than the kiro-stats-mcp console script. Kiro spawns MCP servers without a shell, and neither Scripts on PATH nor a bare python is dependable there — on Windows 10/11 python often resolves to the Microsoft Store alias stub.

Platforms

The 1.0+ path is home-relative everywhere, matching the extension's own path.join(os.homedir(), ".kiro", "sessions"). Only Windows has been tested.

Requires Python 3.10+ and Kiro opened at least once.

Sources

Kiro's storage layout is not publicly documented, and kirodotdev/Kiro is docs and issue tracking only — there is no source to read. These schemas were derived from the shipped kiro.kiro-agent bundle and verified against live session data on 1.0.337. Expect drift between releases.

Uninstall

pip uninstall kiro-stats-mcp
# remove "kiro-stats" from ~/.kiro/settings/mcp.json
# delete ~/.kiro/steering/stats.md

License

MIT