Faria is a macOS desktop agent that understands your screen and takes action. Press a shortcut to open it, describe what you want, and it handles the rest — clicking, typing, running commands, searching the web, editing files, or calling any tool in your workflow.
| Provider | Models |
|---|---|
| Anthropic | Claude Opus 4.6, Claude Sonnet 4.6 |
| Gemini 3.1 Pro, Gemini 3.1 Flash Lite | |
| OpenAI | GPT-5.4 |
Switch models at any time from Settings. Bring your own API key or sign in to use the managed proxy.
When you invoke Faria, it sees your screen through screenshots and executes actions using a set of built-in tools:
- Computer actions — click, type, scroll, drag, key combos via the Accessibility API
- Bash — run shell commands
- Web search — Serper-powered search with structured results
- File tools — read, write, and edit files
- Replace selected text — in-place text substitution in any app
- Memory — persistent vector memory across sessions; the agent recalls relevant context automatically
- Composio — A lot of app integrations (GitHub, Notion, Gmail, Slack, etc.)
Prerequisites: macOS 12+, Node.js 18+
git clone https://github.com/Panchangam18/faria.git
cd faria
npm install
# Build the native macOS accessibility addon
npm run build:native
# Copy env template and add your API key(s)
cp .env.example .env
# Install cliclick for mouse/keyboard automation
brew install cliclick
npm run devOn first launch, go to Settings and enter at least one LLM API key if you haven't set it in .env. Grant Accessibility permissions when prompted.
The faria-proxy/ directory is a Cloudflare Worker that proxies LLM and tool requests for signed-in users. You only need this if you want to run your own managed deployment (i.e. users sign in and don't bring their own keys).
cd faria-proxy
npm install
# Set provider keys as Worker secrets
npx wrangler secret put ANTHROPIC_API_KEY
npx wrangler secret put OPENAI_API_KEY
npx wrangler secret put GOOGLE_API_KEY
npx wrangler secret put SERPER_API_KEY
npx wrangler deployThen set FARIA_PROXY_BASE=https://your-worker.workers.dev in your .env.
npm run build:native # compile native addon
npm run build # bundle appOutput is in dist/. For a signed and notarized DMG, set the APPLE_* variables in .env and run:
RELEASE_TAG=v1.0.0 npm run release:localfaria/
├── electron/
│ ├── main.ts # Electron entry, IPC, window management
│ ├── preload.ts # Renderer ↔ main bridge
│ ├── agent/ # Agent loop, tools, memory flush, prompts
│ ├── services/ # State extraction, models, proxy, auth, memory
│ └── db/ # SQLite (settings, history, custom tools)
├── src/ # React renderer (command bar, settings, chat UI)
├── native/ # Swift + node-gyp addon for window visibility
└── faria-proxy/ # Cloudflare Worker proxy
MIT — see LICENSE.