Weftens

Where did the ad money go, and what should change? Give Weftens an exported report from Google Ads, Meta, Amazon, or an SEO crawl, and it gives you back a ranked change sheet — each recommendation with where it applies, why it's proposed, what it's worth, and what could go wrong if you're wrong.

4 proposed changes  |  $604.27 of spend flagged
account: spend $910.00, 208 clicks, 11 conversions, CPA $82.73

1. Bid down or restrict "premium widget wholesale bulk"   $417.27
   where  campaign: Brand / Brand - Exact
   why    CPA $500 vs account $82.73 (6x); $500 for 1 conv
   risk   Converting term — restricting too hard can cut real volume; prefer a bid cut first.

2. Add "free blue widgets" as a negative keyword   $90.00
   where  campaign: Generic / Widgets - Broad
   why    60 clicks, $90 spent, 0 conversions (expected ~3.2 at the 5.3% account rate)
   risk   If the query is actually relevant, you forfeit those impressions.

Proposals only — nothing was sent to your ad account. Apply what you agree with.

That is the actual output of the sample export included in this repo, produced by:

npm i weftens
npx weftens send paid-search audit --input node_modules/weftens/agent-cores/paid-search/test/fixtures/search-terms.csv

Same file in, same change sheet out, every time. The ad and SEO auditors are arithmetic, not a model — nothing is generated, so nothing can be invented, and two runs can be diffed to prove nothing moved. They read a file you already have and never sign in to your ad account. Note the second line of the first recommendation: that keyword converted. "Flagged" means the numbers crossed a threshold, not that the money is guaranteed back — the risk line is there because the call is still yours.

Not technical? You don't have to run this. Send the repo link and your exported report to whoever manages your ads, or paste this to an AI assistant that can use your computer (Claude, ChatGPT/Codex, Gemini): "install weftens and run the paid-search audit on my export."

What's finished, and what isn't

• Finished and deterministic — seven auditors: paid search (Google Ads), paid social (Meta), Amazon PPC, technical SEO, content SEO, supply-path verification, content operations. No model, no key, propose-only.
• Model-backed seats run on an AI CLI you already have and are logged into — your subscription, no API key, nobody is billed through Weftens. They are only as good as the model you point them at. claude and codex are verified; gemini and grok are configured but have never been run.
• Two seats are not in this repo. richy (representation) and pio (prospect research) are clients for separate services that aren't open source. Without those services configured they return sample data that says so in its own output.
• The content pipeline is not in this package. Ten seats are defined in agents/, but the pipeline they run through isn't published — it emitted placeholder output, so shipping it would have implied a capability that doesn't exist. The content seat says so when you call it.

Free, MIT licensed, no account, no billing.

Install

git clone https://github.com/Weftens/weftens.git
cd weftens
npm install
npm test

That's the whole install. Everything lives in this one repo — the deterministic auditors (agent-cores/) and the agent seat definitions (agents/). A fresh clone runs on its own; there is no second checkout and no external directory. (Verified by cloning to an unrelated path and running the suite there — the earlier version of this claim was false: the end-to-end test resolved agent-cores/ from the repo's parent, so it only passed on the author's machine.)

Node 22+. npm test runs both suites: test:unit (vitest, the router/registry/CLI layer) and test:cores (node --test, the deterministic auditors — they are zero-install by design so a single core can be handed to someone who has nothing but Node).

For the model-backed agents, have a model CLI installed and logged in (e.g. claude) — that's your own subscription, no key. The deterministic ad/SEO auditors need no model at all.

Use it as an SDK

import { weftens, route, invoke, REGISTRY } from "weftens";

// one call — route a request and run the chosen agent:
const { decision, outcome } = await weftens("audit our facebook ads", { inputFile: "meta.csv" });
console.log(decision.agent.name, outcome.result);

// or drive the pieces yourself:
const d = route({ text: "who are the funders for this grant" });
const o = await invoke(d.agent, { text: "..." });

Run

node bin/weftens.js list                      # the agent directory + which have a deterministic core
node bin/weftens.js verify                     # prove the deterministic cores use no model (see below)
node bin/weftens.js --route "<request>"        # dry run: which agent it routes to, and the words it matched
node bin/weftens.js send "<request>"           # route, then run
node bin/weftens.js send <agent> "<request>"   # address one agent directly
node bin/weftens.js send <agent> --input report.csv          # feed a file to a calculator agent
node bin/weftens.js send <agent> "<...>" --provider gemini   # pick which model runs it

Examples:

# paid media — PROPOSE-ONLY, never touches an account:
node bin/weftens.js send paid-search x --input google-ads-export.csv
node bin/weftens.js send meta-ads    x --input meta-ads-export.csv
node bin/weftens.js send amazon-ppc  x --input amazon-search-terms.csv

# a judgment call, run on your own model:
node bin/weftens.js send hilbert "will this tagline survive being repeated: ..."

Don't take "no model" on trust — run it

Plenty of tools print the word deterministic. It usually means a fixed rubric applied to evidence a language model extracted, which is not reproducible at all. You cannot tell those apart by reading a README, so this one ships the check instead of the claim:

$ weftens verify
  PASS  seo-content    no model, identical  sha256:b5ba1c0177121876  7908B
  PASS  paid-search    no model, identical  sha256:932689f9f625f7d0  3597B
  PASS  amazon-ppc     no model, identical  sha256:a002e1e7f0893494  3308B
  PASS  meta-ads       no model, identical  sha256:fbb4ab62984c32da  3054B
  PASS  supply-verify  no model, identical  sha256:546f728933e2c582  5884B
  PASS  content-ops    no model, identical  sha256:1d33ff35c8fd2481  8927B

not checked:
  --    seo-technical — fetches a live URL — network-dependent by design, so not reproducible

Each core runs twice, inside a sealed process (scripts/no-model.mjs) with both routes to a model removed — the network and subprocess spawning. Spawning is the one that matters: the model-backed seats reach a model by shelling out to your AI CLI, not over HTTP, so sealing the network alone would be a true statement that proved nothing. API keys are stripped from the environment too.

Two independent properties, because neither implies the other:

• no model — it produced its result with no way to reach one.
• identical — the two runs were byte-for-byte the same (SHA-256 of raw stdout, not a parsed comparison, which would forgive an embedded timestamp).

You should get the same hashes. They are produced by arithmetic over the shipped fixtures, on your machine, with nothing to call.

The seal is tested against a negative control in both directions (test/verify.test.js): five probes — fetch, net, https, dns, spawn — all succeed without it and all fail with it, and a deliberately shifting core fails verification while its fixed twin passes. A check that cannot fail is not a check.

What this does not prove: it covers the run in front of you, not code that never executed, and it says nothing about whether the recommendations are any good — only that the same input produced the same output, with no model involved. seo-technical is excluded and says why: it fetches a live URL, so its output legitimately changes when the page does.

What's inside

• Deterministic auditors (no model; run on an exported report; propose changes a human applies): paid-search (Google Ads), meta-ads (Facebook/Instagram), amazon-ppc, seo-technical, seo-content, supply-verify, content-ops.
• Model-backed seats (run on your AI CLI): the evaluation and marketing agents — hilbert, lippmann, agent2060, growth-marketing, social-voice, claims-content, security-writer.
• Content team: the content lead runs the 10-seat media pipeline as one node.
• Richy + PIO: representation and operations agents with their own orchestrator/synthesizer — node bin/weftens.js route request.json, or weftens ask / weftens chat for a conversation.

Routing is deterministic and explainable: a request matches an agent by its declared keywords, and the CLI prints which words matched, so you always see why a request went where it did.

Configuration

• WEFTENS_PROVIDER — which model CLI to use (default claude).
• providers.json (or WEFTENS_PROVIDERS_FILE) — map a provider name to its command, e.g. { "providers": { "gemini": { "cmd": "gemini", "args": ["-p"] } } }.
• WEFTENS_HOME — where agent-cores lives (default: the install root, so a clone is self-contained).
• WEFTENS_CONTENT_DIR — where the content pipeline lives. It is not part of this package; point this at a checkout to enable the content lead.
• WEFTENS_AGENTS_DIR — where the agent seat files live. Defaults to the copies bundled in this repo (agents/), so a fresh clone runs self-contained; override to point at your own set.
• WEFTENS_ROUTE_CACHE — where routing decisions are remembered, so the same question reaches the same seat every time. Defaults to your platform's state directory (%LOCALAPPDATA%\weftens\ on Windows, $XDG_STATE_HOME or ~/.local/state/weftens/ elsewhere) — never inside the package. Set it to off to disable, or run --why to print the path. It is plain JSON; delete it to forget.
• WEFTENS_ORG / WEFTENS_WEBSITE — the organization richy and pio answer about, so you don't have to pass --org on every call.
• WEFTENS_RICHY_URL / WEFTENS_RICHY_KEY, WEFTENS_PIO_URL / WEFTENS_PIO_MEMBER / WEFTENS_PIO_PASSWORD / WEFTENS_PIO_TENANT — point the two specialist seats at running services. Unset, they return self-labelling sample data (see Honest status).

Honest status

• Verified: deterministic routing, all seven auditor cores end-to-end, both specialist legs (Richy/PIO) through the door, and BYOM model-produce via claude. 246 tests pass — 142 unit/CLI (vitest) + 104 core (node --test), confirmed in a fresh clone at an unrelated path, not just in the author's workspace.
• Installing it costs you nothing but this package. weftens has zero runtime dependencies. The Anthropic SDK — needed only by ask and chat — is an optional peer dependency, which is the only kind npm genuinely leaves out. Someone who wants the deterministic auditors installs the auditors, not an API client they will never call. Run weftens ask without it and you get a one-line install instruction, not a stack trace.
• Richy and PIO are interfaces here, not implementations — read this before you install. Two of the seats (richy, representation intelligence; pio, prospect research and grants) are clients for separate services that are not part of this repo and are not open source. What ships here is the seat definition, the wire client, the orchestrator that joins their answers, and fixtures. Point WEFTENS_RICHY_URL/WEFTENS_RICHY_KEY and the WEFTENS_PIO_* group at running services and they work. Without those, they return sample data that labels itself as sample data ("sample": true, and the headline says so) — so you can see the shape of the output, and you can never mistake it for a finding about a real business. Everything else in this repo — all seven deterministic auditors, the router, the CLI, the SDK — runs entirely on what you just cloned. weftens send richy --org "Acme Co" "audit our listings" shows you exactly this.
• A file it cannot read is never reported as clean. Hand an auditor the wrong export and it says so — "could not read this as the report this agent expects… this is NOT a finding that your account is clean" — and exits non-zero. Six of the seven cores are covered by this; content-ops reports item counts with no monetary values, so the generic check cannot distinguish a wrong file from a real inventory. Treat a content-ops run on an unexpected file with suspicion.
• ask and chat are the exception to "no API key". Those two commands drive a conversational orchestrator and need ANTHROPIC_API_KEY. Everything else — all routing, every deterministic auditor, and every model-backed seat via your own CLI — needs no key.
• The router refuses rather than guesses. Generic words alone ("site", "listing", "people") no longer dispatch — a confident wrong route in front of a customer costs more than a reprompt.
• Licensed MIT. Free to use, including commercially.
• Published: npm i weftens installs the real thing (MIT). Verified from the registry by a clean third-party install — npx weftens list prints the registry, and a deterministic core runs a real audit from inside node_modules. (0.0.1 was an empty name-holder; ignore it.)
• Known defect in the published 0.1.5, fixed in source, not yet on the registry. 0.1.5 went out declaring a dependency on weftens@^0.1.4 — the package depended on an older copy of itself, so an install unpacks a second, stale copy underneath it. It resolves and runs, so an install still works; it is dead weight, not a break. The cause was running npm install weftens inside the repo while checking that a third party could install it: the verification step edited the thing it was verifying. test/package-invariants.test.js now asserts against it in both the manifest and the lockfile. The fix ships in 0.1.6; until that is published, what is on npm still has it.
• Two providers verified, not one: claude and codex both produce end-to-end through the user's own subscription (codex confirmed 2026-07-19). gemini and grok remain config-only — the shape is right, but neither CLI is installed here, so neither has been run. A missing or broken provider degrades to a plain note; it never fabricates an answer.
• Dry-run only: the content pipeline produces placeholder output; real content generation is gated on open decisions.
• Propose-only: every ad/SEO core proposes changes and writes nothing to a live account.

Notes

Weftens is the company AND this front door — one thing, not two. Richy and PIO are two of the agent seats behind it, not standalone products under a brand. Architecture and agent-wiring detail: ARCHITECTURE.md.

Invariants that must not break: each agent stays independently runnable; PIO's wire-shape (grantengine_session cookie, x-grantengine-* headers) is frozen; the privacy spine — sanitized exports, human review gates, receipts — is shared across every seat.