📱 mobile-ai-context

Mobile-First AI Context Engine for Claude Code · Cursor · Gemini CLI · Antigravity

Scan your mobile app once → AI instantly understands your Flutter, React Native, iOS, and native Android architecture deeply.

💡 Why mobile-ai-context?

When building or refactoring mobile applications, AI assistants (Claude Code, Cursor, Gemini CLI, Antigravity) spend 10 to 15 file-read operations per task trying to locate screen routes, state providers, network clients, native bridge methods, or color hex tokens.

That amounts to 25,000–35,000 tokens wasted on context-hunting for every single prompt.

mobile-ai-context solves this by statically parsing your mobile project once using AST-level analysis. It compiles a unified Semantic Context Engine (.aictx/) and automatically projects native rules and context files into your AI tools of choice.

| Metric | Standard AI Assistant Setup | Target with mobile-ai-context (Estimated) | |:---|:---:|:---:| | Initial File Explorations | 10 – 15 files per task | 2 – 3 files (Typical) | | Token Cost per Task | ~30,000 tokens | ~6,000 tokens (Typical) | | Context Overhead Reduction | 0% | 70% – 80% Estimated Savings | | Architecture Accuracy | Guesses routes & state names | AST-Assisted & Statically Verified Indexing | | SDK Dependency | Requires active SDK environments | Zero SDK Required (Standalone AST) |

🚀 Quick Start

Initialize mobile-ai-context in your mobile project root in seconds:

npx mobile-ai-context@latest init

Direct Target Selection via Flags

# Target Cursor AI specifically
npx mobile-ai-context init --target cursor

# Target Claude Code and Gemini CLI simultaneously
npx mobile-ai-context init --target claude,gemini

# Re-scan after adding new screens, routes, or state providers
npx mobile-ai-context sync

🧠 The .aictx/ Semantic Context Engine

When you run mobile-ai-context, it indexes your mobile codebase into structured, highly optimized YAML and JSON files stored under .aictx/. This folder serves as the single source of truth for all AI assistants.

your-mobile-project/
├── .aictx/                 ← Unified Semantic Context Engine
│   ├── manifest.yaml       ← Architecture, state, router & platforms
│   ├── routes.yaml         ← Screen catalog & route path parameters
│   ├── state.yaml          ← State stores (Riverpod, BLoC, Zustand)
│   ├── api.yaml            ← Network clients (Dio, Retrofit, GraphQL)
│   ├── di.yaml             ← Dependency injection wiring & service locator graph
│   ├── protocols.yaml      ← Abstract interfaces & active protocol implementations
│   ├── design-system.yaml  ← Color tokens, typography & components
│   ├── storage.yaml        ← Detected or inferred local storage (Drift, MMKV, SQLite)
│   ├── permissions.yaml    ← Android & iOS privacy permissions
│   ├── native-bridge.yaml  ← MethodChannels & Swift/Kotlin bridges
│   ├── firebase.yaml       ← Firebase services & config files
│   ├── features.yaml       ← Feature modules & architecture metrics
│   ├── warnings.yaml       ← Code smells & missing configurations
│   ├── graph.json          ← Module dependency graph
│   └── context.json        ← Master token-optimized AI snapshot
└── AGENTS.md               ← Universal agent standards file

project:
  framework: Flutter
  flutter: ">=3.0.0"
  dart: ">=3.0.0"
architecture:
  pattern: Clean Architecture (Feature-first)
  state: Riverpod
  navigation: GoRouter
  network: Dio
  local_db: Drift
  storage: FlutterSecureStorage
platforms:
  ios: true
  android: true

colors:
  primary: "#1E88E5"
  secondary: "#00ACC1"
  background: "#121212"
  surface: "#1E1E1E"
typography:
  fontFamily: "Roboto"
  heading1: { fontSize: 24, fontWeight: "bold" }
  bodyText: { fontSize: 14, fontWeight: "normal" }
components:
  - AppButton (lib/core/widgets/app_button.dart)
  - CustomCard (lib/core/widgets/custom_card.dart)

🛠️ Multi-AI Tool Target Support

mobile-ai-context formats and places context files into native directory structures for all leading AI developer tools:

1. Cursor AI (.cursor/rules/)

Generates lightweight .mdc rules that reference .aictx/ files as ground truth. Only global rules use alwaysApply: true, while feature rules use file globs (globs: lib/**/*.dart) to keep Cursor fast.

.cursor/
├── rules/
│   ├── architecture.mdc    ← Architecture & boundaries (always)
│   ├── stack.mdc           ← Tech stack details (always)
│   ├── patterns.mdc        ← Engineering standards (always)
│   ├── flutter-routes.mdc  ← Navigation & screen rules
│   ├── flutter-api.mdc     ← API clients & endpoints
│   ├── flutter-state.mdc   ← State management rules
│   ├── design-system.mdc   ← Theme tokens & styling
│   └── modules/*.mdc       ← Feature module context
└── prompts/
    ├── plan-feature.md     ← Prompt: New feature implementation
    ├── fix-bug.md          ← Prompt: Root-cause debugging
    ├── add-api.md          ← Prompt: Endpoints & repository
    └── add-screen.md       ← Prompt: Screen UI & route setup

2. Claude Code (.claude/ & CLAUDE.md)

Creates structured context guides in .claude/context/, custom slash commands in .claude/commands/, and can optionally install a live status bar script.

CLAUDE.md               ← Project commands & index
.claude/
├── context/
│   ├── architecture.md ← Architecture & directory map
│   ├── stack.md        ← Tech stack & versions
│   ├── patterns.md     ← Code patterns & standards
│   └── modules/*.md    ← Per-module context files
├── commands/
│   └── ask.md  plan.md  sync.md  ctx-stats.md
├── skills/
│   └── ship/SKILL.md   ← Multi-agent pipeline skill (optional)
└── ctx-statusline.mjs  ← Real-time status bar script (optional)

3. Gemini CLI (GEMINI.md & .gemini/)

Employs Gemini's native @path import syntax in GEMINI.md and injects AGENTS.md into .gemini/settings.json. Generates TOML slash commands with {{args}}.

GEMINI.md         ← Root context index (@imports .gemini/)
.geminiignore     ← Skipped build & cache directories
.gemini/
├── settings.json ← Configured context file index
├── context/      ← Architecture, stack & module rules
└── commands/     ← TOML slash commands (ask, plan, sync)

4. Google Antigravity (.agent/)

Antigravity reads AGENTS.md natively. mobile-ai-context generates glob-scoped rules under .agent/rules/ and workflow commands under .agent/workflows/.

AGENTS.md       ← Read natively by Antigravity
.agent/         ← Official workspace directory (singular)
├── rules/      ← Glob-scoped rules (stack, patterns)
└── workflows/  ← Workflow slash commands (ask, plan, sync)

💡 Migration Note: Antigravity uses .agent (singular). When Antigravity output is generated, running npx mobile-ai-context sync automatically migrates legacy .agents (plural) folders.

🔍 Mobile Static Parsing & AST Capabilities

mobile-ai-context operates without requiring the Flutter SDK or Native Mobile toolchains installed in your build environment. It uses Dart AST parsing plus static pattern and config scanning:

┌──────────────────────────────────────────────────────────────────┐
│        DART AST PARSING & STATIC PATTERN/CONFIG SCANNING         │
├─────────────────┼────────────────────────────────────────────────┤
│ Flutter / Dart  │ • Riverpod, BLoC, Provider & GetX stores       │
│                 │ • Injectable, GetIt & DI container wiring      │
│                 │ • Abstract classes & Dart interface resolution │
│                 │ • AutoRoute & GoRouter navigation              │
│                 │ • Dio, Retrofit & HTTP network clients         │
│                 │ • MethodChannels (invokeMethod & handlers)     │
│                 │ • ThemeData & Color Hex Tokens (0xFF...)       │
├─────────────────┼────────────────────────────────────────────────┤
│ React Native /  │ • InversifyJS, tsyringe & React Context DI     │
│ Expo            │ • TypeScript interfaces & abstract contracts   │
│                 │ • React Navigation & Expo Router               │
│                 │ • Redux Toolkit, Zustand, MMKV, SQLite         │
│                 │ • NativeWind, Tamagui, React Native Paper      │
├─────────────────┼────────────────────────────────────────────────┤
│ Native Android  │ • Hilt (@Module/@Provides/@Binds),Koin & Dagger│
│ (Kotlin / Java) │ • Jetpack Compose & XML Navigation routes      │
│                 │ • ViewModel, StateFlow, LiveData & Coroutines  │
│                 │ • Room entities, DAOs, SQLDelight & DataStore  │
│                 │ • Retrofit (@GET/@POST), Ktor & Apollo GraphQL │
│                 │ • AndroidManifest permissions, activities & DLs│
│                 │ • colors.xml, themes.xml & Compose Color.kt    │
└─────────────────┴────────────────────────────────────────────────┘
│ Native iOS      │ • SwiftUI Views & UIKit Controllers            │
│                 │ • Swift Protocols & Implementation resolution  │
│                 │ • Swinject & Factory DI container wiring       │
│                 │ • ObservableObject & SwiftUI State stores      │
│                 │ • NavigationStack, Coordinators & Sheets       │
│                 │ • Alamofire & URLSession API clients           │
│                 │ • UserDefaults & Keychain storage patterns     │
│                 │ • Info.plist privacy permissions & Firebase    │
└─────────────────┴────────────────────────────────────────────────┘

📜 Universal AGENTS.md & Non-Negotiable Mobile Standards

mobile-ai-context generates a root AGENTS.md file that enforces non-negotiable mobile engineering standards across all AI assistants.

Self-Updating Dual-Zone Structure

<!-- mobile-ai-context:agents:start -->
# Auto-generated stack, architecture, commands & mandatory standards.
# Refreshed automatically on every `npx mobile-ai-context sync`.
<!-- mobile-ai-context:agents:end -->

## Project rules (developer-maintained)
<!-- Developer rules appended here PERSIST permanently across syncs -->
- Always use Dio Interceptors for JWT auth refresh.
- Color hex codes MUST reference design-system.yaml AppColors tokens.

Core Mobile Engineering Principles Enforced

[!IMPORTANT] All AI tools receiving mobile-ai-context rules are instructed to follow these strict mobile performance & UI guidelines:

• Performance (60fps Target): Virtualize long lists (ListView.builder, FlatList, LazyColumn). Never render large lists eagerly. Avoid unnecessary widget rebuilds and re-renders. Offload heavy computations from the UI main thread.
• UI Consistency & Design Tokens: Reuse existing design system components from .aictx/design-system.yaml. Follow Material 3 (Android) and Apple HIG (iOS) guidelines. Respect safe areas/notches, support dark mode, dynamic type, and screen readers (TalkBack & VoiceOver).
• State & Data Integrity: Use a single consistent state management pattern. Persist sensitive tokens in platform secure storage (Keychain / Keystore). Handle offline states gracefully with explicit loading, error, and empty states.
• Platform Correctness: Request and handle permissions properly. Handle app lifecycle transitions (foreground/background), deep links, and navigation restoration.

⚡ CLI & Slash Commands Reference

Terminal CLI Commands

| Command | Action | |:---|:---| | npx mobile-ai-context init | Interactive setup — scans mobile app and generates .aictx/ + AI tool configs. | | npx mobile-ai-context init --target cursor | Setup targeting Cursor AI specifically (.cursor/rules/ + prompt templates). | | npx mobile-ai-context sync | Re-scan codebase and regenerate all context files after adding new screens or refactoring. | | npx mobile-ai-context sync --templates | Refresh slash command templates and status bar scripts after package upgrades. | | npx mobile-ai-context stats | Display the terminal ASCII context health dashboard. | | npx mobile-ai-context help | Print full CLI and slash command reference. |

In-Chat Slash Commands & Skills

Available in Claude Code (.claude/commands/, .claude/skills/), Gemini CLI (.gemini/commands/), and Antigravity (.agent/workflows/):

| Command / Skill | Description | |:---|:---| | /ask <request> | Context-aware plan & execution for daily feature additions or bug fixes. | | /plan <request> | Interactive planning mode — presents UI layout options & architecture breakdown without editing code. | | /sync | Re-run context sync directly from inside your AI chat session. | | /ctx-stats | Display the context dashboard and stale file warnings inside chat. | | /ctx-help | Show available commands and mobile workflows in chat. | | mobile | Optional generated skill/rule for running emulators/simulators, Maestro E2E tests, screenshot inspection, and builds. |

📊 Context Health Dashboard & Status Line

Terminal ASCII Context Dashboard (npx mobile-ai-context stats or /ctx-stats)

╭──────────────────────────────────────────────╮
│  mobile-ai-context · context dashboard       │
│  ──────────────────────────────────────────  │
│  Files scanned     184                       │
│  Context size      ~22.4 KB (~5.6k tokens)   │
│  Modules           8                         │
│  Last sync         1h ago                    │
│  Stale files       2 files (auth, router)    │
│                                              │
│  widgets     ██████████   34 files   6.8 KB  │
│  state       ██████░░░░   18 files   4.2 KB  │
│  router      ████░░░░░░   12 files   3.1 KB  │
╰──────────────────────────────────────────────╯

Stale File Alert: Highlights uncommitted source files in scanned modules, prompting you when it's time to run sync.

Claude Code Live Status Line

Opt in during init to display real-time context stats at the bottom of Claude Code:

📊 CTX 22KB · 184 files · 8 mod · synced 1h ago  │  ctx 28% (56k/200k) 🟢  │  claude-3-7-sonnet

🔄 Keeping Context Fresh

| Event / Trigger | Automatic / Recommended Action | |:---|:---| | git commit, git pull, git checkout | Auto-syncs .aictx/ incrementally via .git/hooks/ (post-commit, post-merge, post-checkout). Fully compatible with CLI and GUI clients (SourceTree, GitHub Desktop, VS Code). | | New Screen or State Provider | Run npx mobile-ai-context sync or /sync in chat. | | Major Architecture Refactor | Run npx mobile-ai-context sync. | | Package Upgrade | Run npx mobile-ai-context sync --templates to refresh slash command templates. |

❓ Frequently Asked Questions

No. mobile-ai-context runs 100% locally on your machine. It utilizes your existing Claude Code, Cursor, Gemini CLI, or Antigravity setup with zero extra API costs or API keys.

No! mobile-ai-context comes with built-in AST static code parsers (dart-parser.js & dart-symbol-resolver.js). It extracts Dart routes, Riverpod providers, BLoC states, AutoRoute configurations, and MethodChannels natively without needing Flutter or Dart SDKs installed.

Yes! During npx mobile-ai-context init, you can select any combination (e.g. Claude Code + Cursor + Antigravity). All tools share the underlying .aictx/ context engine and root AGENTS.md.

Yes! You should commit .aictx/, AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules/, .agent/, and .claude/context/. This ensures your entire team gets instant AI codebase awareness. Machine-specific cache files (.last-sync, .ctx-stats.json) are automatically added to .gitignore.

📄 License

MIT © techvootsolutions