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 — which is why the wizard turns it off for you on the entry-level plans (Claude Pro, ChatGPT Plus, and Standard seats on Claude Team or ChatGPT Business) and leaves it on everywhere else. Flipping it either way is one ask away — just tell ClaudeCodex:

> Turn the QA phase off so sites go straight from build to deploy

It takes effect from the next pipeline run; ask for it back on the same way whenever you want the extra polish. (If you change plan, re-running npx klaudius@latest configure resets the default to match.)

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, ChatGPT Plus, or a Standard seat on Claude Team or ChatGPT Business), 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 failed runs (build errors, unusable photos, etc.) and sends you an alert. On Claude Code, an infrastructure-level failure — an API socket drop, auth expiry, a supervisor error — stops it on the first occurrence, since those usually need a human eye; on Codex a lone abnormal exit just costs that slot, and only three in a row stop the pool. A usage limit is neither: both wait for your window to reset and resume the interrupted sessions.

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

Klaudius runs on your own Claude or ChatGPT subscription. There are two ways to set it up, and both end with the same project.

npx klaudius@latest init my-agency

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

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

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

Troubleshooting

Diagnostics

Klaudius has a built-in install-time health check. The main moment to use it is right after the wizard finishes. Open your agent inside the project and ask:

Check my Klaudius install is healthy.

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 — then reads the results back to you and walks you through fixing anything that came back red.

Beyond install, you generally won't need the health check 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 the health check comes back green and your agent still can't make sense of what's happening, email hello@klaudius.dev with what it told you and we'll dig in.

Email

Checking your email lands: /deliverability

Ask your agent to run /deliverability and it will tell you whether your outreach email is set up correctly.

It works in two steps. First it sends a single test message from your own account to itself, reads it back, and reports how the receiving mail service actually treated it: the SPF, DKIM and DMARC verdicts it stamped on the message. That's the authoritative answer, because it's read off a real delivered message rather than inferred from your DNS records. Then it checks your sending domain's DNS and tells you what needs fixing, with the exact record to paste into your registrar wherever one applies.

Worth running once when you set up, and again any time replies dry up or you suspect something has changed.

The daily loop

Follow-ups every day, without remembering

Most replies come from the follow-ups, not the first message, and the first one is due three days after you pitch. /follow-up does the whole job: it checks every conversation for replies, works out who is due, and drafts each follow-up for you to read. Nothing is sent until you have seen the list and approved it. The only thing left to you is starting it each day, and you can hand that over too.

In the Klaudius app: switch on Daily follow-ups in Settings and pick a time. Each morning the app prepares the day's follow-ups, then the warm-leads report, and tells you when they are ready. If the app was closed or your computer asleep at that time, it catches up when you open it, up to 8pm. The follow-ups wait in the Inbox as an approval queue: read each drafted message, edit the wording if you like, then approve all of them, only some, or none. Whatever you leave stays in the queue for the rest of the day.

In the terminal: your agent can start itself on a schedule.

A scheduled run stops at the proposal, exactly as it does when you start it yourself. It sends you a notification (Telegram, or whatever you chose at setup) such as "6 follow-ups ready for review, 2 warm replies waiting", and saves the proposal in your project. When you are back, open that conversation and answer in plain words (in a new conversation, ask to see today's follow-up proposal first): "send all", "send all except harbour-barbers", "send these: …", or "use this text for harbour-barbers: …". Before each send your agent re-reads that conversation, and it skips anyone who has replied in the meantime. A proposal is only good for the day it was made; the next day's run makes a new one.

Getting paid

Invoicing a client: /send-invoice

When a client says yes, ask your agent to invoice them — /send-invoice {business name}. It writes a professional PDF invoice for that client and leaves a ready-to-send email sitting in your own mailbox's drafts folder, with the invoice already attached and the client already in the To field. You read it and press send. It never sends anything itself — the last click on a money email is always yours.

You don't have to tell it much, because your project already knows the client: their business name, the owner, their email, the address, and the price you quoted them. Pass an amount if you're billing something different from the quoted price (a deposit, an add-on, a maintenance period) and it uses that instead.

The first time you ever run it, it asks a handful of questions about your own business — the name you invoice under, your address, whether you charge sales tax or VAT, and how clients pay you — then remembers all of it, so every invoice after that goes straight to confirming the numbers. Before anything is written, it shows you the whole invoice, tax arithmetic included, for you to confirm or correct. Invoice numbers run in sequence and are never reused — they come from a ledger in your database; if something needs correcting, you get a fresh number that references the one it replaces.

The PDF is filed alongside that client's site in your project, and the ledger keeps the record of every invoice and quote: what was billed, when it was due, and when it was paid. A card payment through the invoice's pay-by-card link (Stripe, below) is recorded on its own: the next /follow-up sees it and marks the invoice paid. A bank transfer you tell your agent about ("Acme paid") and it does the same. Either way that client becomes converted and their total stays right. Ask "who still owes me?" and it answers from the ledger. Quotes work the same way — /send-quote {business name} — in their own number series.

Card payments through your own Stripe account

Say "connect Stripe" and your agent asks for a restricted key from your own Stripe dashboard (it tells you exactly which permissions to tick), checks it, and stores it in your project. From then on every invoice carries a single-use pay-by-card link — on the PDF and in the email — and when the client pays, the next /follow-up records it without you doing anything. The money goes straight to your Stripe balance; nothing sits in between, and clients who prefer a bank transfer still have the details on the invoice. Invoices that go past their due date show up in /follow-up too, with a friendly reminder drafted for you to send.

Monthly fees: hosting, maintenance, care plans

Ask for it in plain English — "charge Acme £40 a month for hosting" — or run /recurring {business name} {amount}/month. It confirms what the fee covers, the amount and the period, then creates the arrangement in your Stripe account and drafts the client an email with a link. The client opens it once, enters a card, and from then on Stripe charges it every month (or year) on its own, retries a failed card itself, and can email them a receipt each time. If a client would rather not leave a card, pick the other mode and Stripe emails them an invoice at the start of each period instead. Either way every payment lands in your ledger, the client's renewal date is tracked, and /follow-up tells you when a payment arrives, fails, or the client cancels. "What's recurring right now?" lists every arrangement and its next charge date; "cancel Acme's monthly fee" ends one.

Stripe's own fees apply to what you collect through it; there is no fee from Klaudius on any of this.

Reconfiguration

Changing your settings

Most of the time you don't need a wizard at all — just tell your agent what you want changed and it edits the right file for you:

Change my pricing to $899.

That covers nearly everything: pricing, outreach tone, which channels you use, which host you deploy to, a credential you've rotated. If your agent needs a new key or token to finish the job, it'll just ask you for it.

If you'd rather go through every setting in one pass, there's a full wizard — and this is one of the few things you run yourself rather than ask your agent for, because it's interactive and needs a real terminal to type into. From inside your project folder:

npx klaudius@latest configure

It 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. The new values are written back to .env.

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.), just tell your agent what changed and hand it the new value — it'll get it updated. Or run npx klaudius@latest configure yourself to walk through the wizard again.

The Klaudius app

The Klaudius app

Klaudius also comes as a desktop app — the same pipeline, with a visual home: a dashboard of your whole operation, an inbox of businesses waiting on a reply, your full client pipeline, a lead finder, and a voice mode you can just talk to. Everything the app does runs through the same files and sessions as the terminal, so you can mix and match freely — start a run in the app, pick the conversation up in your terminal, or the other way round.

Download it from klaudius.dev/download (Mac or Windows). If you set Klaudius up in the terminal, point the app at the project folder you already have — there's nothing to redo. It keeps itself up to date.

Maintenance

Updating to the latest version

Open your agent in the project and ask:

Update Klaudius.

It pulls the latest core skills, scripts, and template files, applies everything that can be applied safely, and then walks you through anything that needs a decision from you. Update is conservative by design:

• Files you haven't touched are updated cleanly in place. Update keeps a copy of every file it replaces or deletes under .klaudius/backup/ (as <name>.bak).
• Files we've stopped shipping are removed just as cleanly — unless you'd edited your copy, in which case it's your call whether to keep it (untracked from then on) or drop it.
• Files you've edited become conflicts — Klaudius writes a report at .klaudius/conflicts.md and stages the canonical incoming versions under .klaudius/incoming/. The report includes a summary of exactly what we changed since your version, so when your edits don't overlap ours the merge is mechanical. Ask your agent to “resolve the conflicts” afterwards — it walks through each one and applies your choice (keep yours, take ours, or merge). Any choice that overwrites or deletes your version saves it first under .klaudius/backup/, so a mis-chosen resolution is recoverable.
• Files you've deleted (say you removed a skill you don't use) are never silently reinstalled — update flags them as conflicts too, and you choose: restore the file, or keep it deleted. “Keep deleted” is remembered permanently, so later updates never ask again.
• 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. Settings introduced by a new version are appended to your .env with their defaults, so nothing you've set gets touched and nothing is left undefined.
• Your .gitignore is merged rather than replaced — every line you've added survives, and any new patterns Klaudius needs are appended underneath.

Reference

Command reference

Two of these you run yourself. They open an interactive wizard, so they need a real terminal to type into — your agent can't drive them on your behalf:

npx klaudius@latest init my-agency   # Scaffold a fresh project
npx klaudius@latest configure       # Re-run the setup wizard on an existing one

The rest you never need to type. Just ask your agent in plain English — it knows these and runs them for you, then reads the results back:

npx klaudius@latest update          # "Update Klaudius"
npx klaudius@latest doctor          # "Check my install is healthy"
npx klaudius@latest install         # "Finish setting up" / "my install is broken"
npx klaudius@latest preflight       # "Does this machine have what Klaudius needs?"

Run any of them from inside your project directory (except init and preflight, which don't need one).