Setup guide

MyAegis documentation

Install the local Aegis daemon, connect your editor and AI tools, then verify that coding, browser, and AI-assisted sessions are flowing into the dashboard.

Start here

Create an account

Install the Aegis CLI

The CLI installs the local daemon, configures hooks, and manages updates.

The daemon listens locally, buffers high-frequency events, and syncs to the API.

Connect tools

Install the editor extension and configure AI hooks for the agents you use.

Check the dashboard

Use the status command and dashboard timeline to confirm sessions are arriving.

macOS fast path

curl -fsSL https://myaegis.dev/install.sh | sh
aegis login
aegis install
aegis install-extension
aegis setup-hooks

What the daemon does

Aegis listens on http://127.0.0.1:45678, receives heartbeats from local tools, buffers them in SQLite under ~/.myaegis, and syncs them to the MyAegis API.

Supported systems

The supported setup today is macOS. Linux builds and service files exist, but Linux should be treated as experimental until it is fully tested. Windows does not currently have a supported MyAegis daemon.

OS	Support level	Release status	Daemon path	Notes
macOS	Supported, tested	Apple Silicon and Intel	launchd user agent	`~/Library/LaunchAgents/com.myaegis.daemon.plist`
Linux	Experimental, not fully tested	x64 and arm64 builds exist	systemd user service path	`Verify manually after install`
Windows	Experimental, not fully tested	x64 build exists	Scheduled task (MyAegisDaemon)	`Install via PowerShell: irm https://myaegis.dev/install.ps1 \| iex`

Installer requirements

The tested path is macOS with the shell installer. It uses curl or wget, writes the binary to /usr/local/bin, and may ask for sudo.

Linux status

Linux may work with the same CLI and a systemd user service, but it is not a confirmed production path yet. After install, verify with aegis status.

Windows status

Windows support is experimental. Install with irm https://myaegis.dev/install.ps1 | iex in PowerShell, then run aegis install to register the daemon as a scheduled task. Verify with aegis status.

Account and API key

Sign in with GitHub, then create an API key from Settings / API Keys. The key is shown once. Store it before leaving the page.

Open MyAegis and sign in with GitHub.
Go to /settings/apikeys and create a key named for this machine or editor.
Paste that key into aegis login. The CLI stores it in ~/.myaegis/config.json with file mode 0600.

Default API

https://api.myaegis.dev

Self-hosted or local development installs can enter a different API URL during aegis login.

Install the daemon

Use this flow for macOS. Linux can use it as an experimental path while daemon support is being validated. Windows is not supported for local daemon tracking yet.

Install the CLI

curl -fsSL https://myaegis.dev/install.sh | sh

Authenticate this machine

aegis login

The prompt asks for the API URL and API key. After authentication, it offers to install the daemon service.

Install and start the background service

aegis install

This creates the platform service, starts it, and can optionally launch the AI hook setup wizard. On macOS this creates a launchd user agent.

Keep the CLI current

aegis update

Useful daemon commands

aegis status              # daemon health, sync queue, and account
aegis projects            # projects with today's tracked time
aegis push                # sync queued local data now
aegis config              # view or edit local preferences
aegis restart             # restart the installed daemon
aegis update              # replace the CLI with the latest release
aegis uninstall           # remove the installed service

Install editor and browser extensions

VS Code and Cursor

The CLI downloads the matching VSIX from the MyAegis release bucket and installs it into any detected editors. Make sure code or cursor is available on your PATH.

aegis install-extension          # choose detected editors
aegis install-extension --vscode  # VS Code only
aegis install-extension --cursor  # Cursor only

The extension sends editor heartbeats to the daemon URL in myaegis.daemonUrl. The optional myaegis.apiToken setting is used when the sidebar creates or assigns projects through the API.

Chrome

The Chrome extension posts productive browsing heartbeats to the local daemon every 30 seconds while you are active. Public Chrome Web Store publishing is still in progress, so the current setup path is to download the latest release ZIP and load it as an unpacked extension.

curl -L -o myaegis-chrome-extension.zip https://dl.myaegis.dev/latest/myaegis-chrome-extension.zip
unzip myaegis-chrome-extension.zip -d myaegis-chrome-extension

Download latest: myaegis-chrome-extension.zip

Open chrome://extensions.
Enable Developer mode.
Choose Load unpacked and select myaegis-chrome-extension.

For local development, you can still run bun run build in extensions/chrome and load that folder directly.

Browser tracking only records development, documentation, testing, research, project management, and infrastructure URLs; idle users are ignored after 90 seconds.

Set up AI hooks

Hooks let AI agents report tool activity directly to the daemon. Run the wizard for all supported tools, or install a specific hook with flags. Hook tracking requires a running daemon, which is currently supported on macOS and experimental on Linux.

aegis setup-hooks
aegis setup-hooks --claude --cursor --codex --scope project

Scope choices

project writes config into the current repo.
local writes gitignored Claude Code config only.
global writes config under your home directory.

Tool	Command	Files written	Tracked events
Claude Code	`aegis setup-hooks --claude --scope project`	`.claude/settings.json`	Edit, Write, and Bash tool lifecycle with file paths and line deltas.
Cursor	`aegis setup-hooks --cursor --scope project`	`.cursor/hooks.json`	AI tool calls and file edit events from Cursor hooks.
Gemini CLI	`aegis setup-hooks --gemini --scope project`	`.gemini/settings.json`	BeforeTool and AfterTool events in git-backed project directories.
Windsurf	`aegis setup-hooks --windsurf --scope project`	`.windsurf/hooks.json`	Code writes and command runs with git branch context.
OpenAI Codex	`aegis setup-hooks --codex --scope global`	`~/.codex/config.toml and ~/.codex/hooks.json`	Bash tool events and turn stops. File edit line counts are not emitted by Codex hooks.

Verify tracking

Check daemon health

aegis status
curl http://127.0.0.1:45678/health

Generate a small test event

Open a git-backed project in VS Code or Cursor, edit and save a file, then run aegis status. For AI hooks, ask the agent to make a small edit in a git repo and check the dashboard timeline.

If sessions do not appear immediately, run aegis push to flush queued data and then refresh the dashboard.

Troubleshooting

The daemon is offline

Run aegis restart, then curl http://127.0.0.1:45678/health. If it still fails, check ~/.myaegis/daemon.err.

The editor installer cannot find VS Code or Cursor

Install the editor shell command first. VS Code uses code; Cursor uses cursor.

AI hook events are skipped

Hooks from directories without a git root are ignored. Run the agent from the project repository you want MyAegis to track.

Chrome does not create sessions

Confirm the daemon is running, the extension is enabled, and the active tab matches a productive URL pattern such as GitHub, localhost, docs, Linear, Jira, or cloud consoles.

API authentication fails

Create a fresh key in /settings/apikeys and rerun aegis login. Keys are shown once and can be revoked from settings.

Data is queued locally

Run aegis push. The daemon keeps local SQLite data in ~/.myaegis/data.db until sync succeeds.