LucidLink

Append to a file (creates if missing). ``content`` is plain UTF-8 text by default; pass ``encoding='base64'`` with base64-encoded content to append binary bytes. Use for log-style writes where you don't want to read-modify-write the whole file. Syncs to the hub after the append.

Acquire an exclusive (or shared) lock over an ENTIRE file. Convenience over ``lock_byte_range`` — gets the file's current size and locks from offset 0. Useful when an agent just wants "let me edit this file safely without worrying about byte ranges." Returns an opaque handle_id; pass it to ``release_file`` when done. ``blocking=false`` returns ``BLOCKED`` instead of waiting. Advisory, like ``lock_byte_range``: it excludes other lock takers, not plain writes. Note: if the file grows after you claim it, the new bytes are NOT covered by your lock. For files that may grow during your edit, use ``lock_byte_range`` with an explicit, conservative length.

Copy/duplicate/back up a file within the filespace. Streams ``src`` to ``dst`` in chunks through the daemon's encryption layer (ZK preserved end-to-end; memory stays bounded, so large media files are fine). Set ``overwrite=true`` to replace an existing destination.

Count files and directories under a path, optionally filtered by name pattern. Walks the tree like ``tree`` / ``find_files`` but only returns totals — useful for quick "how big is this directory?" checks before deciding to grep through it. Honors the global walk budgets. ``include_pattern``/``exclude_pattern`` are fnmatch globs on the entry NAME (``*.mp4``), not the path; exclude wins, and an excluded directory is skipped whole: nothing below it is counted or visited. ``path_prefix`` itself is never excluded.

Create a directory, including any missing parent directories (``mkdir -p``). Succeeds if the directory already exists.

Return the current account's linked filespaces (current one first), or a hint if none is linked.

Delete a file or directory. For directories, pass ``recursive=true`` to delete non-empty ones. Hosts that honor tool annotations prompt before this fires.

Replace lines [start_line, end_line] (inclusive, 1-indexed) with ``new_content``. ``new_content`` may be empty (deletes those lines) or contain newlines (multi-line replacement). A trailing newline is added to the file body if missing. Pass ``dry_run=true`` for a preview without writing. ``expected_content`` (recommended): the text you believe lines [start_line, end_line] currently contain. If the file has changed since you read it, the edit is refused and the actual content is shown — so you never clobber lines that drifted under you. In multi-agent filespaces, pair this with ``claim_file``. NOTE: the file is rewritten with LF line endings — CRLF (and unicode line separators) are normalized to ``\n`` across the whole file. Use ``search_replace`` to edit a CRLF file without changing its endings.

Summarize the linked filespace: entry count, stored size, and external-file totals. For a files-vs-directories breakdown, use ``count_files`` (a tree walk).

Find files / directories by name (fnmatch glob). ``name_pattern``: shell-style glob, e.g. ``'*.py'``, ``'*report*'``. ``limit``: max paths returned (clamped to 1000). Walks the filespace tree under ``path_prefix``. Stops at the configured walk budget (default 5000 entries / 30s) and reports partial results.

Return metadata for a single file or directory. ``ctime``/``mtime`` are epoch nanoseconds; the ``*_iso`` twins are the same instants in ISO 8601 UTC — paste them straight into ``read_audit_trail``'s ``time_range`` (e.g. ``'<ctime_iso>/'``) to scope an audit query to the entry's lifetime.

Search file CONTENTS via Python regex (re.search). ``pattern`` is a Python regex applied per line. ``include_pattern`` / ``exclude_pattern`` are fnmatch globs filtering filenames before reading; an excluded directory is skipped whole (``exclude_pattern='node_modules'`` never enters one). ``path_prefix`` itself is never excluded. Files larger than ``max_file_size_bytes`` are skipped. ``limit`` is clamped to 1000; the walk stops at the global budget and reports partial results. Walking the tree via the SDK is slower than native grep on a local FS — prefer narrow ``path_prefix`` and ``include_pattern`` for large filespaces.

Link an S3 object as a read-only file in the linked filespace. ``data_store_name`` is an S3 data store; ``object_id`` is the S3 object key, which the daemon looks up in the bucket before linking.

Link a direct HTTP/HTTPS URL as a read-only file in the filespace. On filespace format 3.8 and newer the link belongs to an HTTP-link data store: pass its ``data_store_name`` (list_data_stores shows them, register_data_store(kind="http_link") makes one). Below 3.8 omit it; a wrong choice is answered with the rule for this filespace. The URL is passed as an argument, so avoid embedding long-lived secrets; prefer public or short-lived signed URLs.

Make a filespace the current one for filesystem / locking / audit tools, linking it if needed. ``name`` accepts the short name, the id, or the globally unique full name ``<filespace>.<workspace>``. Resolution is CROSS-ACCOUNT: when the current account can't see it, the other configured accounts are searched and the current account switches automatically (the output says so) — no use_account needed first. ADDITIVE: any previously linked filespaces stay live (their locks and subscriptions survive), so switching back later is instant. Links count against a per-account cap (``maxLinkedFilespaces``); ``unlink_filespace(name=...)`` frees a slot. A linked filespace allocates a 1 GiB disk cache that stays until the server exits. ``account`` pins the lookup to one configured account; a successful link always makes its account the current one.

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. Returns an opaque handle_id token. Pass it to ``unlock_byte_range`` to release (works even after switching filespace or account — the handle remembers where it lives). To modify the locked range, use ``write_at(path, offset, ...)`` for a positional patch (or ``write_file`` to replace the whole file).

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_prefix scopes to one entry: the exact path or anything under it as a directory (/reports does not match /reports-archive). time_range accepts '24h' / '7d' / '30m' or an ISO range 'from/to' with either side omittable ('2026-01-01/2026-02-01', '2026-07-01/'); range ends are midnight-UTC of the named day, so an inclusive "through June" range ends at 07-01. Epoch seconds/millis/ micros/nanos also work as range endpoints. Pass time_range=None for no time filter — '' is rejected, as is path_prefix=''. SCOPING FOR SPEED: logs are month-partitioned and pruned by time_range BEFORE any I/O — a tight range skips whole months of reading. For one existing file's history, call get_entry(path) first and start the range at creation: time_range='<ctime_iso>/'. Its mtime_iso is a safe UPPER bound only for content-write history (moves/renames do not bump mtime; reads never do) — for move/delete/read history leave the range open-ended. Deleted files have no get_entry: fall back to path_prefix (or action=FileDelete) over an explicit wider range. Renames change entry_path, so path_prefix misses pre-rename history regardless of time scoping.

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 and skips their subtrees entirely, so they cost nothing against the walk budget. The default hides the audit trail — query that with ``read_audit_trail``, or map it via ``tree(path="/.lucid_audit")``, which works because exclusion never applies to ``path`` itself. Pass null to map everything.

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'`` with base64-encoded content to write binary bytes. Mirrors POSIX ``pwrite``: an ``offset`` past the end of the file zero-fills the gap, so a large ``offset`` grows the file with zero bytes. When a write grows the file the result says ``GREW file old->new bytes`` — for a fixed-layout patch that usually means the ``offset`` was wrong. ``sync=true`` (default) flushes to the hub immediately; ``sync=false`` skips the flush for bulk writes — you MUST call ``sync_filespace`` afterward or the unsynced writes are LOST when the session ends.

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; you MUST call ``sync_filespace`` afterward or the unsynced writes are LOST when the session ends.