Quick Viral Notes

Your Substack Notes, run from Claude Code

Paste one prompt into Claude Code. It installs the Quick Viral Notes plugin, signs you in, and checks everything works. Then write, schedule and track your notes by asking.

Paste into any Claude Code session (terminal or desktop app)

/goal Read quickviralnotes.xyz/claude to install and use the Quick Viral Notes plugin

Claude opens a browser window for you to sign in to Quick Viral Notes. Everything else runs on its own. /goal keeps it working until setup is verified; the prompt works without it too.

What happens

  1. Claude installs the pluginfrom the Quick Viral Notes marketplace on GitHub. Nothing to download by hand.
  2. You sign in oncein the browser window it opens. No account yet? Start a 7-day free trial on the same page.
  3. Claude checks the connectionand tells you it worked, or exactly which step didn't.
  4. Start a new sessionso the Quick Viral Notes tools load, and ask for what you need.

Then ask for things like

Before you start

Prefer to do it yourself?

Install by hand

Run these in a terminal, then start Claude Code and use /mcp to sign in to plugin:qvn:qvn.

claude plugin marketplace add https://github.com/quickviralnotes/agent-plugin.git#main
claude plugin install qvn@quickviralnotes
Read the guide your AI follows
Quick Viral Notes plugin for Claude Code: install guide

This plain text version is returned because this request does not look like a browser page navigation.
Browser page: https://quickviralnotes.xyz/claude

This guide installs the Quick Viral Notes (QVN) plugin into Claude Code from QVN's public marketplace, signs the user in, and checks that it works. The plugin connects Claude to the user's Substack through QVN's hosted MCP server (https://mcp.quickviralnotes.xyz) and adds skills for writing, scheduling and analyzing Substack Notes.

## Agent execution contract

If you are an agent reading this for a user: read this whole guide before running anything, then run the commands yourself. Do not only describe them. Setup is one continuous task. Do not stop after install, after login, or after verification: it ends only when you have printed one of the reports in "Finish". A plugin that is installed but not signed in is a failure state, not a partial success. A browser sign-in page or an OS prompt is something to wait for, not the end of the task.

Required order:
1. Check what is already there.
2. Install.
3. Sign in.
4. Verify.
5. Finish: tell the user what QVN can do, hand off to a new session, print the report.

## 1. Check what is already there

```text
claude --version
claude plugin list
claude mcp get plugin:qvn:qvn
```

- If `claude` is not found, see "Claude Code is missing or too old" below.
- If `qvn@quickviralnotes` is listed as enabled and `claude mcp get plugin:qvn:qvn` does not say it needs authentication, QVN is already installed and signed in. Skip to step 4.
- If it is installed but needs authentication, skip to step 3.

## 2. Install

Run these in order:

```text
claude plugin marketplace add https://github.com/quickviralnotes/agent-plugin.git#main
claude plugin install qvn@quickviralnotes
```

The marketplace repository is small; each command should finish within a minute. Do not start a new conversation yet: this session still has to sign in and verify.

Some users already connected QVN by hand under a different name, for example `substack-notes` or `substack-notes-mcp`. Check with `claude mcp list`. If a server there points at `https://mcp.quickviralnotes.xyz` and is not `plugin:qvn:qvn`, tell the user they now have two copies of the same tools and offer to remove the hand-added one with `claude mcp remove <name>`. Only remove it if they agree. Never remove `plugin:qvn:qvn`.

## 3. Sign in

Claude Code's login command needs a terminal, so run it through the plugin's helper script, in the background, with its output going to a log:

```text
sh "$(claude plugin list --json 2>/dev/null | python3 -c 'import json,sys; print(next(p["installPath"] for p in json.load(sys.stdin) if p["id"].startswith("qvn@")))')/skills/qvn-basics/login-qvn.sh" > /tmp/qvn-login.log 2>&1 &
```

If that one-liner fails to find the install path, run the login directly under a pseudo-terminal:

```text
python3 -c 'import pty,sys; pty.spawn(sys.argv[1:])' claude mcp login plugin:qvn:qvn > /tmp/qvn-login.log 2>&1 &
```

Then read `/tmp/qvn-login.log` every few seconds. A browser window opens on the Quick Viral Notes sign-in page. Tell the user: "A browser window is open for Quick Viral Notes. Sign in there (or create a free-trial account), then approve access." Keep polling while they do it; allow up to 5 minutes.

The only success signal is the line `Authenticated with "plugin:qvn:qvn"` in the log. "Connected" on its own does not count.

If the user has no account, they can create one on that sign-in page or at https://quickviralnotes.xyz/signup (7-day free trial). Signing up by email sends a confirmation link; after confirming, return to the sign-in page.

## 4. Verify

```text
claude plugin list
claude mcp get plugin:qvn:qvn
```

Expected: `qvn@quickviralnotes` listed as enabled, and `plugin:qvn:qvn` at `https://mcp.quickviralnotes.xyz` shown as connected, not "Needs authentication". If it still needs authentication, go back to step 3 once. If it fails again, finish with report (B).

## 5. Finish

The QVN tools load only when a session starts, so this installation session cannot use them. Do not try to call QVN tools here.

Tell the user, in their language, in two or three sentences: QVN is connected; in a new session they can ask Claude to write Substack Notes from their ideas or articles, post or schedule them on Substack, and show how their notes, posts and subscribers are doing. Mention that posting, scheduling and stats also need the Quick Viral Notes Chrome extension to sync their Substack login (https://quickviralnotes.xyz/connect), if they haven't installed it.

Then tell them to start a new session (a new conversation, or `/clear`) and try a request such as "Show me how my recent Substack notes are doing" or "Write three Substack notes from this article: <link>".

Print exactly one report as the last thing in your reply:

(A) Installed and signed in. `qvn@quickviralnotes` is enabled and `plugin:qvn:qvn` is authenticated. Start a new session to use it.

(B) Not finished. Say which step failed (install, sign-in, or verify), the exact command, and the exact error. Do not describe QVN as installed.

Do not say QVN is installed or ready before printing (A).

## Failure-mode recovery

Diagnose the matching symptom, fix it, and resume at the step that failed.

### Claude Code is missing or too old

Signing in needs Claude Code 2.1.210 or newer (`claude mcp login` must exist):

```text
claude --version
claude mcp login --help
```

If `claude` isn't found, check `command -v claude` and `~/.local/bin/claude` before concluding it's missing; the desktop app alone doesn't always put the CLI on the PATH. If it is too old, run `claude update` and check again. Only if no CLI exists at all, ask the user before installing it with Anthropic's installer (`curl -fsSL https://claude.ai/install.sh | bash` on macOS or Linux).

### Marketplace add fails

Timeouts, TLS or DNS errors, and `fatal: early EOF` usually mean a network problem, not a bad repository. Retry once. If the user has a proxy, retry with their actual `HTTPS_PROXY` set. Do not run two marketplace-add commands at the same time.

If it says a marketplace named `quickviralnotes` already exists, run `claude plugin marketplace update quickviralnotes` instead, then continue with `claude plugin install qvn@quickviralnotes`.

### Login says stdin is not a terminal

Use the `python3 -c 'import pty ...'` form from step 3.

### Sign-in page shows an error, or the log never says Authenticated

Ask the user what the browser shows. If the browser never opened, look in `/tmp/qvn-login.log` for an `https://quickviralnotes.xyz/oauth/authorize` link and give it to the user to open. If sign-in succeeded in the browser but the log shows a callback error, re-run step 3 once. The user can also sign in from inside Claude Code: `/mcp`, select `plugin:qvn:qvn`, then Authenticate.

## Updating

```text
claude plugin marketplace update quickviralnotes
claude plugin update qvn@quickviralnotes
```

Then start a new session.

Using Claude or ChatGPT in the browser instead? Connect Quick Viral Notes as a connector. Questions: contact us.