The all-seeing Android automation engine

Natural-language automation for Android, compiled by an LLM, executed by a deterministic engine.

Argus is a Tasker-class Android automation app where the LLM is the compiler, not the executor: you describe a rule in plain language ("every day at 9 send me the BTC price", "when I leave home turn off Wi-Fi"), the LLM compiles it into a structured {trigger → conditions → actions} rule, you review and approve a byte-stable fingerprint of the executable data, and from then on a deterministic engine runs it — no LLM in the execution loop, except for explicitly generative actions. Elevated privileges are optional via Shizuku; a base tier works without it.

The app UI is bilingual (English/Italian, follows the system language).

Privacy & license at a glance. Argus operates no project backend or account service and includes no telemetry or analytics. It contacts only the LLM provider or self-hosted bridge that you explicitly configure, and never probes it automatically on app start: network access begins with an explicit connection check, a compile request, or an approved generative action. Rules, logs and API keys stay on your device (keys encrypted; the audit log records outcomes with no personal content). Argus is free software under GPL-3.0: you may study, modify and share it, but any derivative must stay open under the same license.

1. What is Argus
2. Architecture
3. Trigger, condition and action catalog
4. LLM providers and the Hermes bridge
5. Security & privacy
6. Permissions and tiers
7. Build & installation
8. For testers
9. Project status and roadmap
10. License

Argus is not a chatbot that "does things". It is an always-on automation engine (Tasker/MacroDroid style) in which the LLM has a single role: compiling natural language into a structured, typed rule. The lifecycle is:

1. You describe the rule in chat, in natural language.
2. The LLM compiles the request into a {trigger, conditions, actions} draft over a closed vocabulary of types.
3. The validator (DraftValidator) checks the draft: closed vocabularies, bounds on every field, security invariants. An error blocks approval.
4. You approve from the detail screen. The rule is shown rendered from the types, never from the LLM's paraphrase, and frozen with a SHA-256 fingerprint of the executable data only.
5. The deterministic engine executes: OS-managed alarms, system receivers, geofences, notification listener. The LLM is not consulted when the rule fires.

The only exception is the explicit generative action (invoke_llm): there the LLM comes back into play at fire time, but inside a rigid contract (closed allowed tools, bound recipient, timeout, budget) that you approved in advance.

Why this separation matters:

• Predictability — the rule that fires at 3 a.m. is exactly the one you approved, byte for byte.
• Cost — no LLM calls on every fire: you pay for (or self-host) the LLM only at compile time and in generative actions.
• Security — the executable program structure and its targets are fingerprinted before arming. In the current Aggressive policy, approved templates may interpolate runtime data into URLs, package names and setting values; this is powerful and intentionally carries injection risk (see Security & privacy). In shell commands, external data enters only as one quoted argument.

The project's current philosophy is Tasker-class power with explicit, reviewable risk: the program tree is immutable after approval, bounds and capability checks remain enforced, while the optional use of untrusted runtime data in the approved template fields (URLs, packages, settings) is permitted by the centralized Aggressive taint policy. In shell commands, external data is always quoted as a single argument.

• When (triggers): a time, a date or a delay; sunrise and sunset; right now; a button, home-screen shortcut, Quick Settings tile or widget you press; arriving at or leaving a place; Wi-Fi, Bluetooth or the charger connecting; headphones; the screen turning on, off or being unlocked; the battery crossing a level; Do Not Disturb or the ringer changing; music starting or stopping; notifications (for example WhatsApp), SMS, calls and missed calls; motion.
• Only if (conditions): a time window, battery, charging, screen, ringer, Do Not Disturb, Wi-Fi, airplane mode, a place; with Shizuku also the app in the foreground and any Android setting or system value.
• Then (actions): notifications, volume, ringer, Do Not Disturb, flashlight, vibration, real alarms and timers, opening apps, links and Settings screens, the clipboard, reading a text aloud, media keys, brightness and auto-rotate, HTTP requests, WhatsApp replies (also written by the AI at fire time); with Shizuku also Wi-Fi, Bluetooth and mobile data, dark mode, any setting and shell commands.
• Rules can use variables (also the current time and date in any time zone), if, bounded while loops and waits, and one switch pauses every rule.

 user (chat, natural language)
        │
        ▼
 ┌─────────────┐   strict JSON draft    ┌────────────────┐
 │ Brain (LLM) │ ─────────────────────► │ DraftValidator │  ERROR ⇒ not armable
 │ compiles    │                        │ closed vocab   │  WARNING ⇒ shown
 └─────────────┘                        └───────┬────────┘
   Hermes bridge │ OpenAI │ Anthropic           │
   Gemini │ OpenRouter │ custom                 ▼
                              ┌──────────────────────────────┐
                              │ APPROVAL (Detail screen)     │
                              │ rule rendered FROM THE TYPES │
                              │ SHA-256 fingerprint of the   │
                              │ executable data only         │
                              └──────────────┬───────────────┘
                                             │ arm
                                             ▼
                              ┌──────────────────────────────┐
                              │ OS-MANAGED REGISTRARS        │
                              │ AlarmManager · geofence ·    │
                              │ NotificationListener ·       │
                              │ SMS/conn/BT receivers ·      │
                              │ sensors                      │
                              └──────────────┬───────────────┘
                                             │ event
                                             ▼
                              ┌──────────────────────────────┐
                              │ DETERMINISTIC ENGINE         │
                              │ trigger match → conditions → │
                              │ actions · cooldown · dedup · │
                              │ audit of every outcome       │
                              └──────┬───────────────┬───────┘
                                     │               │ generative actions only
                                     ▼               ▼
                              deterministic actions  invoke_llm lane
                              (no LLM)               (LLM under a closed contract)

The names below are the model's real wire discriminators (engine-core).

A single composable tree with and / or / not (max depth 8, max 64 conditions).

Fail-closed semantics: an unreadable state is UNKNOWN and the condition fails closed, even under not.

Schema-v2 rules can bind up to 16 typed values from literals, trigger payloads, approved device-state readers, engine-generated random_int, the current time (clock, with a time zone and a format) and captured shell/model output. They support nested if, bounded while (literal or variable iteration count, clamped to 1–1000), and cooperative wait, with at most 64 action nodes, flow depth 4 and a hard six-hour runtime budget. Values carry integrity, confidentiality and provenance labels; only their rendered values change at runtime—the approved program tree and fingerprint do not.

The "Brain" is pluggable: the app always owns the loop, the LLM is a reasoning service behind a transport interface.

• BYOK: hosted direct providers require your own API key, entered in-app and stored encrypted on the device. A Custom endpoint may omit authentication. No Argus account, no project backend.
• Budget: per-turn usage tracking (tokens and, where the price list is known, micro-USD), configurable limits; a generative rule that exceeds its budget is suppressed and audited (SUPPRESSED_BUDGET).
• On-device models: Custom accepts unauthenticated OpenAI-compatible servers and cleartext HTTP only on the exact loopback hosts localhost, 127.0.0.1, and ::1. Every LAN or remote endpoint still requires HTTPS.
• Local server presets: the Custom dialog has one-tap presets for Ollama (http://127.0.0.1:11434/v1), LM Studio (http://127.0.0.1:1234/v1) and the llama.cpp server (http://127.0.0.1:8080/v1), with a note on the context they need (about 16,000 tokens). Local servers get a 3-minute compile timeout instead of 65 seconds. There is no compact prompt: models too small to write valid rules are not worth the effort.
• Structured output: when the provider supports it, the compile asks for a native JSON answer (response_format on OpenAI-compatible endpoints, output_config.format on Anthropic) instead of a sentence plus an @@META@@ line. If the provider rejects the parameter or the model ignores it, Argus falls back to the @@META@@ protocol by itself, which stays the base.
• Reasoning diagnostics: Custom and OpenRouter can omit reasoning control or send none, low, medium, or high per request. When the server reports them, Settings shows reasoning-token usage and the latest finish_reason.

Argus needs a capable model: at least the base model of a major provider, or a self-hosted model with about 27B parameters or more. Smaller models can't write valid rules. In our tests, 3–4B models (Gemma 3 4B, Llama 3.2 3B) got 2–19% of the requests right.

Model names change over time, so Argus suggests concrete models only as one-tap chips in the provider dialog, and updates them with each release. On OpenRouter the chips use the ~provider/model-latest aliases, which OpenRouter moves to the newest version of each family by itself.

Measured with Argus's AI test bench in October 2026, all through OpenRouter. The bench sends rule requests in English and Italian (125 in 0.3.7, 162 since 0.4.1 with the new triggers and actions), plus 12 generative answers, through the app's real prompt, transport and validator.

"Typical wait" is the median time to compile one rule, and it depends on the provider's load. All the models wrote the 12 generative answers correctly, except Qwen 3.8 Flash (10). GPT-6 Luna still asks more questions than the others, and sometimes says that an available action is missing; MiMo often answers in the wrong language. The rows for Claude Haiku 5.5, GPT-6 Luna and the preset are from Argus 0.4.1 (162 requests; the preset's over two runs); the other rows are from 0.3.7.

• Reasoning. "Default" leaves the choice to the provider. In Argus you pick the reasoning level in the provider dialog for Custom and OpenRouter; the direct providers use their default. Off (none) works for most models and is the fastest. Some models can't turn it off (on OpenRouter: Gemini Flash, GLM Flash, MiniMax Flash); with none Argus then retries once at low. High reasoning rarely pays off: on the hardest programs DeepSeek Flash at high stays at 2–7 s, while Claude Haiku goes up to 15 s and gets worse.
• Self-hosted. A model in the class of Qwen 3.8 27B is a reasonable floor for a local server (llama.cpp, Ollama, LM Studio and similar). Give it at least about 16,000 tokens of context.
• Run the bench yourself: ARGUS_BENCH_KEY=<OpenRouter key> ./gradlew :automation-android:testDebugUnitTest --tests "dev.argus.automation.bench.AiBenchTest". Optional variables: ARGUS_BENCH_MODEL, ARGUS_BENCH_REASONING, ARGUS_BENCH_STRUCTURED (on, off or auto, the default: as the app does), ARGUS_BENCH_FILTER (comma-separated case prefixes), ARGUS_BENCH_REPEAT, ARGUS_BENCH_PARALLEL, ARGUS_BENCH_BASE_URL. The report is written to automation-android/build/reports/ai-bench/. Without the key, the bench is skipped, so regular test runs never touch the network.

ops/hermes/bridge.py is a one-shot service meant for people who already run a self-hosted LLM agent on their own server: it exposes POST /compile (NL → rule draft) and strict versioned POST /act lanes, with bearer token, idempotent request-ids, body/output limits and fail-closed parsing. /act v1/v2 cover legacy and state-aware delivery; v3 carries P4 resolved runtime values in a strictly validated DATA envelope. Android requires v3 in /health/v2, so a stale bridge fails visibly before execution. The service binds to loopback only and should be published over HTTPS on a private network (e.g. a mesh VPN / Tailscale Serve). Follow the step-by-step installation guide; the systemd unit and .env template are included beside it.

The app works without the bridge: just pick a direct provider with your own key. The bridge exists only for those who want to compile rules with their own self-hosted agent instead of a commercial API.

Full contract: docs/design/hermes-bridge-contract.md.

The main threat model is prompt injection from external content (SMS, notifications, web pages): the defense is structural, not filter-based.

• Approval fingerprint — SHA-256 (argus-approval-v1) of the canonical JSON of the executable data only; the LLM's prose is excluded from the hash. What fires is byte-for-byte what you approved; any change requires re-approval.
• Rendering from the types — the approval screen shows the rule reconstructed from the domain types, never the LLM's paraphrase. Shell commands are shown in full, in monospace, never truncated.
• DraftValidator — no draft enters the engine without validation: closed vocabularies (state keys, enums, tools), bounds on every field (lengths, ranges, condition-tree depth), hard invariants (e.g. invoke_llm's allowed_tools can never contain shell.run or automation.* — re-checked at fire time as well).
• Centralized taint and egress policy — integrity labels remain monotonic, but the Aggressive policy deliberately permits a TAINTED trigger/capture value in approved template fields such as URLs, packages and settings (shown in full at approval). The program structure and capabilities remain fingerprinted, but data-driven authority creates a real injection surface. In shell commands, external data always enters as a single quoted argument and never becomes command syntax. Remote egress is a separate decision: future credential-vault values are blocked from every remote Brain regardless of the taint posture, while generic SECRET data requires explicit review.
• Shell arguments are always quoted — external data placed in an approved shell command always enters as one single-quoted argument (decision D1), so it cannot add, remove or reorder words, or otherwise change the command that was approved.
• StaticShellSafety — run_shell can only be triggered by triggers with a non-forgeable identity (time, immediate, geofence, connectivity, sensor, screen, battery, audio output, mode changes, and manual, which only the unlocked phone's owner can start) or by a whitelisted WhatsApp 1:1 chat identified by a stable conversationId. SMS, caller ID, media playback and an app being opened or closed are excluded as a hard limit (anyone can cause them), and the approved-trigger ↔ live-event binding is verified at runtime.
• PII-free audit log — every fire, suppression, error and lifecycle transition (arm/disable/delete/needs-review) is recorded in append-only Room with closed-vocabulary reason codes: never free text, never message content; event ids are hashed.
• Minimization toward the Brain — compile receives a capability manifest and a redacted device state (only keys from the approved registry); GPS coordinates never leave the phone (only location_available is sent). Generative replies are bound to the trigger's sender, whitelisted 1:1 chats only.
• Fail-closed everywhere — missing state = UNKNOWN = condition false; ambiguous metadata (e.g. unknown isGroup) = not authorized; Shizuku absent = the privileged action fails cleanly and is audited, never executed "later".
• Keys and secrets — API keys encrypted on-device, never in UI state, never in the repo, never in the APK; app backup disabled.

Argus degrades explicitly: the onboarding shows an honest list of what depends on what, and every extra permission is granted only when a rule uses it.

Required to start: Brain configuration (any provider) and privacy acknowledgment. Everything else is skippable.

With Shizuku running once, System → "Grant permanent permissions" lets Argus keep write_setting on SECURE/GLOBAL, the foreground-app condition, brightness and rotation, and Do Not Disturb access after a reboot, without Shizuku. On rooted phones Argus can use Sui (Shizuku as a Magisk/KernelSU module, which starts at boot) or run privileged commands through su (System → "Use root (su)", off by default).

Note: on non-rooted devices Shizuku must be started via ADB and does not survive a reboot; Argus detects this and degrades fail-closed (the privileged action is never executed late), guiding you through recovery.

tap and input_text (coordinates and blind typing) stay rejected by the executor and marked unavailable in the capability manifest: screen automation goes only through ui_steps, with closed steps reviewed at approval.

# engine suite (pure JVM, fast — the primary verification)
./gradlew :engine-core:test

# debug APK
./gradlew :app:assembleDebug
# → app/build/outputs/apk/debug/app-debug.apk

# release APK (signed if a local keystore.properties exists — see below; unsigned otherwise)
./gradlew :app:assembleRelease
# → one APK per ABI: app/build/outputs/apk/release/app-<abi>-release.apk
# (build a single ABI with -PargusAbi=arm64-v8a)

# per-module tests
./gradlew :brain-android:test :automation-android:test :data:test :ui:test

To sign your own release: create keystore.properties in the root (storeFile, storePassword, keyAlias, keyPassword) — the file and the keystores are gitignored and must never be committed. Official signed APKs are on the GitHub Releases.

Installation:

1. GitHub releases (newest version first). Download the APK for your phone from the latest release and install it (open the file on the phone, or adb install). Each release has one APK per processor type, named argus-<version code>.apk; the last two digits tell which one it is:

   File name ends in	Processor (ABI)	Who needs it
   …02.apk (in 0.4.2: argus-1702.apk)	arm64-v8a	almost every phone from the last years: take this one if unsure
   …01.apk	armeabi-v7a	old or entry-level 32-bit phones
   …04.apk	x86_64	emulators, Intel or AMD Chromebooks and tablets
   …03.apk	x86	old 32-bit emulators

   If Android says the app is not compatible with your phone, try the …01 file. The digits before the last two are the version code (17 is 0.4.2).

2. F-Droid. Argus is also at f-droid.org/packages/dev.argus: the F-Droid client picks the right file by itself and keeps it updated. New versions arrive there later than on GitHub, after F-Droid's review and build.

There is no Play Store distribution. On first launch the onboarding walks you through the LLM provider and permissions.

Create a local.properties file with sdk.dir=<path to your Android SDK> if Android Studio does not generate it by itself.

Thanks for trying it. Useful things to know and to stress:

What to try

• Compilation: ask for rules in chat, from trivial to ambiguous ("in 2 minutes send me a notification with the EUR/USD rate", "when I leave home turn off Wi-Fi", "if my wife writes on WhatsApp after 11 pm reply for me"). Check that the draft rendered on the approval screen matches what you meant — it is the real rule, not the paraphrase.
• Approval: try to get "nasty" rules proposed (shell from SMS, disallowed tools, out-of-range values) and check that the validator blocks them with a clear reason.
• Execution: arm time rules (cron and one-shot), immediate, connectivity, geofence, notifications. Test the hostile cases: reboot, timezone change, DST, app killed by the OEM, Shizuku turned off midway.
• End-to-end suite: e2e/ runs 162 hand-written rules on an Android emulator with Shizuku as root, as shell and without Shizuku, through a hook that exists only in debug builds (see e2e/README.md).
• New in 0.4: manual rules (a button, a Quick Settings tile, a widget), "Pause automations", sunrise and sunset, the screen, unlock, battery, headphones and music triggers, reading aloud, brightness and HTTP requests.
• Degradation: deny permissions and turn off Shizuku, and check that the app honestly says what it cannot do instead of failing silently.
• Budget (generative rules): set a low limit and verify the audited suppression.

Which logs to look at

• In-app "Log" tab: every fire, suppression (cooldown/duplicate/budget), error and lifecycle event, with an expandable per-action detail. It is the source of truth: if a rule did not fire, the reason code is there.
• "System" screen: transport/provider status, Shizuku, permissions, battery exemption — useful to attach to a report.
• For crashes: adb logcat filtered on dev.argus.

How to report

Open an Issue with: what you asked in chat (exact text), the rule as shown on approval, what you expected, what happened, the relevant lines from the in-app Log, Android version and OEM, Shizuku status. The in-app log contains no message texts and no personal data: it is safe to paste.

Active development. Phases completed and verified on a real device: P0 (engine core + Android glue), P1 (notifications/WhatsApp generative replies), P2 (background triggers: SMS/OTP, calls, connectivity/power/BT, geofence), P3 (parametric state readers, sensor triggers, base tier without Shizuku, multi-provider with per-provider budgets and usage tracking), and P4 variables, deterministic structured flow, resolved model capture and nested delivery. Since v0.2.0 the app is fully bilingual (English/Italian, follows the system language).

Short roadmap:

• Next — fixes and small features from user feedback; no large phase is planned after the 0.7.0 redesign.

Disclaimer: this is a personal project, developed and tested mainly on a single device (OnePlus 15, Android 16) and on an Android 16 emulator. Expect rough edges on other OEMs — that is exactly the feedback we are looking for. No warranty: rules execute real actions on your phone, read what you approve.

Argus is released under the GNU General Public License v3.0 (GPL-3.0). You are free to use, study, modify and redistribute it; derivative works must remain open under the same license.