LucidLink

List the configured named accounts (service-account identities). Marks the current account (the one tools use when no ``account`` argument is given) and shows each account's login state and linked filespaces. Switch with ``use_account(name)``. Single-token setups have exactly one account named "default".

List data stores registered on the linked filespace, with their kind.

Paginated listing of files linked from a data store. Pass the ``cursor`` from the output's "more available" note to fetch the next page.

List entries in a directory of the linked filespace. ``pattern`` is an fnmatch glob applied to entry names.

List filespaces visible to a service account. Returns a newline-separated list of ``name (id)`` entries, marking the ones currently linked. Call this first if you don't know which filespace to operate on. ``account`` selects a configured account (default: the current one; see ``list_accounts``).

List byte-range locks currently held by THIS MCP process. Shows handle_id, filespace, path, byte range, mode, and how long held — across every linked filespace and account. Process-local — locks held by other agents (other MCP servers / other clients) won't appear here, and no API exists to enumerate them. To probe whether someone else holds a lock, attempt a non-blocking acquire (``blocking=false``): a ``BLOCKED`` answer means it's held. The audit trail records file operations, not lock events.

Acquire a byte-range lock on a file in the current filespace. ``mode``: ``exclusive`` excludes every other lock taker; ``shared``/ ``read`` (synonyms) admit other shared takers; ``write`` is a protected write lock. Locks are advisory: they exclude other lock takers (``lock_byte_range``, ``claim_file``, ``exclusive=true`` writes), never plain reads or writes, so every writer to be kept out must take the lock too. ``blocking=true`` waits until acquired, up to the daemon's IO timeout (then errors — call again to keep waiting); ``false`` returns immediately with ``BLOCKED`` when the range is held…

Move/rename within the same filespace (atomic where possible).

Return audit events newer than the last poll, oldest-first. Rows are raw audit records: ONE user-visible action can fan out to many (a macOS safe-save of a single file emits create/write/move/move/delete across a temp sibling). Read the sequence, don't count it. ``limit`` clamps to 200; anything over stays queued for the next poll.

Query the linked filespace's audit trail (NDJSON under .lucid_audit/). Events are returned NEWEST FIRST; ``limit`` keeps the newest N, so "what changed last?" is one call: mode=search, a small limit, and optionally action=FileWritten / FileCreate to exclude reads. Note a recording-to-readable LAG: an event can take a short while to appear here after the operation. Don't treat a just-made change being absent as "not recorded" — re-read after a moment. Mode extras: user_activity needs user, file_history needs path_prefix, aggregate needs group_by — and ignores limit (top 50 groups). path_pref…

Read file content from the linked filespace. ``offset``/``length`` are byte counts (use ``read_lines`` for line ranges). With no ``length``, a file over the read cap is refused — pass a ``length`` slice; a ``length`` over the cap is clipped and the result says so. The cap is the ``readSizeCap`` config key. ``encoding``: ``auto`` (default) returns plain UTF-8 text for text content (``OK text N bytes:``) and base64 for binary (``OK base64 N bytes:``); ``text`` forces text (errors on binary); ``base64`` forces base64 (binary-safe round-trips).

Read a line-range from a text file. Lines are 1-indexed and inclusive. Omit ``end_line`` to read to EOF. Useful for inspecting a specific section of a large file without pulling the whole thing across the wire.

Register a minted credential as a named account for THIS session. Reads the bearer token from a credential file that ``mint_service_account_admin`` / ``create_identity_admin`` wrote (``~/.lucidlink/sa-<frag>.id-<frag>.token`` — the mint output prints the exact path); the token itself never appears in tool output. Session-scoped: gone on server restart — persist an account with ``lucidlink-mcp-setup --account NAME`` instead. Switch to it with ``use_account(name)``; authentication happens lazily on first use.

Register a data store on the linked filespace. ``kind="s3"`` links S3 objects (link_external_file). Its credentials are NOT passed to this tool: an operator stores them in ~/.lucidlink/data-stores.json (mode 0600), keyed by store name, and this reads the entry for ``name``, so S3 keys never enter the conversation. ``kind="http_link"`` groups URL links (link_external_url) on filespace format 3.8 and newer and needs nothing. Returns identity only, never credentials.

Release a previously claimed file (companion to ``claim_file``). Releases all byte-range locks held on the handle and closes it. Equivalent to ``unlock_byte_range(handle_id)`` with no offset/length.

sed-style find-and-replace within a single text file. ``regex=false`` does literal substring replace. ``regex=true`` treats ``find`` as a Python regex; ``\1`` etc. in ``replace`` reference groups. ``dry_run=true`` reports what would change without writing. Omit ``max_replacements`` to replace every match.

Open a cursor on audit events under a path prefix of the CURRENT filespace. Returns a ``subscription_id``. Call ``poll_changes(subscription_id=...)`` to retrieve events newer than the last poll — the cursor stays bound to this filespace even if you switch to another one. Call ``unsubscribe_changes`` to stop; unlinking the filespace drops it. PULL-based: nothing arrives between your ``poll_changes`` calls, and the FIRST poll replays up to an hour of pre-subscribe history rather than starting empty. ``poll_interval`` is an advisory pacing hint only.

Flush all pending writes to the hub, making them durable and visible to other clients. Call this after ``write_file(sync=false)`` batches; unsynced writes are lost if the session ends before a sync.

Map the directory hierarchy, grouped under full directory paths. ``ls -R`` style: every directory is named in full once, with its entries beneath it and a blank line between directories, so each path in the output is usable as-is — nothing has to be rebuilt from indentation. A directory shown with a trailing ``…`` was not expanded because ``max_depth`` stopped there; a header with nothing beneath it is an empty directory. ``max_entries_per_dir`` caps each listing; out-of-range arguments are clamped and the clamp is reported. ``exclude_pattern`` (fnmatch on entry names) hides matching entries…

Truncate or extend an existing file to exactly ``size`` bytes. ``size=0`` clears the file in place (keeps the path); a smaller size drops the tail; a larger size pads with zero bytes. Moves no file data, so it is cheap on large files. Use it to roll back an append, repair a partial write, or empty a file. Syncs to the hub after.

Remove an external-file link from the filespace. Inverse of ``link_external_file`` / ``link_external_url``: drops the link only; the S3 object or URL target is untouched. A link is removed like any file, so on a regular file this is a delete: confirm the path with list_external_files first, and use delete_path for regular files.

Detach ONE linked filespace (the current one when ``name`` is omitted); other links stay live. Releases that link's connection to the hub and frees a slot under the link cap; its disk cache stays until the server exits. Its byte-range locks and change subscriptions are dropped — locks and subscriptions on OTHER filespaces are untouched. A named filespace is resolved across every account's live links. The next filespace operation falls back to another linked filespace, or re-links automatically (the default/only filespace, or it asks you to pick).

Release a byte-range lock and close the underlying handle. Pass both ``offset`` and ``length`` to unlock that range, or neither to unlock every range on the handle — one without the other is rejected.

Drop a session-registered account (the inverse of ``register_account``). Unlinks its filespaces and closes its client. Only accounts added via ``register_account`` can be dropped — configured accounts can't (they would come back on restart), and neither can the CURRENT account (switch away with ``use_account`` first). Typical teardown order: switch home → revoke/delete the credential → unregister.

Remove (unregister) a data store from the linked filespace. Inverse of ``register_data_store``, either kind. Refused while any external file is still linked from the store: list them with list_external_files and remove them with unlink_external_file first. The S3 objects and URL targets themselves are never touched.

Close a subscription's cursor (on whichever filespace it lives).

Repoint an existing HTTP/HTTPS external-file link to a new URL. ``path`` is an existing link created by ``link_external_url``. The new URL must serve the same content (the daemon refuses a different size): this refreshes an expired or moved URL, it does not swap the content.

Switch the current account for subsequent tool calls. Filespace links (and their locks/subscriptions) are PER ACCOUNT and stay live across switches — switching back restores that account's context as you left it. Authentication happens lazily on the first filespace operation.

Check whether the CURRENT account's LucidLink token is accepted. Follows use_account switches. Does NOT require the daemon. Single HTTPS round-trip (~0.5s). Returns a one-line status; a missing or rejected token is an error carrying a hint to fix it.

Return the current agent's identity and session state. Includes service account name + id, workspace id, token status/expiry, and the currently-linked filespace (if any). Use it at the start of a multi-agent session so each agent knows which identity it is acting as.

Overwrite bytes at a byte ``offset`` in an existing file, preserving the rest. Unlike ``write_file`` (which replaces the whole file), this patches in place: it writes the given bytes starting at ``offset`` and leaves every other byte untouched. It never truncates and never creates the file. Use it for fixed-layout edits — a header, a fixed-width record, a reserved placeholder. To coordinate the same range with other writers, take a ``lock_byte_range`` first, or pass ``exclusive=true`` for a one-call whole-file-locked patch. ``content`` is plain UTF-8 text by default; pass ``encoding='base64'…

Write file content to the linked filespace. ``content`` is plain UTF-8 text by default; pass ``encoding='base64'`` with base64-encoded content to write binary bytes. Missing parent directories are created automatically; pass ``create_parents=false`` to error on a missing parent instead. ``exclusive=true`` holds a whole-file exclusive lock for the write (released on close) to coordinate with other clients writing the same file. ``sync=true`` (default) flushes to the hub immediately, so the write is durable and visible to other clients. ``sync=false`` skips that flush for fast bulk writes; y…