Skip to content

AGENT.md

Latest commit

 

History

History
111 lines (86 loc) · 3.7 KB

AGENT.md

File metadata and controls

111 lines (86 loc) · 3.7 KB
Raw

AGENT.md

This repository is a local desktop token dashboard for Codex usage. It scans local Codex session logs under ~/.codex, indexes token events into SQLite, exposes CLI summaries, and renders a PySide6 tray/menu-bar UI for macOS and Windows.

Working Agreement

  • Prefer small, focused changes that preserve the current architecture.
  • Keep the app local-first. Do not introduce network calls or model-dependent features into normal app usage unless explicitly requested.
  • Preserve the current meaning of time windows:
    • today = rolling last 24 hours
    • week = rolling last 7 days
    • month = rolling last 30 days
    • cumulative = all indexed history
  • Reuse existing query, formatting, and indexing helpers instead of duplicating logic in the UI layer.
  • Follow the current UI tone and layout unless the task is explicitly a redesign.

Environment

  • Python: >=3.12
  • Primary runtime: .venv
  • Install dev dependencies with:
.venv/bin/python -m pip install -e ".[dev]"
  • For Qt tests in headless mode, use:
QT_QPA_PLATFORM=offscreen .venv/bin/python -m pytest -q

Repository Map

  • src/codex_token_menubar/cli.py
    • CLI entrypoints for refresh, summaries, and doctor output.
  • src/codex_token_menubar/indexer.py
    • Session discovery, incremental indexing, and rollup recomputation.
  • src/codex_token_menubar/parser.py
    • Parses token_count events from Codex session JSONL logs.
  • src/codex_token_menubar/store.py
    • SQLite schema and persistence helpers.
  • src/codex_token_menubar/queries.py
    • Aggregate summary queries used by both CLI and UI.
  • src/codex_token_menubar/ui/panel.py
    • Main summary window.
  • src/codex_token_menubar/ui/tray.py
    • Tray/menu-bar application shell and interactions.
  • scripts/build_macos.sh
    • macOS PyInstaller build and release zip creation.
  • scripts/build_windows.ps1
    • Windows PyInstaller build.
  • tests/
    • Pytest suite. Add or update tests for every behavior change.

Change Rules

  • If behavior changes, update or add tests first when practical.
  • Do not change the meaning of token accounting fields without updating parser, queries, tests, and docs together.
  • Keep database changes backward-conscious. If schema changes are necessary, update initialization and tests in the same change.
  • Avoid editing build/, dist/, .pytest_cache/, .ruff_cache/, or __pycache__/.
  • Do not commit generated packaging output. Release assets are built locally and uploaded separately.

Testing Expectations

  • Run targeted tests for the area you changed.
  • Run the full suite before claiming completion for code changes:
QT_QPA_PLATFORM=offscreen .venv/bin/python -m pytest -q
  • UI work should usually touch:
    • tests/test_ui_panel.py
    • tests/test_ui_tray.py
  • Query or indexing work should usually touch:
    • tests/test_queries.py
    • tests/test_indexer.py
    • tests/test_store.py
    • tests/test_parser.py

Packaging And Release

  • macOS build:
./scripts/build_macos.sh

  • Expected macOS artifacts:

    • dist/Codex Token Usage.app
    • dist/codex-token-menubar-macos.zip

  • Windows build:

powershell -ExecutionPolicy Bypass -File .\scripts\build_windows.ps1
  • When cutting a release:
    • bump version in pyproject.toml
    • update any user-facing release notes if needed
    • run the full test suite
    • build the release artifact for the relevant platform
    • upload the built archive to the GitHub release

Notes For Agents

  • The app reads from CODEX_HOME when set; use that for isolated testing instead of touching real user data.
  • Prefer rg for code search.
  • When changing docs or workflow instructions, keep them aligned with the actual scripts and artifacts in this repo.