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 your agent 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 your agent (Claude Code or Codex) in your project folder and just talking to it. Ask it 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. The agent handles the change for you. When something breaks, it 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 the agent can't easily surface on its own (model and reasoning-effort selection, the parallel-pipeline mode, account scaling) — everything else, just ask.

2. Balance output volume against quality

The biggest fork in how to run Klaudius is which agent and which plan tier you're on. The defaults that work best differ across both axes — pick the box below that matches your install:

A note on the QA stage. After the agent 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 and a real slice of your usage — especially when a site fails the first round and needs a fix pass — so on the cheaper plans, removing it is the right call if you're leaning toward volume over quality. To do that, ask ClaudeCodex directly:

> Remove the QA phase from the pipeline — update the project instructions so sites go straight from build to deploy

It will edit the pipeline instructions for you, and every future run skips QA without you having to ask again.

3. Run your agent on autonomous mode

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

Drop back to interactive 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 session

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

> Run pipeline x3

On the cheaper plans (Claude Pro or ChatGPT Plus), start with x2 instead — parallel sessions all draw from the same usage pool, and three concurrent builds will burn through the lower tiers' limits mid-run.

The agent 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. The mechanics underneath that single command differ by agent — both work for the operator, but the underlying machinery differs:

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 usage 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, running multiple agent subscriptions in parallel is the next move — 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 throughput up around the clock.

Setup

First-time install

Before the wizard, get your machine ready. Open Claude Code or Codex in your terminal and paste the line for your system (it'll run it for you):

macOS / Linux:

curl -fsSL https://klaudius.dev/setup.sh | bash

Windows (PowerShell):

irm https://klaudius.dev/setup.ps1 | iex

It installs the prerequisites Klaudius needs — Node.js (22.15+) and Python (3.10+) — into your user space, with no admin password and no clicks, then runs a preflight check and tells you when you're ready. It skips anything you already have at a good version, so it's harmless on an existing developer setup and safe to re-run. (Want to read it first? Open the URL in your browser before running it.)

Then, in a new terminal tab, scaffold the project:

npx klaudius@latest 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 your agent (see Run your agent on autonomous mode):

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

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

Troubleshooting

Diagnostics: npx klaudius@latest doctor

npx klaudius@latest doctor is the install-time health check. The main moment to run it is right after the wizard finishes — ask your agent inside the project to run it and confirm everything wired up cleanly. The agent 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@latest 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 your agent directly. It reads the error, reasons about it, and usually fixes it on the spot.

If doctor reports green and your agent 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@latest 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 your agent 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 your agent to help you get it updated, or just run npx klaudius@latest configure to walk through the wizard again.

Maintenance

Updating to the latest version

npx klaudius@latest 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 your agent 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, plus your agent's MCP config — .mcp.json + .claude/settings.json for Claude Code installs, .codex/config.toml for Codex installs) is never overwritten — those belong to your install, not the template.