token-companion

KO | EN

gitlite — search

#mcp #video #command-line #android #macos #editor #api #json #generative-ai #ai-agent

token-companion

(★ 9)

Local, privacy-first desktop analytics for Claude and Codex usage records already on disk.

파일 탐색기

ZIP 다운로드

- - build.yml
  - ci.yml
  - docs.yml
- - icon.png
  - scr-drill-down.jpg
  - scr-models.jpg
  - scr-pricing.jpg
  - scr-sessions.jpg
- astro.config.mjs
- package-lock.json
- package.json
- - package-lock.json
  - package.json
  - README.md
- icon.icns
- icon.ico
- icon.png
- pricing.default.json
- dist.mjs
- gen_icon.py
- install.mjs
- verify-release-version.mjs
- verify.mjs
- - index.ts
  - pricing.ts
  - scan.ts
  - sources.ts
- - index.ts
- - App.tsx
  - env.d.ts
  - format.ts
  - index.html
  - main.tsx
  - styles.css
  - styles.d.ts
- - aggregate.ts
  - ipc.ts
  - types.ts
.gitignore
.npmrc
AGENTS.md
electron-builder.yml
forge.config.ts
install.ps1
install.sh
package-lock.json
package.json
README.md
tsconfig.json
tsconfig.node.json
tsconfig.web.json
webpack.main.config.ts
webpack.plugins.ts
webpack.preload.config.ts
webpack.renderer.config.ts
webpack.rules.ts

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**See exactly what your AI coding sessions cost.**

Local, privacy-first desktop analytics for Claude and Codex usage records already on disk.

[![Release](https://img.shields.io/github/v/release/pzarzycki/token-companion?style=flat-square&logo=github)](https://github.com/pzarzycki/token-companion/releases)
[![Build](https://img.shields.io/github/actions/workflow/status/pzarzycki/token-companion/ci.yml?style=flat-square&logo=githubactions&logoColor=white)](https://github.com/pzarzycki/token-companion/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://raw.githubusercontent.com/pzarzycki/token-companion/main/LICENSE)
[![Docs](https://img.shields.io/badge/docs-online-8b5cf6?style=flat-square&logo=readthedocs&logoColor=white)](https://pzarzycki.github.io/token-companion/)

[Install](#install) · [Documentation](https://pzarzycki.github.io/token-companion/) · [What it reads](#what-it-reads) · [Building](#building-from-source)

</div>

## Highlights

- 100% local. No accounts, no telemetry, no cloud sync.
- Exact token counts from real usage records, not estimates.
- Editable per-model pricing in the app.
- One view across Claude CLI, Claude Desktop Cowork/agent modes, VS Code, and Codex CLI.
- Session, model, and project-folder attribution.

## Install

Use the source-first install paths below. The full platform matrix, including release artifacts, lives in the install docs.

### Option 1: build locally with `npx`

Prerequisite: Node.js 22.12.0 or newer. `npm` and `npx` are included with the standard Node.js install. Install Node.js from https://nodejs.org/en/download if `npx` is missing.

```bash
npx token-companion@latest
```

Useful flags:

```bash
npx token-companion@latest --dry-run
npx token-companion@latest --version v0.1.9
```

- `--dry-run`: print checks, build commands, and install target.
- `--package-only`: build packages but do not copy or install the built app.
- `--install-dir <path>`: macOS `.app` destination. Windows uses one-click NSIS install and rejects this option.

What the npm package actually is:

- `token-companion` on npm is a small bootstrapper package, not the Electron app bundle and not the full source tree.
- `npx token-companion@latest` downloads the matching GitHub source tag, runs the checked-in installer, builds the app locally, and then installs the built desktop app for the current OS.
- The npm package exists to give users a one-line entry point with normal npm tooling while keeping the app itself open-source and locally built.

### Option 2: run the checked-in wrapper script

Use the repo script if you want the same tagged-source installer flow without invoking the npm bootstrapper command directly.

Windows:

```powershell
powershell -ExecutionPolicy Bypass -File .\install.ps1
```

macOS / Linux:

```bash
sh install.sh
```

Useful script flags:

- Windows: `-Version <ref>`, `-DryRun`, `-PackageOnly`, `-InstallDir <path>`
- macOS / Linux: `--version <ref>`, `--dry-run`, `--package-only`, `--install-dir <path>`

Install details: [docs](https://pzarzycki.github.io/token-companion/install/).

## What it reads

| Source | Location | Token data |
|---|---|---|
| Claude CLI + Claude Desktop agent modes + VS Code | `~/.claude/projects/**/*.jsonl` | Per-message `usage` |
| Claude 1p Cowork | `~/Library/Application Support/Claude/local-agent-mode-sessions/**/audit.jsonl` | Result usage and exact reported cost |
| Claude 3p title-gen | `~/Library/Application Support/Claude-3p/title-gen/**/*.jsonl` | Usage records |
| Codex CLI | `~/.codex/sessions/**/*.jsonl` | Last cumulative `token_count` per session |
| Claude/Codex desktop plain chat | IndexedDB / LevelDB stores | Discovery only; no token counts exposed |

Validation rules in `scripts/verify.mjs`:

- Claude usage is summed per assistant message and deduplicated on `message.id`.
- Codex totals are taken from the last cumulative session snapshot, never summed across events.

## Building From Source

Token Companion uses [Electron Forge](https://www.electronforge.io/) for development packaging, [electron-builder](https://www.electron.build/) for release artifacts, React 19, Astro 7 for docs, and TypeScript 6. Builds are platform-local because `classic-level` is a native dependency and the distributables are OS-specific.

### Prerequisites

- Node.js 22.12.0 or newer with npm and npx
- macOS: Xcode Command Line Tools
- Linux: `build-essential`, Python 3, `fakeroot`, and `rpm`

The source installer checks these prerequisites before building. It fails with the original command output if dependency install, typecheck, or packaging fails.

### Install

```bash
git clone https://github.com/pzarzycki/token-companion.git
cd token-companion
npm install
```

The repo pins npm's cache to a local `.npm-cache/` directory to avoid Windows profile-cache permission issues during install.

### Development

```bash
npm run typecheck
npm run dev
```

### Build

```bash
# Package the current OS without making installers
npm run package

# Build current-platform distributables with electron-builder
npm run dist

# Platform-specific distributable commands when you are on that OS
npm run dist:mac
npm run dist:win
npm run dist:linux
```

On macOS, `npm run dist:mac` repairs the Forge-produced `.app`, removes stale signatures, ad-hoc re-signs it, verifies the bundle with `codesign`, and only then hands it to `electron-builder` for the final DMG/ZIP artifacts.

Backward-compatible aliases remain available: `npm run make`, `npm run make:mac`, `npm run make:win`, and `npm run make:linux`.

Packaged app output lands in `out/`. Final distributables land in `out/dist/`.

Packaging targets:

- macOS: `dmg` + `zip`
- Windows: NSIS installer `.exe`
- Linux: `deb` + `rpm`

### Verify

```bash
npm run verify
npm run audit:prod
npm run audit
```

`npm run verify` validates parser and pricing logic against local Claude/Codex data. It is for contributors and maintainers, not part of the end-user installer path.

## Release And Publish

The release source of truth is a version tag on `main`.

Versioning rules:

- Keep the desktop app version in the root [package.json](package.json) aligned with the installer package version in [packages/npm-installer/package.json](packages/npm-installer/package.json).
- Create one tag per real release: `vX.Y.Z`.
- Do not publish from an untagged commit if you want `npx token-companion` to resolve a matching source tarball cleanly.

Steady-state release flow:

1. Update `package.json`, `package-lock.json`, `packages/npm-installer/package.json`, and `packages/npm-installer/package-lock.json` to the same `X.Y.Z`.
2. Merge the release commit to `main`.
3. Push `main`.
4. Create and push tag `vX.Y.Z`.
5. GitHub Actions runs `.github/workflows/build.yml`.
6. The workflow verifies that the tag matches both package versions.
7. The workflow builds platform artifacts, publishes the GitHub Release, and publishes `packages/npm-installer` to npm through Trusted Publishing.

Trusted Publishing setup:

- npm package: `token-companion`
- Publisher: `GitHub Actions`
- GitHub owner: `pzarzycki`
- Repository: `token-companion`
- Workflow filename: `build.yml`
- Allowed action: `Allow npm publish`

Why the installer downloads GitHub source:

- The published npm package intentionally stays small and only contains the installer entry point.
- The real application source is taken from the matching GitHub tag tarball such as `https://github.com/pzarzycki/token-companion/archive/refs/tags/v0.1.9.tar.gz`.
- This keeps the published npm artifact small, makes the release source explicit, and ensures the local build uses the same tagged source as the GitHub release.

Recovery path:

- Manual `npm publish` should be treated as recovery-only when fixing publishing setup.
- Normal releases should come from the tag-triggered GitHub Actions workflow so npm, GitHub Release artifacts, and the source tag stay aligned.

## Security Posture

- Full `npm audit` and production-only `npm audit --omit=dev` are expected to pass clean on a fresh install.
- The packaged app enables Electron fuses, uses `contextIsolation`, runs the renderer sandboxed, and denies browser permission requests by default.
- The preload bridge exposes a small typed API only, and session-entry IPC now rejects file paths outside the known Claude/Codex session roots.

### Regenerate icons

```bash
python scripts/gen_icon.py
```

This writes `resources/icon.png`, `resources/icon.icns`, and `resources/icon.ico`.

## Pricing

Default rates live in [resources/pricing.default.json](resources/pricing.default.json). They are bundled into the app and copied to `<userData>/pricing.json` on first run, which the in-app Pricing tab edits. Entries marked `verify` are unpublished aliases mapped to the closest documented model price and should be confirmed before relying on totals.

## Architecture

```text
src/
├── main/      Electron main process: scanning, parsing, pricing persistence, IPC
├── preload/   Typed contextBridge API
├── renderer/  React UI
└── shared/    Shared types and pure aggregation logic
```

## Known Gaps

- Plain desktop-chat stores are detected but not yet costed because they do not expose token usage directly.
- Some unpublished OpenAI / Codex model aliases still require manual confirmation.

## License

[MIT](LICENSE)

<div align="center">
<sub>Built with Electron, Electron Forge, webpack, React, and TypeScript.</sub>
</div>

token-companion

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

Download README