Marc Mintel
9c6f80de9d
Production bug 2026-05-02 22:30: Bot got trapped in a restart loop: 1. 'tap reels tab' → VLM clicked wrong element → EXPLORE_GRID 2. After 2 failures → action masked 3. HD Map: 'REELS_FEED unreachable due to masked edges' 4. GOAP: 'completely trapped' → force Instagram restart 5. Repeat forever ALL TESTS WERE GREEN because NONE of this logic was tested. NEW: test_system_goap_navigation.py — 63 tests across 8 contracts: CONTRACT 1: Screen Identification from XML (16 tests) - Home, Explore, Reels, Profile, DM, Story, Modal, Foreign App - Post detail vs Home feed (action_bar discriminator) - Reels full-screen (no tab bar, structural markers only) CONTRACT 2: Available Actions Extraction (4 tests) - All 5 tab actions present on home feed - Screen-specific actions (first post on Explore) CONTRACT 3: HD Map BFS Routing (7 tests) - Direct routes, multi-step routes, already-there - Masked edges, all-edges-masked → None CONTRACT 4: Goal → Target Screen Mapping (14 tests) - All navigation goals + non-navigation goals return None CONTRACT 5: Action Failure Masking (4 tests) - Mask after MAX_RETRIES, no mask under threshold - Full production chain reproduction CONTRACT 6: Goal Achievement Detection (9 tests) - Screen-based, context-based, non-nav goals CONTRACT 7: Structural Action Protection (4 tests) - HD Map actions are structural, random actions are not CONTRACT 8: Step-Aware Navigation Validation (5 tests) - Expected screen for action, mismatch detection
GramPilot
Full Self-Driving for Instagram.
An autonomous Agentic Engine that navigates the Instagram App like a human.
Originally derived from GramAddict, completely re-architected.
Created by Marc Mintel <marc@mintel.me>
🏎️ What is GramPilot?
GramPilot is not a traditional script. Traditional bots rely on fixed UI locators (like XPaths) or external APIs, causing them to crash with every Instagram update or get banned within days.
GramPilot introduces a Telepathic Full Self-Driving (FSD) approach to UI navigation: It uses a 3-Stage Resolution Cascade backed by CPU Fast-Paths, Ollama Vector Similarity, and OpenRouter LLMs (Gemini/Qwen) to "read" the screen, understand context, and learn new UI layouts asynchronously.
If Instagram updates its app and moves a button, GramPilot doesn't crash. It falls back to its Agentic LLM reasoning, dynamically reasons about the new layout using raw XML structure, clicks the right button, and never hallucinates on that button again.
✨ Core Features
- 🚫 Zero Limits Configuration: Forget about configuring "max_likes" or "delays". GramPilot uses a Dopamine Pacing Engine to simulate human boredom. If the content isn't interesting, it skips it or ends the session early.
- 🎯 Mission-Driven Navigation: Say goodbye to abstract goal configurations. Define a
strategy(likeaggressive_growthornurture_community) inconfig.yml, and the Goal Decomposer Engine automatically orchestrates the optimal routing and task allocation using enabled plugins. - ⚖️ Active Inference (Shadow Mode): The bot continuously predicts the outcome of its clicks. If it lands on a popup instead of a profile, it registers a "Prediction Error", presses back, and dynamically recalibrates without panicking.
- ⛩️ Telepathic Engine: A strictly tiered resolution cascade (Keyword -> Vectors -> LLM) that ensures 90% of navigation happens at 0-token cost while maintaining fallback AI resilience.
- 🧬 Resonance Oracle: The bot only interacts with content that matches a pre-defined persona aesthetic, completely bypassing spam or low-quality content.
- 🛡️ Honeypot Radome: Instagram plants invisible, 1x1 pixel trap buttons for bots. Our Radome Sensor sanitizes the XML view before the agent ever sees it, mathematically guaranteeing evasion of tracker traps.
🏗️ Project Status (April 2026)
The engine has undergone a massive stabilization refactor to achieve 100% TDD compliance on critical navigation paths.
- Navigation Reliability: Resolved 'Identity Shadowing' bugs to ensure deterministic detection of
OWN_PROFILE. - Autonomous Recovery: Hardened the
SituationalAwarenessEngine(SAE) to handle 12+ anomaly states including system dialogs and persistent survey modals. - Zero-Latency Memory: Optimized Qdrant vector retrieval for sub-second navigational decisions.
🚀 Quick Start
Prerequisites
- A physical Android device or emulator
- Python 3.10+
adb(Android Debug Bridge) installed and added to your PATH
Installation
-
Clone the repository:
git clone https://github.com/marcmintel/grampilot.git cd grampilot -
Initialize Environment & Dependencies:
python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt -
Start the Engine:
python3 run.py --config config.yml
Note
Unlike legacy bots, GramPilot requires zero maintenance. It will automatically re-learn the UI over time using its integrated Qdrant memory vectors.