Argus

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.

---

Table of contents

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

---

What is Argus

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 also interpolate runtime data into authority fields; this is powerful and intentionally carries injection risk (see Security & privacy).

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 command/routing fields is permitted by the centralized Aggressive taint policy.

---

Architecture

Gradle modules

Compile → approve → arm → fire flow

 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)

---

Trigger, condition and action catalog

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

Triggers

Conditions

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.

P4 variables and structured flow

Schema-v2 rules can bind up to 16 typed values from literals, trigger payloads, approved device-state readers, engine-generated random_int, 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.

Actions

---

LLM providers and the Hermes bridge

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.
• Reasoning diagnostics: Custom 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.

Hermes bridge (optional, self-hosted)

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.

---

Security & privacy

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 authority templates such as commands, URLs, packages and settings. The program structure and capabilities remain fingerprinted, but data-driven authority creates a real injection surface. 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.
• StaticShellSafety — run_shell can only be triggered by triggers with a non-forgeable identity (time, immediate, geofence, connectivity, sensor) or by a whitelisted WhatsApp 1:1 chat identified by a stable conversationId. SMS and caller ID are excluded as a hard limit (spoofable), 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.

---

Permissions and tiers

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 and without Shizuku

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 are present in the domain/tooling as foundations for future computer-use, but the production executor rejects them and the capability manifest marks them unavailable.

---

Build & installation

Requirements

Commands

# 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: download the APK matching your device from the latest GitHub release and sideload it (adb install or APK transfer). Most current Android phones use the arm64-v8a asset (for v0.3.3, argus-1002.apk); the release notes map every filename to its ABI. The F-Droid submission is still under review; do not assume it is available in the official client until the metadata merge request is merged. 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.

---

For testers

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.
• 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.

---

Project status and roadmap

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:

• State-aware P4 generation — design a resolved invoke_llm_v2 lane with the same strict runtime-data framing as v3. Until that contract exists, the compiler and validator reject this combination before approval.
• Broader device control — complete and validate interactive screen→action execution, including a conservative accessibility/vision fallback for UI surfaces that expose insufficient semantics.
• Cross-OEM hardening — expand the real-device matrix beyond the current OnePlus/Android 16 test device, especially background starts, Shizuku recovery and notification metadata.

Disclaimer: this is a personal project, developed and tested mainly on a single device (OnePlus 15, Android 16, non-root). 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.

---

License

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.

Novità principali

• Supporto all’AI locale sul dispositivo tramite endpoint OpenAI-compatible.
• HTTP consentito esclusivamente verso 127.0.0.1, localhost e ::1; HTTPS resta obbligatorio altrove.
• Chiave API facoltativa per il provider Custom.
• Controllo del livello di ragionamento e diagnostica di reasoning_tokens e finish_reason.
• Guida completa a Hermes Bridge, dall’installazione alla configurazione in Argus.

Risolve #6 e #7.

APK per architettura

• argus-1101.apk — armeabi-v7a
• argus-1102.apk — arm64-v8a
• argus-1103.apk — x86
• argus-1104.apk — x86_64

Gli APK sono firmati e sono stati verificati con due build pulite e riproducibili.