How to set up an AI agent that runs your Google Ads
2026-10-21
What the AI agent does and what stays with you
The AI agent runs the mechanics of Google Ads and works toward one goal number: dollars per sales-qualified lead (SQL). You define SQL and set the spending limits. The AI agent changes the account within those limits and records what happened after each change.
I ran this approach for a B2B software company in September–October 2026. The template repository replaces its details with Northstar Dispatch, a fictional company; the examples below are not that company's results.
The AI agent does not run all the time. A script checks the account every hour and wakes the AI agent only when a sprint is due or a limit breaks. Each such run is called a pass: the AI agent reads the rules and the open work, makes or checks changes, and ends with a journal line. Work comes as sprints. A sprint is a GitHub issue with a goal, a deadline and a scope, the list of things the AI agent may change.
From that company's real journal, the week of 12–18 October 2026: $273 spent on 77 people from ads, one SQL, 19 passes that moved a sprint and 41 that recorded why nothing moved. On 19 October a brand campaign sprint closed early: three booked sales demos at about $80 each, against a limit of $202.
Before you give the AI agent access to the account, agree on who decides what. The split is written in rules/agent-rules.md and PROCESS.md.
| Who decides | What |
|---|---|
| The AI agent, inside the sprint's scope | Bids and click price limits, conversion goals, negative keywords, pausing keywords and ads, countries, ad texts and tracking tags |
| The AI agent, if you gave it publishing access | Landing page copy named in the sprint's scope |
| A person, with an explicit “yes” | Raising the total budget, turning a campaign on or off, and anything sent to people outside the agreed channel and repository |
A sprint never grants permission to raise the budget or switch a campaign on or off. Record the person's answer in the sprint issue or its Slack thread.
The week follows this schedule.
- 1Human
You set the goal
You define SQL and the spending limits.
- 2AI agent
The AI agent reads the rules
It reads the goal and the current sprint before every pass.
- 3AI agent
The watch runs hourly
A script checks the limits; the model stays asleep.
- 4AI agent
A sprint becomes due
The AI agent accepts work, advances it or closes it.
- 5AI agent
Monday closes the week
A script rebuilds the weekly table and writes the goal number.
- 6AI agent
A limit breaks
The AI agent handles the alarm within its rights and asks for any decision beyond them.
- 7Human
You answer a decision
You give an explicit yes when the change needs you.
The record stays in the repository
Every change has an experiment ledger entry and an undo command.
The repository: copy the template and set it up
Start with a private copy of the template. The repository is the AI agent's memory: it holds the rules, the experiment ledger and the journal. Save the script of every change with its undo there; between passes, the AI agent can rely only on what was written down.
Work through the first evening in this order.
- Choose Use this template, keep your copy private and clone it to your computer.
- Fill
goal.yamlwith your campaigns and SQL definition, then replace the example targets with numbers from your account. - Set your click price and overspend limits in
monitors/rules.yaml. - Ask your developer for the setup list below, then copy
loop.env.exampletoloop.envand fill it outside git. - Write the name of the person who says “yes” in
goal.yaml(owner), then fill the first sprint using.github/ISSUE_TEMPLATE/sprint.md. - Create the Python environment next to the repository folder and load your keys:
python3 -m venv ../venv && . ../venv/bin/activate && pip install "google-ads>=34" gspread google-auth requests python-dotenv pyyaml, thenset -a; . ./loop.env; set +a. Keep the environment outside the repository folder, because every pass of the AI agent commits withgit add -A. - Run
python scripts/selftest.py, thenpython monitors/check.py --dryandpython scripts/gaql.py search_terms start=YYYY-MM-DD end=YYYY-MM-DDfor last week. The last two read your account and change nothing; they must finish without errors, and the second must print your own search terms. - Choose the Hermes bot or the OpenClaw agent for a server that stays on, or start with Claude Code on your computer using the root
AGENTS.md. - In GitHub, turn on Settings → Actions → General → Workflow permissions → Read and write permissions, then run Actions → sprint-sync → Run workflow once. That first run creates the
sprint-statebranch the AI agent reads and the four sprint labels. - When steps 1–10 of the Launch checklist at the end of this guide are done, open the filled sprint issue with the label
sprint. That happens weeks after the first evening: step 8 waits until the import action is past its first 14 days and daily uploads have run for one or two conversion cycles.
examples/northstar/ shows the finished sprint and journal; the fictional goal and limits are already filled at the repository root.
For a bot installation, loop.env sits beside the cloned repo/ directory. On your computer it can sit in the repository root, where .gitignore excludes it. The names come from loop.env.example; this excerpt shows the main ones.
LOOP_REPO=your-name/google-ads-loop # owner/name of this repo on GitHub
LOOP_TZ=America/Chicago # the loop's clock
# ...
SLACK_CHANNEL= # id of #ads-loop, used by sprint_gh.py post (same value as SLACK_HOME_CHANNEL)
GOOGLE_ADS_CUSTOMER_ID=1234567890 # the ad account, digits only (123-456-7890)
# ...
GOOGLE_SA_JSON=/root/.hermes-ads/secrets/google-sa.json # path to the key file; also edits the weekly sheet and sends conversions through the Data Manager API
# ...
WEEK_SHEET_ID= # the Google Sheet of the weekly table (share it with the service account as editor)
POSTHOG_API_KEY= # personal API key with "Query Read"
POSTHOG_PROJECT_ID=
POSTHOG_HOST=https://us.posthog.com # or https://eu.posthog.com
CRM_OPPORTUNITIES_CSV= # CSV export of CRM opportunities (email,created,stage); empty = repo/data/crm-opportunities.csv
CONVERSION_ACTION_ACTIVATED= # id of the Google Ads conversion action "Activated" (import from clicks)
CONVERSION_ACTION_DEMO= # id of the conversion action "Demo booked" (import from clicks)
Hand your developer this list once; the repository's README.md holds the same list.
- A Google Cloud project with the Google Ads API and the Data Manager API enabled. Enabling the Google Ads API gives the project Test access, which works only with test accounts, so a call to your live account fails with
CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION. Apply for Explorer access on the project's Google Ads API Overview page in Google Cloud Console; Explorer allows 2,880 operations a day on live accounts. Google reviews the application automatically and grants Explorer in most cases. Apply from the Cloud project, not from the API Center of a Google Ads manager account as older tutorials say; Google no longer processes applications made there. The person who applies needs the Owner, Editor, Quota Administrator or Service Usage Admin role in the project. Google lists a known issue: a project on the Google Cloud free trial, or with suspended or disabled billing, can be refused. Upgrade the project to a paid tier, or remove its billing if it runs nothing else, wait a few minutes and apply again. Google's developer token page Google's access levels - A service account in that project, added as a user of the ad account with Standard access; its key file path goes in
loop.env. - A deploy key with write access to your repository, so the AI agent can push its journal and sprint request files.
- In your application, sign-up keeps
gclid(orgbraid,wbraid) with the new person, identifies that person by email in the same PostHog project as the landing page, and sends the events named in Tie every click to a person and a sale. From your CRM, a CSV export of opportunities refreshed intodata/crm-opportunities.csv(see Tie every click to a person and a sale). - The server: the Hermes service or the OpenClaw gateway, with every key file restricted by
chmod 600. - Vercel: the project with Root Directory
site, its variables, and Protection Bypass for Automation if previews need a login (see The landing site the AI agent rebuilds).
Two checks remain yours before you trust the numbers: your PostHog event names match site/README.md, and the two outcome queries in scripts/upload_conversions.py return the counts your product shows (see Send outcomes back to Google).
The AI agent's rules on one page
Keep these rules in rules/agent-rules.md, which the AI agent reads before every pass. The runtime's operating file points to it; SOUL.md holds the voice.
The goal
- The loop moves one number: the dollars per SQL of the goal campaigns in
goal.yaml. - Never type a number into
scoreboard/;scripts/scoreboard.pywrites the numbers. - A pass that moves no sprint and no experiment is a failed pass.
- Decide on funnel steps (people, opened sign-up, signed up, activated), not on one week of SQL.
What the AI agent decides alone
- Inside the sprint frame: bids, price limits, conversion goals, negative keywords, pausing keywords and ads, countries, ad texts, tracking tags.
- Landing-page copy, only with publishing access, only what the sprint frame names, after backing up the page.
- Changes that need code are outside the loop; shape the sprint so that copy is enough.
- Outside the running sprint's frame it decides nothing; a new idea becomes a new sprint.
What only a person decides
- Raising the total budget and turning a campaign on or off need a person's explicit “yes” in the sprint issue or the Slack thread.
- Silence is “no”, a missed deadline never becomes “yes”, and the default in a DECISION post is never to spend more or switch a campaign.
- A sprint frame never grants a budget raise or a campaign switch; a frame that asks for one is refused.
- Before asking, the AI agent checks that the access or the choice is really missing.
Before any change
- A ledger row in
experiments/LEDGER.mdcomes first: the expected effect on a step, the reading date, the decision rule, the undo. - One change per step at a time; two active sprints never change the same step of the same campaign.
- Every account or page change goes into
data/changes.jsonwith its date and one line. - Back up the page and keep the change script, so the undo is a command.
- Read
LESSONS.mdbefore any change to bidding, budgets, tracking or conversions.
Reading results
- 15 or more people and no activity on the page: cut the keyword or ad.
- 150 or more people and no SQL: cut it; with fewer people, 0 SQL is still normal luck.
- One test per page, decided at 100 people per half, or earlier when one half is 3 or more SQL ahead.
- A reading never holds a lever: a measurement longer than a sprint goes into the weekly report and never postpones the next sprint.
- A sprint lasts at most seven days and its Point B is countable inside the week; SQL is never a sprint's Point B.
- Numbers come from the scripts; if a script gives none, say so and do not estimate.
Work comes as sprints
- All planned work is a sprint issue; the AI agent accepts it unless
SPRINTS.mdsays to refuse. - A goal sprint is always open; closing one opens the next in the same pass, on the step that loses the most money.
- A Slack request never changes a running sprint; it becomes a new sprint issue.
- Point B of an accepted sprint changes only to shorten it to seven days; a change made by a person goes into the next report.
- Every pass ends with one journal line per sprint or alarm handled, then a commit and push.
Talking to people
- One door: only the posting script posts into the channel — sprint cards, DECISION, ALARM, and one plain line when the machinery is broken.
- A DECISION post opens with
**DECISION**, what to decide, by when and the default; an ALARM post opens with**ALARM**, what is broken and what it costs; each adds at most four short lines. - A problem the AI agent fixed itself goes only into the journal.
- Sprint titles and cards use plain words and numbers a salesperson can act on.
- The AI agent writes only in the agreed channel and the repository's issues.
- Every scheduled job delivers its output locally on the server.
Keys
- Never print, copy or commit a key;
loop.env, the bot's env file andsecrets/stay where they are.
When a script fails
- Say what failed in one line, keep the error in the journal line, and do not guess numbers.
- Retry a failing call at most twice, then stop and report it.
Write the experiment ledger row before the change so the decision rule cannot shift after the result arrives. Name the expected effect on a funnel step and the reading date; include the keep-or-restore rule and the exact undo in the linked experiment file, using experiments/TEMPLATE.md.
Keep one change per funnel step at a time because simultaneous changes prevent you from identifying which one helped. Two sprints can run together when they change different steps or different campaigns.
A late reading does not delay the next sprint: sprints end within a week, while SQL continues to arrive in the background. Close the sprint against its countable Point B and keep the later SQL reading in the weekly report.
One script sends every message to Slack. Scheduled jobs also produce errors and routine final answers; those stay in the server log and journal, and the script posts only sprint cards, decisions and alarms. A lasting failure in the posting machinery produces one plain notice.
One number and the steps to it: goal.yaml
Define the goal number as spend from the goal campaigns divided by SQL among people whose first ad click falls in the period. Keep that click period fixed when later SQL arrives. A person counts as an SQL when a sales call becomes an opportunity in the CRM, or when the person completes the product action after which your customers usually pay; staff never count.
Do not make sign-ups or MQL the goal number. The AI agent will learn to buy the stage you reward, even if those people never become customers.
The campaign and SQL definitions live in goal.yaml.
goal: $ per SQL - Google Ads search campaigns "QuickBooks sync" 1111111111 and "Dispatch software" 2222222222 # example
formula: Google spend of the 2 goal campaigns (USD) / SQL among people whose first ad click falls in the period
sql: a person who came from an ad and then either (a) had a sales call logged as an opportunity in the CRM, or (b) connected QuickBooks AND added 3+ technicians within 14 days of signup. Staff and test accounts never count. # example
note: the Brand campaign is watched by the monitor and may have its own sprints, but the goal counts the two campaigns marked goal=true below only.
currency: USD # the account's currency; limits in monitors/rules.yaml are in this currency
timezone: America/Chicago # the account's time zone; weeks run Monday 00:00 to Sunday 23:59 in it
customer_id: "123-456-7890" # example; the real value is also in loop.env (GOOGLE_ADS_CUSTOMER_ID)
campaigns: # id, name as shown in reports, goal=true if the goal counts it
- {id: 1111111111, name: QuickBooks sync, goal: true, landing: /lp/quickbooks-dispatch} # example
- {id: 2222222222, name: Dispatch software, goal: true, landing: /lp/hvac-dispatch-software} # example
- {id: 3333333333, name: Brand, goal: false, landing: /} # example
staff_email_domains: [northstar-dispatch.example] # people with these domains never count
sql_params: {activation_technicians: 3, activation_days: 14, signup_window_days: 2}
baseline: {value: 260, period: 2026-09-07..2026-10-04, people: 1000, sql_per_100: 2.3, source: first 4-week table} # example
milestone: {value: 200, people_from: 2026-11-02, people_to: 2026-11-29, first_read: 2026-12-14, final_read: 2026-12-21} # example
# ...
Replace the fictional campaign identifiers and staff domain with yours. Replace the activation condition with a product action supported by your own customer data.
The funnel steps and reserved decisions continue in goal.yaml.
steps:
- {name: $ per person from ads, metric: usd_per_person, baseline: 6.00, aim: "<= 6.50", read: weekly} # example
- {name: opened signup per 100 people, metric: opened_signup_per_100, baseline: 12, aim: ">= 20", read: 2026-11-09} # example
- {name: opened signup -> signed up in 2 days, metric: signup_2d_rate, baseline: 0.30, aim: ">= 0.45", read: at 25 openers} # example
- {name: signed up -> activated in 14 days, metric: activated_rate, baseline: 0.30, aim: ">= 0.35", read: 2026-11-23} # example
- {name: SQL per 100 people (4 weeks), metric: sql_per_100, baseline: 2.3, aim: ">= 3.0", read: 2026-12-14 and 2026-12-21} # example
owner: "Dana Reyes (@dana-reyes)" # example; the one person whose explicit "yes" the agent waits for
owner_decides: raising the total budget; turning a campaign on or off; anything sent to people outside
Replace each baseline and aim with your own figures. Keep the metric names that scripts/scoreboard.py uses unless your developer adds a new calculation. Take the baselines from your own weeks. For each of the last four full weeks in which your landing pages already saved the click, run python scripts/week_table.py <monday> <sunday> with the dates as YYYY-MM-DD; it writes data/week-<monday>.json and changes nothing in Google Ads, PostHog or the CRM. Then run python scripts/scoreboard.py. In scoreboard/SCOREBOARD.md, the Now column under Steps against their aims gives each step's value over the last four weeks in the data. For the baseline line, divide the goal campaigns' spend in those weeks by the SQL among their people, as in the goal reading below; for the SQL-per-100 step, take 100 times those SQL divided by those people. Count each person once: after weeks are rebuilt, the scoreboard counts an opportunity created in a later week a second time in that week.
Use the steps according to the time they need to produce a useful reading.
Step from goal.yaml | How to use it |
|---|---|
| Dollars per person from ads | Read it weekly to see whether spend buys more people or merely more expensive clicks. |
| Opened sign-up per 100 people | Use it for a sprint that changes landing page copy. |
| Opened sign-up to signed up within two days | Use it for a sprint that improves completion after the click on the sign-up link. |
| Signed up to activated within 14 days | Read it only when sign-ups have had the full activation window. |
| SQL per 100 people over four weeks | Read it in the background to check whether earlier gains produce qualified leads. |
A small account gets few SQL each week, and some arrive weeks after the click. Check the days from click to deal in your own data and judge the goal number over a period longer than that delay. Use the earlier steps for decisions that must fit inside a week.
Every Monday, scripts/scoreboard.py writes scoreboard/SCOREBOARD.md and scoreboard/weeks.csv; the AI agent never types those numbers. The example aims for $200 per SQL before reaching $150, but choose a target from your own economics.
The weekly scoreboard counts an SQL in the week it happens, for the campaign whose ad brought the person. The goal number counts by click period instead: on the read dates in goal.yaml, rerun scripts/week_table.py for each week of the period, because it follows the people of that week up to today, and divide the spend of those weeks by their SQL. Test both views on one person who clicks in one week and has a sales call logged as an opportunity in the next: the weekly scoreboard shows that SQL in the second week, and the goal reading credits the first week exactly once.
Judge keywords and landing page tests by the thresholds in the Reading results group of rules/agent-rules.md. PROCESS.md explains one of them, 150 people with no SQL: at an SQL rate of about 2 %, fewer people with no SQL is still normal luck.
Tie every click to a person and a sale
Turn on auto-tagging in Google Ads. Google adds gclid to the landing page URL; your landing page saves it before sending the first analytics event. Keep the same click identifier on every later event and pass it into the sign-up record.
The starter sends events to PostHog. Its site/instrumentation-client.ts stores attribution before the first page view, and site/components/ad-landing/AdLandingTracker.tsx adds click values to sign-up links. Your developer must connect the application to the same PostHog project as the landing page, so the ad visitor and the new account stay one PostHog person. At sign-up the application calls posthog.identify() and sets the person property email; if the landing page and the application sit on different subdomains, follow PostHog's cross-domain tracking setup. The scripts read the click from that person's landing $pageview and every outcome from named PostHog events, so a gclid kept only in your own database never reaches them. The application sends signup_completed and demo_booked, plus your activation events in place of the starter's quickbooks_connected and technician_added; if your names differ, change EV_* in scripts/week_table.py and the two outcome queries in scripts/upload_conversions.py.
Find the keyword in Google's click_view report by gclid. Each query must cover exactly one day, and the report reaches back 90 days, so collect it regularly. Click report reference
The saved query lives in scripts/queries/click_by_gclid.gaql.
# Which keyword brought one click? gclid -> keyword, from Google's own click log (more reliable than tags in the landing URL).
# click_view needs exactly one day in the filter and reaches back 90 days at most: pass the day of the click.
# Used by week_table.py for every click; run it by hand to check one visitor.
# usage: python scripts/gaql.py click_by_gclid date=2026-11-03 gclid=<the gclid from the landing URL>
SELECT
click_view.gclid,
click_view.keyword_info.text,
click_view.keyword_info.match_type,
click_view.ad_group_ad,
campaign.id,
campaign.name,
ad_group.name,
segments.date,
segments.device
FROM click_view
WHERE segments.date = '{date}'
AND click_view.gclid = '{gclid}'
Supply the click date and the gclid from your landing event through scripts/gaql.py. Keep the letter case of gclid: Google rejects an identifier whose case differs.
Keep UTM tags only in the campaign's final URL suffix. Sitelinks with their own UTM tags overwrite campaign tags, so remove those duplicates and treat URL tags as the fallback when the click log cannot supply the keyword.
Run scripts/week_table.py to build the weekly table without a model. It writes data/week-<START>.json; scripts/week_sheet.py can also publish the table to a spreadsheet shared with the service account.
A person's row must contain:
| Part of the row | What to check |
|---|---|
| Click | Keep the first click date and its identifier. |
| Campaign and keyword | Match them to the click log. |
| Page actions | Show what the person actually did after landing. |
| Sign-up | Record whether the person opened and completed it. |
| Product action | Record whether the qualifying action happened within your chosen window. |
| Call and opportunity | Match the CRM contact to the person and keep the opportunity date. |
| SQL | Count the person once when either qualifying path is satisfied. |
Sales calls come from your CRM as a CSV export of opportunities. crm_opportunities() in scripts/week_table.py reads data/crm-opportunities.csv, or the path in CRM_OPPORTUNITIES_CSV, with three columns; examples/northstar/crm-opportunities.example.csv shows the shape.
email,created,stage
ops@lakeside-hvac.example,2026-10-21,Discovery call
ops@lakeside-hvac.example,2026-09-02,Closed lost
dispatch@prairie-plumbing.example,2026-10-27,Demo held
Refresh the export before each table run, by hand or with a scheduled CRM export. The script matches each opportunity to the person by email, and by company domain for addresses outside free mail services; an opportunity created before the ad click does not count. A booked demo alone is not a sales call logged as an opportunity. The file holds emails, so .gitignore keeps it out of git.
Remove staff and Google's landing page checker from the decision table. The starter drops the checker's visits, which carry ad_id=0 and no click identifier, and marks staff so the scoreboard excludes them; verify both exclusions against your actual events before accepting the counts. It also appends Google clicks with no matching site visit for reconciliation, so keep those separate from the one-row-per-person counts.
Compare the totals with your account and CRM before opening the first sprint. A test person should retain the same keyword from the landing event through the final SQL row.
Send outcomes back to Google, so bidding learns from them
Smart Bidding learns from the primary conversion selected for the campaign. With sign-up as primary, Google buys sign-ups; with no conversion signal, it has no account outcomes to learn from. A conversion built from a GA4 event is a secondary, observation-only action by default and can be made primary only in Google Ads. Google's primary and secondary actions GA4 can also credit the event to a later visit from another source, such as a link in a tool the user connects to your product, so upload your own outcomes by gclid to keep the credit with the ad click. The starter sends two outcomes: a product activation and a booked demo. It does not send CRM deals until your developer adds that outcome to scripts/upload_conversions.py.
Use Data Manager API events:ingest for a new setup. Since 15 June 2026, the Google Ads API has accepted offline conversion uploads only from developer tokens that sent such uploads between 17 December 2025 and 15 June 2026. Developer tokens were retired on 9 September 2026, and that restriction still applies. Google's deprecation notice
Enable Data Manager API in the service account's Cloud project. Add the service account email under Google Ads Admin → Access and security with Standard access, so the AI agent can change the account; Google does not allow Email only access for service accounts and advises administrator access only when a call needs it. Google's service account guide Use the https://www.googleapis.com/auth/datamanager scope. This route needs no developer token. Google's access guide
Create one conversion action with the source Import from clicks and a 90-day click window for each outcome you send; the starter sends two, activation and booked demo. Create them before collecting the clicks you intend to credit. To find an action's identifier, open Goals → Conversions → Summary in Google Ads, click the action's name and open the Details tab: the identifier is the number next to Conversion type ID. Put it in CONVERSION_ACTION_ACTIVATED or CONVERSION_ACTION_DEMO in loop.env. If you leave a variable empty, the starter skips that outcome.
Allow for the first 14 days of the conversion action, which Google calls its trial period (not your product's trial). An uploaded event whose transactionId matches no tag event becomes a new conversion; during those 14 days such conversions appear in reports but are not used for bidding, and after that they become biddable automatically. The starter builds transactionId from its own key, so every event it sends in those days is such a new conversion. Google's event ingestion guide
Upload every day for one or two conversion cycles before making the action primary. When gclid is unavailable, enhanced conversions for leads can use a hashed email, with an import limit of 63 days; imports by gclid allow up to 90 days. Google's offline conversion FAQ
Google advises judging Smart Bidding results over a period with at least 30 conversions, such as a month or longer. Google's Smart Bidding guide Make the step that reaches 30 conversions a month your primary conversion. If SQL is too sparse, bid on the product action; once your developer adds the CRM outcome, send deals as secondary conversions. Manual CPC with a bid for each keyword is the other option.
The request construction lives in scripts/upload_conversions.py.
dest = {
"operatingAccount": {"accountType": "GOOGLE_ADS", "accountId": gads.customer_id()}, # 10 digits, no hyphens
"productDestinationId": ACTIONS[kind], # the conversion action id; the action must be of type UPLOAD_CLICKS
}
login = os.environ.get("GOOGLE_ADS_LOGIN_CUSTOMER_ID", "").replace("-", "")
if login: # only when the service account reaches the ad account through a manager account
dest["loginAccount"] = {"accountType": "GOOGLE_ADS", "accountId": login}
body = {
"destinations": [dest],
"events": [{
"eventTimestamp": t.replace(" ", "T") + "Z", # RFC 3339
"eventSource": "WEB",
"transactionId": hashlib.sha1(key.encode()).hexdigest()[:32], # optional; makes a repeat harmless
"conversionValue": 1.0, "currency": CURRENCY,
"adIdentifiers": {"gclid": gclid},
} for key, (t, gclid, email) in items],
"validateOnly": bool(validate_only),
}
# Consent for people in the EEA (Digital Markets Act) is optional in the request: add
# "consent": {"adUserData": "CONSENT_GRANTED", "adPersonalization": "CONSENT_GRANTED"} only for people who gave it.
# Field names checked against https://developers.google.com/data-manager/api/reference/rest/v1/events/ingest (20.10.2026).
r = session.post("https://datamanager.googleapis.com/v1/events:ingest", json=body, timeout=120)
Set the conversion action identifiers and account credentials through loop.env. The starter selects only people with gclid; your developer must extend both the selection and the request to send hashed email through userData when the click identifier is missing.
Before enabling uploads, run the two outcome queries from scripts/upload_conversions.py in PostHog's SQL editor and compare their counts with your product. Replace the Northstar activation events with your own qualifying action.
The hourly Hermes job executes bots/hermes/scripts/conv-upload.sh.
#!/bin/bash
# No-AI job every hour: send activations and booked demos of ad visitors back to Google Ads as click conversions
# (scripts/upload_conversions.py), so Smart Bidding learns from them. Output goes to repo/state/conv-upload.log, which the
# hourly watch reads (monitors/rules.yaml, conv_upload: 2 failed runs in a row, or the log older than 2.5 hours).
bash /root/.hermes-ads/scripts/loop.sh sh -c 'python scripts/upload_conversions.py --days 3 >> state/conv-upload.log 2>&1'
Keep the log location when adapting the paths because the watch reads it. The Hermes section below installs the hourly schedule at minute 17.
Run python scripts/upload_conversions.py --dry-run to inspect the selected events, then python scripts/upload_conversions.py --validate-only to have Google validate the request without ingesting it. After a real upload, retain request_id and inspect RetrieveRequestStatus after 30 minutes; an accepted request alone does not prove that every event was credited.
The starter selects activations and booked demos, and looks for the latest preceding click within 30 days. A 90-day conversion window in Google does not extend that query automatically: have your developer extend the collection window when your sales cycle needs it.
Work comes in as sprints: a GitHub issue
Open work through Issues → New issue → Sprint using .github/ISSUE_TEMPLATE/sprint.md. Fill the goal and deadline, then specify Point B and the scope of permitted changes; the AI agent fills Point A from scripts when accepting the sprint.
Nobody approves a sprint. The AI agent accepts it at the next hourly check, or at the time in its **Starts:** line, and refuses only an issue it cannot run, with the reason in the issue. The other sprint rules are in The AI agent's rules on one page; SPRINTS.md in the repository holds the same rules.
The AI agent accepts with Point A in numbers, checks in every six hours and reports daily. At the deadline, it closes with the result and a retrospective, then opens the next sprint in the same pass. All details stay in the issue; Slack receives a card for each report.
The filled example in examples/northstar/sprint-issue.md gives a countable target and a narrow scope.
**Goal:** 20 of every 100 ad visitors open signup on the QuickBooks and Dispatch pages (now about 12)
**Campaign:** 1111111111, 2222222222
**Step:** opened signup per 100 people (goal.yaml)
**Ends:** 2026-11-03 09:00 Chicago
**Check-in every:** 6h
# ...
### Point B - where we must be at the end
Among ad visitors who see the new first screen, count how many open the signup page, per 100.
- 20 or more of 100: reached, keep the new text.
- 15 to under 20: partly reached, keep and improve in the next sprint.
- under 15: not reached, restore the old text (E-002 undo).
### Frame
- Budget: unchanged ($35 a day and $45 a day)
- The bot may change: the subheading text under the main headline of both pages, English only
- The bot must not change: buttons, links, other sections, keywords, countries, other campaigns
- Always a human "yes": raising the total budget, turning a campaign on or off
# ...
### Stop early if
40 or more visitors have seen the new text and fewer than 9 of 100 opened signup: restore the old text the same day.
### Undo
Restore the two subheading fields from the backups in `data/backups/` (only those fields). Read both pages back.
Replace the campaign identifiers and deadline, then define the exact fields the AI agent may change. Keep an early-stop rule and an undo in the complete issue.
The acceptance comment in examples/northstar/sprint-issue.md records Point A with its source.
<!-- sprint-bot:accepted -->
**Status:** on track
**Now:** Accepted. Last week 13 of 101 ad visitors opened signup on these two pages (13 of 100); the aim is 20 of 100 by Tuesday.
**Next:** Publish the new first-screen text today and start counting from the moment both pages are live.
---
Point A: window 19-25 Oct, ad visitors of campaigns 1111111111 and 2222222222, staff excluded, each person once:
QuickBooks page 6 of 47, Dispatch page 7 of 54. Source: scripts/week_table.py, data/week-2026-10-19.json.
The corresponding card lives in examples/northstar/slack-cards.md.
(green) Sprint #4: Twice as many ad visitors start signup on the QuickBooks and Dispatch pages
Goal Deadline
20 of every 100 ad visitors open signup (now about 12) Tue 3 Nov
Where we are now
27 of 121 ad visitors opened signup since the new text went live (22 of 100), above the 20 aim.
Check-in - Next: final count at the deadline, Tuesday 09:00 - next report ~21:27 - full text in GitHub
A person can create the sprint from a filled sprint.md using this command from SPRINTS.md.
gh issue create -R OWNER/REPO --label sprint \
--title "Sprint: Twice as many ad visitors start signup on the QuickBooks and Dispatch pages" --body-file sprint.md
Replace OWNER/REPO with your private repository. The person's gh login is used only for this command.
The AI agent reads and writes issues without a personal GitHub key. .github/workflows/sprint-sync.yml uses the repository's Actions token to copy sprint issues and comments to issues.json on the sprint-state branch. The AI agent pushes request files to sprints/outbox/, and the workflow applies them before recording the result in processed.json.
Keep the workflow on main; the first-evening steps in The repository turn on its write permission and run it once. Give the AI agent a repository deploy key with write access so it can push its journal and request files. If sprint-state is more than seven hours old, inspect the repository's Actions tab before assuming the AI agent has seen a new instruction.
The watch without a model, and the AI agent's schedule
The watch is monitors/check.py, which runs every hour without a model. Within the limits, it sends nothing to Slack and ends with {"wakeAgent": false} for the scheduler. When a limit breaks, it writes state/alarm.json and requests an alarm pass; the same alarm is raised at most once in 24 hours.
The limits live in monitors/rules.yaml.
currency: USD
expensive_click:
rule: average click price of a keyword today above the limit
limit_usd: 15 # example; about 2.5 x the normal click of the goal campaigns
overspend:
rule: campaign spend today above its daily budget x factor
factor: 1.5 # Google may spend up to 2 x the daily budget on one day, so 1.5 is an early warning
dark_campaign:
rule: enabled campaign with 0 impressions in the last N complete hours, while the same hours a week ago had more than M
hours: 4
week_ago_min_impressions: 10
disapproved:
rule: an enabled ad in an enabled ad group is disapproved by Google
foreign_change:
rule: a change in the account not made through the API (a person in the Google Ads web interface, an agency, Google itself - auto-applied recommendations, automated rules, scripts)
api_client: GOOGLE_ADS_API
loop_user_email: "" # optional: the service-account or user email the loop signs in with; API changes by anyone else are flagged too
conv_upload:
rule: the hourly upload of CRM outcomes to Google Ads (scripts/upload_conversions.py) failed in its last runs, or its log went stale
failed_runs: 2
log: state/conv-upload.log # the upload job appends its output here; relative to the repo root
max_age_hours: 2.5
Replace the $15 average keyword CPC limit with your own limit. Fill loop_user_email so the watch can also distinguish another person's API changes from yours.
The example alarms at 1.5 times a campaign's daily budget. It also checks for four complete hours without impressions when the same hours a week earlier had more than ten, and flags disapproved ads. Conversion uploads trigger an alarm after two failed runs or a log older than 2.5 hours; make sure the first upload creates that log, because a missing log is not treated as a failure.
Read other people's changes through change_event, which identifies the user and the client used to make a change. It keeps 30 days and does not return changes uploaded from Google Ads Editor. Google Ads Editor changes show up in change_status: it lists the campaigns, budgets, ad groups, ads and keywords that changed in the last 90 days, with only the latest change of each and no field-level values. It does not say who made a change, so compare its rows with the AI agent's own API changes in change_event. The starter's watch reads only change_event, so either have your developer add a change_status check or agree with your PPC specialist that every Editor upload is noted in the sprint issue. Google's change history documentation Google's change status documentation
Before launch, turn off Recommendations → Auto-apply in Google Ads. Otherwise Google can change bids and keywords while the AI agent is measuring its own change.
The exact times below come from bots/hermes/jobs.sh and use America/Chicago from its configuration.
| Job | When | Model? |
|---|---|---|
| Alarm | It checks hourly at minute 07. | A script starts a model pass only when a limit or job check requires it. |
| Sprint | It checks hourly at minute 27. | A script starts a model pass only when a sprint is due. |
| Slack posting | It runs every ten minutes. | It uses no model. |
| Conversion upload | It runs hourly at minute 17. | It uses no model. |
| Weekly sheet | It refreshes every four hours at minute 40. | It uses no model. |
| Week close | It runs Monday at 08:40. | It uses no model. |
The Monday week close rebuilds the previous full week and writes the scoreboard. The goal sprint's next Monday pass writes the weekly report from those numbers. If your account uses another time zone, change it consistently in goal.yaml and the bot configuration, then in the schedule and LOOP_TZ.
On your own computer, run the passes from an open Claude Code session with /loop 60m Follow AGENTS.md, section "One pass". A /loop task runs only while Claude Code is open and idle, and it expires after seven days, so create it again then. A Claude Code desktop scheduled task with the same prompt every hour runs only while the app is open and the computer is awake. That pass covers the watch and the sprints only, and it posts nothing to Slack. Schedule the other jobs as cron lines that enter the repository root, activate ../venv and load loop.env: LOOP_HOME=. SPRINT_REPO_DIR=. python scripts/sprint_gh.py post every ten minutes, which posts the sprint cards and the DECISION and ALARM files that the alarm pass leaves in slack-outbox/; python scripts/upload_conversions.py --days 3 >> state/conv-upload.log 2>&1 every hour; python scripts/week_sheet.py every four hours; and on Monday at 08:40 python scripts/week_sheet.py <monday> <sunday>, then python scripts/scoreboard.py, a commit and a push. The posting script reads SLACK_BOT_TOKEN and SLACK_CHANNEL from loop.env. The token is the xoxb- bot token of a Slack app with the chat:write scope; invite the app to the channel with /invite, because Slack does not add it on its own. With LOOP_HOME=. the script keeps sprint-posted.json and slack-outbox/ in the repository folder, so add both to .gitignore before the first pass commits with git add -A. Move to the Hermes bot or the OpenClaw agent when the loop must run while your computer is off.
A model pass every few hours that only looks at the account changes little and measures nothing; work comes as sprints, and a script should wake the model when there is work to do. The OpenClaw installation needs the optional condition scripts described next to achieve the same behavior on quiet hours.
The Hermes bot: every file and the install commands
Use the Hermes bot when you want a dedicated process on a server that stays on. Its complete file tree is shown below, with paths relative to bots/hermes/.
| File | What it does |
|---|---|
SOUL.md | It sets the voice. |
hermes.md | It loads the operating rules and pass procedures. |
config.yaml.template | It configures the model and gateway behavior. |
env.example | It names the credentials for the two private environment files. |
hermes-ads.service | It runs the gateway as a server service. |
install.sh | It installs the configuration and scripts. |
jobs.sh | It creates the six scheduled jobs. |
scripts/loop.sh | It enters the repository and loads the keys and Python environment. |
scripts/monitor.sh | It checks account limits and the Hermes bot's job health before an alarm pass. |
scripts/sprint-gate.sh | It checks whether a sprint needs a pass. |
scripts/gh-issue.sh | It exposes the issue commands to the Hermes bot. |
scripts/sprint-post.sh | It runs the only scheduled posting route into Slack. |
scripts/conv-upload.sh | It uploads conversions and saves the log. |
scripts/week-sheet.sh | It refreshes the weekly table. |
scripts/week-close.sh | It closes the week and commits the scoreboard. |
The installer also copies scripts/sprint_gh.py from the repository root; it handles issue synchronization, due work and channel posting, and the OpenClaw agent runs the same file.
The full voice file is bots/hermes/SOUL.md.
# SOUL
You are the Google Ads loop of Northstar Dispatch: a quiet, exact growth operator.
- Numbers first: SQL, $ per SQL, what changed. Then the one thing that needs a human.
- English, plain words, no filler, no emoji, no exclamation marks.
- Never overstate. "1 SQL this week, $240 per SQL" — not "great progress".
- When you do not know, say so and say how you will find out. Never guess out loud.
- One message where one message is enough. A pass with nothing new is one line or silence.
- You own the result, not the activity: a pass is judged by what moved, not by what was checked.
Replace Northstar Dispatch with your company. Keep permission rules in the operating files so a voice edit cannot silently redefine them.
The settings you need in bots/hermes/config.yaml.template:
| Setting in config.yaml | Why |
|---|---|
approvals.mode: "off" and approvals.cron_mode: approve | Scheduled passes have nobody available to press approval buttons, and the earlier approval mode added a model check per command. |
approvals.deny includes git push --force* and git push -f*. | Repository history is the record of the work. |
approvals.deny includes systemctl * hermes-*. | The Hermes bot must not stop or restart itself. |
skills.disabled lists all bundled skills. | Those skills caused tests and citation files to be written for ordinary chat questions. |
slack.require_mention: true and slack.strict_mention: true | People can talk in the channel without waking the Hermes bot. |
terminal.cwd: /root/.hermes-ads | A relative or automatic path can resolve to the user's home, where the gateway misses the rules file. |
platforms.slack.gateway_restart_notification: false | Restart notices must not appear in the channel. |
display.busy_input_mode: steer | A new message joins the current run without discarding its work. |
display.tool_progress: "off" and display.interim_assistant_messages: false | A run produces one final message instead of a stream of tool notes. |
The files keep the model the Hermes bot ran on, openai/gpt-6.1-sol through OpenRouter; the OpenClaw files keep the model of that agent, so the two differ. Any strong model works. Change the model in both config.yaml.template and jobs.sh if you choose another one.
Create the Slack app after Hermes itself is installed (the first command below) and before you fill the keys. Run hermes slack manifest --agent-view --write, then at api.slack.com/apps choose Create New App → From an app manifest and paste the file it wrote; the manifest sets the scopes, events and Socket Mode. Install the app to your workspace and copy the xoxb- Bot User OAuth Token as SLACK_BOT_TOKEN. Under Settings → Basic Information → App-Level Tokens, create a token with the connections:write scope and copy the xapp- value as SLACK_APP_TOKEN. After the gateway starts, invite the bot to the channel with /invite @<your app name>; Slack does not add it to channels on its own.
Before starting, fill /root/.hermes-ads/.env with OPENROUTER_API_KEY, SLACK_BOT_TOKEN and SLACK_APP_TOKEN. Set SLACK_HOME_CHANNEL to the channel identifier, then fill /root/.hermes-ads/loop.env from loop.env.example (see The repository); restrict both files with chmod 600. The posting script reads SLACK_BOT_TOKEN and the channel identifier from these two files itself.
The installation sequence in bots/README.md runs bots/hermes/install.sh and bots/hermes/jobs.sh.
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash # Hermes itself
git clone <your repo> /root/.hermes-ads/repo # with a deploy key that can push
# put your keys into /root/.hermes-ads/.env and /root/.hermes-ads/loop.env (see bots/hermes/env.example)
bash /root/.hermes-ads/repo/bots/hermes/install.sh --start
bash /root/.hermes-ads/repo/bots/hermes/jobs.sh
Replace <your repo> with your private repository address and use its deploy key. If Hermes is installed elsewhere, update the executable path in hermes-ads.service before starting it.
The operating-file links are installed by bots/hermes/install.sh.
# identity and rules come straight from the repo
ln -sfn "$SRC/SOUL.md" "$HH/SOUL.md" # identity and voice only
ln -sfn "$SRC/hermes.md" "$HH/.hermes.md" # operating rules: the project context file, first match wins
ln -sfn "$SRC/hermes.md" "$HH/AGENTS.md" # cron jobs with --workdir load AGENTS.md from the home
The installer also copies job scripts into /root/.hermes-ads/scripts, because Hermes requires scheduled scripts to resolve inside that folder. It creates the Python environment and installs the server service, which must stay running for the schedule to tick.
The six job definitions live in bots/hermes/jobs.sh.
HH=/root/.hermes-ads
export HERMES_HOME=$HH
H=/root/.hermes/hermes-agent/venv/bin/hermes
# Any strong model works; the real bot pinned this one through OpenRouter. Change both words here and in config.yaml.template.
PIN=(--model "${LOOP_MODEL:-openai/gpt-6.1-sol}" --provider "${LOOP_PROVIDER:-openrouter}")
# Options go before the schedule: argparse drops a prompt that follows options placed after the schedule.
have() { $H cron list 2>/dev/null | grep -qw -- "$1"; }
have alarm || $H cron create --name alarm --script monitor.sh --workdir "$HH" --deliver local "${PIN[@]}" "7 * * * *" \
"Alarm pass of the Google Ads loop. The hourly watch found the alarms above (details: repo/state/alarm.json). Follow repo/PROCESS.md, section 'Alarm'. Fix what is within your rights; what needs a human becomes a DECISION post. If an alarm touches a campaign of an active sprint, add a line to that sprint's next check-in. End with the journal line, commit and push. Your final answer is not posted anywhere. Only if a person must act - a limit you could not fix, or a decision only a human makes - write the post to a new file /root/.hermes-ads/slack-outbox/<YYYYMMDD-HHMM>-alarm.md in the format of hermes.md, section Slack; a script posts it. If you fixed everything, write no file: the journal line is the record."
have sprint || $H cron create --name sprint --script sprint-gate.sh --workdir "$HH" --deliver local "${PIN[@]}" "27 * * * *" \
"Sprint pass of the Google Ads loop. The sprint gate above lists what is due on the sprint issues. Follow repo/SPRINTS.md, section 'What the bot does', for each item (accept, check-in, daily, weekly, close). Read and write issues only with bash /root/.hermes-ads/scripts/gh-issue.sh. End with one journal line per sprint touched, commit and push. Everything people must see goes into the issue as a comment (a DECISION too, as a decision comment): a script posts every new bot comment to Slack. Your final answer is not posted anywhere: end with one line for the log."
have sprint-post || $H cron create --name sprint-post --no-agent --script sprint-post.sh --deliver local "*/10 * * * *"
have conv-upload || $H cron create --name conv-upload --no-agent --script conv-upload.sh --deliver local "17 * * * *"
have week-sheet || $H cron create --name week-sheet --no-agent --script week-sheet.sh --deliver local "40 */4 * * *"
have week-close || $H cron create --name week-close --no-agent --script week-close.sh --deliver local "40 8 * * 1"
$H cron list
Run HERMES_HOME=/root/.hermes-ads hermes cron list to check this bot's schedule. Confirm that all six jobs deliver locally and that the four script jobs use --no-agent.
The business permissions still come from rules/agent-rules.md: turning off runtime approval prompts does not authorize a budget raise. Read /var/log/hermes-ads/agent.err if the gateway starts but cannot run a job, and check that the absolute working directory contains the installed rules links.
The same AI agent on OpenClaw
Use the OpenClaw agent when you already operate an OpenClaw gateway. It gets its own workspace and its own Slack app; the account rules and scripts stay in the same repository.
The complete file tree under bots/openclaw/ has seven files.
| File | Where it goes and what it does |
|---|---|
AGENTS.md | It goes in the workspace root and defines operating rules; its ## Tools section holds local service notes and credential names. |
SOUL.md | It goes in the workspace root and defines the voice. |
IDENTITY.md | It goes in the workspace root and defines the identity. |
USER.md | It goes in the workspace root and records the owner's dated preferences. |
JOBS.md | It stays inside repo/bots/openclaw/ as the procedure each scheduled job reads. |
openclaw.agent.json5 | It supplies the agent and Slack configuration patch. |
README.md | It contains the installation procedure and all six job commands. |
Install from bots/openclaw/README.md in this order.
- Stop the gateway with
openclaw gateway stop, then create the agent withopenclaw agents add ads --workspace /data/.openclaw/workspace-ads --agent-dir /data/.openclaw/agents/ads/agent --model openai/gpt-5.6-sol --non-interactive. - Clone your private repository into
/data/.openclaw/workspace-ads/repousing a deploy key with write access, and create the workspace'smemory/directory. - Copy the four root workspace files listed above, replace the owner placeholders and remove the generated
BOOTSTRAP.mdif it exists. - Put service credentials in workspace
.env.*files and inloop.envfromloop.env.example, then restrict those files withchmod 600. - Create the Python environment and install its packages with
python3 -m venv /data/.openclaw/workspace-ads/venv && /data/.openclaw/workspace-ads/venv/bin/pip install google-ads gspread google-auth requests python-dotenv pyyaml. - Install the Slack integration with
openclaw plugins install @openclaw/slackif needed, create a Socket Mode app and invite it to the agreed channel. - Put
SLACK_ADS_BOT_TOKENandSLACK_ADS_APP_TOKENin the gateway's~/.openclaw/.env. The posting script reads only the workspace files, so also put the same bot token asSLACK_BOT_TOKENand the channel identifier asSLACK_CHANNELin workspaceloop.env. - Replace the channel identifier in
openclaw.agent.json5, runopenclaw config patch --file ./bots/openclaw/openclaw.agent.json5 --dry-runfrom the repository, then repeat without--dry-runwhen validation passes. - Add the route with
openclaw agents bind --agent ads --bind slack:ads, then runopenclaw gateway start. - Check
openclaw agents list --bindingsandopenclaw channels status --probe, then mention the OpenClaw agent in its channel.
Add the route with agents bind because config patch replaces arrays; a new bindings array could remove existing routes. Configuration reference
The agent entry is part of bots/openclaw/openclaw.agent.json5; the excerpt omits the Slack configuration.
{
"agents": {
// Agents are keyed by id under agents.entries (older gateways kept an array, agents.list; `openclaw doctor --fix` migrates it).
"entries": {
"ads": {
"name": "Ads Loop",
"workspace": "/data/.openclaw/workspace-ads", // the folder with AGENTS.md, SOUL.md, IDENTITY.md, USER.md and repo/
"agentDir": "/data/.openclaw/agents/ads/agent", // never share an agentDir between agents
"model": {
"primary": "openai/gpt-5.6-sol", // any strong model works
"fallbacks": ["openrouter/openai/gpt-5.6-sol"] // used when the primary fails; without `fallbacks` the primary is strict
},
"thinkingDefault": "xhigh" // off | minimal | low | medium | high | xhigh | adaptive | max | ultra
// ...
}
}
},
// ...
}
Replace the workspace and agent directory paths together if you use another location. Keep each agent's directory separate. Each bot's files keep the model its real bot ran on, so the OpenClaw and Hermes files name different models. Any strong model works in either; set it in both places of the bot you run.
Create all six jobs with openclaw automations create using the commands in the README. The alarm and sprint jobs are agent turns that run their gate first and stop with NO_REPLY when nothing is due; Slack posting and conversion upload are shell commands, as are the weekly sheet and week close. Every job uses --no-deliver.
The alarm job is defined in bots/openclaw/README.md.
# 1. Hourly account watch, minute 07. Agent turn, gate first.
openclaw automations create "7 * * * *" \
"Alarm pass of the Google Ads loop. Follow repo/bots/openclaw/JOBS.md, section 'Hourly account watch'. Run its gate first; if the gate says nothing is due, reply NO_REPLY and stop." \
--name ads-alarm --agent ads --tz America/Chicago --session isolated --no-deliver
The shell-command example for Slack posting is also in bots/openclaw/README.md.
# 3. The Slack door, every 10 minutes. Shell command, no model.
openclaw automations create "*/10 * * * *" --name ads-slack-door --agent ads --no-deliver \
--command 'LOOP_HOME=/data/.openclaw/workspace-ads python3 /data/.openclaw/workspace-ads/repo/scripts/sprint_gh.py post'
Use your workspace path in every job command. Confirm all six with openclaw automations list --all, then inspect a test run with openclaw automations runs <jobId>.
The two default agent-turn jobs start a model every hour to run the gate. To skip the model on quiet hours, install the README's optional condition scripts with --trigger-script; those run the gate first and return fire: true only when work is due. Test them with openclaw automations run <jobId> --due, and use them only when the gate finishes within the 30-second condition-script limit. OpenClaw's automation schedules page
Keep credential values out of AGENTS.md and memory files. Slack tokens belong in the gateway environment because a gateway service does not inherit a terminal's exported variables. Rule-file and skill changes go through the owner: the OpenClaw agent proposes the text, and the owner applies it.
Use this comparison from bots/README.md when maintaining either installation.
| Setting | Hermes | OpenClaw |
|---|---|---|
| Rules | hermes.md is linked as .hermes.md and AGENTS.md in the bot home. | Workspace AGENTS.md points to the shared repository rules. |
| Voice | SOUL.md sets it. | SOUL.md sets it, with IDENTITY.md and USER.md supplying identity and preferences. |
| Schedule | jobs.sh creates six Hermes jobs. | The README creates six automation jobs. |
| Slack | scripts/sprint-post.sh posts scheduled messages; jobs deliver locally. | Account ads has its own route; the same posting script sends cards and jobs use --no-deliver. |
| Keys | .env and loop.env live in the bot home. | .env.* and loop.env live in the workspace; Slack tokens also live in the gateway environment. |
| Installation | Run install.sh, then jobs.sh. | Follow the installation sequence in bots/openclaw/README.md. |
The landing site the AI agent rebuilds: Next.js on Vercel
Give every campaign a separate landing page under /lp/<page> and keep those pages out of search results with noindex. The starter sets that in the page metadata and response headers.
- The visitor clicks an ad for one campaign.
- Google opens
/lp/<page>?gclid=…on that campaign's landing page. - The landing page sends analytics events carrying the click identifier.
- The sign-up link carries the click into the application, which saves it with the person.
- The weekly table joins that person's later actions to the original click.
Deploy the starter once, then let copy changes follow the same build process each time. In Vercel, import the repository and set Root Directory to site; keep main as the production branch. Add the variables from site/.env.example for Production and Preview, then connect your landing-site domain.
The local commands live in site/README.md.
cd site
cp .env.example .env.local # fill NEXT_PUBLIC_POSTHOG_KEY; leave the rest for now
npm install
npm run dev # then open /lp/quickbooks-dispatch on port 3000
npm run build # the same build Vercel runs; it checks the JSON files and the types
Set NEXT_PUBLIC_POSTHOG_KEY and the correct ingestion host in .env.local. Set NEXT_PUBLIC_COOKIE_DOMAIN to the shared parent domain if the application and landing page use subdomains of the same domain.
Page copy lives in site/content/landing/<page>.json; this excerpt comes from site/content/landing/hvac-dispatch-software.json.
{
"meta": {
"title": "HVAC Dispatch Software for Small Crews",
"description": "Schedule technicians, send the right person to the right call and keep customers informed. Built for HVAC, plumbing and electrical companies. $49 per user per month. 14-day free trial."
},
"badge": "Dispatch software for home-service crews",
"headline": "Put the right technician",
"headlineAccent": "on the right call.",
"subheading": "Northstar Dispatch shows who is free, who is closest and what each job needs. Your office stops calling around. $49 per user per month, 14-day free trial.",
// ...
"cta": {
"text": "Start free for 14 days",
"url": "https://app.northstar-dispatch.example/signup"
},
"secondaryCta": {
"text": "Book a demo",
"url": "https://northstar-dispatch.example/demo"
},
// ...
}
Replace the fictional copy and destination URLs with your own. Every price and trial claim must match your pricing page.
For each copy change, follow this sequence.
- The AI agent writes the experiment ledger entry and creates a branch.
- It edits only the named fields in
content/landing/<page>.jsonand pushes the branch. - Vercel builds a preview; the AI agent opens it and checks the changed text and every button link.
- A person merges the checked branch into
main, which updates production. - The AI agent checks the live page again and records the publication time, then measures from that time.
Vercel creates a preview from each pushed branch and deploys the production branch when it changes. Git deployment documentation If a preview requires a login, enable Protection Bypass for Automation and give the AI agent the secret for the x-vercel-protection-bypass header.
A new campaign page is a copy of an existing JSON file plus one entry in lib/adPages.ts. The build checks that both exist and that the JSON has the required fields. Point the ad at the new page only after production serves it; undo a copy change by reverting its merge commit.
For a split test, add the variantB fields shown in site/README.md to that page's JSON.
"variantB": {
"testId": "cta-text-2026-11",
"ctaText": "Connect QuickBooks free for 14 days"
}
Give each test its own testId and run only one test per page. Preview both halves with ?lp_variant=a and ?lp_variant=b before merging.
useSplitTest.ts assigns the visitor to one half and sets a 90-day cookie. AdLandingTracker.tsx registers the half before it sends ad_landing_viewed, so the first visit already carries lp_variant_<testId>; later events carry it too, and the person gets lp_test_<testId>. Verify that the application keeps the same person after sign-up. Forced preview visits are marked and excluded from results, and the normal decision point is 100 ad visitors per half.
Filter preview traffic out of production reports with deploy_env = production. The cookie requests 90-day persistence, but browser restrictions can shorten it; for long sales cycles, have your developer preserve the assignment and click record with the person on the server.
The real landing site used Sanity. If your copy already lives there, have your developer change loadLanding in lib/landingContent.ts to read the CMS; the supplied starter otherwise reads JSON files.
With CMS publishing access, the AI agent can change copy through the CMS API itself. It first backs up the published document and records its hash, then changes only the named fields using a revision check. It calls the signed revalidate endpoint and checks the live page before declaring the change published; keep the backup for undo.
The signed refresh request lives in site/README.md and calls the endpoint implemented in site/app/api/revalidate/route.ts.
import base64, hashlib, hmac, json, os, time, requests
secret = os.environ["SANITY_REVALIDATE_SECRET"]
body = json.dumps({"_type": "page", "slug": {"current": "quickbooks-dispatch"}}, separators=(",", ":")).encode()
millis = int(time.time() * 1000)
digest = hmac.new(secret.encode(), str(millis).encode() + b"." + body, hashlib.sha256).digest()
signature = f"t={millis},v1=" + base64.urlsafe_b64encode(digest).decode().rstrip("=")
r = requests.post("https://go.your-domain.com/api/revalidate", data=body,
headers={"Content-Type": "application/json", "sanity-webhook-signature": signature}, timeout=60)
r.raise_for_status()
Replace the example hostname and page slug. Store SANITY_REVALIDATE_SECRET in both loop.env and Vercel's environment variables.
Restoring a CMS change means writing back only the backed-up fields, so later edits to other fields survive. The AI agent then repeats the signed refresh and live-page check.
The AI agent changes only content/landing/*.json and, when it adds a page, one entry in lib/adPages.ts. It never changes other website code or tracking, and it never writes prices, trial lengths or guarantees that are absent from the pricing page. Anything beyond that is a separate task for a person.
Google Ads traps the AI agent must know
Keep the mechanisms from LESSONS.md in the AI agent's reading before account changes.
- Several changes at once under Maximize conversions can make the same clicks more expensive, because in a Search campaign this strategy has no working click price ceiling (see below), so change one thing at a time and do not raise its budget while testing.
- Check every explanation against the change dates and the daily results before acting on it.
- An old price in an ad contradicts a newly priced landing page, so update ad texts and sitelinks on the day the site price changes.
- Google does not credit a click made while the account had no conversion action at all, so create the Import from clicks action before the first paid click. Google rejects imports into a just-created action and asks you to try again in six hours, so wait six hours after creating it before the first upload; a click must also be at least six hours old before its conversion is uploaded.
- Switching bidding strategy can mean hours without impressions during learning, so avoid switching merely to fix click price and first inspect the keywords causing the cost.
- One or two expensive clicks can consume a small daily budget, so pause the keywords that bring them, or lower their bids on manual CPC, before asking to increase spend.
- A daily budget is an average and, for most campaigns, can spend up to twice its amount in a day and 30.4 times it in a month, so put the overspend alarm below twice the budget. Google's daily budget guidance
- Broad-match brand keywords can buy other companies' searches, so use phrase match for the brand campaign and turn off campaign-level broad match.
- Sitelinks with their own UTM tags overwrite the campaign's tags, so keep tags in the campaign's final URL suffix and recover keywords from
click_view. - An expensive click can become a valuable SQL, so judge keywords by outcome, not by click price. Contain overspending by pausing or narrowing the keywords that bring expensive clicks, or with per-keyword bids on manual CPC, not with a strategy bid limit. Keep the
expensive_clicklimit inmonitors/rules.yamlas an alarm, not as a cap. - A GA4 conversion can be credited to a later visit from another source, such as a link in a tool the user connects to your product, so send the outcome by the stored
gclid. - Earlier account history can reflect different campaigns and tracking, so use data collected since the AI agent started unless you separately reconcile the historical benchmark.
- Invalid clicks and duplicate people can inflate the visitor table, so exclude staff and test traffic and verify totals against a second source.
- Google reports spend in the account's billing currency, so keep the dollar settings in
goal.yamlandmonitors/rules.yamlconsistent with this dollar-account template.
Do not count on a click price ceiling under Maximize conversions in a Search campaign. Its field, cpc_bid_ceiling_micros, can be set only on a portfolio strategy, and Google's strategy reference adds that for Search campaigns bid limits “are not supported and are disregarded by the bidding system.” Every campaign in this guide is a Search campaign, so hold click prices through keywords: pause or narrow the ones that bring expensive clicks, or bid per keyword with manual CPC.
Launch checklist
This order is adapted from docs/launch-checklist.md, with the landing page and the goal calculation checked before the AI agent makes its first change.
| Step | Done when |
|---|---|
| 1. Define the goal and owner. | goal.yaml contains your campaigns, the SQL definition and the person who gives an explicit “yes” (owner), and python scripts/selftest.py passes. |
| 2. Connect account access. | The Cloud project has Explorer access or higher, read-only queries in RUNBOOK.md return your campaigns, the service account appears in account access settings, and credential files are excluded from git. |
| 3. Deploy the landing page. | Production serves the campaign's page with the correct button links and a noindex directive. |
| 4. Verify click persistence. | A test click appears on the landing event and the sign-up record, and campaign UTM tags exist only in the final URL suffix. |
| 5. Finish the weekly table. | A real person's row shows the keyword and CRM result, while staff and landing page checker traffic are excluded from the decision counts. |
| 6. Verify the goal calculation. | A delayed SQL is counted exactly once under its original click period, and scripts/scoreboard.py writes the checked result into scoreboard/SCOREBOARD.md. |
| 7. Start conversion uploads. | The import action has a 90-day window, validation succeeds, and the upload runs every hour on a schedule: the cron line from The watch without a model until the bot's conv-upload job takes over in step 10. Its log shows successful uploads whose request status shows acceptance. |
| 8. Prepare bidding and disable automatic edits. | The import action is past its first 14 days, daily uploads have run for one or two conversion cycles before the chosen action becomes primary, and Google Ads shows auto-apply recommendations switched off. |
| 9. Test the watch. | A normal check requests no model pass; a temporary lower limit produces an alarm, after which the original limit is restored. |
| 10. Install the bot and schedule. | All six jobs appear in the runtime's job list with local delivery or --no-deliver, and a channel mention receives a reply. |
| 11. Start the first sprint. | The issue has an acceptance comment with Point A in numbers, and the experiment ledger entry exists before the first account or page change. |
| 12. Verify the reports. | The first sprint card appears in Slack, and the Monday job writes a dated scoreboard that matches the checked weekly table. |