Aethel ← Back to home

Aethel User Guide

Lucin Solutions LLC · Aethel v2.17.0 · September 2026

Welcome

Aethel is a personal AI assistant that lives on your Mac or PC. She reads your calendar, sends emails on your behalf, drives your real Chrome browser, runs scheduled tasks while you sleep, watches inboxes and web pages for changes, remembers what you tell her, and chats with you on Telegram or in a browser. All by talking to her in plain language.

This guide walks you through everything: installing, the setup wizard, day-to-day use, every page of the app, troubleshooting, and managing your license. It's written to be read top to bottom, but skip to whatever you need.

In a hurry? Read the Quick Start guide instead, it's two pages.

What you'll need before starting

Installing Aethel

On Mac

  1. Double-click the Aethel Mac.pkg installer we sent you. On an Intel Mac the file is Aethel Mac Intel.pkg, same steps.
  2. macOS blocks it the first time because the installer isn't Apple-notarized yet. Click Done, open System Settings → Privacy & Security, scroll down, and click Open Anyway next to the message about the installer, then confirm. On macOS 14 or older there's a shortcut: right-click the installer, choose Open, and when macOS asks "Are you sure?", click Open again. (On macOS 15 and newer, Apple removed that trick for unsigned software, the Settings trip above is the way.)
  3. The installer walks you through a few clicks and asks for your Mac password. Along the way you'll see an Installation Type screen with three options; Install/Upgrade is already selected, leave it as is and continue. (Clean Install and Uninstall are explained in the next section, Updating and removing Aethel.)
  4. It installs Aethel into Applications and launches it for you when it finishes, no dragging, no hunting for the app.

Why does macOS block the installer?

Apple blocks any installer that hasn't gone through their paid notarization program, it's normal and says nothing about safety. We're working on Apple Developer notarization; once we have it, this whole dance disappears. Until then, each new update's installer needs the same one-time approval.

On Windows

  1. Open Aethel Windows.zip we sent you, then double-click the Aethel.exe installer inside.
  2. Windows shows a blue "Windows protected your PC" screen with "Microsoft Defender SmartScreen prevented an unrecognized app from starting." Click the small More info link (it's quiet, easy to miss), then click the Run anyway button that appears.
  3. The installer asks where to install (default: C:\Aethel\), then shows three checkboxes, all ticked on a fresh install: a desktop shortcut, Start Aethel automatically when Windows starts, and adding the Aethel folder to Windows Defender's exclusion list (faster launches, but Defender skips scanning that folder). We recommend leaving all three on; auto-start is what keeps your scheduled tasks running.
  4. Click Install. On the finish screen, leave Launch Aethel ticked and click Finish. Aethel opens and the Setup Wizard appears.

What if Windows Defender quarantines Aethel after install?

Rare, but it can happen with unsigned apps, mostly if the Defender exclusion checkbox was unticked during install. Open Windows Security (Start menu → "Windows Security") → Virus & threat protection → Protection history → find the Aethel entry → Restore. Then go to Manage settings → Exclusions → Add or remove exclusions → Add an exclusion → Folder → C:\Aethel\. That tells Defender to leave Aethel alone for future updates.

We're working on a Windows code-signing certificate; once we have it, SmartScreen and Defender will both stop flagging us.

Updating and removing Aethel

Aethel can keep itself up to date. While it is running it quietly checks for a newer version (when you start it, and about once a day), and if one is available it downloads it in the background so it is ready to go. When an update is ready you will see a banner on the Dashboard with the new version and a link to the release notes. You stay in control: nothing installs on its own, and the actual install is always started by you from the app on your computer.

You can adjust this under Settings → System → Software update and news: turn automatic checking or downloading on or off, choose your update channel, and use Check now to look right away. The page also shows your current version and when it last checked.

Aethel news

The same section has a News switch, on by default. With it on, Aethel now and then passes on a short message from us, things like a new feature worth knowing about or a cheaper AI model you can switch to. It arrives as a short Telegram message headed "Aethel news" and goes to the account owner, usually within an hour of us publishing it. Each one is sent once, and if your computer has been off for a while you get a single message rather than a pile of them. Turn the switch off and Aethel stops asking for them entirely.

You can still update the manual way at any time: run the installer for the new version on the same computer. When Aethel is already installed, the installer offers three choices, Windows asks in a dialog right after launch, and Mac shows the same three on the installer's Installation Type screen:

On Windows you can also uninstall the usual way: Windows Settings → Apps → find Aethel → Uninstall (or use the Uninstall Aethel shortcut in the Start Menu). It does exactly the same thing, removing the app and all its data after a confirmation.

On a Windows computer that never had Aethel, the installer skips the question and simply installs. The Mac installer always shows the Installation Type screen; on a fresh Mac, leave Install/Upgrade selected and continue.

First-time setup (the Wizard)

The wizard has ten short steps (nine on Windows, which skips the Mac-only Permissions step). The Back and Next buttons are at the bottom; your progress is saved if you close midway and come back. Most steps take under a minute, the AI engine sign-in and Telegram bot creation take the longest.

1. Welcome

The Aethel logo and a short hello. Tick the "I agree to the Terms of Use and Privacy Policy" checkbox (links to read the Terms of Use, Privacy Policy, and EULA are right below it) and the Next button appears. Click Next.

2. License

You'll see two cards:

If you've already used Aethel on another computer and forgot your key, click the small Forgot your key? link at the bottom; that opens the Lemon Squeezy customer portal where you can look it up.

The wizard validates your key against our license server, so make sure your computer is online for this step.

3. Dependencies

Aethel needs a few open-source tools to run her AI engine and features: Python, Node.js, npm, and Git, plus ffmpeg and Transcription (voice messages), Semantic search (memory search), Browser automation (driving Chrome), and Remote access (reaching your web chat away from home). On Windows there is one more, Visual C++ runtime: a Microsoft component that voice transcription and memory search are both built on, which many computers already have. A 2016 edition is not enough; the tile says out of date when yours is too old, and Install updates it. The wizard checks each one and shows a green check if it's installed, or a red mark if not. Everything needs a green check before Next appears.

If a tile is amber rather than red, the tool is installed but its engine will not start on this computer. That is almost always the Visual C++ runtime above; install it from the tile, or from Settings → System, and the feature comes back without a restart. Aethel also installs a missing or out-of-date runtime by itself the next time it starts: Windows shows its permission prompt, and if Windows needs a restart to finish, Aethel tells you once. Click No and Aethel waits a week before asking again.

Click Install Missing if anything is red; one button installs everything that's missing, one after the other, with a progress bar. On Mac you may be asked to type your password, Aethel downloads each tool's official installer and runs it for you. On Windows the installs run through the built-in Windows package manager, just approve any permission prompt that appears.

Version requirements

The wizard isn't picky about which installs you have, only that they're new enough:

If Python is missing, the wizard installs Python 3.12, which works on every supported Mac and Windows.

If you previously installed Node via nvm or another version manager, the wizard might miss it. Open a terminal, type node --version, and if you see a number ≥ 18, click Re-check in the wizard.

4. Permissions (Mac only)

macOS asks for permission before any app can:

The wizard shows one row per permission with a Grant… button. Click Grant…: macOS shows its permission prompt, approve it and the row turns green by itself. A couple of permissions have no macOS prompt; for those, the right System Settings pane opens instead - flip the toggle next to Aethel and the row still updates on its own. There's nothing to re-check manually, and stale permission entries left by older Aethel versions are cleared automatically.

You can skip this step and come back later from Settings → System. Without these permissions, only those specific features stop working; everything else (Telegram, email, calendar, web chat) is fine.

Note for updates: macOS resets these permissions whenever an app's files change, so after updating Aethel some rows may turn red again. That's Apple policy, not something we can fix. Open Settings → System in Aethel and click Grant… on each red row, one click per row. Updates keep all your data. If an update needs attention later (for example a new component to install), the wizard reopens at just that step, not from the beginning.

5. AI Engine

Aethel needs an AI brain. Pick whichever provider you already have a plan with:

You can switch engines later from Settings → AI, so picking "wrong" today is reversible.

What happens when you click "Install" and "Sign in"

This part has more moving parts than the others, so here's what to expect:

  1. Install: the button shows a spinner while Aethel downloads and installs the engine in the background. No Terminal window opens and there's nothing else to do; a status line below the cards reports success or any error. Aethel also checks engines that are already installed for updates in the background when you reach this step.
  2. Sign in: first, a small window explains exactly what's about to happen, with a Create Account button if you don't have an account yet. Click Continue, then:
    • Codex: your browser opens to OpenAI's sign-in page. Sign in with your OpenAI (ChatGPT) account; Aethel detects it automatically. If a Terminal window also opened, close it when you're done.
    • Antigravity: a Terminal window opens. Follow its prompts to pick a sign-in method, sign in with Google in the browser that opens, then close the Terminal window when it says you're done.
    • Claude: a Terminal window opens with a menu. Pick "Sign in with Browser", finish the sign-in in your browser, come back, and close the Terminal window when it says you're done.

When sign-in succeeds, Aethel's wizard detects it within a few seconds and the Next button unlocks. If the Terminal hangs, close it and click Sign in again.

6. Google sign-in

Click Sign in with Google. Your browser opens to Google's OAuth consent screen. Pick the Gmail account you want Aethel to use (usually your main one). You'll see a screen asking you to approve four permissions:

About the "Google hasn't verified this app" warning

You'll see a screen with a warning that says "Google hasn't verified this app" and the words "unsafe" or "dangerous." That's Google's standard language for any app still going through their review process; it doesn't mean Aethel is unsafe. Specifically:

To proceed: click Advanced at the bottom of the warning page (it's small and looks disabled), then click Go to Aethel (unsafe) at the very bottom of the expanded section. You're back on the consent screen, click Continue, then Allow to approve all four permissions in one go.

The browser shows a message that the sign-in is complete and the window can be closed. Aethel's wizard detects success and the Next button unlocks.

Using more than one Google account

The wizard connects one account to get you started. Later, an admin can connect several Google accounts (for example a personal Gmail and a work account) and choose which one each person is allowed to use. It's optional: if you only ever connect one account, nothing changes. It all lives under Settings → System → Google.

A couple of things still use your first (primary) account only for now: the optional background activity observers, and the "why do you think that?" explanation when it traces a fact back to an email or calendar event. Everyday calendar, email, tasks, and contacts work uses whichever account you or the assignment picks.

7. Browser (optional)

This step lets Aethel drive your real Chrome browser, opening tabs, filling forms, clicking buttons, all the things a person would do when "log into my bank and check the balance" or "cancel this subscription." It's powerful and optional. Skip if you don't need it now; you can set it up later from Settings → System.

If you want it:

  1. Click the Open Chrome Web Store button. The Playwright MCP Bridge extension page opens in Chrome.
  2. Click Add to Chrome. Chrome shows a permission dialog asking "Allow this extension to debug websites?". Click Allow. That permission is how the bridge works (it uses Chrome's official debugger API, the same thing developer tools use). It's not malware.
  3. Click the puzzle-piece icon in Chrome's toolbar (top-right), find Playwright MCP Bridge in the list, and click the pin icon next to it. Then click the extension's icon that now appears in your toolbar. The popup shows a line of text starting with PLAYWRIGHT_MCP_EXTENSION_TOKEN= followed by a long token.
  4. Copy that whole line (or just the token, the wizard accepts both and strips the prefix). Paste it into the wizard's token field.
  5. Click Verify. Aethel pings Chrome to confirm the connection, which takes about 15 seconds, then shows a green check saying browser automation is ready.

8. Telegram

Telegram is the main surface where you'll chat with Aethel from anywhere in the world. The wizard guides you through creating your own personal Telegram bot:

If you don't have a Telegram account yet, use the wizard's small Sign up link first; it opens Telegram in your browser so you can create a free account.

  1. The wizard offers two buttons: Open Telegram Web (no install, Telegram opens in your browser) or Open BotFather chat (uses the Telegram app you already have). Either one opens a chat called @BotFather.
  2. In the BotFather chat, type /newbot and send it. BotFather replies asking for a name for your bot.
  3. Type a display name (anything, e.g., "My Aethel"). Send.
  4. BotFather asks for a username. The username must end in bot, for example carlos_aethel_bot or aethel_demo_bot. If someone's already used that username, BotFather will ask you to pick another.
  5. BotFather replies with a long token that looks like 123456789:AAEx.... Copy the entire token. (Tap and hold on phone, or click and select on web.)
  6. Paste the token into the wizard's Bot token field. Click Test connection. You should see a green check confirming Aethel can talk to your bot.
  7. An Authorize Your Account panel appears in the wizard. Open the chat with your new bot in Telegram (BotFather sent you a t.me/your_bot_name link), then click Authorize User in the wizard. A small window waits for a message: send any message like "hi" to your bot, confirm your name in the window, and click Authorize. That makes you the bot's admin (that's what authorizes you to talk to Aethel).

You can authorize more people later (family, teammates) from Settings → System. Authorized non-admins can chat with the bot but only see their own data; admins (you, by default) see shared memory and can approve AI-suggested automations.

9. First task

Create one scheduled task to make sure everything works end to end. The wizard pre-fills a Morning Briefing for 7 a.m.:

Keep it, or change the time and prompt to whatever you want, e.g., "Remind me to drink water every two hours" or "Sweep my inbox each evening at 6 pm and tell me what's left to handle." Then click Create Task; the wizard confirms the task is saved and Next unlocks.

10. Test run

The last step runs your task right now so you can watch what happens. Click Run Now, and a live log streams in the wizard:

This usually takes 30 to 90 seconds. If anything fails, the log shows the specific error; fix the problem and click Run Now again. The Finish button only appears after a successful run.

When the test succeeds, click Finish. The wizard closes and the main Aethel window opens on the Dashboard. Aethel's background assistant starts (and is set to start automatically when you log in), and a message points out its icon in the menu bar (Mac, top-right) or system tray (Windows, near the clock).

Day-to-day use

Once setup is done, you mostly forget the GUI exists. You chat with Aethel through one of two surfaces.

Telegram

Message your bot like a friend. Examples:

You can send voice messages too (tap and hold the microphone in Telegram). Aethel transcribes them locally with Whisper and replies. Send a voice message and she replies with a voice note of her own, with the text on screen too so you can re-read it. The text and the voice note arrive together rather than one behind the other; if the audio is going to be slow she sends the text and says the voice reply is following. She also keeps the transcriber loaded for ten minutes after you use it, so a second voice note is answered in about a second and a half instead of six. Typed messages get text replies, though you can always ask her to say something out loud. Want voice every time (or never)? Set it with /voice on, /voice off, or /voice auto (auto is the default: she speaks back only when you send a voice note).

You can send photos, documents, audio files, anything Telegram supports. Aethel can describe images, read PDFs, and process audio.

You can also share your location: tap Telegram's attachment (paperclip) button, choose Location, and send a pin, or pick Share Live Location to keep it updated while you move. Aethel saves it quietly without cluttering the chat. Once she knows where you are, questions like "what's a good pharmacy near me?", "how long is the drive to the airport?", or "find a gas station nearby" use your latest shared spot, and it helps her get your local time right. Each person's location stays private to them; only the admin can also ask where another authorized user last shared from. Sharing is entirely optional, and Aethel never reads your location from anywhere else unless you turn that on yourself under Data Sources.

Reply to a specific message using Telegram's own reply function (swipe on the message, or long-press and choose Reply) and Aethel gets that message as context alongside what you just wrote. Handy for "translate this one", "what did you mean here?", or picking one line out of a long list she sent earlier. It works on her messages and on your own.

What you'll see while Aethel is working

The instant you send a message, a "⏳ Thinking…" placeholder appears. As the AI gets to work it becomes a progress card headed by the engine and model doing the thinking (e.g. "CODEX GPT-5.5" or "CLAUDE Claude Opus 4.7"), with a running timer after the first few seconds. As the AI works, you see a list of human-readable tool names appear under it:

`` CODEX GPT-5.5 · (8s) 🔧 Checking the weather 🔧 Searching the web /cancel to stop ``

Each 🔧 line is a tool the AI is calling on your behalf, and a 💭 thinking… line means the model is reasoning between steps. When the answer text starts streaming, the progress placeholder gets replaced by the answer. If a run is taking too long, type /cancel at any time to stop it.

Web chat

Open the URL shown on Aethel's Dashboard in any browser on your home Wi-Fi. It looks like https://YourMac.local:5004 or https://192.168.x.x:5004. Sign in with the password you set the first time.

The web chat has the same brain as Telegram, plus:

You'll see the same kind of progress card as on Telegram — a small panel with the model name and a growing list of "🔧 Checking the weather" / "🔧 Searching the web" style lines while the AI works. The card vanishes the moment the answer text starts flowing. The Stop button has a brief 0.7-second cooldown right after you hit Send so an accidental double-click doesn't cancel the message you just sent.

About the browser security warning for web chat

The first time you open the web chat, your browser shows "Your connection is not private" or "Not Secure". This is because Aethel uses a self-signed HTTPS certificate (HTTPS is required by browsers for microphone access on local networks; we can't avoid it without buying a certificate for every user, which isn't practical). Click Advanced → Proceed anyway. Your browser caches the trust, so you only see this once per device.

Reaching the web chat away from home

Out of the box the web chat only works while you're on the same network as Aethel. If you want it from anywhere, turn on Remote access in Settings → System → Web Chat (it's off by default). Aethel asks you to pick a name and gives you a personal address like https://yourname.tryaethel.com that works from any network, with the same sign-in and the same conversation. Once it's active, the Dashboard shows that address instead of the local one, and a Change button next to the Remote URL in Settings lets you pick a different name later (the old address stops working immediately).

Web chat password

The first time you sign in, pick your name from the account dropdown. Since it's your first visit, Aethel offers to text a 6-digit code to your Telegram bot chat. Click Send code via Telegram, type the code into the web form, then set a password (at least 8 characters). From then on, just log in normally.

If you forget your password, click Forgot password? on the sign-in page. Aethel sends a 6-digit code to your Telegram and you set a new password on the spot. An admin can also clear a stored password from Settings → System → Web Chat → Reset password; the user then sets a fresh one the same way on their next sign-in.

Slash commands

Anything you type that starts with / is treated as a slash command and bypasses the AI entirely. Slash commands work on both Telegram and web chat. The point: when the AI itself is misbehaving (rate-limited, confused, out of quota), you still need a way to control Aethel, type /help from the train and you can see status, swap engines, list tasks, all without sending a single AI request.

Finding the commands. You don't have to memorize them. On Telegram, tap the command menu (the / button by the message box) to see the full list. In the web chat, click the commands button in the toolbar, or just type / and a menu pops up and filters as you keep typing; pick a command with the mouse or the arrow keys. Commands that take input (like /recall or /note) drop the command into the box so you finish the sentence; the rest run on the spot.

If you type a / command Aethel doesn't recognize, you'll get "Command not recognized. Type /help to see available commands." Aethel won't try to interpret it as a chat message. The / prefix is reserved.

Reference

Commands marked (admin) only work for admins: anyone with the Admin box checked in Settings → System → Authorized users. When nobody is checked, the first user in the list is the admin. One exception: /engine changes always require the first user in the list.

Command Does what
/start A friendly welcome and a pointer to /help. (Telegram sends this automatically the first time you open the bot.)
/help List all slash commands.
/status Snapshot: current engine + model, license state, scheduler running yes/no, next task, web chat address, tray uptime. The "is Aethel even alive" command.
/tasks List your scheduled tasks with their times and on/off status.
/routines List your on-demand routines.
/pending List anything waiting for your approval (tasks and routines), numbered so you can approve or reject by number.
/reminders List your pending reminders.
/watchers List your active URL / inbox watchers.
/recall <query> Look something up in your memory (e.g. /recall ring size). No AI call, so it works even when the engine is down.
/note <text> Save a quick note to memory on the spot, no AI call.
/location Show the last location you shared (rough area only, never an exact address); /location clear forgets it.
/whoami Show your name, chat id, and whether you're an admin (handy when adding authorized users).
`/voice on\ off\ auto` (Telegram) Set how Aethel replies by voice: on always, off never, auto only when you send a voice note. (The web chat has its own speaker button instead.)
/cancel Stop the AI mid-reply. Works on Telegram and web chat; in the web chat you can also click the Stop button next to the input box.
/engine Show the current engine + model + a list of available models.
/engine <engine> (admin) Swap engine. <engine> is claude, codex, or antigravity. Keeps your saved model for that engine if any.
/engine <engine> <model> (admin) Swap engine + set model in one go. Model is fuzzy-matched: flash picks the newest Flash, opus picks the newest Opus, 5.5 picks GPT-5.5. The full slug also works.
/engine <engine> default (admin) Switch engine and clear any Aethel-side model override (let the CLI pick its own default).
/approve <number> (admin) Approve an AI proposal, a scheduled task or a routine. Send /approve on its own to see a numbered list, then /approve 1. The id from the proposal message still works too.
/reject <number> (admin) Reject an AI proposal and discard it. Same numbered picker (/reject then /reject 1); the id also works.
/why <claim> Trace where a memory came from and how it changed over time (e.g. /why decaf). Reads the memory database directly, no AI call, so it works even when the engine is down.

Why /engine is the most useful one

When one engine hits its usage limit or a CLI silently breaks after an update, you don't have to be at the GUI to recover. From your phone:

`` /engine codex ``

…and Aethel switches over for the next message. Your subscriptions or API keys for the other two engines are how you keep moving when one goes down.

Approving AI proposals (tasks and routines)

After Aethel runs a few tasks, she may notice patterns and propose a new scheduled task. "You've asked me to summarize your inbox at 6 pm three days in a row. Want me to do this automatically every evening? /approve abc123 to confirm, /reject abc123 to dismiss."

Reply /approve abc123 and the task starts running on schedule. /reject abc123 dismisses it. Prefer not to copy the code? Send /approve (or /reject) on its own and Aethel lists everything pending with a number beside each, so you can just reply /approve 1. A rejected task proposal stays in the Scheduled Tasks list with a "rejected" badge so Aethel won't suggest the same thing again; you can delete it there any time.

The same flow covers routines: when Aethel has an idea for a reusable procedure, she proposes it rather than creating it silently, and /approve <id> makes it available to everyone.

You can also review pending proposals in the GUI's Automations tab: task proposals show a yellow "pending approval" badge in the Scheduled Tasks view, routine proposals in the Routines view, where you can read the full instructions before deciding.

Stopping a response mid-stream

If Aethel is generating a response and you realize you asked the wrong thing, you can interrupt:

What Aethel does on her own (and what she asks first)

Aethel is built to act, not defer. When you ask her to do something, she'll do her best to complete it, including logging in to accounts, navigating sites, and using your signed-in sessions and the logins saved in her Vault. She won't refuse a task because a site is "sensitive."

That said, anything that moves money, deletes data, posts publicly, or reaches out to someone on her own initiative is paused for your explicit go-ahead before the irreversible step. When you spell out a message yourself ("text Bob I'm late"), your request is the permission, and she sends it without asking again. Here's the full breakdown.

The four categories Aethel checks for any action:

  1. Login → just do it
  2. Read → just do it
  3. Write to yourself → just do it
  4. Write with impact → confirm first, then do it

🌐 Browser actions (driving your real Chrome)

What you ask Category What Aethel does
Log into your bank / Gmail / LinkedIn Login Uses your signed-in session or a login saved in her Vault. No asking. If she has neither, she asks you for the password, not for permission.
Check your bank balance Read Navigates, reads the number, reports it.
View your order history on Amazon Read Navigates, summarizes.
Compose a tweet draft (don't post) Self-write Opens compose, types, leaves it.
Post the tweet Public write Shows what's about to post, asks, then clicks Post.
Transfer $50 to a friend Money write Fills the form, asks for confirmation, then sends.
Cancel a subscription Account write Shows what's being canceled, asks, then clicks.
Find a "Buy Now" button you didn't ask about Unrequested write Doesn't click. Mentions it instead.

Letting Aethel work on a tab you already have open

By default, when Aethel uses the browser she opens her own tab. If instead you want her to act on a page you already have open (a site you are signed into and looking at right now), you share that one tab with her. Aethel can only see tabs you share this way, never the rest of your open tabs.

  1. Ask Aethel to look at the tab (for example, "look at this tab"). This wakes up her browser connection, which is what makes the sharing option appear in Chrome.
  2. In Chrome, right-click the tab you want to share, choose Add tab to group, then pick Playwright.
  3. That's it. Aethel can now read and act on that tab.

You can add more than one tab to the Playwright group the same way, and Aethel can switch between the tabs you have shared. To stop sharing a tab, remove it from the group (right-click the tab, then Remove from group).

Tip: the Playwright option only appears once Aethel's browser connection is active, so ask her to look at the tab first, then add it to the group.

Finding something you saved or visited

Separately from driving the browser, Aethel can search the bookmarks and history Chrome already keeps on your computer. Ask her things like:

She reads and never changes anything, and this only happens when you ask. It is for the owner of the computer: other people you have authorized cannot search your browsing.

A few things worth knowing about the answers:

🖥️ Desktop / app actions (input + screen capture)

What you ask Category What Aethel does
Open Notes and find a saved snippet Read Opens the app, reads it.
Switch to Slack and look at a channel Read Just does it.
Save a new note Self-write Just does it.
Send a Slack DM to a coworker Third-party write If you asked her to send it, she types it and sends. If messaging them is her own idea, she shows it and asks first.
Quit an app with unsaved work Destructive Asks first.
Change a system setting Destructive Asks first.

📨 Email, calendar, tasks, Telegram

What you ask Category What Aethel does
Read your inbox / search emails Read Just does it.
Read your calendar Read Just does it.
Save a draft email Self-write Just creates the draft.
Mark a task complete / archive an email Self-write Just does it.
Email yourself a reminder Self-write Sends to yourself.
Telegram yourself a note Self-write Just sends.
Email a third party Third-party write If you asked for the send ("email Bob the report"), she sends it. If it is her own idea, she shows recipient + body and asks first.
Telegram another authorized user Third-party write If you asked her to send it, she sends it. If it is her own idea, she shows the message and asks first.
Delete a calendar event Account write Asks, then deletes.
Create a calendar event for yourself Self-write Just creates it.
Cancel a scheduled Aethel task Account write Asks, then cancels.

🐚 Files and shell commands

What you ask Category What Aethel does
git status, ls, list a directory Read Just runs.
Run a Python data-crunch script Read Just runs.
Write a new file you asked for Self-write Just writes.
Edit a file you're iterating on Self-write Just edits.
Set a reminder, schedule a task Self-write Just creates.
rm -rf anything Destructive Asks first, always.
git reset --hard Destructive Asks first.
git push --force Destructive Asks first.
Drop a database table Destructive Asks first.
Kill a process Aethel didn't start Destructive Asks first.

Editing Excel, Word and PowerPoint files

When you ask Aethel to change an Office file ("add a column to my price list", "replace the client name in this contract", "duplicate slide 3", "export this as a PDF"), she makes the change through the Excel, Word or PowerPoint you already have installed, on Windows and on Mac. That is what keeps a logo in the sheet header, column widths, currency formats, merged cells and the print area intact; rebuilding the file with a library silently loses those.

A few things to know:

⏰ Scheduled tasks (the cron-style jobs you set up)

A scheduled task you wrote yourself is itself the authorization, Aethel won't re-confirm anything when running a scheduled task. A daily "transfer $50 to savings" job runs without asking each morning. If you want a confirmation step, split the job in two: write the task to prepare the work and message you the details, then give the go-ahead yourself in chat when you're ready.

When Aethel asks before something irreversible

She'll show you exactly what she's about to do, the recipient name, the dollar amount, the file path, the command, and wait for a yes/no in chat. One quick reply ("yes" / "go" / "do it") and she completes the action.

Watchers with an action (same rule as scheduled tasks)

A watcher you set up to act when it fires, by running one of your routines or following a short instruction, is pre-authorized the same way a scheduled task is: setting it up was the permission. When it fires, Aethel does the work unattended and sends you a Telegram summary of what she did. Only the admin can give a watcher an action; alert-only watchers are open to every authorized user.

One guardrail applies to every unattended run, scheduled or watcher-fired: Aethel won't take an irreversible step the instructions didn't spell out (moving money, deleting or closing an account, posting publicly, messaging a third party). If the job seems to need one, she skips that part and tells you about it in her wrap-up instead of guessing.

One thing she will never do

Refuse without trying. If Aethel says she can't do something, she should also tell you the specific blocker (wrong password, captcha she can't solve, network error, missing permission). "I'd rather not log in for you" is a bug, please report it.

Nudges (off until you opt in)

Aethel can also reach out first. With nudges enabled, her nightly review may decide that one pattern she noticed deserves an unsolicited Telegram message, like an aging to-do or a chore she could clearly take over. This is off by default and deliberately rare: you choose how many are allowed per day.

Aethel decides when each one should reach you. She knows the time and the day where you are, keeps clear of the hours you would be asleep, and checks what she has already lined up so two never land together. A bill due tomorrow goes out early, while you can still do something about it; a suggestion to tidy your inbox can wait for the middle of the day.

If your computer was switched off when a nudge was due, she does not just fire it late and hope. She re-reads it first: still useful ones are sent when you are back, ones that no longer make sense as written are reworded to be honest about the delay ("I could not reach you earlier, that bill was due three days ago"), and anything overtaken by events is quietly dropped. When several are waiting, they come through about an hour apart rather than all at once.

You can ask her about them any time. "Do I have any nudges?" lists what is scheduled and when, and you can cancel any of them or ask for one yourself: "remind me to call mum tonight". Nudges you ask for count towards the same daily allowance.

Requests for your approval still wait for daytime. The toggle is at the bottom of Settings → System, under Data Sources; turn it off there to silence nudges completely.

The Aethel window (GUI)

Most of the time you won't open this; chatting on Telegram is enough. But when you do (click the menu-bar / tray icon → Open GUI), the sidebar has five destinations, and every page opens with a one-line description of what it's for:

  1. Dashboard — is everything running, and what's coming up.
  2. Automations — the work Aethel does for you: Scheduled Tasks, Routines, Reminders, and Watchers, as views along the top of the page.
  3. Memory — what Aethel knows and what it did: Memories, Tool calls, and Decisions views.
  4. Settings — everything configurable: System, AI, Connectors, Vault, Custom Instructions, and Account views.
  5. Logs — a live view under the hood, at the bottom.

The same menu-bar / tray menu has two more items worth knowing. Stop running AI tasks appears only while Aethel is actively working and stops every AI run in flight; it's the emergency brake if a run is stuck or eating through your AI plan. Exit quits Aethel completely: scheduled tasks, Telegram, and the web chat all stop until you start her again (Mac: Spotlight, type Aethel; Windows: Start menu, type Aethel). Just closing the Aethel window does neither; she keeps working in the background.

Dashboard

The home screen. From top to bottom:

Automations

Everything Aethel does for you lives on this one page, with four views along the top: Scheduled Tasks, Routines, Reminders, and Watchers. Click a view's button to switch; each is described below.

Scheduled Tasks

The list of scheduled things Aethel does for you. From here you can:

You can do all of this by asking, too, if you're the owner: "pause my morning briefing", "rename it to Daily Brief", "delete the invoice task". Aethel checks with you before anything permanent, since there's no undo.

What a finished run tells you. A task that ran isn't always a task that worked, so every run reports what it actually achieved:

The task row, the result window, the Dashboard's recent activity and the /tasks command all show this, so a run stopped by an expired password never looks like one that succeeded. Runs you start yourself with Run report the same way but never message you, because you're watching the result.

One row is special: the System Maintenance task (formerly "Nightly Review") that keeps Aethel's memory tidy and checks each night that your automations are still running carries a system pill and a lock. You can run it any time, but it can't be edited, disabled, or deleted, and it quietly re-creates itself if it ever goes missing.

Routines

Routines are reusable procedures Aethel runs on demand. Where a scheduled task fires on a clock ("every morning at 7"), a routine fires when you ask for it by name, in chat or from inside a task:

"Do weekly-report."

Aethel looks up the routine, follows its steps, and reports back. A routine has three parts: a short dash-separated name (like weekly-report), a one-line description, and the instructions Aethel follows. Routines can reference other routines, so a big procedure can be built out of small ones.

From here you can:

Two things worth knowing:

Reminders

Every reminder Aethel has set, either because you asked her to set one, or because a watcher fired. From here you can see the reminder text, when it fires, and delete it if you no longer want to be reminded.

When a reminder fires, Aethel sends you a Telegram message with the reminder text. Reminders that have fired are removed automatically.

Watchers

Aethel can watch:

When something changes, you choose what Aethel does:

Active watchers appear in this tab. You can see what each one is watching, when it last checked, and delete any you don't want. Web page watchers check about every 5 minutes unless you ask for a faster or slower pace; inbox watchers check about once a minute. Watchers also expire on their own, after a day unless you ask for longer (up to a week), and a one-off watcher stands down once it fires. Ask for a repeating watcher if you want it to keep going.

Memory

Everything Aethel has learned about you, in one searchable list. As you chat, she quietly stores facts ("I'm vegetarian", "my landlord is Dave"), your preferences, and reminders of unfinished things, then uses them later so you don't have to repeat yourself. She also keeps a short, self-updating page on each person, project, or topic that comes up a lot, and a running recap of where you last left off. This tab is where you see and control all of it, with four views along the top: Memories (the list below), What I've noticed (patterns from your optional observers), plus Tool calls and Decisions (the audit trail, described after).

Your notes live here too. Ask Aethel to "save a note" in chat (a packing list, meeting notes, a draft) and it lands as a memory of kind note; filter the Kind picker by note to browse them, or use + Add Memory to write one by hand. The separate Notes page from earlier versions was folded into this tab.

The list refreshes every few seconds, so new memories show up without a reload. Anything you explicitly ask her to remember appears right away; the facts she picks up on her own are filed a little after the conversation, not mid-sentence.

What I've noticed

What I've noticed gathers the patterns Aethel has picked up from the optional Data Sources observers you've turned on: the people you email most, where you tend to be, your calendar accept and decline habits, and the like. If it's empty, none of those observers are on yet (turn them on under Settings → System → Data Sources). It's read-only, and everything it shows stays on your machine.

Tool calls and Decisions

The Memory tab's other two views are an audit trail of what Aethel has been doing:

Like the Memories view, both update live every few seconds.

Settings

Everything configurable lives on one Settings page, with six views along the top: System, AI, Connectors, Vault, Custom Instructions, and Account. The form views autosave as you type (Custom Instructions is the one exception, with its own Save button); a small "Saved at HH:MM:SS" badge in the bottom-right confirms each save. The bottom bar (visible from every view) also has the Open config.yaml and Re-run Setup Wizard escape hatches.

AI

Pick which AI engine drives Aethel: Claude, Codex, or Antigravity. The view shows a "Currently using" hero card at the top with the live model (e.g. "Claude Opus 4.7") and sign-in state, plus a per-engine details card with the engine's tagline, CLI version, signed-in account, a Model dropdown to pick a specific model (or (Default) to let the CLI choose), and an action button (Install / Sign in / Open CLI).

Picking an engine

Not sure which to pick? Codex is the recommended default for most users. All three engines need their own provider plan: Codex via a ChatGPT subscription or OpenAI API key, Claude via a Claude subscription or Anthropic credits, and Antigravity via a Google account. You can switch later from this tab without losing anything.

Antigravity

Best for: everyday tasks on a Google account. Antigravity is Google's CLI; it offers several model families behind one sign-in.

Plan: sign in with a Google account, or set an Antigravity API key.

Model Notes
Gemini 3.5 Flash Fast, lightweight; a good default for everyday chats
Gemini 3.1 Pro Stronger reasoning
Claude Sonnet 4.6 (Thinking) Anthropic's balanced model, via Antigravity
Claude Opus 4.6 (Thinking) Anthropic's strongest reasoning model, via Antigravity
GPT-OSS 120B Open-weight model option

Antigravity has no -m / --model flag, so Aethel sets the model by writing the CLI's settings file before each run. The Model dropdown in Settings handles that for you.

Codex

Best for: code generation, repo-wide refactors, running tests in a loop. Made by OpenAI (the company behind ChatGPT).

Plan: as of May 2026, Codex CLI is included on ChatGPT Free + Go plans as a temporary promo (verify on OpenAI's pricing page since this changes). Otherwise needs ChatGPT Plus ($20/mo), Pro ($100 / $200), Business, Edu, or Enterprise. You can also use a pay-per-token OpenAI API key without any subscription (preferred_auth_method = "apikey" in ~/.codex/config.toml).

Model Cost Notes
GPT-5.2 Cheapest Older; lighter reasoning
GPT-5.3-codex Cheap Code-tuned mid-tier
GPT-5.4-mini Cheap "mini" auto-fallback when the big model exhausts
GPT-5.4 Mid Full GPT-5.4
GPT-5.5 Most expensive Frontier model; default in Codex installs today

ChatGPT Plus 5-hour caps roughly: 160 GPT-5.5 messages every 3 hours on the chat surface; CLI usage shares the budget. Pro $100 = 5x Plus, Pro $200 = 20x Plus.

Claude

Best for: long-context reasoning over a whole codebase, careful explanations, nuanced writing. Opus 4.7 (1M context) is the strongest single model in Aethel for "read everything, then think hard" tasks.

Plan: none free for Claude Code. The free claude.ai chat (~40 short messages/day) does not unlock the agent Aethel uses. Testers need either Claude Pro ($20/mo), Max ($100 / $200), Team / Enterprise, or Anthropic Console API credits (prepaid, ~$5 minimum).

Model Cost (API per 1M tokens) Notes
Claude Haiku 4.5 $1 in / $5 out Cheapest + fastest; great for simple lookups
Claude Sonnet 4.6 $3 in / $15 out Balanced default for most tasks
Claude Opus 4.7 $5 in / $25 out Most expensive; strongest reasoning + 1M context. Bundled into "(Default)" in the dropdown.

On Pro ($20/mo) you get roughly 10–40 Claude Code prompts every 5 hours on Opus, plus a separate weekly Opus-only cap on top of the overall budget. Heavy users typically need Max.

Data Sources (optional observers)

The System view has a Data Sources section: seven optional observers, all off by default, that let Aethel learn patterns from activity you already share with it. Location pings, email send patterns, incoming email patterns, calendar accept/decline habits, Chrome browsing patterns, Safari browsing patterns (Mac only), and Downloads, Documents and Desktop file patterns. They store aggregate signals (counts and patterns), never raw content: filenames only, never file contents; subject keywords, never email bodies; locations saved as a place name rather than exact coordinates; banking, health, and government sites skipped unless you explicitly opt in. If you've linked more than one Google account, the email and calendar observers cover all of them unless you narrow the selection per account, and each observation is labeled with the account it came from. Turning one on asks you to confirm first; most sources also have an extra checkbox to widen what they may look at (unchecked by default); and every source has a Forget all observations button that makes Aethel forget everything that source has recorded, if you change your mind. Each source also tells you whether it has actually found anything recently, so one that is switched on but has nothing to look at says so rather than looking healthy.

Connectors

Third-party MCP servers are how the AI gets new tools. The Aethel ecosystem has hundreds of them — Slack, GitHub, Postgres, your own internal services, anything someone's published. Each one runs locally on your machine and adds new abilities the AI can use the moment they're installed.

The Connectors view shows what you have:

To install via chat: just ask, "find me an MCP for Slack". Aethel searches the marketplace, describes what it does, and asks before installing. Connectors are added to your local config and become available on the next AI turn — no restart.

No ready-made connector? Aethel can build one. If the marketplace doesn't have what you need, it won't just give up: it looks up the service's own API (or a community server for it), and offers to wire it up for you — saving any credentials to your Vault, writing a small program that calls the API, and saving that as a Routine you can re-run on demand. It nails down what you're trying to do and shows you the plan before building anything.

Trust caveat. Connectors run locally with the same privileges as Aethel. Only install from sources you trust. The "Allow AI to install connectors for itself" toggle is off by default for that reason.

Custom Instructions

Your Custom Instructions, one optional text box. Aethel ships with a good default personality and habits built in; anything you write here becomes your standing overrides, and your words always win over the defaults. Examples: "Always reply in Spanish." or "Sign my emails just 'C.'" Leave it empty to use the defaults. Click Save under the box; changes apply from your very next message, no restart needed. (The assistant's name and maker are fixed and can't be changed here.)

Earlier versions had two editors here, Identity and Instructions, pre-filled with default text. Those defaults are built in now; if you had written your own custom lines in them, copy those lines into the new box once.

Vault

Aethel's encrypted credential store. When the AI helps you log in to a site, it can offer to save the username + password so the next time it just types them in for you, no asking required. Saved entries are AES-GCM-256 encrypted on disk; the master key lives in your OS keychain (Mac Keychain / Windows Credential Manager), so the file alone is useless without the keychain.

Per row you get:

The header has + Add Credential to seed an entry manually (domain / username / password / notes). The AI can also add entries when you ask it to ("save this login").

Bringing over the logins Chrome already has. Chrome won't let an automated click choose an entry from its own saved-password list, so any sign-in that depends on that little chooser popping up is one Aethel can't finish for you. The fix is to move those logins into her vault once: ask her to "import my Chrome passwords" and she'll walk you through Chrome's own export screen, then read the file into the vault and delete it. After that she signs you in herself, with no chooser involved. If the import fails partway she tells you exactly where the exported file is so you can remove it.

Heads-up. The master key is per-machine. If you reinstall the OS, swap to a new computer, or your keychain database is wiped, your saved logins can't be recovered — there's no server-side backup. Treat the vault as a convenience, not a safety net for irreplaceable credentials.

System

The one place for how Aethel connects and runs. General at the top: timezone, log level, auto-start at login, language and TTS voice. (On a Mac, a Permissions section also sits at the bottom of this view; see the Permissions reference.) Then the connection settings, in order: Telegram bot token + authorized users; Web Chat enable / port / URL + reset-password (and Remote Access); Browser Automation token; and Google sign-in status with a Switch account button. Below those, Memory search shows whether search by meaning is actually running, with the reason when it is not, and on Windows an Install button for the Microsoft runtime it needs. (The Open config.yaml and Re-run Setup Wizard buttons live in the Settings page's bottom bar, visible from every view.)

Adding another person

Anyone you authorize can chat with your Aethel from their own Telegram account. To add someone:

  1. Send them your bot's link (the t.me/... link from when you created the bot) and ask them to open it and send any message, like "hi". Until they're authorized, the bot won't answer them.
  2. Open Settings → System, find Authorized users in the Telegram card, and click Authorize user.
  3. A window says it's waiting for a message. Have the person send one more message to the bot. Their name appears in the window.
  4. Adjust the display name if you like, then click Authorize.

They can now chat on Telegram and claim their own web chat password. Each person sees only their own conversations and memories. You stay the admin: only you can approve Aethel's proposals or change settings.

Account

Your license: status, plan, renewal date, full key with Show / Copy buttons, and four actions: Manage billing, Refresh license check, Change license key, and Deactivate this computer.

Below the license, About & Legal: vendor info, the app version, and links to the Terms of Use, Privacy Policy, and EULA you agreed to during setup.

Logs

Live tail of Aethel's activity log. Useful when something looks off and you want to share what happened with support. The view follows new lines as they arrive. Open in Editor opens the full log file in your text editor, handy for searching it or sending it to support, and Clear empties it. (For a friendlier view of just the AI's actions, use the Memory page's Tool calls view.)

Keeping Aethel running

Aethel only works when your computer is powered on and not sleeping. The display can be off, that's fine, but if the whole machine sleeps, scheduled tasks won't fire and the bot stops responding until you wake it. The good news: within a couple of minutes of waking, Aethel notices and runs the scheduled tasks it missed earlier that day, so a briefing you slept through still arrives shortly after the computer wakes.

On Mac

  1. Open System Settings → Battery and click Options… at the bottom (on a desktop Mac the setting is under Energy Saver instead)
  2. Turn on "Prevent automatic sleeping on power adapter when the display is off"
  3. Your display can still turn off on its own schedule, that's fine (the timing is under Lock Screen if you want to change it)
  4. On macOS 12, the same checkbox is in System Preferences → Battery → Power Adapter
  5. Plug your laptop in when you go to bed; sleep behavior on battery is different and can pause Aethel.

On Windows

  1. Open Settings → System → Power & battery
  2. Click Screen and sleep (newer Windows 11 versions call it Screen, sleep, & hibernate timeouts)
  3. Set the "put my device to sleep after" option for plugged in to Never
  4. On a laptop, consider also setting the on battery option to Never if you want Aethel to keep running unplugged.

On Windows 10, the same settings are under Settings → System → Power & sleep.

If Aethel ever seems unresponsive, the first thing to check is whether your computer dozed off.

Permissions reference

On Mac

The easiest place to manage these is Settings → System inside Aethel, each row has a Grant… button and a live status. They all live under System Settings → Privacy & Security if you prefer to flip them by hand.

If you ever update Aethel, macOS may reset some of these, Apple resets trust on every binary change. Open Settings → System and click Grant… on any row showing a warning icon instead of a green check; one click per row.

On Windows

Aethel doesn't need any special permissions on Windows. The first-launch SmartScreen warning is the only friction. If your antivirus quarantines Aethel, add C:\Aethel\ to the exclusions list in your antivirus settings.

Managing your license

Open Settings → Account to:

If your license expires, Aethel pauses scheduled tasks, the bot, and the web chat, but it doesn't delete anything. As soon as you renew, it picks up where it left off.

Troubleshooting

"Aethel didn't run my morning task!"

Most likely your computer was asleep. See Keeping Aethel running above. To confirm: open the GUI → Logs and look for activity around the scheduled time. No log entries means the machine wasn't awake.

If the task's row reads couldn't finish or waiting on you instead, the run did happen: click it to see what stopped it.

"My Telegram bot isn't replying."

  1. Open the GUI → Dashboard. Is the status banner at the top green, reading "Aethel is running"? Opening Aethel starts the background service by itself, so if the banner stays gray, quit Aethel and open it again.
  2. Check Connections → Telegram, does it show a green dot?
  3. Open Logs and send a test message; you should see a [telegram] line showing your name and message within a few seconds. If you don't, the bot token may be wrong or revoked. Re-paste it in Settings → System.

"Google says my session expired."

Open Settings → System → Google and click Switch account (or Sign in if you're signed out). The OAuth refresh token can expire if you've gone weeks without using Aethel; signing back in fixes it.

"I closed the menu-bar / tray icon by accident."

"Settings I changed don't seem to take effect."

Settings autosaves 500ms after your last edit. Wait two seconds, then watch for the green "Saved at HH:MM:SS" badge in the bottom-right of the Settings page; it is shared by every Settings tab. If the badge says "Save failed", check Logs for details.

"I want to start over from scratch."

Open Settings and, in the bar along the bottom of the page, click Re-run Setup Wizard. Your existing config is kept until you change something.

"I'm getting too many notifications."

Open Automations → Scheduled Tasks, find the chatty task, click the toggle to Disable it without deleting. You can re-enable any time.

"macOS reset my permissions after updating Aethel."

This is normal, Apple resets trust whenever an app's files change. Open Settings → System in Aethel; the Permissions section shows the current state. Click Grant… next to each red row and approve the prompt (or flip the toggle in the System Settings pane it opens). The rows update by themselves.

You can also just ask Aethel in chat which permissions she has: she answers from what she measured at startup and names the exact pane to fix. When a permission that was refused works again, she sends you one message saying so, even if the macOS Privacy list does not show her.

"The web chat shows 'Not Secure' in my browser."

That's the self-signed HTTPS certificate warning. Click Advanced → Proceed anyway once per device, your browser caches the trust. We can't avoid this without buying a certificate for every user's local network, which isn't practical.

"My AI engine won't sign in."

Open Settings → AI → click Sign in. Codex opens a browser window; Claude and Antigravity open a terminal window with the engine's sign-in flow. If the window hangs, close it, then click Sign in again. If sign-in keeps failing, the engine app itself may be out of date. Aethel updates all three engines automatically about once a day while it's running. You can also open Settings, click Re-run Setup Wizard, and revisit the Engine step, which checks for engine updates in the background.

Getting help

We're a small team and we genuinely want your feedback. Tell us what's confusing, what's missing, what surprised you. The more honest, the better.

Thanks for being one of our first users. 🙏

The Lucin Solutions LLC team