Binderclip

Business analytics dashboard for Claude Code.

Run one slash command. Watch SEO audits, competitor intel, finance dashboards,
and content drafts stream into a live UI — no orchestration layer, no heavyweight
backend, just a dumb event relay and a React canvas.

hero.mp4

---

Quick start

git clone https://github.com/misbahsy/binderclip.git
cd binderclip
pnpm install && bash scripts/setup.sh

Then open Claude Code with Sonnet or Haiku (not Opus — see below) and run:

claude --model sonnet        # recommended — best balance of quality/cost
# or
claude --model haiku         # cheapest, fast, fine for most packs

/marketing brainycanvas.com

Events stream to http://localhost:5173 as they complete.

Tip

Don't run packs with Opus. The skills are mechanical work (WebFetch, curl, jq) — Opus burns tokens for no benefit. Use Sonnet (recommended) or Haiku (cheapest). Reserve Opus for editing binderclip's own codebase. When dispatching subagents inside a skill, also pass model: "sonnet" or "haiku".

Slash commands

One-shot analysis (run, finish, dashboard fills in)

Command	What it does
/marketing <url>	SEO audit, GEO score, competitors, AI visibility, citability, crawler access, content ideas
/finance	MRR, billing health, forecast, pricing strategy (uses Stripe key from .env.local)
/sales <url>	Pipeline analysis, cold email sequences, outreach templates, sales enablement
/audience <url>	Personas, segmentation, customer research, free-tool strategy
/funnels <url>	Page CRO, signup flow, pricing page, conversion audit, churn prevention
/run-all <url>	Run all 5 packs end-to-end
/action-plan <pack>	Generate prioritized action items from completed analysis

Individual skills: /marketing-skill audit-site <url>, /finance-skill mrr-check, etc.

Ambient watchers (persistent, stream events as conditions change)

Command	What it does
/watch <type> <target>	Start a Monitor-backed background watcher; Claude reacts as events fire

Watcher types: lighthouse, competitor, uptime, mentions, log, ai-crawler, stripe-churn, stripe-payment-health, stripe-new-signup. See Ambient mode below for the full catalog and usage.

Environment variables

Copy .env.example to .env.local and fill in the keys you need:

PORT=3500                # Default (Paperclip uses 3100)
STRIPE_API_KEY=sk_...    # Required for finance pack; enhances sales/audience/funnels

Optional: OPEN_PAGERANK_API_KEY, BING_WEBMASTER_API_KEY, DATAFORSEO_LOGIN + DATAFORSEO_PASSWORD.

Zero-key mode: the marketing pack runs a full audit with no API keys (uses WebFetch + WebSearch + Playwright).

MCP tools used

Built into Claude Code (no setup): WebFetch, WebSearch, Bash.

Recommended MCP plugins:

• Playwright — strongly recommended. Used for real Lighthouse scores (via pagespeed.web.dev), AI platform searches (Perplexity, Google), and signup flow analysis. Install via Claude Code plugin.
• Stripe MCP (optional) — alternative to raw API key. claude /plugin install stripe@claude-plugins-official.

Pack coverage without keys

Pack	Without keys	With Stripe key
Marketing	Full audit	Same
Finance	Pricing strategy only	MRR, billing, forecast
Sales	Cold-email, outreach, enablement	+ pipeline-check
Audience	Personas, research, free-tool	+ segment-analysis
Funnels	Page/signup/pricing CRO	+ funnel-analysis, churn-prevention

Ambient mode (watchers)

The analytics packs are one-shot: run a command, watch the dashboard fill in, done. The watchers pack is different — it uses Claude Code's built-in Monitor tool to run background pollers that stream events as external conditions change. One watcher starts, then lives in a Claude session all day, interrupting you conversationally whenever something meaningful fires.

Start a watcher with:

/watch <type> <target>

Available watcher types

Nine types, split into generic (useful on any project) and pack-aligned (each naturally maps to a follow-up analytics pack):

Generic

Type	Fires on	Recommended interval
lighthouse <url>	Mobile performance score drops ≥10 pts or below 80	15 min
competitor <url>	Page content hash changes (pricing, feature list, changelog)	60 min
uptime <url>	Non-2xx, timeout, or SSL error on a health endpoint; recovery	1 min
mentions "<brand>"	New Reddit or Hacker News mentions (cursor-based, once per URL)	30 min
log <path> [pattern]	Every log line matching the regex (via tail -F + grep)	real-time

Pack-aligned

Type	Fires on	Follow-up pack	Recommended interval
ai-crawler <url>	robots.txt changes for GPTBot, ClaudeBot, PerplexityBot, etc. (Tier 1/2/3)	/marketing crawlers	6 hr
stripe-churn [threshold]	Subscription cancellations per hour ≥ threshold	/funnels churn-prevention	10 min
stripe-payment-health [t]	Failed charges per hour ≥ threshold (declines, card errors)	/finance billing-audit	10 min
stripe-new-signup	Every new customer.subscription.created event	/sales pipeline-check	5 min

Each pack-aligned watcher knows which analytics pack to suggest when it fires. A Lighthouse drop offers /marketing audit-site, a churn spike offers /funnels churn-prevention, a new signup offers /sales pipeline-check. Claude always asks before running the follow-up — it doesn't auto-chain.

Typical ambient-mode workflow

Dedicate a tmux pane (or a long-lived terminal) to a single Claude Code session running on Haiku:

cd binderclip
bash scripts/start-server.sh &    # server on :3500
cd ui && pnpm dev &                # UI on :5173
claude --model haiku

Inside that session, start one or more watchers:

/watch lighthouse https://brainycanvas.com
/watch stripe-churn 3
/watch stripe-new-signup

Then go do something else. When a watcher fires, Claude interrupts the session with a plain-text narration and (optionally) offers to run a follow-up analytics pack. Stop a watcher with "stop watching lighthouse" — Claude calls TaskStop internally and clears the dashboard card.

All bundled pollers live at packs/watchers/skills/scripts/*.sh and follow the Monitor best practices (grep --line-buffered, || true on every network call, strict rate limits). If you want a new watcher type, drop a script in that folder and add an example section to packs/watchers/skills/watch.md — see Adding your own pack.

Architecture

All slash commands are thin wrappers (10–40 lines each) around a single router skill at .claude/skills/binderclip/SKILL.md. The router is the canonical source of truth for:

• Mode routing (which command maps to which pack)
• The standard per-pack workflow (read agent.md → read pack.json → execute each skill → validate)
• The watchers workflow (Monitor tool invocation, event API, stop/resume)
• The event API conventions and the validation loop
• Pack quick reference with direct paths to every skill file

The pack content itself still lives at packs/<pack>/skills/*.md exactly as before, so non-Claude-Code agents (Codex, opencode, Cline) can still read the skill playbooks directly without going through the Claude Code skill system — see Using outside Claude Code. The router skill is additive: it gives Claude Code users a clean entry point without changing the cross-agent story.

Adding your own pack

1. Create packs/<name>/agent.md — subagent instructions (role, tools, event API, skills list)
2. Create packs/<name>/pack.json — { "id": "<name>", "name": "<Name>", "description": "...", "skills": [...], "pipeline": [...] }
3. Create packs/<name>/skills/<skill>.md — one file per skill. Include ## Input, ## What to do, ## Output Events, and a ## Gotchas section for anything non-obvious.
4. Add .claude/commands/<name>.md as a thin wrapper (see the existing pack commands — ~20 lines each, delegating to the router skill and packs/<pack>/)
5. Update .claude/skills/binderclip/SKILL.md — add a row to the mode-routing table and an entry under ## Pack quick reference listing every skill file one level deep. The router skill is the canonical source of truth for what packs exist and how they run.
6. Skills POST events to http://localhost:3500/api/packs/<name>/events

The UI auto-discovers packs from server events. No UI code changes needed unless you add a new component type, in which case:

• Add schema to src/schemas.ts
• Add renderer to ui/src/catalog/

Adding a new watcher type

Watchers follow a slightly different pattern since they're all one skill (packs/watchers/skills/watch.md) with many worked examples:

1. Write a bundled poll script at packs/watchers/skills/scripts/<type>-poll.sh — follow the quality bar of the existing scripts (set -euo pipefail, closed-set arg validation, grep --line-buffered in pipes, || true on curl, bundled sources of .env.local for API keys)
2. Add a worked example section to packs/watchers/skills/watch.md — trigger rule, stdout format, Claude's reaction on fire, the Monitor tool parameters
3. Update the closed-set type list in three places: packs/watchers/skills/watch.md (Input section), .claude/skills/binderclip/SKILL.md (mode table + discovery menu + watchers pack reference), .claude/commands/watch.md (type list)
4. Update this README — add a row to the watcher types table in Ambient mode

Using outside Claude Code

Binderclip's server is agent-agnostic — the Hono relay accepts POSTs on http://localhost:3500/api/packs/<pack>/events from anything that speaks HTTP. Two common integration patterns:

1. External orchestrator (Paperclip, n8n, Python, etc.)

Any agent framework or script can POST events directly:

curl -X POST http://localhost:3500/api/packs/<pack>/events \
  -H 'Content-Type: application/json' \
  -d '{
    "skill": "<skill-name>",
    "component": "seo_score",
    "props": { "score": 79, "issues": [] },
    "status": "completed"
  }'

Events appear in the UI in real time.

2. Other AI coding agents (Codex, opencode, Cline, etc.)

The skills in packs/*/skills/*.md are markdown instruction files — no Claude-specific SDK, no special runtime. Any agent with Bash + file read + HTTP access can execute them. Skip the Claude Code slash command layer and point the agent at the skill file directly:

# Codex
codex "Run packs/marketing/skills/audit-site.md for https://example.com — POST events to http://localhost:3500/api/packs/marketing/events"

# opencode
opencode "Execute packs/marketing/skills/audit-site.md for https://example.com"

The skill file is the instruction set. Any agent that can follow "curl this URL, parse with jq, POST the result" can run a pack.

Caveats:

• Playwright-dependent skills (Lighthouse audit path, signup-flow-cro) need a headless-browser tool in the agent. Claude Code uses the Playwright MCP plugin; check your agent's browser capabilities or skip those specific skills.
• No slash command auto-discovery outside Claude Code — .claude/commands/*.md files are Claude Code-specific. Invoke skills by file path instead.
• .env.local loading works anywhere — skills use plain source .env.local 2>/dev/null + curl, which is just bash. Stripe / DataForSEO / Open PageRank / Bing Webmaster fallback behavior is identical across agents.

Bottom line: the architecture is dumb event relay + markdown skills + agent-executes-curl. Claude Code is the smoothest experience; anything with a bash tool and HTTP access works.

Tests

pnpm test                    # vitest unit tests
bash test/e2e-smoke.sh       # end-to-end API smoke test

License

MIT