The mounted working set.

Most agent-to-repo integrations work in one of two ways: the agent greps the whole repo (slow, noisy, token-expensive), or the agent reads pre-computed embeddings from a vector store (fast, but lossy and opaque). Neither maps cleanly to how a developer actually navigates a codebase.

TokenFluid takes a third path. The local index knows your repo's symbol graph, import graph, file structure, and package boundaries. When the agent asks a question, TokenFluid scores files by relevance to the task, picks the top N, and mounts them as a directory. The agent navigates that directory with the tools it already knows — rg, cat, sed, head, tail, find — against real files, not chunks.

This beats RAG for a concrete reason: real files are navigable. The agent can read line 40 to line 60 of a file, grep for a symbol, follow an import to its definition. Embedding-based RAG returns chunks; the agent cannot navigate between them, cannot see surrounding context, and cannot tell whether the chunk it got is the whole function or the middle of one. A mounted working set is just a smaller repo.

The selection is also auditable. Every file that makes the cut has a recorded reason — which symbols matched, which imports connected it, which boundaries were crossed. You can reconstruct why the agent saw what it saw. That is impossible with opaque embedding scores.

When the agent calls mount_working_set with a task description, TokenFluid scores every file in the local index against that task. Scoring uses three signals: symbol matches (does the task name symbols that live in this file?), import proximity (does this file import or get imported by files that scored high?), and boundary affinity (does this file live in a package that is relevant to the task?).

The top N files (default 12, configurable) are mounted. Files that scored just below the cutoff are kept on a candidate list, available via get_selection_reasons if you want to understand why a file did or did not make the cut. The selection is deterministic for a given index state and task description, so you can reproduce it.

Selection reasons are logged locally in the session audit log. For each file, the log records the matching symbols, the matching imports, and the boundary affinity score. This is what makes the mounted working set auditable: you can see, after the fact, why the agent saw file X and not file Y.

The selected files get mounted into .tokenfluid/sessions/<id>/working_set/, preserving the directory structure of your repo. A file at app/services/auth.py in your repo appears at .tokenfluid/sessions/<id>/working_set/app/services/auth.py. The agent navigates the same paths it would in your repo.

Mounting is configurable: files can be symlinked (default, fast, reflects live changes in your repo) or copied (safer, isolates the agent from in-flight edits). Symlinks are recommended for most workflows; copies are recommended when the agent is going to run for a long time and you do not want your own edits to surprise it mid-session.

The working set is read-write. The agent can edit, create, and delete files inside it. Those edits stay in the sandbox until you approve a patch — the patch approval flow is what propagates changes back to your real working tree. There is no implicit sync.

The agent uses the same tools it always has. TokenFluid does not introduce a new filesystem API, a new query language, or a new search syntax. The agent does cd into the working set, then uses rg, grep, cat, sed, head, tail, and find normally. The agent does not know it is inside a sandbox.

1$ cd .tokenfluid/sessions/abc/working_set
2$ rg "login_user"
3app/services/auth.py:42:def login_user(email, password):
4app/services/auth.py:58:    token = issue_session(user)
5$ sed -n '40,60p' app/services/auth.py
640
741  def login_user(email, password):
842      user = users.find_by_email(email)
943      if not user or not user.check_password(password):
1044          raise AuthError("invalid credentials")
1145      token = issue_session(user)
1246      return token
13...
14$ find . -name "*.py" | head -8
15./app/services/auth.py
16./app/services/sessions.py
17./app/models/user.py
18./app/api/routes/login.py

Because the agent uses its normal tools, every prompt-pattern and every workflow that worked before keeps working. You do not need to retrain your prompts. You do not need to teach the agent a new toolkit. You just give it a smaller directory to work in.

The working set is scoped. Files outside the set are invisible to the agent — they do not exist in the mounted directory. The agent cannot accidentally read a file that was not selected, and it cannot accidentally edit a file outside the sandbox.

Path traversal attempts are rejected. TokenFluid validates every path the agent reads or writes against the working set root, canonicalizes the path, and refuses anything that tries to escape via .. or symlink tricks. If the agent tries to cat ../../etc/passwd, it gets an empty result or an error, not the file.

The boundary is enforced at the filesystem layer, not at the MCP layer. Even if a future MCP tool bug tried to expose a path outside the set, the underlying file access would fail. This defense-in-depth is intentional — the sandbox is the trust boundary, not the tool surface.

If the repo changes mid-session — you pull a new commit, you stash some work, a teammate pushes — the working set may be stale. Run tokenfluid refresh to rebuild the local index incrementally and re-run selection. The working set is updated in place; the agent keeps working with the new files.

1tokenfluid refresh

Refresh is safe to run at any time. The agent's in-flight edits are preserved — they live in the working set, not in the index. If a refresh would remove a file the agent was actively editing, TokenFluid warns you and keeps the file in the set until the session ends or you explicitly drop it.

For long-running sessions, refresh is a good habit. It keeps the agent working against the current state of the repo, which means its proposed patches apply cleanly to your real working tree. A stale working set produces patches that conflict with recent changes — refresh avoids that.