Documentation

boardfella turns the usage of AI coding tools into a public leaderboard. A helper on your computer reads the logs of those tools and shows you your own token numbers. If you choose to publish them, the website ranks them against other users who published theirs.

Everything starts on your computer. No usage numbers are sent to the leaderboard when you open the helper, read your logs or connect a computer. Only the numbers you release yourself go to the leaderboard. The one exception is an auto upload that was already on from an earlier version: it keeps running on its own schedule until you pause it (see Auto upload below).

The helper supports 20+ tools: Claude Code, Codex, OpenClaw, OpenCode, Hermes, Qoder, Cursor, Copilot, KiloCode, Kelivo, Gemini CLI, Kimi Code, CodeBuddy, Kiro, Grok Build, Antigravity, Roo Code, Zed, Goose, oh-my-pi, pi, Craft, Droid, ZCode, CodeFuse, and Trae.

Viewing the public leaderboard needs no account. To appear on it you need three things, one after the other: a website account, a confirmed computer and a release of concrete numbers. The next sections explain each one.

Connecting is three separate decisions:

• Website account. You sign in or create an account on this website. This is only a login.
• Confirm this computer. You compare the device name and the code on the approval page with the helper, then approve or decline. This connects the computer to your account and shares the device name and the helper version with the website. After that, the computer sends its daily usage privately to My usage. Nothing goes to the leaderboard yet.
• Release concrete numbers. In the helper you see a preview of the numbers that would be sent, tick a box and press the button. The helper version and operating system are sent with them. Only then are numbers sent to the leaderboard.

The /connect page on this website explains the same path.

Start the helper

Run this command on your computer. It needs Node.js 22 or newer.

npx boardfella@1.5.22 connect

Once the helper has read the logs on your computer, your browser opens it at http://127.0.0.1:3847/connect (or the next free port, which the startup message shows). The first time this can take a few minutes. If it does not open, open that address yourself, then press Connect with my account.

Website account

On boardfella.com you can register and sign in with e-mail and password, with GitHub or with Linux.do. The account is a login, and it decides who your numbers belong to.

After you register with e-mail, the website sends a verification e-mail. Open the link in it, then sign in; signing in before that is refused with "Please verify your email before signing in". If you sign in with GitHub or Linux.do, no manual verification is needed because the website uses the verified e-mail of that account.

Confirm this computer

In the helper, choose Connect with my account. The helper asks the website for a device code and shows a device name and a code on the helper page and, if it runs in a terminal window, in that window too. Press Open the website to approve and sign in with the account your numbers should belong to.

The approval page shows the device name, the helper version, when the request was made, when it expires and the code. Compare:

• The device name and the code on the page must match the ones in the helper.
• If they match, tick "The code on this page matches the code my helper shows on its page or in its terminal window", then press Connect this computer.
• If they do not match, do not connect: press Decline. Declining never needs the box.
• The code expires 10 minutes after the request.

Release your numbers

Once the computer is connected, the helper shows a preview of the numbers that would be sent. The helper version and operating system are sent with them. After you have read it, tick "I release these numbers to the board" and press Release and send. No usage numbers are sent to the leaderboard until you press that button.

The Leaderboard page of the local dashboard walks you through five steps:

• Your numbers: the local helper reads your tool logs on your computer and shows this month on this computer: tokens, active days and sessions. You need no account to look.
• Connect: connect this computer to your account as described in the previous section.
• Preview: the helper shows the numbers that would be sent: the time of the numbers, the recipient, your profile state, the periods in this release and, per period, the tokens of each tool and model. Periods without usage are listed as not sent. The helper version and operating system are sent with them.
• Transfer: after you release, the helper sends the numbers and confirms a receipt with the website: summary prepared, sending, receipt confirmed.
• Result: the helper tells you which periods are accepted. Your rank is shown on the website. The helper does not show a rank.

Each computer uploads only its own usage: records synced from your other devices are not included. The website adds up the computers connected to your account.

Periods and review

The website checks every period it receives. Each period ends up in one of these states:

• Accepted: your released numbers are accepted.
• In review: your numbers arrived and the website is checking them.
• Rejected: the website did not accept this period.
• Not sent: this period had no usage, so it was not sent.
• Unconfirmed: the helper could not confirm that the website has it. A timeout does not mean nothing arrived, so check the receipt first.
• Received, status pending: the website has it but has not given a result yet.

Periods in review do not count for a rank yet. When a period is not accepted, the helper shows a reason, for example: "Many models are unknown to the website", "The same numbers were uploaded many times recently" or "The numbers rose unusually fast".

Periods overlap: today is also part of this week, this month, this year and all time. Their totals are not added up, and they must not be.

Days, weeks (Monday to Sunday), months and years follow UTC. Today changes at 00:00 UTC, not at your local midnight.

Auto upload

Auto upload is off by default. When on, this computer reads your usage and uploads the same kind of summary as the preview, at most once per interval. It can only be switched on after you have released numbers yourself. Switch it off to pause: the numbers already on the board stay there. Auto upload runs while the helper runs on this computer. The switch "Keep my numbers up to date every day" (or boardfella autostart enable) adds a daily start at 12:00 through the scheduler built into the computer (Task Scheduler on Windows, a LaunchAgent on macOS, a systemd user timer on Linux). The daily start runs the newest boardfella from npm and catches up after the computer was off. It is removed again when you switch it off, log out or the computer is revoked. If auto upload was already on from an earlier version, it keeps running on its own schedule, also before you release anything with the new steps, until you pause it. The Leaderboard page of the dashboard shows a notice about this with Pause auto upload and Continue as before.

The leaderboard release contains only this:

• Aggregated token totals per period (day, week, month, year, all time)
• Breakdowns per tool, per model and per tool and model
• The helper version, the operating system and the device name you see on the approval page

This is never sent to the leaderboard:

• Prompts and answers
• Source code
• File paths and project names
• Session ids
• Per-request timestamps
• Local cost estimates

Nothing else goes to the leaderboard. The local database and the pages of the local dashboard stay on your computer. Sync is a separate optional feature. If you set it up, it sends your usage records, including project paths, to the backend you choose. If auto upload was already on from an earlier version, it keeps uploading the same kind of summary on its own schedule until you pause it.

Separately from the release, a connected computer sends its daily usage (tokens per tool and model per UTC day) privately to My usage. Prompts, answers, source code and file paths are never part of it.

This section explains the numbers you see on the website leaderboard and in the helper preview.

Leaderboard and filters

The public leaderboard shows aggregate data that users chose to publish. Viewing does not require sign-in. You can change:

• View: Users or Models
• Metric: Tokens or Cost
• Period: Today, This week, This month, This year, All time, with arrows to move to the previous period
• Scope: All, Provider, Tool or Model, then a chip to pick one

If you are on the board, the page shows Your rank for the current filter. Periods are calendar periods in UTC, not rolling windows.

Token Types

• Input: Prompt tokens sent to the model
• Output: Tokens generated by the model
• Cache Read: Tokens read from cache (billed at a lower rate)
• Cache Write: Tokens written to the cache
• Thinking: Tokens used by Extended Thinking mode

Estimated costs

The website estimates cost from the token figures, the model name and the model prices. The helper does not send cost to the leaderboard, so a cost on the website is not a bill and not the number you see in your local dashboard.

Model Prices

The Model Prices page lists the AI model prices boardfella uses to estimate costs. They are not subscription prices for boardfella.

After connecting, you manage three things on the website: the connected computers, the uploads and how you appear on the board.

Uploads page

After you sign in, open /uploads:

• Authorized Devices: name, creation date, last upload and status (active or revoked) of every connected computer, and a revoke button.
• Upload History: the latest 100 upload snapshots, grouped by period type, with total tokens, device name, date and status (accepted, flagged or rejected; flagged means in review), plus the reason where there is one.
• Update now: opens the helper on this computer, which reads your AI tools' logs again and sends your newest totals after one click. The helper must be running; if nothing opens, start it with the command shown and press the button again. The first time, or after something changed (another account, computer or kind of data), the helper shows its normal steps with the full preview instead. It works on the computer where your AI tools run, not on a phone.

Revoke a device

Press Revoke device on the uploads page, or choose Log out and revoke device in the helper, to revoke a computer. A revoked computer cannot send new numbers, the usage it uploaded is removed from the leaderboard, its history is removed from My usage, and this cannot be undone.

Every connection is a device of its own. If the same computer appears twice under one name, revoke the old entry, or its last upload keeps counting and its history stays in My usage.

Profile privacy

In /settings you decide how you appear on the board. The preview shows your current state:

• Public: your name and avatar are shown on the board.
• Anonymous: you are ranked, but your name is masked. In Settings this is the Participate anonymously box.
• Private: you do not appear on the public board.

The same page lets you change your username (30-day cooldown), display name, avatar and password.

Each case shows the wording of the product first, then what to do.

The helper opens a dashboard on your computer at http://127.0.0.1:3847 (or the next free port). It only reads and shows data from your computer:

• Home: a live token total, quota warnings, and a summary of cost, sessions and active days.
• Overview: aggregated stats with filters for date range, device and tool, including tokens and cost per tool and the most called tools.
• Tokens: a daily bar chart (split by type or combined) and a detail table.
• Cost: estimated total cost, a daily cost chart and the top 10 by tool and by model.
• Models: models ranked by token usage, with provider, call count and share.
• Tool Calls: a ranking of tool calls within sessions.
• Projects: tokens and cost grouped by project directory. Project names and paths are shown only on your computer and are never sent to the leaderboard.
• Sessions: a paged list of sessions; open a row to see the session detail.
• Quotas: utilization and reset countdowns of the quota tiers for Claude Code, Codex and GitHub Copilot.
• Leaderboard: the five steps to connect and publish, described above.
• Settings: device alias, week start, refresh interval, data sources and the leaderboard site address.
• Sync: an optional feature that keeps usage data in step between your own computers. It is independent of the leaderboard. If you set it up, it sends your usage records, including project paths, to the backend you choose.
• Export: your usage as CSV, JSON or NDJSON.

My usage shows your own usage on this website, for the computers connected to your account. After you sign in, open /usage. Only you see it.

It has four pages:

• Overview: your totals and a daily chart for the range you pick.
• Tokens: tokens per day, split by type, with a detail table.
• Costs: estimated cost per day, and the tools and models that cost the most.
• Models: your models ranked by tokens.

Where the numbers come from: once a computer is connected, the CLI sends a private daily history to your account. For each UTC day, tool and model it holds the five token counts: input, output, cache read, cache write and thinking. It is sent right after connecting, when the helper starts, regularly while the helper runs and with every upload run. It does not depend on your release to the leaderboard. Prompts, answers, source code and file paths are never sent.

Days are UTC days, as on the leaderboard. A day changes at 00:00 UTC, not at your local midnight.

Costs are estimates. The website works out the cost from the token counts, the model name and the public Model Prices, so it is not a bill.

Computers with an older CLI version only send the days around each upload, so My usage has gaps for them. Update the CLI and the computer sends its daily history.

When you revoke a computer on the uploads page, its history is removed from My usage.

Once the package is published, these are the commands you need: