# FakeParrot Mac folder --- **Last updated:** October 5, 2026 --- The FakeParrot Mac app puts your company's wiki in Finder. Every page is a Markdown (`.md`) file, so any AI app that can read files on your Mac can read and edit your company's knowledge. Changes you save sync back to FakeParrot. ## Install 1. [Download the FakeParrot Mac app](/download). It needs macOS 13 or later. 2. Open the installer. It puts FakeParrot in Applications and starts it. 3. Sign in. The app opens your browser, you approve this Mac there, and the browser hands you back to the app. You never type a password into the app. 4. Finder asks you to turn the folder on. Click the blue **Enable** button at the top right of the Finder window. The installer also adds the [`fakeparrot` command](/developers/cli) and a FakeParrot skill for Claude Code, Codex and Cursor. The app checks for updates on its own and shows a dot on its menu-bar icon when one is ready. ## Where the folder is - In Finder, under **Locations** in the sidebar. - On disk, at `~/Library/CloudStorage/FakeParrot-`. `` is your company's short name in FakeParrot, for example `FakeParrot-woolf`. macOS manages this folder for the app. Point your AI app at the path above; do not copy the folder somewhere else, because a copy does not sync. ## What is in it The folder has four top-level folders. You see only what you can read in FakeParrot: the server sends this Mac nothing else. | Folder | What it holds | Who sees it | |---|---|---| | **System** | Pages FakeParrot manages for your company. Read-only. | Set by FakeParrot | | **Company** | The company wiki, including team pages. | Everyone the page is shared with: the whole company, or the members of that team | | **Shared** | Private pages people have shared one to one, both pages shared with you and pages you shared. | You and the people each page is shared with | | **Private** | Your own pages. Your **Inbox** folder lives here. | Only you | Beside the four folders is one file, `AGENTS.md`: instructions for AI apps that work in the folder. It says what the folder is, how to find what a task needs and where to save what the app learns. It also asks the app to save a short check-in page, `FakeParrot check-in.md`, on the first task of each chat and to tell you in one line. The check-in names the app, the date and the revision of the instructions, so you can see the app read them. From the top level, the check-in goes in `Private/Inbox/`. FakeParrot writes the file and updates it when the instructions change; you cannot edit, rename or delete it. An app follows it only if it reads instructions from the folder it works in. If yours does not, ask it to read `AGENTS.md` first. If you do not see the file, update the Mac app. Each page appears as `.md`. An HTML page appears as `.html`. Uploaded files, such as PDFs or spreadsheets, keep their own names. When two pages in a folder have the same title, the newer one gets the first eight characters of its page ID added, for example `Pricing (3f2a9c1b).md`. A padlock on a file or folder means you cannot change it. System is always read-only, and so is any page you can read but not edit. ## What syncs ### Changes made elsewhere - **How fast:** the FakeParrot server tells the app about changes as they happen. The app also checks every 30 seconds, in case that connection drops. - **Downloads on first open:** a page's text downloads the first time something opens it. Up to 12 index and home pages near the top are downloaded ahead of time so the folder does not look empty. - **Keep offline:** right-click a folder and choose **Offline** to keep everything in it on your Mac. Your company's admin can set a default for each top-level folder. ### Changes you make | You do this in the folder | FakeParrot does this | |---|---| | Save a page | Saves a new version of the page. | | Save a page someone else changed since you opened it | Keeps their version. Your text is saved in the page's history, and the app tells you where. | | Add a `.md` file | Creates a page. The file name becomes its title. | | Add an `.html` file | Creates an HTML page. | | Add any other file | Uploads it as a file in that folder. | | Add a folder | Creates a folder. A new folder directly under Company goes to an admin for review. | | Rename a page | Changes the page's title. Old links still work. | | Move a page or folder | Moves it in FakeParrot, if you are allowed to. One moved directly into Company goes to an admin for review. A refused move snaps back. | | Move a page to the Trash | Deletes it. You can restore it from the FakeParrot Trash in Finder, or from the web app. | Some changes are refused: - Nothing can be added to System, moved there or deleted from it. - Files dropped directly into Company, Shared or Private go to your Inbox in Private. Put them in a folder inside Company to share them. - macOS packages, such as Keynote or Pages documents, are refused. Zip or export them first. - Hidden files, `.DS_Store`, Office lock files (`~$…`) and temporary files are skipped. - A file over the upload size limit stays on your Mac and is not uploaded. If your Mac is offline, saved changes wait on the Mac and upload when it is back online. If FakeParrot is not running, a file at the top of the folder says so; anything you save there syncs once the app runs again. ### Confirm a Markdown save from an agent The native `sync` commands below reach installed Macs with the next signed FakeParrot release that includes them. A web deployment does not update the installed command or File Provider extension. If `fakeparrot sync` is unknown, update FakeParrot. Until then, do not report a folder save as confirmed from the tray's check mark; use the existing REST page/version reads through [`fakeparrot call`](/developers/cli) to check the server's content. ```bash fakeparrot sync resolve "$HOME/Library/CloudStorage/FakeParrot-woolf/Private/Inbox/Notes.md" fakeparrot sync status "$HOME/Library/CloudStorage/FakeParrot-woolf/Private/Inbox/Notes.md" fakeparrot sync wait "$HOME/Library/CloudStorage/FakeParrot-woolf/Private/Inbox/Notes.md" --wait-seconds 180 ``` `resolve` returns the page's stable UUID, File Provider identifier and current path. It does not read the body or confirm a save. An unassigned new file, missing manifest, older extension or unreachable File Provider can return `unavailable`; retry once FakeParrot has assigned the page its identity. `status` inspects one body. `wait` captures the UTF-8 body digest and file modification time once, then watches that body through the stable identifier, including a rename during the wait. It uses the upload journal's matching mutation receipt and independently reads the named version through `GET /api/wiki/pages/{page_id}/versions/{version}`. It never submits the body itself. A manifest poll or daemon collection in `replica` is a separate check, and cannot confirm that the save reached the server. For a save you are about to make, record its time before writing. Pass that time as `--after`, especially if your writer preserves the old modification time. To resume an interrupted wait, reuse `body.content_sha256` and `body.saved_after` with the latest `body.path`: ```bash fakeparrot sync wait "/current/path/Notes.md" \ --sha256 SAVED_BODY_SHA256 --after SAVED_AFTER --wait-seconds 180 ``` `--after` accepts Unix epoch seconds with a fractional part, or an ISO-8601 timestamp. JSON times use epoch seconds with their fractional precision. `--poll-seconds` changes the wait cadence (default: 2 seconds). All three commands emit one JSON envelope; `--json` is also accepted. | `body.state` | Evidence and next action | Exit | |---|---|---| | `pending_upload` | No matching receipt yet. The journal may hold the body, or the daemon may not have handed it to the extension. Keep the local file. | 2 for `status`; 4 if the wait expires | | `confirmed` | This body's receipt was applied, and the named server version was read successfully. `server_version` names that version; a later server edit may already be current. | 0 | | `conflict` | The concurrent server edit stays current. This body's `save.receipt.saved_draft_version` was read from History. Read and reconcile both versions. | 3 | | `unavailable` | The extension, manifest, journal or server version could not be read, or its receipt cannot prove an applied/preserved body. Open or update FakeParrot, check CLI sign-in and page access, then retry. | 2 for `status`; 4 if the wait expires | `resolve` exits 0 when identity resolution succeeds, with a message that no save confirmation was requested. For `status` and `wait`, only `confirmed` has `ok: true`. A timeout has `timed_out: true` and `upload_cancelled: false`; it leaves the upload and the user's bytes alone. Never retry a timeout by overwriting the server through another write route. The journal keeps the latest observed content save for each page and account. An older save that has been superseded, or a save made before the new extension recorded receipts, may lack evidence. It remains unconfirmed. The receipt binds the submitted body digest; `server_content_sha256` describes the stored version, which can differ when the server normalizes page content. ### Not built - **No pause.** Sync runs whenever the app runs. Quitting the app stops sync; the folder stays in Finder until you open the app again. - **No instructions file inside folders, and no `CLAUDE.md`.** The only instructions file is `AGENTS.md` at the top level. The `fakeparrot integrate` command adds instructions to your own Claude Code and Codex settings; the [memory guide](/developers/memory) covers each AI app. - **No search index on disk.** Pages download when opened, so searching the whole folder downloads every page. Use the CLI or MCP server to search. Signing out of the app (Settings → Account → **Sign out of this Mac**) removes the folder and its downloaded copies. Changes that had not finished uploading are moved to a folder in your home folder first, and the app tells you where. ## How an AI app should use FakeParrot Use the first of these three your AI app can reach. Each one acts as you, so the app sees and changes only what you can. ### 1. Folder If the app can read files on your Mac, read wiki pages from the folder. - Read `AGENTS.md` at the top of the folder first. - Open a page you can name, or one linked from an index page. - Do not search the whole folder. Each page downloads on first open, so a folder-wide search downloads every page. - Edit pages by saving the file. An edit is in FakeParrot only once it has synced. - The folder holds wiki pages, not live data. Workflow runs, connections and other live company data are not in it. Works in Claude Code, Codex and Cursor on your Mac, Claude Cowork as a connected folder, and the Claude desktop app with file tools turned on. ### 2. CLI If the app can run commands in a terminal on your Mac, use `fakeparrot` to search the wiki and to read live data, such as workflow runs and connections. The Mac app installs it and signs it in. Run `fakeparrot auth status` to check. See the [CLI guide](/developers/cli). Works in Claude Code, Codex and Cursor. Cowork runs commands in a separate sandbox, so it cannot run the Mac CLI. ### 3. MCP server Use the MCP server at `https://fakeparrot.com/mcp` when the folder and the CLI are not available, or cannot do the task. The CLI can reach workflow authoring through `describe` and `call`; a missing convenience command is not a missing capability. It is the only option in claude.ai, ChatGPT and Cowork's web sessions. See the [MCP server guide](/developers/mcp). ## Help Email [support@fakeparrot.com](mailto:support@fakeparrot.com). Report security issues to [security@fakeparrot.com](mailto:security@fakeparrot.com).