docs/desktop-agent

Desktop Agent

v1.3.0last modified 2026-03-27

System Requirements

minimum requirements

os:macOS 12 (Monterey) or later

architecture:Apple Silicon (M1+) or Intel x86_64

disk:~50 MB

memory:~30 MB resident (menu bar process)

network:HTTPS outbound (encrypted)

plan:Pro plan required

Download & Install

1. Open Ekachit app → Settings → Desktop Agent → Download

2. Open the downloaded installer

3. Drag Ekachit Agent to Applications

4. Open Ekachit Agent from Applications

The agent launches and appears as a icon in your menu bar. It will ask you to sign in with your Ekachit account.

Verify Installation

1. Look for the icon in your macOS menu bar

2. Click the icon → Status should show "Connected"

3. If the icon shows a warning badge, see Troubleshooting below

If the menu bar icon shows the with no warning badge, the agent is running correctly.

Accessibility API Permission

The agent needs Accessibility API access to detect which category of application is in the foreground.

// grant permission

1. System Settings → Privacy & Security → Accessibility

2. Click the lock icon to unlock (Touch ID or password)

3. Toggle Ekachit Agent → ON

4. Restart the agent (menu bar → Restart)

ℹ What it can do: Read the bundle identifier of the frontmost app (e.g., com.microsoft.VSCode)

✕ What it cannot do: Read screen content, capture keystrokes, interact with other apps, read file contents, access clipboard

The Accessibility API gives us the app name — which we immediately convert to a category and discard. The raw app name is never transmitted or stored.

Screen Recording Permission

⚠ This permission is OPTIONAL and OFF by default. Most users do not need it.

Screen Recording permission is only needed if you enable the experimental "window title categorization" feature, which uses the window title to more accurately categorize browser tabs (e.g., distinguishing GitHub from YouTube). Even then, the title is processed locally and never transmitted.

# If you're unsure, skip this. The agent works fine without it.

Configuration

Configure the agent from the menu bar: click the → Preferences

configurable options

sync_frequency:How often data syncs (default: every 5 minutes)

idle_detection:Time before marking you as idle (default: 5 minutes)

excluded_apps:Apps to ignore (won't be categorized)

auto_start:Launch agent on login (default: on)

All configuration is stored locally with owner-only file permissions.

Tracking Categories

The agent classifies every foreground app into one of these categories:

IDE:VS Code, IntelliJ, Xcode, Vim, Neovim, Cursor

browser_work:Chrome/Safari on GitHub, Jira, Confluence, Docs

browser_social:Chrome/Safari on Twitter, Reddit, YouTube, News

communication:Slack, Discord, Teams, Telegram, WhatsApp

meeting:Zoom, Google Meet, FaceTime, Webex

design:Figma, Sketch, Adobe XD, Photoshop

terminal:Terminal, iTerm, Warp, Alacritty, Kitty

file_manager:Finder, Forklift, Path Finder

media:Spotify, Apple Music, VLC, QuickTime

other:Unrecognized apps (extensive built-in database)

# browser_work vs browser_social requires the optional Screen Recording permission.
# Without it, all browser activity is categorized as "browser_work".

Sync Interval

sync settings

default:Every 5 minutes

range:1 minute to 30 minutes

transport:Encrypted HTTPS

offline:Queues locally, syncs when reconnected

Lower intervals give more real-time data but use slightly more battery. The default of 5 minutes is optimal for most users.

How Categorization Works

// categorization pipeline

step 1: Read frontmost app bundle ID via Accessibility API

e.g., com.microsoft.VSCode

step 2: Look up in local mapping (500+ known apps)

e.g., com.microsoft.VSCode → IDE

step 3: Record: { category: "IDE", timestamp, duration }

step 4: Discard the bundle ID — never stored, never transmitted

The mapping file ships with the agent and is updated via brew upgrade. Unknown apps default to other.

What IS Tracked

✓app_category (enum: IDE, browser_work, meeting, etc.)

✓timestamp (ISO 8601, when the category became active)

✓duration_seconds (how long you stayed in that category)

✓is_idle (boolean — true if no input for idle_threshold seconds)

What is NOT Tracked

✕window titles (which document, which tab)

✕URLs (which websites you visit)

✕file paths (which files you open)

✕keystrokes (what you type)

✕screenshots (what's on your screen)

✕clipboard contents (what you copy/paste)

✕network traffic (which servers you connect to)

✕other apps' data (we can't read other processes)

✕mouse movements or click coordinates

✕audio or microphone input

Common Issues

Agent not appearing in menu bar

Open Ekachit Agent from Applications manually. If it still doesn't appear, restart your Mac and try again.

"Accessibility permission denied" error

System Settings → Privacy & Security → Accessibility → remove Ekachit Agent → re-add it → toggle ON. Then restart the agent.

High CPU usage (>5%)

Usually happens during the first sync after a long offline period. Click the menu bar icon → Restart. Contact support if it persists.

Data not appearing in mobile app

Click the menu bar icon and verify it shows "Connected". If connected but no data, ensure you're signed into the same account on both devices.

Agent tracking while idle

Adjust idle detection in Preferences. Lower the threshold for more aggressive idle detection.

Logs

View logs: Menu bar icon → View Logs

Rotation: Daily, retained for 7 days

Send to support: Menu bar icon → Send Diagnostics

Uninstall

1. Click menu bar icon → Quit

2. Drag Ekachit Agent from Applications to Trash

3. Empty Trash

Uninstalling the agent does not delete your cloud data. Activity history remains in your Ekachit account until retention expiry or account deletion.

Need help? Contact support@ekachit.app