Give your agent a map of the work

Start here

Copy the default agent instructions

Give this to your agent, or add it to your project's agent instructions. It explains how to find the executable on macOS, Linux or Windows, connect through the client, and remember your preference in supported global memory. If the connection is already available, the agent can use it immediately. Agents without local access or persistent memory will explain what you need to set up. You only need the manual setup below if the agent cannot complete the connection.

Remember tokenstat on this machine.

- tokenstat's MCP server is a local stdio server named `tokenstat`. If it is already configured in this client, reuse it.
- If it is missing and you have shell/filesystem access, find the executable: `command -v tokenstat` on macOS/Linux (installer default ~/.local/bin/tokenstat) or `(Get-Command tokenstat -ErrorAction SilentlyContinue).Source` on Windows (default %LOCALAPPDATA%\tokenstat\tokenstat.exe). Resolve the real home/LOCALAPPDATA, never copy YOUR_USERNAME literally. Verify the file exists.
- Configure a stdio MCP server named tokenstat with that absolute path and args ["mcp"] (standalone tokenstat-mcp uses args []). Use this client's MCP setup, do not overwrite other servers. Reconnect if needed. No port or API key. The macOS app bundle holds the host helper, not the MCP server. A browser-only agent needs a client-supported local bridge. Windows MCP covers archive tools; workspace/task/note/job tools need the Unix host (run tokenstat or tokenstat-hostd on macOS/Linux).
- Save in this agent's global memory or user instructions: use tokenstat for work tracking and project notes; the server name, verified command path, args, stdio transport, platform limits, tokenstat://guide, and workspace_list -> workspace_context. Paths and workspace IDs are machine-specific, recheck per machine and project. Merge with existing instructions. No credentials or note bodies in memory. If memory is unavailable, say so and return a short note to save.

When I ask about tokenstat, usage, projects, tasks or notes, use the tokenstat MCP tools:

1. Call workspace_list, match this project's absolute folder path to its workspace ID. If missing, workspace_add the existing absolute path. Never invent an ID or use a path as workspaceId.
2. Read workspace_context with {id} for one project, or {} for all projects.
3. `projects` is historical usage, not folder discovery. workspace_context takes `id`; list tools take `workspaceId` (omit = all workspaces, "" = unassigned only on list). task_list and note_list accept includeArchived and query; use includeArchived=true for older cards.
4. Read tokenstat://guide and the tool descriptions when unsure.

Discovery

The server explains what is available

During connection, initialize.instructions gives the agent a working guide. tools/list supplies tool descriptions, parameters and required fields. The same guide is readable through the MCP resource tokenstat://guide. That resource is available inside the client, not as a web page.

Ask the agent to call workspace_list, match your folder's path, then read workspace_context with its id. Omit id for a memo of every workspace and its tasks and notes. projects is a historical usage report, not the workspace registry.

{
  "title": "Prepare the release",
  "notes": "Run checks and record remaining blockers.",
  "workspaceId": "REPLACE_WITH_WORKSPACE_ID"
}

Pass that object to task_create, or use note_create to save a memo. Use the returned workspace ID, never a name or path. Omit workspaceId to create a global/unassigned card. On list tools, omitting the filter shows all projects; an empty string selects only unassigned cards.

Complete tool map

49 tools across seven areas

Read each tool's purpose and inputs, plus setup, examples and troubleshooting in the help guide.

Manual setup

Advanced setup and installation

Install the tokenstat CLI, then run command -v tokenstat in your terminal to find its absolute path. The installer uses ~/.local/bin/tokenstat on both macOS and Linux. Replace YOUR_USERNAME below and add the entry to your client's MCP configuration. Clients with a setup form use the same executable and the argument mcp.

macOS

{
  "mcpServers": {
    "tokenstat": {
      "command": "/Users/YOUR_USERNAME/.local/bin/tokenstat",
      "args": [
        "mcp"
      ]
    }
  }
}

Linux

{
  "mcpServers": {
    "tokenstat": {
      "command": "/home/YOUR_USERNAME/.local/bin/tokenstat",
      "args": [
        "mcp"
      ]
    }
  }
}

Windows: archive tools

{
  "mcpServers": {
    "tokenstat": {
      "command": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\tokenstat\\tokenstat.exe",
      "args": [
        "mcp"
      ]
    }
  }
}

Windows installs to %LOCALAPPDATA%\tokenstat\tokenstat.exe. Use your actual LOCALAPPDATA location if it differs. Workspace, task, note and job management currently requires the Unix host.

Use the full path, not ~ or $HOME in JSON: clients may not expand them. Custom installations should use the path returned by command -v tokenstat. The macOS app bundle contains the host helper, not the CLI MCP executable; install the CLI even when tokenstat is in Applications.

Restart or reconnect the client. Keep the tokenstat app or tokenstat-hostd running on the same Unix machine for workspace and job tools. Archive queries work independently. Run tokenstat scan to refresh usage.

No web port, URL or tokenstat API key is needed. The client launches the local process and communicates over stdio. A browser-only agent needs a local MCP bridge supplied by its client; it cannot connect to your executable by visiting this website.

Data and permissions

Know what access you are giving

The MCP connection runs locally over stdio. Usage results include local project names and are returned to the calling agent, whose provider may process them as part of its context. These tools do not expose tokenstat account sync or profile publication.

Task tools can change the board. Automation and workflow tools can start jobs through the host, including agent, shell, and HTTP steps. Those steps may access files, connect to services, or change Git state according to their configuration. Review your MCP client's approval settings.

Setup, examples, and tool permissions →

Next