# Fa (Flutter Agent Harness)

> One agent harness, every device. Fa is an open-source coding agent for Dart and
> Flutter with a real tool loop: a sandboxed shell (curl, wget, jq, yq, rg, sed,
> awk, find, xargs, diff/patch, tar/zip), git over HTTP and SSH, python3 and
> sqlite3 running in the browser, secrets redaction, a file browser, and a
> session tree with context compaction. It runs on iOS, Android, web, desktop,
> as a CLI, as a Chrome extension, and as an Outlook add-in.

## Live demo

- [Try Fa in your browser](https://fa1.dev/app/):
  bring your own key (BYOK). Keys are held in memory only — never persisted —
  and calls go directly from the visitor's browser to the LLM provider.

## Install

- CLI (macOS, Windows, Linux; requires the Dart SDK, bundled with Flutter):
  `curl -fsSL "https://fa1.dev/install.sh" | sh`
  or `dart pub global activate flutter_agent_harness`. Both provide the `fah`
  and `fa` executables. Set a provider API key (e.g. OPENROUTER_API_KEY),
  then run `fah`.
- Flutter demo app from source:
  `git clone https://github.com/IstiN/flutter_agent_harness`, then
  `cd flutter_agent_harness/flutter_app && flutter run`.

## Chrome extension

- MV3 extension that hosts the full Fa web app in a side panel; the agent
  runs in the service worker and drives the browser with 34 tools:
  `tabs_open`, `tabs_close`, `tabs_update`, `tabs_query`, `tabs_move`,
  `tabs_group`, `tabs_ungroup`, `tabs_reload`, `tabs_discard`,
  `windows_open`, `windows_update`, `windows_close`, `windows_list`,
  `groups_update`, `groups_close`, `sessions_recent`, `sessions_restore`,
  `history_search`, `bookmarks_list`, `bookmarks_add`, `bookmarks_update`,
  `bookmarks_remove`, `downloads_start`, `downloads_search`,
  `downloads_cancel`, `cookies_get`, `cookies_set`, `cookies_remove`,
  `inject_js`, `inject_css`, `cdp_eval`, `page_screenshot`,
  `app_screenshot`, `nav_wait` — plus four Settings-gated second-tier
  tools that surface once the user enables them:
  `browser_search`, `top_sites`, `reading_list`, `page_capture`.
- Entry points: the side panel, the omnibox (`fa <query>`), the
  Ctrl+Shift+1 hotkey, and the context menu on any selection. Page-derived
  content is quarantined as untrusted data. `inject_js` prompts on every
  call in every session mode by default — explicitly switching the
  session to yolo drops that guard (the override is cleared, not
  bypassed silently).
- Artifact (rebuilt on every deploy):
  https://fa1.dev/extension/fa-extension.zip — unzip, then open
  chrome://extensions, enable Developer mode, Load unpacked, pick the
  unzipped folder.
- Architecture and operations: `docs/browser-extension.md` in the repository.

## Outlook add-in

- Fa as an Office Add-in taskpane (MailApp manifest with a
  VersionOverrides command surface, Mailbox 1.8+, ReadWriteItem
  permission): the same pure-Dart agent core plus three mail
  tools — `outlook.read_current_item` (metadata + body of the open email),
  `outlook.read_attachment` (one attachment, base64, 50 MB cap), and
  `outlook.insert_draft_body` (compose mode). Attachment reads and draft
  writes always prompt for approval.
- Email bodies and attachments enter the model context only inside a
  quarantine fence marked as untrusted data, so instructions inside a
  message can never drive the agent.
- Manifest artifact: https://fa1.dev/outlook/manifest.xml — download it,
  open https://aka.ms/olksideload (My add-ins), then Custom add-ins →
  "+ Add a custom add-in" → Add from file → manifest.xml → Install.
  Microsoft removed the manual "Add from a URL" entry, so
  download-then-file is the only self-service install path (works in
  Outlook on the web, new Outlook for Windows, and classic Outlook;
  tenants that block custom add-ins need an admin deployment or a
  personal Outlook.com account). Entry point per client (manifest ≥
  1.1.0.0): new Outlook for Windows and OWA show the «fa» button in a
  message's Apps flyout, classic Outlook on the Home ribbon. The
  taskpane page lives at https://fa1.dev/outlook/; full step-by-step
  guide with troubleshooting: https://fa1.dev/outlook/support.html
- Sources: `office_addin/` in the repository.

## Agent tools (every platform)

- Core tools on every host: `read`, `write`, `edit`, `ls`, `bash`
  (plus background `bash_job`), `web_search`, `web_fetch`, `task`
  (parallel subagents: explore/review/plan; managed with `task_status`,
  `task_send`, `task_observe`, `task_cancel`), `lsp`,
  `memory_add`, `memory_delete`, `memory_list`, `memory_search`,
  `checkpoint`, `rewind`, `ask`, `request_secret`, `config`,
  `agent_message`, `agent_directory`, `schedule_message`, `reply`,
  `transcribe_audio`, `inspect_image`, `generate_image`, `generate_video`.
- MCP: any server configured in `~/.fah/config.yaml` registers its tools
  as `mcp__<server>__<tool>`.
- CLI browser bridge: `fa serve --bridge` + `/browser connect` pairs a
  desktop agent with the extension for `browser_navigate`, `browser_click`,
  `browser_type`, `browser_press_key`, `browser_select`, `browser_tabs`,
  `browser_switch_tab`, `browser_read_dom`, `browser_screenshot`,
  `browser_eval`, `browser_wait_for`.
- The shell behind `bash`: pure-Dart builtins on web, WASI binaries
  (uutils coreutils, ripgrep, python3, sqlite3) on iOS/Android, the host
  shell on macOS/Windows/Linux.

## Project

- [GitHub repository](https://github.com/IstiN/flutter_agent_harness)
- [pub.dev package](https://pub.dev/packages/flutter_agent_harness)
- [Issue tracker](https://github.com/IstiN/flutter_agent_harness/issues)

## Key facts

- Written in Dart; the core library is pure Dart (no dart:io) and compiles to web.
- Providers: OpenAI-compatible (incl. OpenRouter and Ollama Cloud), Anthropic, Google.
- Web sandbox is a pure-Dart in-memory shell; mobile uses WASI binaries
  (uutils coreutils, ripgrep, sed/awk, python3, sqlite3, lua) under an embedded
  wasm runtime.
- Ships as: CLI (`fa`/`fah`), Flutter apps (iOS/Android/macOS/Windows/Linux),
  a static web app, a Chrome MV3 extension, and an Outlook Office add-in.
- License: MIT. Published on pub.dev as `flutter_agent_harness`.

## FAQ (quotable answers)

- What is Fa? An open-source coding agent for Dart and Flutter: a pure-Dart
  agent core plus a sandboxed workbench (shell, git, python3, sqlite3) running
  identically on iOS, Android, web, desktop, and as a CLI — plus a Chrome
  extension and an Outlook add-in on the same core.
- Is the API key safe in the web demo? Yes: memory-only (never persisted to
  localStorage/cookies/disk, gone on reload), and calls go directly from the
  browser to the provider — the page is static files, no server or proxy.
- Which providers? OpenAI-compatible endpoints (OpenRouter, Ollama Cloud,
  self-hosted llama.cpp/LM Studio/vLLM), Anthropic, Google; custom endpoints
  with a base URL, with model list/context window/output caps auto-detected.
- Which platforms? iOS, Android, web (static files), macOS, Windows, Linux,
  CLI — plus a Chrome MV3 extension and an Outlook Office add-in.
- What can the agent do? Shell (curl, jq, rg, sed/awk, tar/zip, diff/patch),
  git clone/push over HTTP and SSH, python3 with pip, sqlite3, QuickJS, file
  edits, web search/fetch, subagents, LSP, MCP tools, persistent memory,
  checkpoint/rewind, and long sessions with automatic context compaction;
  the Chrome extension adds 34 browser tools, Outlook adds three mail tools.
- Is it free? The project is MIT-licensed open source; users pay their own LLM
  provider for tokens only — no subscription or account.
- How to install the CLI? `curl -fsSL "https://fa1.dev/install.sh" | sh`
  (or `dart pub global activate flutter_agent_harness`), then run `fa`.
- How do I install the Chrome extension? Download
  https://fa1.dev/extension/fa-extension.zip, unzip it, then
  chrome://extensions → Developer mode → Load unpacked.
- Does Fa run in Outlook? Yes: download
  https://fa1.dev/outlook/manifest.xml, open https://aka.ms/olksideload
  (My add-ins), then Custom add-ins → "+ Add a custom add-in" →
  Add from file (Microsoft removed "Add from a URL"; guide:
  https://fa1.dev/outlook/support.html). In new Outlook for Windows and
  OWA, open the «fa» button from a message's Apps flyout; classic
  Outlook shows it on the Home ribbon.

See the on-page FAQ for the same answers with anchors:
[fa1.dev FAQ](https://fa1.dev/#faq)

## Widgets

- Sample JS widgets for the Fa agent run in its sandboxed interpreter;
  permissions are declared per widget and default-denied.
- Gallery: https://fa1.dev/widgets/
- Machine-readable catalog:
  https://github.com/IstiN/fa_widgets/releases/latest/download/catalog.json
- Sources and contribution guide: https://github.com/IstiN/fa_widgets