# Faceclaw - An unofficial user interface for the Even Realities G2 smart glasses

This is an unofficial user interface for the Even Realities G2 smart glasses.
It is entirely unofficial, and comes with no support or warranty from Even
Realities or from anyone.

This app runs on Android, and requires installing custom firmware on the
glasses. The Android app itself can install and uninstall the custom firmware;
it downloads the stock firmware from Even and applies patches generated from
https://github.com/jimrandomh/g2flash.


## Installation

To compile, you will need an Android SDK environment with SDK version 35
installed and licenses accepted, and the ANDROID_HOME pointing to the install.
You will need Nativescript installed, and a JDK environment (v21), with the
JAVA_HOME environment variable pointed at it. You will also need a reasonably
up to date npm and nodejs installed.

To install a version that you compiled, you will need `adb` connected. Go to
Settings>About phone and tap the "Build number" field seven times. Then plug
the phone's USB-C port into your computer, authorize access on the phone, then
run `nativescript run android 

The compile, run
  'npm run build'
To install, run
  `nativescript run android --juslaunch`

## Features

 * A voice assistant that wakes up when you say "Hey Even", transcribes text
   with an on-device model, OpenAI Whisper, or ElevenLabs API, and responds
   to queries and commands using an Anthropic or OpenAI model (requires an API
   key), or using your own long-running OpenClaw agent (see "Connecting an
   external agent" below).
 * Multitasking, with an app-switcher sidebar and app launcher
 * A lock screen; glasses lock automatically when you take them off and unlock
   when you unlock your phone
 * Full-screen apps can use  the full 640x480 display area (rather than the
   576x288 that EvenHub apps can use)
 * Integration with Android notifications: A top-bar that shows the
   same icons your phone does, popups when notifications arrive, and menu
   items to dismiss or use Android-app-provided custom actions like mark as
   read or quick reply.
 * Mirror terminal apps such as Claude Code or Codex CLI with g2mirror
   (https://github.com/jimrandomh/g2mirror), view them on the glasses, and
   send them inputs with the voice assistant
 * Media player controls including playlist and media library navigation,
   compatible with most Android media players
 * Turn-by-turn directions (requires a Mapbox API token)
 * Nightscout, an app for viewing blood-glucose data (requires a cloud server
   and API token)
 * Power management: the glasses go to sleep properly when the screen is off,
   and wake when you double-tap the ring or speak the wakeword, allowing
   battery life similar to the stock Even app.
 * Connection management with auto-reconnect, and autodetection of conflict
   with the official Even Realities app
 * On-phone screen mirroring and simulated ring input
 * Dual-language NativeScript architecture with Java for the multithreaded
   Android API and bluetooth stack bits, Typescript for the bits you want to
   hack on

## Connecting an external agent (OpenClaw)

Instead of calling an LLM API directly from the phone, the voice assistant
can route queries to your own long-running agent, which also gets access to
the glasses' tools (show alerts, read notifications, control media, type
into apps including terminals) both during conversations and proactively. This
works through the faceclaw-agent-bridge OpenClaw plugin
(https://github.com/jimrandomh/faceclaw-agent-bridge): the phone dials out to
it over a websocket (typically across a tailnet).

Setup lives in the faceclaw-agent-bridge repository's README. It covers
both the OpenClaw-host side (plugin install and configuration) and the
phone side, which can be configured either by hand in Settings > Assistant
on the glasses, or over adb using scripts/pull_config.sh and
scripts/push_config.sh from this repo; the instructions are written so an
OpenClaw agent with the phone plugged into its host can perform the whole
setup itself. Note that a pulled settings file contains your API keys, so
treat it as a secret (the default output path is gitignored here).

## Additional Caveats

Some permissions are used, but may not reliably prompted for. Go to Android
Settings > Apps > Faceclaw to ensure permissions are available or things may
not work.

Being a background app on a locked Android phone is fraught, and there may be
issues with manufacturer-psecific battery optimization software that lead to
it getting paused, throttled to low CPU usage, etc.