openads-ai 0.2.1 → 0.2.2

package/README.md

@@ -11,10 +11,11 @@
   AI Command Center for Marketers
 ```
 
-> **Talk to your ad campaigns in plain English.** Connect your Google Ads and Meta accounts, pick your favorite AI model, and let OpenAds handle the analysis while you focus on strategy.
+> **Talk to your ad campaigns in plain English.** Connect your Google Ads, Google Analytics (GA4), and Meta accounts, pick your favorite AI model, and let OpenAds handle the analysis while you focus on strategy.
 
 <p align="center">
   <img src="https://img.shields.io/badge/Google%20Ads-MCP-4285F4?style=flat-square&logo=google-ads" />
+  <img src="https://img.shields.io/badge/Google%20Analytics%204-MCP-E37400?style=flat-square&logo=google-analytics" />
   <img src="https://img.shields.io/badge/Meta%20Ads-MCP-1877F2?style=flat-square&logo=meta" />
   <img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" />
 </p>
@@ -32,7 +33,7 @@ OpenAds is an **open-source CLI tool** that turns any AI model into a marketing
 | Feature | What it means for you |
 |---|---|
 | 🧠 **Pre-built marketing skills** | The AI already knows Google Ads best practices, Meta creative formats, CRO frameworks, and copywriting rules. You just ask. |
-| 🔌 **Direct platform access** | Connect your Google Ads and Meta accounts. The AI reads your live data — no more copy-pasting reports. |
+| 🔌 **Direct platform access** | Connect your Google Ads, Google Analytics (GA4), and Meta accounts. The AI reads your live data — no more copy-pasting reports. |
 | 🤖 **Bring your own model** | Use Google Gemini, OpenAI, Claude, or a local model running on your machine. Your choice. |
 | 🛡️ **Nothing goes live without you** | The AI can read freely, but every write operation (campaign change, budget edit) requires your explicit approval. |
 | ⚡ **Autonomous loops** | Let the AI research competitors, test ad variants, and generate hypotheses overnight. Review in the morning. |
@@ -51,33 +52,56 @@ Here is a look at OpenAds in action:
 
 ## ⚡ Quick Start
 
-### 1. Install
+### 👶 New to the terminal? Start here!
 
+OpenAds is a local desktop application that runs in your computer's **Terminal** (a text-based window where you can run commands). Follow these simple steps to get started:
+
+#### Step 1: Install Node.js (Required)
+OpenAds runs on your computer using Node.js. If you don't have it yet, installing it is just like any normal application:
+1. Go to [nodejs.org](https://nodejs.org/) and click the **LTS (Recommended)** button to download it.
+2. Open the downloaded file and run the installer (just click "Next" until it finishes).
+
+#### Step 2: Open your Terminal
+* **Mac:** Press `Cmd + Space` (Spotlight search), type **Terminal**, and press `Enter`.
+* **Windows:** Press the `Windows Key` on your keyboard, type **cmd** (Command Prompt), and press `Enter`.
+
+#### Step 3: Install OpenAds
+Copy the command below, paste it into your Terminal window, and press **Enter**:
 ```bash
 npm install -g openads-ai
 ```
+> 💡 **Permissions Error?** If your Terminal shows a red error about "EACCES" or permissions, copy and paste this command instead:
+> `sudo npm install -g openads-ai` (Mac will ask you to type your computer password and press Enter).
 
-> **Tip:** If you see a permissions error, prefix with `sudo` or [configure npm for global installs](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally).
-
-### 2. Set up (one time)
-
+#### Step 4: Run the Setup Wizard
+Paste this command into your Terminal and press **Enter**:
 ```bash
 openads setup
 ```
+This launches a beautiful, step-by-step interactive setup wizard where you can:
+* **Select your favorite AI model** (Google Gemini, OpenAI, Claude, or a free local model)
+* **Link your ad accounts** (Google Ads, GA4, and/or Meta Ads)
+* **Describe your business** (so the AI writes copy tailored exactly to your brand)
+
+#### Step 5: Start using OpenAds!
+Whenever you want to audit your campaigns or write copy, just open your Terminal, type:
+```bash
+openads
+```
+and press **Enter** to open your dashboard.
+
+---
 
-The setup wizard walks you through three things:
-- **Pick your AI model** — choose from Google Gemini, OpenAI, Claude, a local model, or any OpenAI-compatible provider
-- **Connect your ad accounts** — Google Ads and/or Meta Ads (both optional)
-- **Describe your business** — so the AI can tailor copy and strategy to your product
+### 💻 Already know how to use the terminal? Quick commands
 
-### 3. Launch
+If you're already familiar with node packages, just run:
 
 ```bash
+npm install -g openads-ai
+openads setup
 openads
 ```
 
-That's it. You'll see a menu with quick actions. Pick one, or just type your question in plain English.
-
 ---
 
 ## 💡 What can I do with it?
@@ -187,7 +211,7 @@ This verifies your config file, API keys, platform connections (live token check
 
 ## 🗺️ Roadmap
 
-- [x] Google Ads integration via MCP
+- [x] Google Ads & GA4 integration via MCP
 - [x] Meta Ads integration via MCP
 - [x] Interactive setup wizard with live token verification
 - [x] 12 pre-built skills: Ads, CRO, Copywriting, Analytics, Email, Video, Research, Strategy

package/dist/cli.js

@@ -12,6 +12,7 @@ import { runSetup } from './setup.js';
 import { runDoctor } from './doctor.js';
 import { runScheduleManager, runScheduledTask, openReportInBrowser, listReports } from './schedule.js';
 import enquirer from 'enquirer';
+import { hasGlobalRtk } from './token-optimizer.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const pkgDir = path.resolve(__dirname, '..');
@@ -81,25 +82,21 @@ _You can also edit this file manually at: ${contextPath}_
 // Makes the agent behave as "OpenAds" instead of generic Pi.
 function buildSystemPrompt(config) {
     const contextPath = path.join(CONFIG_DIR, 'context', 'my-business.md');
+    const isLaunchMode = config.mode === 'launch';
     const parts = [
         'You are OpenAds, an AI marketing assistant built for digital marketers.',
         'You specialize in Google Ads, Meta Ads, copywriting, analytics, CRO, and go-to-market strategy.',
         'Always speak in plain marketing language. Never use developer jargon.',
         'Address the user as a marketing professional.',
         'When writing ad copy or recommendations, always reference the user\'s product context first.',
-        'For any write operation (creating campaigns, changing budgets), always preview the change and ask for explicit confirmation before executing.',
-        '',
-        '## Memory',
-        '',
-        `Your business context file is at: ${contextPath}`,
-        'This file contains everything you have learned about the user\'s business across sessions.',
-        'At the START of every conversation, read this file to recall past context.',
-        'At the END of a conversation (or when you learn something significant), APPEND new insights to the "## Learnings" section of that file.',
-        'Things worth remembering: product details, audience segments, campaign performance benchmarks, winning ad angles, competitor insights, budget constraints, seasonal patterns, and any preferences the user expresses.',
-        'Format each learning as a bullet point with a date, e.g.: "- (2026-05-24) Best-performing Meta creative uses customer testimonial videos."',
-        'Never overwrite existing learnings — only append new ones.',
-        'If the learnings section grows beyond 50 items, summarize the oldest 25 into a "## Summary" section at the top and remove the individual bullets.',
     ];
+    if (isLaunchMode) {
+        parts.push('YOU ARE OPERATING IN LAUNCH MODE (READ-WRITE).', 'You are authorized to execute active write modifications on ad accounts (e.g. pausing campaigns, scaling bids, altering daily budgets, creating ads).', 'CRITICAL SAFETY RULE: For any write operation, you MUST generate a clear visual preview card outlining the exact changes and ask the user for explicit confirmation (Y/N) before executing. NEVER make active changes without their explicit confirmation.');
+    }
+    else {
+        parts.push('YOU ARE OPERATING IN AUDIT MODE (SAFE / READ-ONLY).', 'You are authorized to read campaigns, analyze performance data, find budget waste, and recommend copy or landing page changes.', 'CRITICAL SAFETY RULE: You are NOT authorized to make any active modifications to campaigns, budgets, or ad creative settings under any circumstances.', 'If the user asks you to pause a campaign, change a budget, or execute a write operation, explain politely that OpenAds is currently in Audit Mode (Safe/Read-only). Outline the exact steps you would take, and tell them to toggle to Launch Mode in Settings (`openads setup`) to execute them.');
+    }
+    parts.push('', '## Memory', '', `Your business context file is at: ${contextPath}`, 'This file contains everything you have learned about the user\'s business across sessions.', 'At the START of every conversation, read this file to recall past context.', 'At the END of a conversation (or when you learn something significant), APPEND new insights to the "## Learnings" section of that file.', 'Things worth remembering: product details, audience segments, campaign performance benchmarks, winning ad angles, competitor insights, budget constraints, seasonal patterns, and any preferences the user expresses.', 'Format each learning as a bullet point with a date, e.g.: "- (2026-05-24) Best-performing Meta creative uses customer testimonial videos."', 'Never overwrite existing learnings — only append new ones.', 'If the learnings section grows beyond 50 items, summarize the oldest 25 into a "## Summary" section at the top and remove the individual bullets.');
     if (config?.productContext) {
         parts.push(`\nThe user's business: ${config.productContext}`);
     }
@@ -252,13 +249,15 @@ async function main() {
     const modelName = chalk.cyan.bold(cleanProvider);
     const googleStatus = config.connectGoogle ? chalk.green('● Connected') : chalk.gray('○ Not connected');
     const metaStatus = config.metaToken ? chalk.green('● Connected') : chalk.gray('○ Not connected');
+    const modeName = config.mode === 'launch' ? chalk.red.bold('Launch Mode (Read-Write)') : chalk.green.bold('Audit Mode (Safe / Read-only)');
     // Build compact status panel
     const statusLines = [
         `  ${chalk.bold.white('Model')}       ${modelName}`,
+        `  ${chalk.bold.white('Mode')}        ${modeName}`,
         `  ${chalk.bold.white('Google Ads')}  ${googleStatus}`,
         `  ${chalk.bold.white('Meta Ads')}    ${metaStatus}`,
         '',
-        `  ${chalk.gray('v0.1.0')}  ${chalk.gray('·')}  ${chalk.gray('AI Command Center for Marketers')}`,
+        `  ${chalk.gray('v0.2.1')}  ${chalk.gray('·')}  ${chalk.gray('AI Command Center for Marketers')}`,
     ].join('\n');
     console.log(boxen(statusLines, {
         padding: { top: 1, bottom: 1, left: 2, right: 2 },
@@ -374,12 +373,21 @@ async function main() {
         baseDelayMs: 15000,
         provider: { maxRetryDelayMs: 120000 }
     };
+    // Setup MCP Servers inside settings.json
+    settings.mcpServers = settings.mcpServers || {};
+    const useRtk = hasGlobalRtk();
+    // Google Ads integration
+    if (config.connectGoogle) {
+        settings.mcpServers['google-ads'] = {
+            command: useRtk ? 'rtk' : 'uvx',
+            args: useRtk ? ['uvx', 'adloop'] : ['adloop']
+        };
+    }
     // Inject Meta MCP server if token is present
     if (config.metaToken) {
-        settings.mcpServers = settings.mcpServers || {};
         settings.mcpServers['meta-ads'] = {
-            command: 'npx',
-            args: ['-y', '@meta/mcp-server'],
+            command: useRtk ? 'rtk' : 'npx',
+            args: useRtk ? ['npx', '-y', '@meta/mcp-server'] : ['-y', '@meta/mcp-server'],
             env: { META_ACCESS_TOKEN: config.metaToken }
         };
     }

package/dist/schedule.js

@@ -7,6 +7,7 @@ import { spawnSync } from 'child_process';
 import gradient from 'gradient-string';
 import open from 'open';
 import { compileHtmlReport } from './report-template.js';
+import { optimizeTokenContext } from './token-optimizer.js';
 const openadsGradient = gradient(['#00d2ff', '#3a7bd5', '#00d2ff']);
 const CONFIG_DIR = path.join(os.homedir(), '.openads');
 const SCHEDULES_DIR = path.join(CONFIG_DIR, 'schedules');
@@ -261,11 +262,15 @@ export async function runScheduledTask(name) {
         stdio: ['ignore', 'pipe', 'pipe'],
     });
     if (result.stdout) {
-        console.log(result.stdout);
-        fullMarkdown += result.stdout;
+        const cleanOutput = optimizeTokenContext(result.stdout);
+        console.log(cleanOutput);
+        fullMarkdown += cleanOutput;
     }
     if (result.stderr) {
-        console.error(result.stderr);
+        const cleanError = optimizeTokenContext(result.stderr);
+        if (cleanError.trim()) {
+            console.error(cleanError);
+        }
     }
     // Compile and save the HTML report
     try {

package/dist/setup.js

@@ -125,6 +125,7 @@ export async function runSetup() {
     let customModel = '';
     let localModelName = '';
     let localBaseUrl = '';
+    let mode = 'audit';
     if (provider === 'local') {
         console.log(chalk.yellow('\n--- Local AI Setup ---'));
         console.log('You can run models 100% offline using tools like Ollama or LM Studio.');
@@ -209,8 +210,26 @@ export async function runSetup() {
         console.log(chalk.green(`\n✓ Local AI configured — ready to connect to ${localBaseUrl}.\n`));
     }
     console.log(chalk.gray('─────────────────────────────────────────\n'));
-    // Step 2: Google Ads
-    console.log(chalk.cyan('Step 2/4: Connect Google Ads (optional)\n'));
+    // Step 2: Choose operational mode
+    console.log(chalk.cyan('Step 2/5: Choose operational mode\n'));
+    console.log('OpenAds has two operational modes:');
+    console.log(` - ${chalk.green.bold('Audit Mode (Safe / Read-only)')}: AI can analyze performance, find budget waste, and recommend strategies. Zero risk.`);
+    console.log(` - ${chalk.red.bold('Launch Mode (Read-Write)')}: AI is authorized to optimize bids, modify budgets, and launch ads (always requires confirmation).\n`);
+    const modeAnswers = await enquirer.prompt({
+        type: 'select',
+        name: 'selectedMode',
+        message: 'Choose your default operational mode:',
+        choices: [
+            { name: 'audit', message: 'Audit Mode (Safe / Read-only — Recommended)' },
+            { name: 'launch', message: 'Launch Mode (Read-Write — Active campaign changes)' }
+        ],
+        initial: existingConfig.mode === 'launch' ? 1 : 0
+    });
+    mode = modeAnswers.selectedMode;
+    console.log(chalk.green(`\n✓ Operational mode configured: ${mode === 'launch' ? 'Launch Mode (Read-Write)' : 'Audit Mode (Safe / Read-only)'}.\n`));
+    console.log(chalk.gray('─────────────────────────────────────────\n'));
+    // Step 3: Google Ads
+    console.log(chalk.cyan('Step 3/5: Connect Google Ads (optional)\n'));
     console.log('OpenAds can read and analyze your Google Ads campaigns, keywords, and performance.\n');
     const { connectGoogle } = await enquirer.prompt({
         type: 'confirm',
@@ -248,8 +267,8 @@ export async function runSetup() {
         console.log(chalk.green('✓ Google Ads module enabled.\n'));
     }
     console.log(chalk.gray('─────────────────────────────────────────\n'));
-    // Step 3: Meta Ads
-    console.log(chalk.cyan('Step 3/4: Connect Meta Ads (optional)\n'));
+    // Step 4: Meta Ads
+    console.log(chalk.cyan('Step 4/5: Connect Meta Ads (optional)\n'));
     console.log('OpenAds can read your Meta campaigns, creatives, and audience performance.\n');
     let metaToken = '';
     const { connectMeta } = await enquirer.prompt({
@@ -355,8 +374,8 @@ export async function runSetup() {
         }
     }
     console.log(chalk.gray('─────────────────────────────────────────\n'));
-    // Step 4: Business Context
-    console.log(chalk.cyan('Step 4/4: Tell me about your business\n'));
+    // Step 5: Business Context
+    console.log(chalk.cyan('Step 5/5: Tell me about your business\n'));
     const { productContext } = await enquirer.prompt({
         type: 'input',
         name: 'productContext',
@@ -379,6 +398,7 @@ export async function runSetup() {
         provider: finalModel,
         apiKey,
         localBaseUrl,
+        mode,
         connectGoogle,
         metaToken,
         productContext

package/dist/token-optimizer.js

@@ -0,0 +1,66 @@
+import { spawnSync } from 'child_process';
+/**
+ * Checks if the Rust Token Killer (rtk) CLI binary is installed globally on the user's machine.
+ */
+export function hasGlobalRtk() {
+    try {
+        const result = spawnSync('rtk', ['--version'], { stdio: 'ignore' });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * TS-native token compression utility. Filters out progress bars, experimental warnings,
+ * download lines, and redundant log noise from CLI processes to optimize AI context windows.
+ */
+export function optimizeTokenContext(text) {
+    if (!text)
+        return '';
+    // 1. Strip ANSI escape sequences (colors, text formatting, control characters)
+    const ansiRegex = /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g;
+    let cleanText = text.replace(ansiRegex, '');
+    // 2. Process line-by-line to strip installation/CLI environment noise
+    const lines = cleanText.split('\n');
+    const filteredLines = lines.filter(line => {
+        const l = line.trim();
+        if (!l)
+            return true; // Keep spacing empty lines
+        // Ignore Node, NPM, NPX, UV/UVX experimental warnings & logs
+        if (l.startsWith('ExperimentalWarning:'))
+            return false;
+        if (l.startsWith('npm notice'))
+            return false;
+        if (l.startsWith('npm warn'))
+            return false;
+        if (l.startsWith('npm ERR!'))
+            return false;
+        if (l.includes('npx: installed'))
+            return false;
+        if (l.includes('npm install'))
+            return false;
+        if (l.includes('audited'))
+            return false;
+        if (l.includes('found 0 vulnerabilities'))
+            return false;
+        // Ignore package/tool downloader progress indicators
+        if (l.includes('Retrieving'))
+            return false;
+        if (l.includes('Downloading'))
+            return false;
+        if (l.startsWith('Resolving'))
+            return false;
+        if (l.startsWith('Installed'))
+            return false;
+        if (l.includes('Warning:'))
+            return false;
+        // Ignore progress bar lines
+        if (l.includes('[====='))
+            return false;
+        if (l.includes('========>'))
+            return false;
+        return true;
+    });
+    return filteredLines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openads-ai",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Open-source AI command center for digital marketers. Audit campaigns, write ad copy, and build strategies — from your terminal.",
   "main": "dist/cli.js",
   "bin": {