--- name: localfiles description: >- Connect this agent to the user's open localfiles.eu tab (documents, sheets, slides kept in their browser) and work on their files. Use when asked to "connect to localfiles.eu" or to read or edit localfiles documents. --- # Connect to localfiles.eu Documents live in the user's browser (IndexedDB), optionally synced to their trusted PSS. Use `localfiles-agent`, a small local bridge (one static binary, no dependencies) that the user pairs with their open tab in one click. Paired, you can do all the user can do in that tab, deleting included: say so and get consent before installing. ## 1. Install the bridge (once; again when the Agent page says "outdated") - Binaries: https://localfiles.eu/agent/bin/ + `localfiles-agent-linux-x86_64`, `-linux-aarch64`, `-macos-universal` (Intel and Apple silicon), `-windows-x86_64.exe`. Pick by `uname -sm` (Windows: `$env:PROCESSOR_ARCHITECTURE`). - Install to `~/.local/bin/localfiles-agent` (Windows: `%LOCALAPPDATA%\localfiles\localfiles-agent.exe`). - Check the download against `files..sha256` in https://localfiles.eu/agent/bin/manifest.json; on a mismatch stop and tell the user. Installed already: re-download when `--version` differs from the manifest `version`. ```sh N=localfiles-agent-linux-x86_64; B=~/.local/bin/localfiles-agent; mkdir -p ~/.local/bin curl -fsSLo "$B" "https://localfiles.eu/agent/bin/$N" && chmod +x "$B" curl -fsSL https://localfiles.eu/agent/bin/manifest.json; sha256sum "$B" # macOS: shasum -a 256 "$B" "$B" --version ``` Windows (PowerShell): `curl.exe -fsSLo `, then `Get-FileHash ` (SHA256). ## 2. Register it for later sessions Use the absolute path of the binary. - Claude Code: `claude mcp add --scope user localfiles -- mcp` - Codex: `codex mcp add localfiles -- mcp` - Any MCP client: stdio server, command ``, argument `mcp`. - Pi and other agents without MCP use the CLI (step 3). - Save this file as a skill so later sessions know it: `~/.claude/skills/localfiles/SKILL.md`, `~/.codex/skills/localfiles/SKILL.md` or `~/.pi/agent/skills/localfiles/SKILL.md`. MCP clients load a new server on their next start; until then this session uses the CLI. ## 3. Pair with the tab - MCP tools loaded: call `localfiles_pair`, give the user the link, poll `localfiles_status` until connected. - Otherwise start a background bridge and get the link (it exits when its tab disconnects): ```sh nohup localfiles-agent serve >/dev/null 2>&1 & localfiles-agent pair --open # prints the link, opens the browser localfiles-agent status # repeat until "connected":true ``` Windows: `Start-Process serve -WindowStyle Hidden`. A sandbox must allow a loopback listener; if it blocks the bridge, ask the user to approve running it outside the sandbox. - Tell the user: "In the localfiles tab that just opened, click **Connect** (allow local network access if the browser asks). Use the browser profile that holds your files." The link opens Agent → Connect an agent. ## 4. Work - Instructions/tool schemas: `localfiles://instructions`, or `localfiles-agent tools`. - Before raw Yjs edits, read `localfiles://format`: lifecycle, container, definitions and body schemas. - MCP: call the tools (or `localfiles_call {tool, arguments}` if the tool list did not refresh). CLI: `localfiles-agent call files_list`, `localfiles-agent call richtext_read '{"id":"..."}'`, or `@args.json`. - Start with `files_list`; `files_search {query}` finds files by title and text, like Home search. Confirm with the user that these are the expected files before editing. Read back writes. - File tools take a local `path` (import from, export to) instead of base64. - `import_archive {path, parentId?}` imports a ZIP (Google Drive download, Takeout chunk, any folder archive): folders recreated, `Takeout/Drive/` stripped, sources imported before skipped by content hash; returns `{imported, skipped, failed, folders}`. `file_import` skips the same way (`{skipped, file?}`). - Moving a Google Drive: ask the user for the Drive **Download** ZIPs or a Takeout export and run `import_archive` (best fidelity, no Google API). With a Drive connector, fetch each document as DOCX/XLSX/PPTX, or Markdown as a fallback, then `file_import {path, parentId}` per file into folders you create with `folder_create`; text-only connectors lose images and formatting, so say so. - `file_copy {id}` forks content into a new file owned by the current account, without shares or history. `backup_restore` keeps verified file ids and merges files and folders; it does not make independent forks. - `folders_list` gives private folder IDs/parents, scoped decisions and pending jobs. Folder names/paths never go to shared-file recipients. `files_list {parentId, recursive:true}` searches a subtree; omit parent for all files. - `folder_create`/`rename`, `folders_move`, `folder_copy`/`export`, `folders_cut`/`paste` use the browser's model. Create/import/copy accepts a target `parentId`. Copy/export requires local content; never silently skips files. - `folder_trash`/`delete` previews recursive scope/counts unless `confirm:true`; `everywhere` defaults false. Ask before confirming; remote-only and already-trashed descendants count too. Never imply remote wipe. `folder_restore`/`retry` takes a batch ID. Other devices may still be syncing after local completion. - Account/directory backups include private organization; single-file exports omit it. Finish pending copy jobs before exporting a backup. A restored file owned by someone else is a backup copy: `sharing_request_access {id}` asks its owner; the owner answers with `sharing_access_answer {id, share}`. - Edits appear live in the tab. Ask before destructive tools (trash, delete, storage key). ## Disconnect and safety - **Disconnect agent** on the Agent page, or closing the tab, revokes access; pairing again needs a new link. - The bridge listens on loopback only, pairs only with https://localfiles.eu by a one-time code, serves one tab and makes no outbound calls. Tool results may reach your model provider; explain that privacy boundary to the user. - Source: https://codeberg.org/localfiles/localfiles (`agent/`).