My Guardian Agent — User Guide

Version 1.0 · September 2026 You Set the Line. We Help You Hold It.

1. What Is My Guardian Agent?

My Guardian Agent is a geofence-based accountability app that uses your phone's GPS to detect when you enter locations you've identified as high-risk — and immediately launches an intervention protocol designed to help you hold the line.

It is not a tracker. It does not report to anyone without your permission. It is a tool you configure for yourself.

What it does:

Monitors your location in the background for zones you define
Triggers an alarm and intervention screen the moment you enter a red zone
Logs every event for personal review
Tracks your sobriety streak visually over time
Provides regulation tools (breathing, urge surfing) at any time

What it is not:

A medical device or clinical treatment
An emergency response service
A replacement for professional counseling or addiction treatment

2. First-Time Setup

2.1 User Agreement

The first time you open the app, you will be shown the Privacy Policy & User Agreement.

Scroll all the way to the bottom to activate the checkbox
Check the box to confirm you've read and agree
Tap "I AGREE — ACTIVATE GUARDIAN" to continue

You will only see this screen once. It is stored permanently on your device.

2.2 Granting Permissions

The app will walk you through each required permission one by one. All of these are necessary for the app to function correctly.

Permission Why It's Needed

Location (precise) - Detects when you enter or exit zones

Background location - Detects zones when the app is closed or screen is off

Notifications - Delivers zone alerts and reminders

Microphone - Records custom audio alerts (optional)

Activity recognition - Counts steps during Walk Tracker sessions

Exact alarms - Schedules green zone check-ins

Battery optimization - Keeps the background service running

Full-screen intent - Wakes the screen during a red zone intervention

Camera - Meal tracking and Mirror accountability protocol (optional)

Android 14+ users: You must grant Full-Screen Intent permission separately. The app will show a red banner on your dashboard if this hasn't been granted — tap the banner to open the settings page and enable it. This permission is what allows the app to wake your screen when you enter a zone.

2.3 Setting Your Sobriety Start Date

On your first daily deployment, set your sobriety start date. This is the anchor for your sobriety heatmap. You can change it at any time from the dashboard.

3. The Daily Deployment

Every day the app opens, you complete a Daily Deployment — a brief check-in that logs your baseline for the day.

What you fill out:

Daily note — how you're feeling, what's ahead today
Mood — a simple rating
Weight (optional) — tracked over time in your baselines
Custom metrics — any personal data points you want to track

Completing deployment unlocks the full dashboard for the day. This takes less than 60 seconds.

Skipping a day does not reset your sobriety streak. The streak is calculated from your zone history and manual overrides, not your deployment log.

4. Your Dashboard

The dashboard is your mission control. From here you can access everything.

Sobriety Heatmap

A color-coded calendar grid showing every day since your sobriety start date:

Color Meaning

🟩 Green Sober day

🟨 Yellow Day 1 of recovery (after a relapse entry)

🟠 Orange Days 2–3 of recovery

🟥 Red Relapse logged (failed red zone exit or manual)

⬛ Dark Before your start date, or future date

Swipe left/right on the heatmap to navigate between months. Up to 2 months are shown at a time.

Tap any day to see its details and manually override the status if needed (e.g., if a GPS check failed but you actually left the zone successfully).

Stats Bar

Shows your Total Sober days, Current Streak, and the date range displayed.

The "Total Sober" count is green and includes sober days plus recovery days (yellow and orange). Relapse days are excluded.

Dashboard Buttons

DEPLOYMENT LOG — View your history of daily check-ins
ZONE CONFIG — Set up your red and green zones
TOOLS & SUPPORT — Breathing, regulation tools, crisis resources
AI AGENT — Open the AI coaching chat
ACCOUNTABILITY — Manage your contacts
WALK TRACKER — Start a step-counting session

5. Configuring Zones

Zones are the heart of the app. A zone is a GPS location that triggers a response when you enter it.

Red Zones (Danger)

Red zones are locations you want to avoid — a bar, a former dealer's street, a neighborhood associated with past use. Entering a red zone triggers the full intervention protocol.

To add a red zone:

Dashboard → ZONE CONFIG
Tap "+ ADD RED ZONE"
Search for the address or drop a pin on the map
Set the radius (how close you need to be to trigger — default is 100m)
Give it a label (e.g., "Downtown Bar District")
Save

Green Zones (Safe Havens)

Green zones are safe locations — your home, a meeting hall, a sponsor's house. Entering a green zone can trigger a positive check-in notification.

Zone Tips

Be specific — a tighter radius means fewer false triggers
Test your zones — walk toward one to confirm it fires
Add multiple zones — every location you've identified as high-risk
You can delete or edit any zone at any time
Zones work when the app is closed and your screen is off — this is the whole point

6. The Intervention Protocol

This is what My Guardian Agent was built for.

Step 1 — Zone Entry Detection

The background service detects you've entered a red zone. This works even when the app is closed and your screen is locked.

Step 2 — Alarm Fires

Your phone's alarm sound plays at maximum volume
The screen wakes up (even from lock screen)
Vibration pattern engages

Step 3 — Intervention Screen

The Intervention Screen appears full-screen. You cannot swipe back or use the back button.

You will see:

The zone label that was triggered
A countdown timer
"ACKNOWLEDGE — I'M LEAVING" button
A countdown to escalation

Tap "ACKNOWLEDGE — I'M LEAVING" when you are ready to begin the extraction process.

Step 4 — GPS Extraction Check

After acknowledging, the app performs a GPS verification to confirm you are actually leaving the zone. You have 60 seconds to move outside the zone boundary.

If GPS confirms you've left: You are routed to the Incident Journal to log the event. The intervention closes.

If GPS can't confirm: A dialog appears with two options:

"STILL IN ZONE" — honestly log that you remained in the zone
"I HAVE LEFT" — manually confirm your exit (used if GPS signal is poor indoors)

Step 5 — Incident Journal

After every red zone event, you complete a brief journal:

What triggered you?
How did you respond?
What will you do differently?

This builds your self-awareness over time and creates a log you can review.

Escalation (If You Don't Acknowledge)

If the countdown on the intervention screen reaches zero without you acknowledging:

The app escalates to the Escalated Intervention Screen
A more intense alarm fires
Your Squad Coms (escalation contacts) receive an urgent SMS
A final 60-second countdown runs
If still unacknowledged, the event is logged as a failed intervention

This is intentional design. The escalation exists to notify people who care about you if you are not responding. Make sure your accountability contacts know this and have consented to receive these messages.

7. Tools & Support

Available at any time from the Dashboard → TOOLS & SUPPORT, not only during a breach.

Call Sponsor

One-tap call to your designated sponsor. Set this number in your accountability contacts.

Tactical Reset (Box Breathing)

A guided box breathing exercise:

Inhale 4 seconds
Hold 4 seconds
Exhale 4 seconds
Hold 4 seconds

Repeat for as many cycles as you need. Use this when urges hit, anxiety spikes, or you need to re-center before a difficult moment.

Timer Tools (Urge Surfing)

Urge surfing is the practice of riding an urge like a wave rather than fighting it. Most urges peak and pass within 15–30 minutes.

Start the timer when an urge hits. Watch it count. The urge will pass.

Incident Log

Manually log a red zone event or personal reflection at any time — not just after a breach. Use this for close calls, high-risk moments, or general journaling.

Crisis Resources

One-tap access to:

988 Suicide & Crisis Lifeline — call or text, free, 24/7
SAMHSA National Helpline — 1-800-662-4357, substance use support, free, 24/7
FindTreatment.gov — locate local treatment centers

8. The AI Agent

The AI Agent is a private, on-demand coaching assistant powered by Google Gemini.

What it's good for:

Talking through a difficult moment
Exploring your triggers and patterns
Getting a non-judgmental sounding board at 2am
Planning for high-risk situations

How to use it:

Dashboard → AI AGENT
Type your message
The Agent responds with context-aware coaching

The AI Agent does not know your zone history, journal entries, or personal data. Conversations stay on your device except for the messages sent to Google's Gemini API to generate responses. Do not share sensitive financial or legal information in chat.
The AI Agent is not a licensed counselor and cannot replace professional mental health support.

9. Sobriety Tracker

Setting Your Start Date

From the dashboard sobriety card, tap the start date to change it. This is the date your current sobriety began.

Manual Overrides

Tap any day on the heatmap to open its detail. You can manually set the status to:

Sober
Relapse
Recovery Day 1
Recovery Days 2–3

Use overrides when automatic detection was wrong (e.g., GPS check failed but you successfully left the zone) or to correct historical entries.

Swipe Navigation

Swipe left or right on the heatmap grid to move between months. The date range label at the top updates as you navigate.

10. Accountability Contacts

Accountability contacts receive SMS messages when you enter a red zone, acknowledge the intervention, and exit.

Adding a Contact

Dashboard → ACCOUNTABILITY → Add Contact

Enter their name and phone number
They will receive a message like: "[Your name] has entered a red zone. My Guardian Agent intervention protocol is active."

Important

You must obtain consent from anyone you add as an accountability contact. They need to know they may receive urgent SMS messages and what those messages mean. Adding someone without their knowledge is not appropriate use of this feature.

Sponsor Contact

Set one contact as your Sponsor — this person appears on the "Call Sponsor" quick-access button in Tools & Support.

Squad Coms (Escalation Contacts)

Squad Coms are notified during escalated interventions only (when the first intervention countdown expires without acknowledgment). These are your most trusted people for crisis situations.

11. Permissions Explained

Why Background Location Is Essential

My Guardian Agent can only protect you when it can see where you are — including when your screen is off and the app isn't open. Without background location, zones will not trigger when it matters most.

Android will occasionally ask you to confirm this permission is still allowed. Always tap "Allow all the time".

Why Full-Screen Intent Matters (Android 14+)

Without this permission, the intervention screen cannot appear over your lock screen. The alarm will still play, but you won't see the intervention screen until you unlock your phone manually. Grant this permission for full protection.

Battery Optimization

Most Android phones will try to "optimize" (kill) background apps to save battery. My Guardian Agent requests an exemption from this. If you notice zones are not triggering, check that battery optimization is disabled for this app:

Settings → Apps → My Guardian Agent → Battery → Unrestricted

12. Troubleshooting

Zone Not Triggering

Check that background location is set to "Allow all the time"
Check that battery optimization is disabled for the app
Check that the app's background service is running (you should see a persistent notification)
GPS accuracy can vary indoors — zones trigger more reliably outdoors with clear sky

Intervention Screen Didn't Appear

Check Full-Screen Intent permission — Dashboard will show a red banner if it's not granted
Confirm the app was not force-stopped
Reboot your phone and test again

GPS Check Failed During Extraction

If the GPS couldn't verify your location during extraction, use the "I HAVE LEFT" self-report option. GPS signals are weakest indoors and in dense urban areas. The self-report is your safety valve for those situations.

SMS Not Sending

Confirm the SMS permission is granted
Verify the phone number is entered correctly (include area code)
Test by asking your contact to confirm receipt after a test zone entry

App Crashing

Force-close and reopen the app. If the problem persists, uninstall and reinstall from the Play Store — your data is stored on your device and will be lost on reinstall, so note your zone locations and contacts first.

13. Crisis Resources

These resources are always available in the app under Tools & Support.

ResourceContact988 Suicide & Crisis Lifeline Call or text 988 (24/7, free, confidential)SAMHSA National Helpline1-800-662-4357 (24/7, free, confidential) FindTreatment.gov Find local treatment providersEmergency911

My Guardian Agent is not an emergency response service. If you or someone else is in immediate danger, call 911.

14. Important Disclaimers

My Guardian Agent is not a medical device and does not provide medical advice, diagnosis, or treatment.
It is not a substitute for licensed addiction treatment, counseling, therapy, or any clinical service.
Geofencing accuracy depends on GPS hardware and signal conditions. The app cannot guarantee detection of every zone entry or exit.
Do not rely on this app as your sole safeguard in high-risk situations.
You are solely responsible for your recovery decisions and outcomes.
Always consult qualified healthcare professionals for medical and mental health guidance.