Documentation
Troubleshooting
The handful of things that actually go wrong, and what each one means.
On one machine
| What you see | What to do |
|---|---|
A browser tab on localhost:8741 will not let you in |
Run tokenome open. Typing the address by hand gives you no session: the service never puts its token into a page, so a tab needs the one-time launch link that tokenome open and tokenome app produce. If the command reports that the service refused a launch code, the service is not running; start the app or run tokenome app. |
tokenome is not a command |
Open Settings in the app and choose Install command-line tool, which puts it at ~/.local/bin/tokenome, then make sure that directory is on your PATH. If you installed the standalone package instead, the three commands come from uv tool install tokenome-ai. |
| Nothing is indexed | Check the Sources page: it says, per source, whether it was found and what to do about it. Claude Code transcripts are read from ~/.claude/projects; ChatGPT and Gemini need an export dropped into their import folder; Claude Desktop needs a session key. Then run an ingest from that page rather than waiting for the next poll. |
| The dashboard says the engine is not healthy | Quit and relaunch the app, which supervises the search engine and restarts it. From the command line, tokenome stop then tokenome start, and tokenome status to confirm. |
tokenome context finds nothing |
The line has to be committed in a git repository for blame to give a timestamp, and the conversation has to be indexed and carry a project. If both are true, widen the window with --window 120 or look on both sides of the edit with --symmetric. |
| A day has no journal entry | Days with no substantive work write nothing, on purpose. A day also only becomes eligible after its window has closed and the material has settled, so today's entry is not written today. tokenome journal --backfill generates every eligible day that is missing one. |
| Your agent says memory is unavailable | The service has to be running: start the desktop app or run tokenome app. If it is running and the agent still cannot see the tools, re-register with tokenome claude install. After a plugin update, run claude plugin update tokenome@tokenome and start a new session; the installed copy is a snapshot. |
Team
| What you see | What to do |
|---|---|
| Enrollment is refused | The token was already used, has expired after 72 hours, was cancelled, or was mistyped. Enrollment tokens are single use and one per device; ask an admin to issue a new one. |
| "Already enrolled" on a laptop you want to re-enroll | This machine already has an identity. To re-enroll deliberately, remove ~/.tokenome/remote.json and ~/.tokenome/device.key, then enroll with a fresh token. |
| "That sign-in link did not work" | Console links work once and for two minutes. Run tokenome remote console again. |
| The console keeps showing the sign-in page | The eight-hour session ended, you signed out, or your device or account was revoked. Plain HTTP to anything other than loopback also drops the session cookie, so use https. |
| "This page is not available to your role" | Your role does not include that page. An admin can change it under People, then Role and groups. |
| "Team results unavailable, showing local only" | The server did not answer in time. Your local results are still correct and complete for your own work. Check the server's health endpoint and that it is reachable from this network. |
| Queued batches never drain | Either the server is unreachable, in which case it retries on its own with backoff, or a batch was parked after the server rejected it. Parked batches sit in the queue directory under ~/.tokenome with a failed suffix; inspect them, then delete them or rename them back to retry. |
| Segments are not appearing on the server | Is the project on tokenome remote projects? Segments with no project are never shared. Then check tokenome remote status for queue depth, and that the app is running so there is something doing the indexing. |
| A laptop that enrolled minutes ago is told its device is unknown | The server's identity database did not survive a redeploy. It needs a persistent volume mounted where its data lives; see Standing up the server. |
| A revoked person's laptop still shows old team data | Expected. Revocation stops server access; it cannot reach into anyone's local index. What they shared is removed by an admin purge. |
Still stuck
Write to hello@tokenome.ai with what you ran and what came back. If it is a team server, the health endpoint's output and the last few lines of the server log are the two most useful things to include.