Mirage: Virtual Filesystem for AI Coding Agents
AI LABSgo watch the original →
the gist
Mirage mounts external services like Gmail, Notion, and Drive as local directories, allowing AI agents to interact with them via standard bash commands instead of complex tool-calling APIs.
The Filesystem Abstraction
Mirage replaces traditional Model Context Protocol (MCP) tool-calling with a virtual filesystem layer. By mounting services as local directories, it enables AI agents to interact with external data using native Unix commands like grep, cat, and cp. This approach avoids the token overhead of learning custom API schemas and prevents context bloat, as the agent executes bash pipelines rather than loading entire tool outputs into its context window.
Implementation and Workflow
To set up the environment, users clone the Mirage repository and allow an agent like Claude Code to guide the installation process. On macOS, the system requires MacFUSE to enable third-party filesystem mounting, which necessitates a system restart and security configuration changes. Once authenticated via OAuth or Google Cloud Console, services appear as folders. Users can chain operations across services using standard bash pipelines, such as searching for email attachments and piping the content directly into a Notion page, without the agent needing to manually manage intermediate tool results.
Persistence and Scalability
Mirage includes a daemon to run workspaces as persistent background servers, solving the issue of lost cache and index states during session restarts. Because the system operates as an HTTP server, workspaces can be hosted remotely, allowing for multi-machine access. This architecture is model-agnostic, supporting any agent capable of executing bash commands, and allows for custom integrations with any service that provides an API.