SwitchSignal OSS Local Kit

SwitchSignal OSS is a local-first toolkit for finding competitor-triggered migration moments and turning them into evidence-bound campaign packs. It is for B2B SaaS growth agencies, founder-led SaaS teams, product marketers, and developers who want to inspect or extend the core intelligence workflow without using the hosted SwitchSignal service.

This repository is intentionally separate from the hosted MCP connector:

• OSS Local Kit: runs on your machine, stores data locally, needs no SwitchSignal account, and can use deterministic generation, OpenRouter, Ollama, LM Studio, or any OpenAI-compatible model.
• Hosted MCP Connector: connects external agents to the hosted SwitchSignal service, requires a SwitchSignal account and API key, and enforces hosted plan entitlements, metering, rate limits, and audit logs.

Hosted connector repo: cliwant/switchsignal-mcp

What This Solves

Generic AI can write campaign ideas, but it does not bring a bounded evidence model, category coverage rules, source-boundary guardrails, or repeatable local workflows. This kit packages the non-secret, public-facing core:

• category evidence audits
• before/after migration-moment signals
• capture-plan worklists
• claim-boundary and cannot-claim guardrails
• client-ready campaign pack generation
• local workspace persistence

Five-Minute Quickstart

git clone https://github.com/cliwant/switchsignal-oss.git
cd switchsignal-oss
npm install
npm run demo
npm run analyze -- --category email-marketing --competitor MailerLite
npm run pack -- --fixture examples/signals/mailerlite-free-tier.json --provider deterministic
npm run report -- --fixture examples/signals/mailerlite-free-tier.json --provider deterministic

No hosted API key is required. Commands write local state to .switchsignal/workspace.json, which is ignored by git.

Want to inspect the output before installing? Read the sample client memo at examples/outputs/mailerlite-client-memo.md.

Optional LLM Providers

Deterministic generation is the default so the kit works offline after install. To use an external or local LLM, copy .env.example to .env and set one provider:

SWITCHSIGNAL_LLM_PROVIDER=openrouter
OPENROUTER_API_KEY=...
OPENROUTER_MODEL=anthropic/claude-sonnet-4.5

For Ollama:

SWITCHSIGNAL_LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434/v1
OLLAMA_MODEL=llama3.1

For LM Studio or another OpenAI-compatible server:

SWITCHSIGNAL_LLM_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_BASE_URL=http://localhost:1234/v1
OPENAI_COMPATIBLE_API_KEY=local
OPENAI_COMPATIBLE_MODEL=local-model

Commands

npm run demo
npm run audit
npm run analyze -- --category forms --competitor Typeform
npm run capture-plan -- --category crm --limit 5
npm run pack -- --fixture examples/signals/mailerlite-free-tier.json --provider deterministic
npm run report -- --fixture examples/signals/mailerlite-free-tier.json --provider deterministic
npm run test
npm run type-check
npm run build
npm run smoke

Output Quality

Every generated signal or pack should preserve:

• evidence
• source boundary
• confidence
• before/after
• affected segment
• business impact
• proof table with claim, evidence, boundary, and verification step
• client delivery decision with reason to act now and reason to wait
• execution checklist that an agency can assign immediately
• quality score for specificity, evidence quality, actionability, business relevance, trustworthiness, and repeat usage value
• urgency or score
• recommended next action
• cannot-claim guardrails
• outcome feedback path

If a source is only current-state or third-party reported, the kit labels it as such and blocks unsupported dated-change claims.

npm run report prints the client memo format used for local adoption checks. It is designed to be pasted into a client note after source archiving, not treated as a generic AI summary.

The checked-in sample at examples/outputs/mailerlite-client-memo.md shows the proof table, client delivery decision, quality score, and execution checklist in the format an agency can review before running the CLI.

Commercial Boundary

This open-source kit is not the hosted SwitchSignal product. It does not include hosted accounts, billing, tenant workspaces, production snapshots, alerting, API keys, operator console, private customer data, or hosted MCP authorization. See docs/security-boundary.md for the public/private split.

MCP Boundary

This repo does not expose hosted service MCP tools. To let Claude, Codex, Gemini, or other agents call the hosted SwitchSignal service, use cliwant/switchsignal-mcp. Hosted MCP calls require a SwitchSignal account and are subject to service-side entitlement, metering, rate limit, and audit logging.

Documentation

• Architecture
• LLM Providers
• Security Boundary
• Contributing
• Security Policy

License

MIT.