Install, index, mount.

TokenFluid ships as a single Python package. Install it with pip, uv, or pipx — whatever you already use. The package provides one command, tokenfluid, with subcommands for indexing, MCP, cloud, and session management. Python 3.10 or newer is required.

The install is small and has no compiled dependencies on most platforms. If you are on macOS or Linux, it should land in under a second. On Windows, you may need the Microsoft Visual C++ redistributable for the SQLite build — most modern Windows machines already have it.

1pip install tokenfluid

Verify the install with tokenfluid --version. If it prints a version, you are good. If it prints a command-not- found error, your PATH is not picking up the install location — check that your Python bin directory is on it.

From the root of your repository, run tokenfluid index .. This walks the tree, extracts symbols, imports, file structure, and package boundaries, and writes them to a SQLite database at .tokenfluid/index.sqlite. The index lives next to your code. Nothing leaves your machine to build it.

1cd ~/myrepo\ntokenfluid index .

The index captures symbols (functions, classes, methods, top-level constants), imports (so we can walk the call graph), file structure, and package boundaries (so monorepos scope correctly). It does not store file contents — only metadata about them. On subsequent runs, the indexer is incremental: it only re-reads files that changed since the last index.

Add .tokenfluid/ to your .gitignore. The directory contains your local index, your working sets, and your session logs — all of which are repo-local and machine-specific. Committing them would create noise in pull requests and bloat your repository for no benefit.

Register TokenFluid as an MCP server with your agent. The CLI does this for you for the common agents — Claude Code, Cursor, Continue — by writing the right config to the right file. For unsupported agents, you can drop the JSON in manually.

1tokenfluid mcp-install .

The config block below is what gets written for Claude Code. The command tokenfluid mcp-serve starts an MCP server that exposes a small set of tools: mount_working_set, list_selected_files, and get_selection_reasons. Your agent calls these instead of grepping the whole repo.

1{
2  "mcpServers": {
3    "tokenfluid": {
4      "command": "tokenfluid",
5      "args": ["mcp-serve"]
6    }
7  }
8}

After the install, restart your agent so it picks up the new MCP server. In Claude Code, that means quitting and reopening. In Cursor, reload the window. The first time the agent calls a TokenFluid tool, the CLI will spin up a server process and the agent will see your repo's index.

Cloud orchestration is off by default. If you want cross-device sessions, shared team history, or cloud-side usage analytics, you can opt in. The opt-in does not grant the cloud access to your source code — it grants the cloud access to metadata, and only the metadata your privacy mode allows.

1tokenfluid cloud enable

The default privacy mode is metadata_first, which sends repo hash, file paths, task type, and token estimates to the cloud. Snippets are not sent unless you switch to snippets_allowed. Full files are never sent in any mode. The privacy docs cover this in detail.

You can change privacy modes at any time from the CLI or the dashboard. Changes take effect on the next session; active sessions keep the mode they started with. Disabling cloud keeps existing session metadata for audit purposes — it is not deleted automatically.

Run tokenfluid status to check that everything is wired up. The output shows the index location and file counts, the registered MCP servers, the cloud mode, the privacy mode, and any active working sets. If anything is missing, the message will tell you what to do.

1tokenfluid status

The expected output looks roughly like the block below. File counts will differ; the structure should match. If MCP server shows not registered, re-run mcp-install and restart your agent. If cloud mode shows disabled and you wanted it on, run tokenfluid cloud enable.

1TokenFluid v0.4.2
2
3Index:        /Users/you/myrepo/.tokenfluid/index.sqlite
4              1,243 files · 18,902 symbols · 4,210 imports
5MCP server:   registered (Claude Code, Cursor)
6Cloud mode:   disabled
7Privacy mode: local_only
8
9Working sets: 0 active

You have a working install. From here, the docs go deeper on the pieces that interest you. MCP covers the protocol layer in detail, including how to wire up agents the install command does not know about. Scoped Mini-Repo is the conceptual deep dive on the mounted working set. Cloud Orchestration covers what metadata is sent and how to control it.

• MCP — the protocol layer
• Scoped Mini-Repo — how selection works
• Cloud Orchestration — metadata and privacy
• Privacy — the four privacy modes
• Security — sandbox, audit, API keys