# Installation Source: https://docs.openclix.ai/getting-started/installation Install OpenClix skills and start agent-based mobile app retention and engagement automation. OpenClix is currently delivered as agent skills plus reference templates. This installation path is intended for agent-based mobile app retention and engagement automation. ## Option A: Agent-first (recommended) Use this prompt in your coding agent: ```text theme={null} OpenClix is an open-source, MIT-licensed project (https://github.com/openclix/openclix). Install OpenClix first-party skills by running: npx skills add openclix/openclix Skills are not available until the next session, so read each SKILL.md directly from the installed skill directory and follow its instructions for this session. Use openclix-init to detect platform, copy templates into the dedicated OpenClix namespace, wire initialization/event/lifecycle touchpoints, and run build verification. If this project already has local notifications outside OpenClix, detect whether they are migration-capable, ask whether to migrate supported flows into OpenClix or keep them as-is, and default to keeping them unchanged. Then use openclix-design-campaigns to create .openclix/campaigns/app-profile.json and generate .openclix/campaigns/openclix-config.json. Then use openclix-update when updating plugin integrations to refresh source files from the latest openclix-init templates. Then use openclix-analytics to detect installed Firebase/PostHog/Mixpanel/Amplitude, forward OpenClix events with openclix tags, and produce a pre/post impact report for D7 retention and engagement metrics. Then use openclix-update-campaigns to draft campaign action recommendations. Then run scripts/retention_ops_automation.sh with --agent all to generate OpenClaw, Claude Code, and Codex review prompts before apply. Do not add dependencies without approval. ``` ## Option B: Manual skill install 1. Install skills: ```bash theme={null} npx skills add openclix/openclix ``` 2. Run `openclix-init` in your app project. If local notifications already exist, it will detect those paths, determine whether supported flows are migration-capable, and default to keeping the current implementation unless you explicitly choose migration. 3. Run `openclix-design-campaigns` to generate campaign config. 4. Run `openclix-analytics` to wire event forwarding and produce impact outputs. 5. Run `openclix-update-campaigns` to draft campaign operation changes. 6. Run `openclix-update` when you want to re-sync OpenClix source files after template updates from this repository. 7. Run `scripts/retention_ops_automation.sh` to generate OpenClaw/Claude Code/Codex review prompts. ## Option C: Claude Code plugin marketplace Use Claude Code marketplace registration when you want managed plugin updates: ```bash theme={null} claude plugin marketplace add openclix/openclix claude plugin marketplace update openclix claude plugin install openclix@openclix ``` For local pre-release validation from a checkout: ```bash theme={null} claude plugin marketplace add /absolute/path/to/openclix ``` To pull marketplace/plugin updates later: ```bash theme={null} claude plugin marketplace update openclix claude plugin update openclix@openclix ``` Validate plugin manifests locally before publishing: ```bash theme={null} bash scripts/validate_claude_plugin.sh ``` Continue with the [agent-based mobile app retention automation workflow](/getting-started/workflow). # Verification Source: https://docs.openclix.ai/getting-started/verification Verification checklist for OpenClix integration and generated artifacts. Use this checklist after running the workflow. ## Build and runtime checks * Run your platform build/analyze commands successfully. * Confirm OpenClix touchpoints are wired in app initialization/event/lifecycle paths. * Confirm local notification / in-app hook paths execute in test scenarios. * If the app already had local notifications, confirm the integration report states what was detected, what was migration-capable, and whether those paths were migrated or preserved. * Confirm notification permission is requested before campaign triggers fire. * Confirm foreground notification display is configured (iOS / Expo). ## Artifact checks * `.openclix/campaigns/openclix-config.json` exists and is schema-valid against `https://openclix.ai/schemas/openclix.schema.json`. * `.openclix/analytics/impact-metrics.json` exists. * `.openclix/analytics/impact-report.md` exists. * `.openclix/campaigns/update-recommendations.json` exists after `openclix-update-campaigns`. * `.openclix/campaigns/openclix-config.next.json` exists after `openclix-update-campaigns`. * `.openclix/openclix-update/openclix-update-plan.json` exists after `openclix-update`. * `.openclix/openclix-update/openclix-update-report.md` exists after `openclix-update` plan/apply cycle. * `.openclix/openclix-update/openclix-update-apply.json` exists after `apply_sync.sh --apply`. * `.openclix/automation/run-summary.json` exists after running retention ops automation. * `.openclix/automation/prompts/` contains expected agent prompt files. ## Schema validation commands Use the canonical schema URL: * `https://openclix.ai/schemas/openclix.schema.json` Run: ```bash theme={null} jq . .openclix/campaigns/openclix-config.json >/dev/null npx --yes ajv-cli validate \ -s https://openclix.ai/schemas/openclix.schema.json \ -d .openclix/campaigns/openclix-config.json ``` If remote schema fetch is restricted: ```bash theme={null} curl -fsSL https://openclix.ai/schemas/openclix.schema.json -o .openclix/campaigns/openclix.schema.json npx --yes ajv-cli validate \ -s .openclix/campaigns/openclix.schema.json \ -d .openclix/campaigns/openclix-config.json ``` ## Retention ops automation check ```bash theme={null} bash scripts/retention_ops_automation.sh \ --root \ --agent all \ --delivery-mode auto \ --dry-run ``` Validate: * Script exits with code `0`. * `.openclix/automation/run-summary.json` reports `status: "ok"`. * Prompt files are generated under `.openclix/automation/prompts/`. ## Behavior checks * At least one representative campaign path can fire under expected conditions. * Existing non-OpenClix local notifications stay intact unless you explicitly chose to migrate supported flows. * Suppression and quiet-hour logic behave as configured. * Debug reasons are available for fired and suppressed outcomes. # Workflow Source: https://docs.openclix.ai/getting-started/workflow Recommended agent-based mobile app retention and engagement automation workflow. ## 1. Integrate with `openclix-init` `openclix-init`: * Detects platform (Expo/RN/Flutter/iOS/Android) * Detects pre-existing local notification paths outside OpenClix * Classifies detected notification paths as migration-capable or keep-as-is * Asks whether to migrate supported notification flows or keep the existing implementation unchanged * Defaults to keeping existing local notifications unless migration is explicitly requested * Copies local-source templates into your repo * Wires minimal initialization/event/lifecycle touchpoints * Reuses existing dependencies where possible * Runs platform-appropriate build/analyze verification ## 2. Generate config with `openclix-design-campaigns` `openclix-design-campaigns`: * Creates a structured campaign planning profile * Designs lifecycle campaigns (onboarding/habit/re-engagement/milestone/feature discovery) * Produces schema-valid config (`openclix/config/v1`) Expected output: * `.openclix/campaigns/app-profile.json` * `.openclix/campaigns/openclix-config.json` ## 3. Measure impact with `openclix-analytics` `openclix-analytics`: * Detects provider: Firebase > PostHog > Mixpanel > Amplitude * Wires OpenClix event forwarding with `openclix_*` properties * Produces pre/post impact artifacts for retention + engagement Expected output: * `.openclix/analytics/impact-metrics.json` * `.openclix/analytics/impact-report.md` ## 4. Sync source integration when template baseline changes `openclix-update`: * Detects template drift in your existing OpenClix integration * Proposes per-file updates while preserving custom code areas when markers exist * Offers conflict reporting for files requiring manual review * Keeps `openclix-update-campaigns` focused on campaign recommendations only ```bash theme={null} bash skills/openclix-update/scripts/detect_integration.sh --root bash skills/openclix-update/scripts/plan_sync.sh --root --plan .openclix/openclix-update/openclix-update-plan.json bash skills/openclix-update/scripts/apply_sync.sh --root --plan .openclix/openclix-update/openclix-update-plan.json --apply bash skills/openclix-update/scripts/report.sh --plan .openclix/openclix-update/openclix-update-plan.json ``` Expected output: * `.openclix/openclix-update/openclix-update-plan.json` * `.openclix/openclix-update/openclix-update-apply.json` * `.openclix/openclix-update/openclix-update-report.md` ## 5. Draft campaign operations with `openclix-update-campaigns` `openclix-update-campaigns`: * Reads impact + campaign metrics and evaluates per-campaign actions. * Produces `openclix-config.next.json` without mutating active config. * Keeps apply behind explicit confirmation. Expected output: * `.openclix/campaigns/update-recommendations.json` * `.openclix/campaigns/openclix-config.next.json` ## 6. Run agent retention operations with `retention_ops_automation.sh` Use the helper script when you want OpenClaw, Claude Code, and/or Codex prompts generated from the latest OpenClix artifacts. ```bash theme={null} bash scripts/retention_ops_automation.sh \ --root \ --agent all \ --delivery-mode auto \ --dry-run ``` Run from the OpenClix repository root, or use an absolute script path if you are currently inside a different project directory. Expected output: * `.openclix/automation/run-summary.json` * `.openclix/automation/prompts/openclaw.md` * `.openclix/automation/prompts/claude-code.md` * `.openclix/automation/prompts/codex.md` ## 7. Maintain Claude plugin registration Keep Claude Code marketplace metadata current as OpenClix evolves: ```bash theme={null} claude plugin marketplace update openclix claude plugin update openclix@openclix ``` Validate plugin manifests before cutting a release: ```bash theme={null} bash scripts/validate_claude_plugin.sh ``` Release rule: * Keep `.claude-plugin/plugin.json` `version`, `.claude-plugin/marketplace.json` `metadata.version`, and `.claude-plugin/marketplace.json` `plugins[0].version` aligned. * Keep `.claude-plugin/marketplace.json` `plugins[0].source` as `./` so plugin installs resolve from the same marketplace checkout. Next: [Agent-based mobile app retention automation guide](/guides/agent-retention-automation) # Agent Retention Automation Source: https://docs.openclix.ai/guides/agent-retention-automation Run a repeatable, agent-based mobile app retention and engagement automation loop with OpenClaw, Claude Code, and Codex. Use this guide after the base workflow (`openclix-init`, `openclix-design-campaigns`, `openclix-analytics`, `openclix-update-campaigns`) is already producing artifacts. Run `openclix-update` separately when template baseline updates are needed. This is OpenClix's primary agent-based mobile app retention automation operating loop. ## Why this layer exists OpenClix already gives deterministic config + metrics artifacts. This guide adds an operations layer so teams can run a weekly or biweekly decision loop with coding agents while preserving a strict human approval gate. ## Capabilities by skill/script * `openclix-init`: integration automation * `openclix-design-campaigns`: campaign config automation * `openclix-analytics`: retention/engagement measurement automation * `openclix-update-campaigns`: campaign action proposal automation * `openclix-update`: source-template synchronization for baseline maintenance * `retention_ops_automation.sh`: OpenClaw/Claude Code/Codex review prompt automation ## Operations loop ```text theme={null} impact metrics + campaign metrics + active config -> evaluate_campaigns.sh recommendation draft -> agent-specific review prompt (OpenClaw / Claude Code / Codex) -> human approval -> apply by delivery mode ``` ## Evidence confidence model Use this grading model when citing examples in retention automation docs: | Grade | Criteria | | ----- | --------------------------------------------------------------------------------- | | A | Public implementation artifacts and reproducible workflow evidence are available. | | B | Workflow and tooling are public, but KPI impact proof is limited. | | C | Anecdotal/operator report without reproducible KPI evidence. | ## Run automation helper script ```bash theme={null} bash scripts/retention_ops_automation.sh \ --root \ --agent all \ --delivery-mode auto \ --dry-run ``` Run from the OpenClix repository root, or invoke the script with an absolute path when your current working directory is different. CLI options: * `--agent openclaw|claude-code|codex|all` * `--delivery-mode auto|bundle|hosted_http|dual` * `--impact-file ` * `--campaign-metrics-file ` * `--config-file ` * `--output-dir ` (default: `.openclix/automation`) ## Generated artifacts * `.openclix/automation/run-summary.json` * `.openclix/automation/prompts/openclaw.md` * `.openclix/automation/prompts/claude-code.md` * `.openclix/automation/prompts/codex.md` The script also generates evaluator outputs in `.openclix/automation/evaluator/` so dry-run usage can stay isolated from active campaign files. ## Weekly / biweekly operating cadence 1. Refresh analytics artifacts with `openclix-analytics`. 2. Run `retention_ops_automation.sh` in dry-run mode. 3. Paste generated prompt(s) into the selected agent. 4. Compare agent recommendations with `update-recommendations.json`. 5. Approve only high-confidence, reversible changes. 6. Apply changes by delivery mode (`bundle`, `hosted_http`, `dual`). 7. Record rationale in your team changelog. ## Approval gate and rollback policy Before apply: * Confirm sampling thresholds were met (`delivered >= 200`, `opened >= 20`). * Reject recommendations that rely on low-confidence data. * Keep delete actions pause-first. Rollback defaults: * `bundle`: restore previous bundled config and redeploy app build. * `hosted_http`: roll back to previous JSON version at stable HTTPS URL. * `dual`: revert both hosted primary and local fallback together. ## Third-party OpenClaw plugin review OpenClix's own skills (`openclix-init`, `openclix-design-campaigns`, `openclix-analytics`, `openclix-update-campaigns`, `openclix-update`) are first-party and source-auditable in this repository. When the retention ops loop incorporates **additional third-party OpenClaw plugins** that are not part of this repository, apply these review steps to those external plugins: * Review the external plugin's source before execution. * Run unfamiliar external plugins in sandboxed or isolated environments. * Prefer read-only analysis prompts for first-pass review of external plugins. * Require human approval before applying config changes from any source. ## Failure codes from helper script * `10`: required command/script missing * `20`: no supported analytics provider detected * `21`: OpenClix integration not detected * `30`: required input artifact missing * `31`: delivery mode unresolved (`unknown`) * `40`: evaluator execution failed # Analytics Impact Source: https://docs.openclix.ai/guides/analytics-impact Forward OpenClix events and generate pre/post impact analysis artifacts. Use `openclix-analytics` after campaigns are running. ## Provider behavior Supported providers: * Firebase * PostHog * Mixpanel * Amplitude Selection priority: ```text theme={null} Firebase > PostHog > Mixpanel > Amplitude ``` If no supported provider exists, the workflow should stop and provide setup guidance. ## Output artifacts * `.openclix/analytics/impact-metrics.json` * `.openclix/analytics/impact-report.md` Next: [Agent Retention Automation](/guides/agent-retention-automation) Default compare window is pre/post analysis with stabilization exclusion as defined by the skill workflow. # Campaign Design Source: https://docs.openclix.ai/guides/campaign-design Design lifecycle campaigns and generate schema-valid OpenClix config. Use `openclix-design-campaigns` to convert product goals + event taxonomy into executable config. ## Typical campaign families * Onboarding nudges * Re-engagement reminders * Streak maintenance * Milestone messages * Feature discovery prompts ## Guardrails to apply * Use trigger and suppression logic that is deterministic and auditable. * Model `do_not_disturb` and `frequency_cap` explicitly. * Keep copy concise and action-oriented. * Validate config before shipping (see [Verification](/getting-started/verification)). ## Output artifacts * `.openclix/campaigns/app-profile.json` * `.openclix/campaigns/openclix-config.json` # Config Delivery Source: https://docs.openclix.ai/guides/config-delivery Choose and operate OpenClix config delivery: app resource or HTTPS JSON. OpenClix supports two delivery paths for config JSON. ## App resource JSON Use bundled config in the app package when you want: * Maximum determinism * No network dependency at evaluation time * Release-based config updates ## HTTPS JSON Use remote JSON when you want: * Faster iteration without app release for each rules change * Central config management * Dynamic or static serving options Both patterns are valid: * Static asset JSON (CDN/object storage) * Dynamically generated JSON (API/server response) ## Recommendation Start with app resource JSON, then move to HTTPS JSON when iteration speed requirements increase. # Config Delivery Patterns Source: https://docs.openclix.ai/guides/config-delivery-patterns Deliver openclix-config.json over HTTP while keeping local rule execution stable. Delivery patterns are optional and come after the local-first base is working. ## Recommended directions * **Static HTTP JSON**: Host `openclix-config.json` on CDN/object storage/static web hosting. * **Dynamic JSON API**: Return schema-compatible `openclix-config.json` payloads from your backend. * **No app redeploy updates**: Change hosted JSON content to adjust copy, timing, and suppression rules without shipping a new build. * **Schema check before publish**: Run the validation flow in [Verification](/getting-started/verification). ## Principle Treat config delivery as a replaceable transport layer, not as a core rule-engine dependency. # OpenClix Docs Source: https://docs.openclix.ai/index Open-source, local-first docs for agent-based mobile app retention and engagement automation. OpenClix mascot OpenClix helps teams run onboarding, habit, re-engagement, and feature-discovery messaging with local-first execution and agent-based mobile app retention automation workflows. The project is designed to be: * Open source and auditable * Source-first (vendored client code, not runtime SDK lock-in) * Agent-friendly (explicit interfaces and clear edit points) * Practical for fast retention experiments ## Start Here * [Install and integrate OpenClix](/getting-started/installation) * [Run the OpenClix workflow](/getting-started/workflow) * [Verify your integration](/getting-started/verification) * [Run the agent-based mobile app retention automation workflow](/guides/agent-retention-automation) ## Conceptual Flow ```text theme={null} config source (app resource JSON or HTTPS JSON) -> app event -> rule evaluation -> schedule/show message -> debug reason ``` ## What OpenClix Is Not OpenClix is not a hosted full engagement platform and does not require a Clix-hosted control plane for the local-first path. # FAQ Source: https://docs.openclix.ai/reference/faq Frequently asked questions about OpenClix positioning, guardrails, and agent-based retention automation usage. ## Is this a notification library or a full platform? OpenClix is an open-source reference codebase for on-device engagement logic, not a hosted full engagement platform. ## Do I install OpenClix as a package dependency? No. OpenClix is source-distributed: client code is copied into your repository and checked in. ## Do I need a backend or push infrastructure? Not for the local-first path. You can start without APNS/FCM send pipelines. ## Do I need Clix-hosted services or a control plane? No. OpenClix is designed to run in your app with your own integrations. ## What happens if my app already has local notifications? `openclix-init` first detects pre-existing local notification paths outside OpenClix. If supported paths can migrate into the current OpenClix model, the agent asks whether to migrate those flows or keep the existing implementation unchanged. If you do not choose, the default is to keep the current local notifications as-is. Unsupported or unrelated notification flows stay untouched. ## How can I deliver `openclix-config.json`? Serve `openclix-config.json` over HTTP either as a static file or from a dynamic API that returns JSON. Updating that static file or API response lets you change campaign settings without shipping a new app release. ## When is OpenClix enough vs a full engagement platform? OpenClix is strong for local-first onboarding/habit/re-engagement/feature-discovery flows. If you need complex vendor tooling or server-triggered real-time push operations, pair it with a fuller engagement stack. ## How should I handle third-party OpenClaw plugins in retention operations? OpenClix's own skills are first-party and auditable in this repository. When using additional third-party OpenClaw plugins from outside this repository, review their source before execution, prefer sandboxed runs, and keep human approval gates before applying campaign config changes. # Project Status Source: https://docs.openclix.ai/reference/project-status Current project status and implementation focus. | Area | Status | Notes | | ---------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Core project spec / direction | Defined | Scope, use cases, and architecture direction are documented. | | Source-distributed reference runtime | Available (template-based) | `openclix-init` provides React Native / Flutter / iOS / Android source templates with verification scripts. | | Config JSON runtime model | Implemented in current templates | `openclix/config/v1` schema and runtime touchpoints for bundled or HTTPS config are available in the workflow. | | Agent retention operations workflow | Implemented (review-loop automation) | `openclix-analytics` + `openclix-update-campaigns` + `retention_ops_automation.sh` generate review artifacts with explicit human approval gates. | | OpenClix source synchronization workflow | Implemented | `openclix-update` maintains existing source integrations when template baseline changes; campaign optimization remains with `openclix-update-campaigns`. | | `openclix-config.json` HTTP delivery | Supported (app-owned endpoint) | Hosted JSON delivery is supported without requiring OpenClix-hosted services. | | Hosted control plane | Not required | Local-first path does not require Clix-hosted services. | ## Near-term focus * Expand reproducible operator evidence and KPI case studies. * Harden campaign evaluator heuristics and delivery-mode apply runbooks. * Keep cross-platform template parity and verification coverage. * Continue stabilizing interfaces for bundled and hosted `openclix-config.json` delivery. # Runtime Model Source: https://docs.openclix.ai/reference/runtime-model Understand the local-first OpenClix execution path. OpenClix executes engagement logic on-device. ## Execution flow ```text theme={null} config source (in-app JSON or HTTPS JSON) -> app event -> rule evaluation -> schedule/show message -> debug reason ``` ## Observability goals * What event happened * What rule matched * Why a message fired or was suppressed ## Why this model This path removes early dependency on push-delivery infrastructure so teams can test retention hypotheses faster. # Use Cases Source: https://docs.openclix.ai/reference/use-cases Representative mobile app retention and engagement automation use cases for OpenClix. ## Onboarding Nudges * Guide setup completion and first-session progress. * Start without building push backend infrastructure first. ## Re-Engagement Reminders * Trigger nudges after inactivity windows using local rules. * Tune timing and copy via config updates. ## Streak Maintenance * Keep habits alive with quiet hours and cooldowns. * Keep eligibility deterministic and auditable. ## Milestone Messages * Celebrate progress thresholds and completions. * Test copy variants through config changes. ## Feature Discovery Prompts * Surface next-best actions after key events/screen visits. * Pair local notifications with in-app hooks. ## Agent Retention Ops * Run a weekly/biweekly review loop from OpenClix metrics and recommendation artifacts. * Generate OpenClaw/Claude Code/Codex prompts while preserving explicit human approval gates.