Skip to content

getmoss/moss-tracker

v0.1.2MIT

Use this when the user wants to review or understand their organisation’s OpenAI or Anthropic API usage and costs from connected accounts, or to set up, open, restart, or stop the Moss AI Spend Tracker dashboard. Opens the local dashboard, which retrieves usage and cost data for finance reporting; does not retrieve data into chat. Does not change provider settings or enforce spending limits. Do not use for ChatGPT or Claude subscription billing, or general model pricing questions.

GitHubOpen Website

Moss AI Token Cost Tracker

A dashboard for tracking your team's AI token spend (Claude + ChatGPT) - no data leaves your machine.

Set up and run the tool

Complete the one-time installation below, then just repeat the "How to run the app" steps whenever you want to use the dashboard again.

Codex / ChatGPT desktop plugin

Works in a local Codex chat in the ChatGPT desktop app, or in Codex CLI. The dashboard runs on your own computer.

Installation (one-time)

ChatGPT desktop app

  1. Open Codex in the ChatGPT desktop app and start a Local chat.

  2. Ask Codex:

    Install the moss-tracker plugin from the GitHub marketplace
getmoss/moss-ai-token-cost-tracker for me.

    Codex can run the installation commands below for you. The plugin is downloaded automatically from GitHub.

  3. Restart the desktop app, open Plugins, and enable Moss AI Token Cost Tracker from the Moss AI Token Cost Tracker marketplace source if it is not already enabled.

  4. Start a new local chat before using the plugin for the first time.

Terminal / Codex CLI

Run these commands in your terminal from any folder:

codex plugin marketplace add getmoss/moss-ai-token-cost-tracker
codex plugin add moss-tracker@moss-ai-token-cost-tracker
codex

In Codex, /plugins opens the plugin browser. Start a new session after installing if Codex was already running.

How to run the app

In a local Codex chat (desktop or terminal), ask:

Use the moss-tracker plugin to start the dashboard.

Codex checks Node.js, launches the installed plugin, and opens the local dashboard in your browser. Node.js 24.21.0 or newer is required; Codex can help set it up if it is missing. Enter provider Admin API keys only in the local dashboard, or click Preview with sample data to try it without keys.

Use the same request whenever you want to open the app again. Codex reuses an already-running dashboard and its existing address. You can also ask Codex to restart the dashboard or stop the instance it started. Saved provider connections are kept outside the plugin installation and survive plugin updates.

Keeping it up to date

On the first dashboard start or open request in each chat, the plugin instructs Codex to check its marketplace and apply a newer version when the client supports it. If a new chat, app restart, or action in Plugins is needed, Codex will tell you. If the update check fails, the installed version can still open.

You can also ask Codex to update explicitly, or refresh its marketplace from your terminal:

codex plugin marketplace upgrade moss-ai-token-cost-tracker

Apply the plugin update in Plugins, then start a new local chat and ask Codex to start the dashboard again.

Claude Code plugin

Works in a terminal Claude Code session, or in the Code tab of the Claude desktop app (make sure the session's environment is set to Local, not Cloud or SSH - this tool needs to run on your own machine).

  1. Start a Claude Code session: open a terminal and run claude, or open the Code tab in the Claude desktop app and start a new Local session.
  2. Install the plugin:
    • Terminal: inside the session, run: 
      /plugin marketplace add getmoss/moss-ai-token-cost-tracker
/plugin install moss-tracker@moss-ai-token-cost-tracker
    • Desktop app: click + next to the prompt box, select Add plugins (or Manage plugins → Browse plugins), then search for and install moss-tracker. You can also type the same /plugin commands directly in the prompt box.
  3. After installing, /moss-tracker:start won't work yet in the same session - run /reload-plugins, or just start a new session, before using it.

How to run the app

Inside a Claude Code session (terminal or desktop app), run /moss-tracker:start any time you want to start or restart the dashboard.

Keeping it up to date

The launch skill checks for updates on its first start/open request in each chat. You can also enable Claude Code's marketplace auto-update (/plugin → Marketplaces → select this marketplace → "Enable auto-update"), or update manually:

/plugin marketplace update moss-ai-token-cost-tracker
/plugin update moss-tracker@moss-ai-token-cost-tracker

AI prompt setup guide (GIF)

AI prompt setup guide

Installation

If you have Claude Code or ChatGPT Codex, you can hand them the whole job.

  1. Open Claude Code or Codex.

  2. Paste this prompt as your first message:

    Clone and set up the moss-ai-token-cost-tracker tool for me. Act as my
setup assistant using your file system and terminal access:

1. First check whether the current folder (or a `moss-ai-token-cost-tracker`
   subfolder) already contains this tool (look for server.mjs and
   index.html). If it's already there, run `git pull` inside that folder
   to get the latest changes, then skip straight to step 3.
2. Otherwise, clone the repo:
   git clone https://github.com/getmoss/moss-ai-token-cost-tracker
   then work from inside that folder, and check whether Git, nvm, and the
   Node.js version this repo's README requires are installed, installing
   or switching to whatever is missing.
3. Double check that everything needed is set up correctly, and then run
   `npm start`. The tool opens into a setup screen where I can connect my
   real accounts with API keys, or click "Preview with sample data" to
   see how it looks with mocked data first, without any API keys.
4. Watch the terminal output for errors. If something fails, diagnose the
   root cause, explain it to me in plain language, and either fix it or
   tell me exactly what to run.
5. Tell me the URL to open in my browser once the server is running.
6. Later, if I ask you to stop or restart the tool, do that for me.

Important: never read, print, or send the contents of my .env file, and
never share any API keys or company data outside this terminal session.

How to run the app

The same prompt works both for the initial setup and every time after, when you just want to run the tool again - just open Claude Code or Codex inside the project folder and paste the same prompt.

Windows setup guide (GIF)

Windows setup guide

Installation (one-time)

Terminal is a text window for giving instructions directly to your computer. Every command below is shown in a code box - copy it, paste it into Terminal, and press Enter. If a box contains several commands, run them one at a time.

The installation commands below download the public code and the programs needed to run it. They do not access your AI accounts or spend data. If your company restricts software installation, ask your IT team to complete the setup.

  1. Open Terminal: right-click the folder where you'd like the project to be created (e.g. your Desktop) and choose Open in Terminal. The tool will be installed inside whichever folder you click.

  2. Install Git (lets your computer copy the tool from GitHub):

    winget install --id Git.Git -e

    Approve the installation if asked, then close and reopen Terminal.

  3. Clone this repo:

    git clone https://github.com/getmoss/moss-ai-token-cost-tracker.git
cd moss-ai-token-cost-tracker

  4. Install Node.js (version 24.21.0 or newer): download the installer from nodejs.org/en/download and run it.

Troubleshooting tip: if something does not work, take a screenshot of the Terminal error or copy the text and upload it to AI assistant asking what is blocking the setup and which command you should run next (make sure it contains no API keys or sensitive company data).

How to run the app

Follow these steps whenever you want to open the dashboard, including the next time you restart your computer or close the tool.

  1. Open Terminal inside the project folder: right-click the moss-ai-token-cost-tracker folder and choose Open in Terminal.

  2. Start the tool:

    npm start

    Keep Terminal open while using the dashboard - closing the window stops the tool.

  3. Open the dashboard. Copy the localhost address from the Terminal output and open it in your browser.

    The dashboard runs locally on your computer rather than on a public website, and the address only works while the tool is running in Terminal.

Follow the on-screen setup to connect your provider Admin API keys. Enter these keys only inside the local application - never in Terminal, email, Slack or a support message.

To stop the tool, return to Terminal and press Ctrl + C. To use it again later, repeat the steps above.

Demo mode (no API keys needed): want to try it out without connecting real accounts? On the setup screen, click "Preview with sample data" to see the dashboard filled with mocked data. You can exit the preview and connect your real keys at any time from the demo badge in the header.

Useful commands:

CommandWhat it does
npm startRuns the local server on port 4173
npm run reset-onboardingRestarts you into the first-run setup flow

.env.bak may contain your previous API keys, so treat it as confidential.

macOS setup guide (GIF)

macOS setup guide

Installation (one-time)

Terminal is a text window for giving instructions directly to your computer. Every command below is shown in a code box - copy it, paste it into Terminal, and press Enter. If a box contains several commands, run them one at a time.

The installation commands below download the public code and the programs needed to run it. They do not access your AI accounts or spend data. If your company restricts software installation, ask your IT team to complete the setup.

  1. Open Terminal: right-click the folder where you'd like the project to be created (e.g. your Desktop) and choose New Terminal at Folder. The tool will be installed inside whichever folder you click.

  2. Install Git (lets your computer copy the tool from GitHub):

    xcode-select --install

    A separate installation window may appear - follow its instructions, then close and reopen Terminal. If Git is already installed, your Mac will tell you and you can continue.

  3. Clone this repo:

    git clone https://github.com/getmoss/moss-ai-token-cost-tracker.git
cd moss-ai-token-cost-tracker

  4. Install Node.js (version 24.21.0 or newer): download the installer from nodejs.org/en/download and run it.

Troubleshooting tip: if something does not work, take a screenshot of the Terminal error and upload it to ChatGPT, Claude or another AI assistant asking what is blocking the setup and which command you should run next (make sure it contains no API keys or sensitive company data).

How to run the app

Follow these steps whenever you want to open the dashboard, including the next time you restart your computer or close the tool.

  1. Open Terminal inside the project folder: right-click the moss-ai-token-cost-tracker folder and choose New Terminal at Folder.

  2. Start the tool:

    npm start

    Keep Terminal open while using the dashboard - closing the window stops the tool.

  3. Open the dashboard. Copy the localhost address from the Terminal output and open it in your browser.

    The dashboard runs locally on your computer rather than on a public website, and the address only works while the tool is running in Terminal.

Follow the on-screen setup to connect your provider Admin API keys. Enter these keys only inside the local application - never in Terminal, email, Slack or a support message.

To stop the tool, return to Terminal and press Ctrl + C. To use it again later, repeat the steps above.

Demo mode (no API keys needed): want to try it out without connecting real accounts? On the setup screen, click "Preview with sample data" to see the dashboard filled with mocked data. You can exit the preview and connect your real keys at any time from the demo badge in the header.

Useful commands:

CommandWhat it does
npm startRuns the local server on port 4173
npm run reset-onboardingRestarts you into the first-run setup flow

.env.bak may contain your previous API keys, so treat it as confidential.

How it works and how your data stays local

This tool runs entirely on your own computer - no cloud server, no sign-up, no Moss-hosted service. Your API keys live only in a local .env file, and your computer uses them to fetch usage and spend data directly from Anthropic/OpenAI and show it on screen.

Nothing - not your keys, not your usage data, not your spend data - is ever sent to Moss or any other third party.

Requirements

License

MIT © Moss