ai-cli-insights 0.1.8

Cross-tool usage analytics for Claude Code and Codex CLI

ai-cli-insights

Cross-tool usage analytics for Claude Code and Codex CLI. Collects session data from both tools and generates rich HTML insight reports with narratives, trend charts, friction analysis, and actionable recommendations.

Features

• Unified data collection from Claude Code (~/.claude/) and Codex CLI (~/.codex/)
• Three report modes: cross-tool comparison, Claude-only, Codex-only
• Optional deep analysis via external LLM CLI (Codex / Claude / Gemini)
• Period-over-period comparison, trend sparklines, quality scoring
• Friction pattern analysis with evidence-based recommendations
• Prompt library with copy-to-clipboard templates
• Zero third-party dependencies — pure Python standard library

Installation

pip install ai-cli-insights

Quick Start

# Generate a cross-tool report for the last 30 days
ai-cli-insights generate --days 30 --tool all

# Force a specific LLM analyzer
ai-cli-insights generate --days 30 --tool all --llm-analyzer claude

# Claude-only report
ai-cli-insights generate --tool claude

# Codex-only report
ai-cli-insights generate --tool codex

# Short form (generate is the default command)
ai-cli-insights --days 7 --tool claude

The HTML report is saved to the output directory and can be opened in any browser.

By default, generate runs with --days 30 --tool all --llm-analyzer auto. Deep LLM analysis order is codex -> claude -> gemini. When LLM analysis succeeds, core narrative/recommendation sections are replaced by live model output.

Configuration

# Create a config template
ai-cli-insights init

This writes a config.json to your config directory:

• macOS: ~/Library/Application Support/ai-cli-insights/config.json
• Linux: ~/.config/ai-cli-insights/config.json

Edit it to customize:

• domain_patterns — keyword patterns to classify sessions into work domains
• project_patterns — patterns to identify which project a session belongs to
• template_modes — report titles and slugs

Without a config file, reports still work — domains and projects will just show raw paths.

Claude Code Skill

# Install a Claude Code skill for easy /multi-insights access
ai-cli-insights install-skill

# Install a Codex CLI skill
ai-cli-insights install-codex-skill

This writes:

• Claude Code skill: ~/.claude/skills/multi-insights/SKILL.md
• Codex CLI skill: ~/.codex/skills/multi-insights/SKILL.md

CLI Reference

ai-cli-insights [command] [options]

Commands:
  generate        Generate an HTML insights report (default)
  init            Write a config template to the config directory
  install-skill   Install Claude Code skill file
  install-codex-skill  Install Codex CLI skill file

Generate options:
  --days N        Analyze the last N days (default: 30)
  --tool MODE     all | claude | codex (default: all)
  --analyst WHO   codex | claude — label the analyzing model (default: codex)
  --output-dir    Override the output directory
  --llm-analyzer  auto | codex | claude | gemini | none (default: auto)
  --llm-model     Optional model name passed to selected LLM CLI
  --llm-timeout-sec  Timeout per provider call (default: 120)

python -m ai_cli_insights also works.

Data Sources

Tool	Source	What it provides
Claude Code	~/.claude/usage-data/session-meta/*.json	Session metadata, tool counts, tokens
Claude Code	~/.claude/usage-data/facets/*.json	Outcomes, friction, goals
Codex CLI	~/.codex/state_5.sqlite	Thread metadata, tokens
Codex CLI	~/.codex/sessions/*.jsonl	Event details, timestamps, tools
Codex CLI	~/.codex/history.jsonl	User message counts

License

MIT