Skip to content

Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.

docs: list every analytics event, its sender and its funnels

leepokai34bc12da961f
diff --git a/docs/features/analytics.md b/docs/features/analytics.md
index ac01a7bb..931ae94e 100644
--- a/docs/features/analytics.md
+++ b/docs/features/analytics.md
@@ -36,40 +36,26 @@ UI: *About usage analytics…*) shows the same promise in the app, in one text p
## Where events come from
-- **Host** (`host/src/analytics.rs`): `api::dispatch` maps successful API calls to events
- (`analytics::observe_call`), so every client is covered once: `bot_created`, `bot_updated`,
- `bots_reordered`, `bot_deleted`, `message_sent`, `turn_stopped`, `session_reset`, `permission_answered`,
- `routine_saved`, `routine_deleted`, `routine_run`, `voice_call_finished`,
- `remote_screen_opened`, `connector_installed`, `skill_installed`. A resent message (same
- `clientNonce`, e.g. a phone replaying after a reconnect) is not counted again. Bot actors
- report `turn_finished` when an agent's turn ends. `client` is `local` (desktop app, terminal UI)
- or `remote` (phones). Each event carries its own `timestamp` and `uuid` (a resent batch counts
- once) and the computer's key (`computer`, a hash of its id); batches go to `/batch/` every 30 s and once more when the
+- **Host** (`host/src/analytics.rs`, `analytics/`): `api::dispatch` maps successful API calls to
+ events (`analytics::observe_call`), so every client is covered once; a resent message (same
+ `clientNonce`) is not counted again. Bot actors report `turn_finished`, the phone channel
+ reports pairing and daily phone connections, and the host reports its own start. Each event
+ carries its own `timestamp` and `uuid` (a resent batch counts once) and the computer's key
+ (`computer`, a hash of its id); batches go to `/batch/` every 30 s and once more when the
host stops.
-- **Desktop** reports app-level events through the loopback-only `track` method
- (`app_opened`, `onboarding_completed` when the welcome screen is finished, `signed_in`,
- `signed_out`) and turns sharing on or off with `setAnalytics`; `hello` carries `analytics: true | false`.
- The **terminal UI** reports only `app_opened` (it has no welcome screen or sign-in).
-- **iPhone** (`CodyncKit` analytics client, no SDK) sends its own app-level events
- (`app_opened`, `onboarding_completed`, `computer_paired`, `signed_in`, `signed_out`,
- `voice_call_started`) straight to PostHog. Widgets and the notification extension never send.
- **Android** (`apps/android/.../Analytics.kt`, its port, no SDK) sends the same events with
- `$lib` `codync-android`; widgets never send.
-
-## Event properties
-
-Besides `env`, `app_version`, `$os`, `$lib`:
-
-| Event | Properties |
-|---|---|
-| `bot_created` | `kind` (`bot`/`group`), `agent`, `model` or `members` (count) |
-| `message_sent` | `kind`, `agent`, `in_thread`, `attachments` (count) |
-| `turn_finished` | `agent`, `outcome` (`done`/`stopped`/`failed`/`incomplete`), `stop_reason` (ACP's, else `other`), `source` (`user`/`routine`/`group`/`bot`), `seconds`; when failed, `error` (`not_installed`/`sign_in`/`timeout`/`exited`/`agent_error`/`io`/`other`) and, for `agent_error`, the agent's JSON-RPC `rpc_code` and its own category when it names one (`agent_reason`: Claude's `rate_limit`, `overloaded`, `billing_error`, …) |
-| `voice_call_finished` | `seconds` |
-| `connector_installed` | `connector` (catalog name or `custom`) |
-| `skill_installed` | `custom` |
-| `computer_paired` | `via` (`qr`/`account`), `computer` |
-| every host event | `client` (`local`/`remote`), `computer`, `arch` |
+- **Desktop and terminal UI** report app-level events (opening, onboarding, sign-in, screens,
+ the star ask, links) through the loopback-only `track` method, which accepts only the
+ catalog's events and properties. The desktop app queues them until the host answers; when it
+ can't get a working host at all, its main process reports `host_setup_failed` straight to
+ PostHog, only while the host's last answer said sharing is on (or on a first install, before
+ the host stored any setting). It turns sharing on or off with `setAnalytics`; `hello` carries
+ `analytics: true | false`.
+- **iPhone** (`CodyncKit` analytics client, no SDK) and **Android** (`Analytics.kt`, its port)
+ send their own app-level events straight to PostHog. Widgets and the notification extension
+ never send.
+- **codync.dev** counts page views and clicks on download and outbound links without cookies.
+
+Every event, its sender and its properties: [analytics events](../reference/analytics-events.md).
## Error tracking
@@ -127,7 +113,10 @@ join an iPhone's `computer_paired` to the computer's events on `computer` in SQL
| Metric | Definition |
|---|---|
| Active user (DAU/WAU/MAU) | Sent ≥1 `message_sent` in the period. Any event at all counts as *present*, not active (`app_opened` on the iPhone fires on every return to the foreground). |
-| New user | First event of any kind in the period. |
+| Present (frequency) | Days in the period with `app_opened`, `window_opened` or `phone_connected` (stickiness). A computer whose only events are `turn_finished`/`routine_run` ran unattended. |
+| New user | First event of any kind in the period. A new computer also sends `host_started` with `first_run`. |
+| Onboarded | Desktop: `onboarding_completed`. Phones: `computer_paired` (or `onboarding_completed` with `via = skipped`, which is not onboarded). Funnels: [analytics events](../reference/analytics-events.md#funnels). |
+| Star rate | `star_prompt_answered` with `starred` ÷ all `star_prompt_answered`, per `ask`. |
| Activated | Sent ≥1 message from a phone (`message_sent`, `client = remote`) within 7 days of first seen. In the first week of data, 4 of 5 such users came back after 24 h and none of the 6 computer-only ones did. |
| Successful turn rate | `turn_finished` with `outcome = done` ÷ all `turn_finished` with `source = user`, per agent and per `$os`. |
| Frustration rate | (`turn_stopped` + `session_reset`) ÷ `message_sent`, per `$os`. |
diff --git a/docs/reference/analytics-events.md b/docs/reference/analytics-events.md
new file mode 100644
index 00000000..03dc79c0
--- /dev/null
+++ b/docs/reference/analytics-events.md
@@ -0,0 +1,144 @@
+# Analytics events
+
+Every event Codync records, who sends it and what it carries. The rules (feature use only,
+never content; one switch per device; identity) are in [usage analytics](../features/analytics.md).
+A property is a count, a boolean, a public catalog name or one of the values listed here; a
+value outside the list is `other`. Add an event here in the same change that sends it.
+
+Common properties on every event: `env`, `app_version`, `$os`, `$lib`, `$session_id`.
+
+## Senders
+
+| `$lib` | Sender | Path |
+|---|---|---|
+| `codync-host` | The host, for every client's API calls, its own start, phone pairing and connections, and the events the desktop app and terminal UI report through `track` | `host/src/analytics.rs`, `host/src/analytics/` |
+| `codync-ios` | The iPhone app | `apps/ios/Kit/Sources/CodyncKit/Analytics/` (`AnalyticsEvent.swift`), `CodyncUI/AnalyticsTracking.swift` |
+| `codync-android` | The Android app | `apps/android/.../Analytics.kt`, `AnalyticsEvent.kt` |
+| `codync-desktop` | The desktop app's main process, only for host setup failures (no host to report through) | `apps/desktop/src/main/analytics.ts` |
+| `web` | codync.dev, cookieless | `web/app/analytics.tsx` |
+
+Host events also carry `computer` (the computer's key) and `arch`. Host events from API calls
+carry `client`: `local` (desktop app, terminal UI, CLI) or `remote` (a phone), and for
+`remote` the phone's `platform` (`ios`, `android`, `macos`).
+
+## `track`: what the desktop app and terminal UI report
+
+`POST /api/track` (loopback only) takes `{"event": "<name>", ...properties}`. The host accepts
+only the events and properties below (`analytics::Reported`, a typed enum) and drops anything
+else, so a client can't send content by mistake. Every reported event carries `app`
+(`desktop`/`tui`, `desktop` when missing). The desktop app keeps what it reports before the
+host answers and sends it once the host is up.
+
+## Onboarding and conversion
+
+| Event | Sent by | When | Properties |
+|---|---|---|---|
+| `app_opened` | host `track` (desktop, TUI), iOS, Android | Desktop: each launch, once the host answers. TUI: each start. Phones: each return to the foreground. | desktop `at_login` (opened by the login item); phones `notifications` (`allowed`/`denied`/`not_asked`), `widgets` (count on the Home Screen) |
+| `window_opened` | host `track` (desktop) | The chat window is shown after being hidden (tray, dock, shortcut, second launch). A long-running menu bar app opens it many times per launch. | — |
+| `host_started` | host | Each start of the host process | `first_run` (the first start of a new install; `open_store` marks a new host id with an empty `analytics_version`), `updated_from` (the previous version, when it changed), `service` (started by launchd, systemd or the Windows runner: `XPC_SERVICE_NAME`, `SYSTEMD_EXEC_PID`, `CODYNC_SERVICE`) |
+| `host_setup_failed` | desktop main | The desktop app couldn't get a working host | `stage` (`missing_binary`/`install`/`verify`/`not_responding`/`environment`) |
+| `onboarding_step_viewed` | iOS, Android | A first-run screen appears | `step` (`welcome`/`install`/`scan`) |
+| `onboarding_completed` | host `track` (desktop), iOS, Android | Desktop: the welcome screen is finished. Phones: the first-run screens are finished and the tabs appear (a computer paired, signed in to an account, or skipped). | desktop `signed_in`; phones `via` (`paired`/`account`/`skipped`) |
+| `computer_access_finished` | host `track` (desktop) | The *Computer access* step is left | `ready` (screen recording and control granted), `onboarding` |
+| `sign_in_started` | host `track` (desktop), iOS, Android | A sign-in button is pressed | `provider` (`apple`/`google`/`hosted`) |
+| `sign_in_failed` | host `track` (desktop), iOS, Android | Sign-in ended without an account | `provider`, `reason` (`cancelled`/`timeout`/`verification`/`error`) |
+| `signed_in` | host `track` (desktop), iOS, Android | Signed in to a Codync account | `provider` |
+| `signed_out` | host `track` (desktop), iOS, Android | Signed out | — |
+| `pairing_code_created` | host (`pairing`) | A pairing QR code is made (desktop, terminal UI, `codync-host pair`), including each new one an open pairing screen makes when its code expires: count persons, not events | `client` |
+| `pairing_failed` | iOS, Android | A pairing attempt fails | `reason` (`not_pairing_link`/`outdated_host`/`invalid`/`expired`/`unauthorized`/`unreachable`/`timeout`/`upgrade_required`/`other`) |
+| `computer_paired` | iOS, Android | The phone reached a computer | `via` (`qr`: scanned or pasted on the scan screen; `link`: a pairing link opened from outside; `account`), `computer` |
+| `device_paired` | host | A phone was added: a pairing code redeemed or an account request approved | `via` (`qr`/`account`), `platform`, `automatic` (approved without a tap) |
+| `access_requested` | iOS, Android | The phone asks an account computer for access | — |
+| `access_request_failed` | iOS, Android | The request ended without access | `reason` (`denied`/`expired`/`cancelled`) |
+| `access_request_denied` | host (`decideAccessRequest`) | The computer's owner denied a phone | `client` |
+| `device_revoked` | host (`revokeDevice`) | A phone's access was removed | `client` |
+| `phone_connected` | host | A paired phone connects, at most once per phone per UTC day | `platform` |
+| `notifications_answered` | iOS, Android | The system notification prompt was answered | `granted`, `source` (`settings`/`widgets`/`automatic`) |
+| `notification_opened` | iOS, Android | A Codync notification was tapped | `kind` (`done`/`needs_input`/`failed`) |
+| `star_prompt_answered` | host `track` (desktop) | The GitHub star sheet was answered or closed | `ask` (`first`/`second`), `starred` |
+| `link_opened` | host `track` (desktop), iOS, Android | An outbound link was opened (`install_command`: an install command copied) | `link` (`github`/`docs`/`issues`/`discord`/`app_store`/`demo`/`tailscale`/`privacy`/`support`/`install_command`/`product_hunt`) |
+
+## Using Codync
+
+| Event | Sent by | When | Properties |
+|---|---|---|---|
+| `screen_viewed` | host `track` (desktop, TUI), iOS, Android | A screen, sheet or tab is shown | `screen` (see *Screens*) |
+| `bot_created` | host | `createBot` | `kind` (`bot`/`group`), `agent`, `model` or `members` (count) |
+| `bot_updated` | host | `updateBot` | `fields`: the settings that changed, as the bot config's own camelCase keys (`model`, `permission`, `pinned`, `modelOptions`, `fastMode`, …), never their values |
+| `bots_reordered` | host | `reorderBots` | — |
+| `bot_deleted` | host | `deleteBot` | — |
+| `message_sent` | host | `send` (a resend counts once) | `kind`, `agent`, `in_thread`, `attachments` (count) |
+| `turn_stopped` | host | `stop` | — |
+| `turn_finished` | host | An agent's turn ends | `agent`, `outcome` (`done`/`stopped`/`failed`/`incomplete`), `stop_reason`, `source` (`user`/`routine`/`group`/`bot`), `seconds`; when failed, `error` and, for `agent_error`, `rpc_code` and `agent_reason` |
+| `session_reset` | host | `newSession` | — |
+| `permission_answered` | host | `respondPermission` | `choice` (`allow_once`/`allow_always`/`reject_once`/`reject_always`/`other`) |
+| `reaction_added` | host | `react` | — |
+| `handoff_answered` | host | `editHandoff`, `keepConversation` | `action` (`edit`/`keep`) |
+| `memory_edited` | host | A memory method that changes something | `action` (`save`/`pin`/`archive`/`forget`/`clear`/`undo_dream`/`answer`/`undo`/`file_save`/`file_delete`/`file_restore`) |
+| `routine_saved` | host | `saveRoutine` | — |
+| `routine_toggled` | host | `setRoutineEnabled` | `enabled` |
+| `routine_deleted` | host | `deleteRoutine` | — |
+| `routine_run` | host | `runRoutine` | — |
+| `voice_call_started` | host `track` (desktop), iOS, Android | A voice call starts, with the engine it really uses after any fallback | `engine` (`on_device`; `openai`/`gemini` realtime; `cloud`: cloud speech to text and back) |
+| `voice_call_finished` | host | `logCall` | `seconds` |
+| `remote_screen_opened` | host | `screenPrepare` (each connection, reconnects included) | — |
+| `screen_taken_over` | host | `screenTakeover` (taking control, not handing it back) | — |
+| `connector_installed` | host | `installConnector`; a Composio app once its connection is `active` | `connector` (catalog name, `composio` or `custom`) |
+| `connectors_imported` | host | `importConnectors` | `count` |
+| `connector_removed` | host | `removeConnector` | — |
+| `connector_signin_started` | host | `connectorSignIn` | — |
+| `skill_installed` | host | `installSkill` | `custom` |
+| `skill_removed` | host | `removeSkill` | — |
+| `credential_saved` | host | A key, login or vault is saved (clearing one isn't) | `kind` (`login`/`onepassword`/`connector`/`composio`/`voice`/`agent_env`) |
+| `agent_setup_started` | host | `agentSetup` (an agent's install or sign-in terminal) | `agent` |
+| `agent_signed_in` | host | `agentAuthenticate` | `agent` |
+| `setting_changed` | host, iOS, Android | A setting is switched | `setting` (host: `remote_access`/`approval` (`on`: approved without the code)/`automatic_updates`/`remote_screen`; phones: `push`/`live_activities`), `on` |
+| `host_update_installed` | host | `installHostUpdate` | — |
+
+## Screens
+
+`screen_viewed` names one screen per value, the same on every client that has it:
+
+| `screen` | iOS / Android | Desktop | Terminal UI |
+|---|---|---|---|
+| `bots` | Bots tab | — (always shown) | — |
+| `state` | State tab | — | — |
+| `chat` | a conversation opened | a conversation opened | a conversation opened |
+| `thread` | a reply thread | a reply thread | a reply thread |
+| `trace` | full conversation | full conversation | full trace |
+| `bot_details` | bot details | details panel | settings page |
+| `memory` | bot memory (Android: the card in bot details, once it scrolls into sight) | memory tab | memory overlay |
+| `routines` | routines (iPhone: a routine's editor, the list being part of bot details) | a routine's editor | routines overlay |
+| `marketplace` | extensions | extensions | marketplace overlay |
+| `settings` | computers & settings, opened from the account | settings | — |
+| `computers` | computers & settings, opened from the computers sheet | computers & devices | — |
+| `usage` | usage | usage | usage overlay |
+| `account` | account sheet | account panel | — |
+| `pairing` | pair a computer after setup (first run: `onboarding_step_viewed`) | pair a phone | pair overlay |
+| `voice_settings` | voice chat settings | voice chat settings | — |
+| `remote_screen` | remote screen | — | — |
+| `computer_access` | — | computer access | — |
+| `help` | — | — | keys overlay |
+
+## Funnels
+
+The *Onboarding & conversion* dashboard in PostHog reads these steps, each per `$os`:
+
+- **Desktop**: first `app_opened` (or `host_setup_failed`) → `onboarding_completed` →
+ `computer_access_finished` → `pairing_code_created` → `device_paired` → `message_sent` with
+ `client = remote` (Activated).
+- **iPhone / Android**: `onboarding_step_viewed` `welcome` → `install` → `scan` →
+ `computer_paired` → `message_sent` with `client = remote` on that `computer`.
+- **Star**: `star_prompt_answered` with `starred` ÷ all `star_prompt_answered`, per `ask`.
+- **Website**: `$pageview` → `download_clicked` (per `platform`) → the first `app_opened` that day
+ (counts only, no link between a visitor and an install).
+
+## Website
+
+codync.dev counts visits without cookies or anything stored on the visitor's device
+(posthog-js `cookieless_mode: 'always'`, which needs the project's *cookieless server hash mode*;
+without it PostHog drops these events): `$pageview`, `download_clicked` (`platform`:
+`mac`/`windows`/`linux`/`ios`; `linux` and the Homebrew `mac` are copies of the install command),
+`link_opened` (`link`). One document-level click listener in `web/app/analytics.tsx` reads each
+link's `href`, so a new link is counted without code; the film counts as `demo` when focus moves
+into its frame.