FakeParrot Mac folder

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

Download the FakeParrot Mac app. It needs macOS 13 or later.
Open the installer. It puts FakeParrot in Applications and starts it.
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.
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 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-<company>. <company> 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 <page title>.md. An HTML page appears as <page title>.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 to check the server's content.

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:

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 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.

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.

Help

Email support@fakeparrot.com. Report security issues to security@fakeparrot.com.