For end users

Installing Pectus

git clone https://github.com/pectusai/pectus.git ~/pectus
cd ~/pectus
claude  # then say: read pectus.md and follow it

The ~ means your user folder (on a Mac, that's Users/yourname). So ~/pectus is a folder called pectus inside your user folder. To install it somewhere else, replace ~/pectus in both lines with the path you want.

Pectus runs on your laptop. The install is driven by Claude Code reading a markdown file (pectus.md). You don’t memorize commands — you paste the file into Claude, and Claude walks you through every step out loud. You confirm each step, paste keys when asked, and watch.

Plan for 60 to 90 minutes. About 90% of that is signing up for and verifying accounts (Supabase, Anthropic, Google Cloud, optionally Vercel and GitHub). The actual setup work between accounts is short, but new-account verification flows, email confirmations, and OAuth dances all add up.

Before you start

You’ll need a few accounts. Only the first two are required to boot Pectus. The rest you can add when you actually need them.

Do Anthropic and Supabase first. Set up your accounts walks all three sections in one page; you can stop after Anthropic + Supabase and come back for Google Cloud later. The install agent expects an Anthropic key and Supabase project URL + access token already in hand when it asks. Pectus boots without any integrations and tells you honestly which surfaces are disabled until you connect one.

You also need:

• A laptop running macOS, Linux, or Windows. (On Windows, you’ll need WSL, which is Microsoft’s Linux compatibility layer. Free, takes about 10 minutes to set up.)
• Claude Code installed: https://claude.com/claude-code
• Node.js 20.19 or newer. (Node.js is what runs Pectus. The 20.19 floor is set by Vite, which the CMS uses internally; older 20.x versions trigger loud install warnings and can fail the dev server in subtle ways. If you don’t have it, Claude installs the right version for you during the first step.)

One thing worth doing on day one even though it’s optional: if you think you’ll ever want Pectus to read LinkedIn ad data, apply for LinkedIn’s Marketing Developer Platform now — approval takes 1 to 3 weeks and the application doesn’t block any other step. You can do it at https://www.linkedin.com/developers.

What this actually costs

Pectus runs on free tiers of almost everything. The realistic monthly cost for a single brand with light to moderate use is around $5 to $20, almost all of it Anthropic API credits.

So for a single user / single brand:

• Day-one minimum: $5 to load Anthropic credits. Everything else is free to register.
• Steady state: usually under $20/mo for moderate use, dominated by what you spend on Claude API calls.
• Pro tiers improve things (more storage, team features, faster API tiers) but nothing about Pectus requires them. The dashboard’s “Refresh insights” button is gated behind a cost-warning so you don’t accidentally rack up credits.

If you’re cost-conscious, watch the Anthropic dashboard during your first week to calibrate. Most users land much closer to $5 than $20 once they see how few API calls a normal week actually uses.

If you already have a website on Vercel + GitHub

Common scenario, dedicated FAQ entry. See I already have a site on Vercel + GitHub. How do I replace it (or add to it) with Pectus? for the two paths (reuse your existing repo vs. new repo with Vercel git-source swap), how to pick the site shape during the Content Insights activation wizard, and how to bring your existing posts across through the Articles → Import flow.

The install in 3 short moves

Once your accounts are ready:

1. Download pectus.md (the button at the top of this page, or right-click the link → Save link as). From the terminal: curl -O https://pectus.ai/pectus.md.
2. Open Claude Code in any empty folder. Whichever folder you open Claude Code in is where Pectus will be installed. A folder on your desktop is fine.
3. Paste the entire contents of pectus.md as your first message to Claude.

Claude reads the file and walks through 13 ordered steps. Below is what those steps actually do, in plain language, so you know what’s happening.

What Claude does, step by step

1. Checks your prerequisites. Confirms node, npm, and git are on your machine. If any are missing, Claude installs them via Homebrew (on macOS) or walks you through your platform’s installer.

2. Clones the Pectus code. Default location is ~/pectus. Claude asks before cloning so you can pick a different path.

3. Installs dependencies. Runs npm install from inside ~/pectus. This pulls down the npm packages Pectus uses — typically under 90 seconds.

4. Brand setup. Claude opens with a reassurance: getting a brand description, system, and prompt that really sings takes a few days, and you’ll have tools for it the whole way (tone of voice, camera settings, full design system). For now, the goal is just a quick start. Claude asks you to describe your brand in your own words: the brand name, what you do, the voice you write in, your main colors, your website URL. Two or three sentences is plenty. Claude turns the description into brand/brand.json, summarizes back what it captured, and lets you correct anything that’s off. About 2 to 5 minutes.

You can polish every field from the Brand page in Pectus once it’s running. If you want a richer design system later (full color palette, typography, component styles), open the Brand page after install and import a Claude Design URL there. Don’t import a design at install time; the install flow stays focused.

5. Asks for your API keys. Claude prompts you for the values from the four required services (Supabase access token, Anthropic API key, Google Cloud OAuth client ID + secret) and writes them to .env.local. You’ll paste each one as Claude asks.

6. Sets up the database. You created the Supabase project yourself in step 5; now Claude prepares the schema. It writes a timestamped SQL file in your install folder (each attempt gets a unique name like run-2026-05-03T15-04-22Z.sql, so retries don’t overwrite earlier attempts and you have an audit trail). You open the Supabase SQL editor, clear any existing content, paste the file’s contents, and click Run. Then you create your admin user from the Authentication → Users page in Supabase. Save the email and password in your password manager; you’ll use them in step 9. Pectus never touches your account directly; you stay in control of the project.

7. Connects Google. Runs npx pectus connect google. You’ll upload a small JSON file from your Google Cloud account that gives Pectus permission to read your data. (The file is called a “service account key”, and Pectus walks you through creating it.) Then you pick which Search Console site and which Google Analytics 4 property Pectus should look at. Pectus tests both connections before finishing.

8. Vercel + GitHub (optional). Runs npx pectus connect vercel and npx pectus connect github if you signed up for them. Vercel is for deploying your public hub later. GitHub is for the publish flow that commits pages to a content-insights repo. Both are skippable today and can be added any time later from ~/pectus.

9. Starts Pectus. Runs npm run dev, which boots Pectus’s admin (the part you actually use) at http://localhost:3000 in your browser. You sign in with the email and password from step 6. You’ll land on the Brands page; you create your first brand and project next.

10. Applies the database baseline. Pectus surfaces an in-CMS overlay at /settings/updates listing the squashed v0.4 migration (0001_pectus_v04.sql) and any follow-ups (0002_content_insights.sql, 0003_project_files.sql, 0004_brand_font_sizes.sql). For a first-time install, paste 0001_pectus_v04.sql once in the Supabase SQL editor; everything after that applies via the Supabase Management API on your behalf, or copy-paste fallback if the access token isn’t set.

11. Creates your first brand and project. From the Brands page click Add brand (fills in a slug and creates brands/<slug>/brand.json on disk), then open the brand and click Add project. A project is one market or audience segment scoped to that brand. If you sell in one country, one project is enough. The wizard asks:

• A name for this market (e.g. “United Kingdom”).
• A short code (e.g. uk). Lowercase letters, digits, and hyphens only; this is what shows up in URLs.
• A locale (e.g. en-GB, en-US, sv-SE). Standard format Google and most platforms use.
• Seed keywords: 5 to 10 short phrases the project plans content around when there’s no traffic data yet. Optional; you can add or change them later under the project’s Seed Keywords app.

That’s it. Project creation is intentionally minimal. The site-shape and publish-repo questions live inside the Content Insights activation wizard (next step), so the project is ready even if you haven’t decided yet how you want to publish.

12. Activates the Content Insights for this project. Open /brands/<slug>/projects/<code>/apps in your browser. Pectus is a connector framework with a UI; Content Insights is one app among peers (GSC, GA4, seed-keywords) and ships pre-installed but inactive. Click the content-insights card. You land on the Content Insights settings page. Fill in:

• What kind of site is this? Pick one:
  • Brand new site: Pectus runs the whole site for you. Pick this for any site Pectus owns at the root, including ones replacing an existing site.
  • Existing site: Pectus only adds a section (like /insights/ or /blog/) to a site you already have. Pick this if your site is already live and you just want to add a content section to it.
• Mount slug. Where Pectus pages live in the URL. / for a brand-new site, /insights/ or /blog/ for an existing site.
• Where will Pectus publish pages? A GitHub repo, written as owner/name (e.g. acme-corp/acme-blog). Optional; fill it in when you’re ready to publish.

Click Save and activate Content Insights. After activation, the project sidebar gains a Content Insights group with Pages, Articles, Insights, Sources, Files, Site URL, Redirects, and Review policy. Inactive apps don’t add nav clutter, and surfaces that need data (Publish, GA4 dashboards, GSC keyword sync) gate themselves honestly with an inline CTA card linking to the fix; article and page authoring are never gated.

13. Runs your first analysis. From the project’s Content Insights → Insights, click Run analysis. Stage 1 calls Opus to interpret your data snapshot (GA4 / Search Console / keywords / articles); Stage 2 ranks ideas with Opus. Each idea card has a one-click Draft that opens the article editor with AI Write pre-filled — Sonnet 4.6 produces a draft, you edit, then move it through draft → brand_review → market_lead_review → published. The CLI equivalent is npx pectus analyze --project <code> --skill weekly-analysis if you’d rather drive it from the terminal.

14. Done. Claude tells you where everything lives, how to start Pectus next time (npm run dev from ~/pectus), and how to keep it up to date — pull from upstream, then apply any pending migrations at /settings/updates.

After install

Things you can do now that Pectus is running:

• Edit your brand any time. Go to /brands/<slug>/profile. Every field has a tooltip explaining what it does. Click “Import from Claude Design” if you want to swap in a fresh design at any point — you’ll see a preview with diff indicators before you Apply. The same page holds your brand example photos and API keys for image generation (Google AI for Imagen 4 / Gemini 3 Pro, fal.ai for Flux Pro, Replicate for Flux Dev / Recraft v3).
• Add data to the knowledge layer. Drop files into brands/<slug>/knowledge/raw/ (CSVs, BigQuery exports, audience research, anything text-shaped). Run npx pectus knowledge digest to have Claude turn the pile into a structured brands/<slug>/knowledge/insights.md that every skill reads.
• Run analyses on demand. Each project’s Content Insights → Insights has a “Run analysis” button. It re-runs Stage 1 interpretation and Stage 2 idea ranking with fresh data, gated behind a cost-warning so you don’t accidentally rack up API charges. The warning shows how many ideas from the previous run you haven’t acted on yet.
• Add more languages or markets to a project. The page builder has locale chips on each row of the page tree. Click to switch between language variants of the same page; click a missing locale to create a new variant pre-filled from the source. Manual click, not an auto-translate.
• Edit page slugs and publish. When you change a slug, Pectus tracks the old URL and shows a redirect proposal at publish time so old links keep working. Manage redirects manually at Project → Content Insights → Redirects if needed.
• Set up a public site URL. Project → Content Insights → Site URL is where you set your mount slug, locale prefix config, and the GitHub repo + branch. Two save buttons: “Save” (just save the config) and “Save & republish all pages” (re-run URL resolution, generate redirects, ship one bulk commit).
• Apply Pectus updates. Pull the latest code (git pull) and then go to /settings/updates to apply any new migrations. The overlay surfaces pending migrations automatically; your brands/, knowledge files, and .env.local are never touched.
• Health check. npx pectus doctor verifies your env vars, network reachability, and config integrity. Run it any time something feels off.

Ad platform integrations (reference docs, connectors not shipped yet)

Pectus is built to read ad spend from Google Ads, Meta (Facebook + Instagram), and LinkedIn so analysis skills can correlate paid spend with content performance. The connector code for these isn’t shipped yet, but the credential procedures are documented because they involve the slowest part — gathering tokens, getting LinkedIn approval — which you can do in advance.

When the connectors land, you’ll have the credentials ready. Until then, treat these as reference docs:

• Google Ads — developer token, OAuth refresh token, customer IDs.
• Meta — Meta Business app, System User, ads_read token.
• LinkedIn — Marketing Developer Platform application (1 to 3 weeks), OAuth refresh token.

The connection status for each will show inside its own app page (/brands/<slug>/projects/<code>/apps/google-ads, /apps/meta, /apps/linkedin) once the connectors ship.

Troubleshooting

git clone says “repository not found” The upstream repo at github.com/pectusai/pectus is the source of everything. If GitHub returns 404, the repo may be temporarily down — check pectus.dev for status, or try again in a few minutes.

A database setup step fails Tell Claude exactly what error you got (copy and paste the message). Claude will walk you through running the missing piece directly from the Supabase dashboard. You don’t need to know SQL; Claude tells you what to click.

Sign-in says “invalid credentials” You set the admin email and password in step 6 (when Claude provisioned Supabase). Check your password manager. If you’ve lost it, reset via the Supabase dashboard’s Authentication tab.

pectus analyze says “ANTHROPIC_API_KEY not set” Open ~/pectus/.env.local in a text editor. Add or fix the line:

ANTHROPIC_API_KEY=sk-ant-...

Save, then re-run.

Dashboard shows “no data” Workspaces start empty. You need to add an ICP (Workspace → ICP), upload some keywords or rely on seed keywords from workspace creation, then run the weekly analysis. The first analysis is what populates the dashboard.

Brand-import says “couldn’t fetch the bundle” Claude Design URLs expire. Open the design in claude.ai/design, generate a fresh handoff, and paste the new URL.

Brand-import says “couldn’t extract brand fields” The bundle was fetched but Claude couldn’t parse a brand profile from it. Usually means the design didn’t include enough signal (no chat transcript discussing voice, no tokens.css). Either iterate on the design until the bundle has more, or fall back to manual brand setup.

For anything else, open an issue: https://github.com/pectusai/pectus/issues