Documentation

The essentials

Getting the most out of Klaudius

The five things below are what almost every operator wishes they'd known on day one. Read them before you start churning out sites.

1. Talk to Claude inside the project — this is the #1 thing

Klaudius is designed to be as hackable and customisable as possible, and the way you do that is by opening Claude Code in your project folder and just talking to it. Ask Claude to walk you through how the pipeline works, what any part of the project does, or what features are available. Want more casual outreach? Say so. Want to raise your pricing, stop pitching restaurants, drop a follow-up touch, source businesses from a different city? Ask. Claude handles the change for you. When something breaks, Claude can almost always fix it.

The project is the product, and the more you treat it as something you converse with, the more you'll get out of it. The rest of this file covers the things Claude can't easily surface on its own (model selection, the parallel-pipeline mode, account scaling) — everything else, ask Claude.

2. Balance output volume against quality

The biggest fork in how to run Klaudius is which Claude subscription tier you're on. Max and Pro need different defaults, so start here:

If you're on Claude Max: use Opus with thinking set to “high”. Don't go higher — bumping thinking to “xhigh” or “max” gives a marginal quality gain in theory but in practice it's diminishing returns and burns through usage limits fast, even on the Max plan. Opus on “high” gives you enough usage to run the whole pipeline at quality, which is where Klaudius really shines — sites come out noticeably more crafted, copy is sharper, design choices are more deliberate. This is the setup we recommend.

If you're on Claude Pro: use Sonnet instead, and consider removing the QA step (see below). Pro's usage limits will burn through very quickly if you try to run Opus on full pipelines, so Sonnet is the right default — sites still come out decent, just with the occasional rough edge that QA would otherwise catch. Just ask Claude to run the pipeline but skip the QA step.

A note on the QA stage. After Claude has finished generating a site, a fresh agent is launched purely to review it. It doesn't just read the code — it takes screenshots of the site across desktop and mobile viewports and visually inspects each one the way a human would, catching broken layouts, missing images, copy that drifted from the brief, broken hrefs, or anything that just looks off. We use a fresh agent because the main building agent has been deep in that codebase for hundreds of tool calls and has tunnel vision: it's been generating components, wiring data, deploying. A fresh-context reviewer walks in cold and is markedly better at spotting the small stuff. It's the cheapest way to neutralise accumulated-context bias, and it's a big part of why Klaudius output reads as crafted rather than generated. That said, QA is often the slowest part of the pipeline — especially when a site fails the first round and needs multiple passes to clear — so skipping it can be the right call for operators (particularly on the Pro plan) who'd rather lean toward volume than quality.

3. Run Claude Code on auto mode

Klaudius is built around long-running, multi-step Claude sessions — finding leads, building sites, sending outreach. Sitting at your keyboard pressing “yes” to every tool approval defeats the point. Switch Claude Code into auto mode and let it run.

Cycle into it with Shift+Tab until the status line reads “auto mode.” Once you're in, Claude executes routine actions — file edits, script runs, API calls — without prompting, while still surfacing output for you to follow.

This isn't reckless. Anthropic has built guardrails into auto mode so genuinely dangerous actions still surface for approval — destructive shell commands, irreversible operations, anything that affects shared production systems. You retain veto power on the things that matter; you just stop being asked about routine work. (Don't use --dangerously-skip-permissions — that bypasses the guardrails entirely for negligible additional speed.)

Drop back to default mode when you're doing something you genuinely want to review step-by-step — composing a reply to a warm lead, say, or registering a domain for a freshly-converted client.

4. Don't cram too many pipeline runs into one Claude Code session

If you try to run many clients sequentially in a single session, you'll fill the context limit and Claude will auto-compact mid-pipeline, which can disrupt whatever it's working on at the time. The fix is to ask Claude to run the pipeline in parallel:

> Run pipeline x3

Claude becomes an orchestrator that dispatches three concurrent pipeline sessions, each running end-to-end on its own client, and refills the pool every time one completes. Each session handles one client and exits, so no instance ever gets bloated context, and your orchestrator session stays light.

Each parallel pipeline session runs as a Claude Code background session managed by the supervisor process — a full Claude Code session, just without a terminal attached. All of this runs on your existing Claude Code subscription, exactly like an interactive claude session. There's no extra billing and no separate credit pool — running three pipelines in parallel uses the same subscription you're already paying for.

The two-tab pattern. Tab 1 is the orchestrator — the Claude Code session you talk to (the one you ran “Run pipeline x3” in). Claude dispatches the initial pool, then refills as each child completes. Leave the tab open — Claude needs to receive completion notifications. Ask for status any time (“How's it going?”, “How many in-flight?”), change pool size on the fly (“Make it 5”), or stop (“Stop after these finish”).

Tab 2 is optional but recommended — a live dashboard of every background pipeline session:

claude agents

Space to peek at what any session is doing right now. Enter to attach to a session's full conversation (useful when one looks stalled or is doing something odd). ← to return to the dashboard. Ctrl+X to delete a session.

Both tabs share state through the supervisor, which runs independently of either terminal. Background sessions survive Ctrl+C in the orchestrator tab and terminal closes; they don't survive reboots (run claude respawn --all after a reboot to restart them where they left off). Reconnect any time with claude agents.

Pool size. Start with x2 or x3. Three is the sweet spot for most operators — enough throughput that you're not babysitting, not so many that you burn through your Claude session limits. The orchestrator stops automatically after three consecutive pipeline-level failures (no candidates in a region, build errors, etc.) and sends you a Telegram alert. Infrastructure-level failures — API socket drops, auth expiry, supervisor errors — trigger an immediate stop on the first occurrence; those usually need a human eye to recover from.

5. Scaling further as a power user

Once sales pick up and you want to really multiply output, it's worth running multiple Claude subscriptions in parallel — so when usage runs out on one account, you switch to the other and keep going. Pair this with the parallel pipeline mode above and you can keep the throughput up around the clock.

Setup

First-time install

npx klaudius init my-agency

The init command scaffolds this project, then launches you into an interactive wizard that walks you through everything — your pricing and outreach preferences, the connection details for the infrastructure Klaudius runs on, and the installation of all dependencies (Node packages, Python packages, browser engines). The whole thing takes 15–20 minutes.

Outreach channels: Klaudius supports a range of outreach channels. You opt into any combination during the wizard and set a priority order — for each candidate, Klaudius tries your priority channels in order and uses the first one that's viable.

After it finishes, move into the new project directory and open Claude Code:

cd my-agency
claude
> Run the pipeline for New Jersey.

Troubleshooting

Diagnostics: npx klaudius doctor

npx klaudius doctor is the install-time health check. The main moment to run it is right after the wizard finishes — ask Claude inside the project to run it and confirm everything wired up cleanly. Claude will execute the command, read the output, and walk you through anything that needs fixing. If you prefer to run it yourself, the command is the same:

npx klaudius doctor

It runs a structured check across everything that needs to be in order for the pipeline to work — language versions, dependencies, project files, and the credentials you configured in the wizard. The output flags whatever's broken and points at the fix.

Beyond install, you generally won't need to reach for doctor at all. The exception is when something environmental has clearly changed — you've moved to a new machine, rotated a credential externally, or a system update has broken something. For everyday pipeline issues — anything mid-run, anything specific to a particular client, anything you'd describe in a sentence — just ask Claude directly. Claude reads the error, reasons about it, and usually fixes it on the spot.

If doctor reports green and Claude can't make sense of what's happening, email hello@klaudius.dev with your output and we'll dig in.

Reconfiguration

Re-running the wizard

npx klaudius configure

Walks you through every wizard step again with your existing answers pre-filled, so you can change anything (pricing, sender identity, outreach channels, API keys, etc.) and skip past anything you want to leave alone. Writes the new values back to .env. Alternatively, you can just ask Claude in the project to change any of these (e.g. “change my pricing to $899”).

Reference

Where your credentials live

Every credential the wizard collects — for your outreach providers, CRM, hosting, data sources, and any other service you wire in — is written to your project's local .env file and stays there. None of these credentials are ever sent to Klaudius's servers. The pipeline uses them directly against each provider from your machine.

If you ever rotate a credential externally (regenerate an app password, issue a new token, etc.), ask Claude to help you get it updated, or just run npx klaudius configure to walk through the wizard again.

Maintenance

Updating to the latest version

npx klaudius update

Pulls the latest core skills, scripts, and template files. Update is conservative by design:

• Files you haven't touched are updated cleanly in place.
• Files you've edited become conflicts — Klaudius writes a report at .klaudius/conflicts.md and stages the canonical incoming versions under .klaudius/incoming/. Open Claude Code afterwards and ask it to “resolve the conflicts” — the resolve-conflicts skill walks through each one and applies your choice (keep yours, take upstream, or merge).
• Files you've created (your own skills, your own scripts, any work under clients/) are invisible to update — they're not tracked, so they're never touched.
• Local config (.env, .mcp.json, .claude/settings.json) is never overwritten — those belong to your install, not the template.