FAQ
Frequently asked.
Short answers to the questions we hear most often. Each section is grouped by topic — jump straight to the one you need, or scroll through.
Can't find what you're after? Ask the docs assistant or send us a question →
basics
The basics
What Claudium is, who it's for, and how it fits next to the tools you already run.
What is Claudium?
Claudium is a live visualization of your AI coding sessions. Every tool call, every token, every region of the model that fires — rendered as a brain in real time, in your browser.
If your team uses Claude Code or another agent runtime, Claudium shows you what it's actually doing — not just whether it finished. The shipped feature set covers the live brain view, a per-org pattern + insight detector, billing, team workspaces, and a custom-domain mode for white-labelling.
Who is Claudium for?
Engineering teams shipping with Claude Code (or any agent runtime that emits tool-use events). The primary buyer is a tech lead or staff engineer who wants visibility into how the agent is spending its tokens — and where its time goes.
Solo developers also use the Free tier to watch their own sessions; the brain is fun on its own. The paid value is mostly about team-scale visibility and pattern detection.
How is this different from Datadog, Sentry, or LangSmith?
Datadog and Sentry watch your application code at runtime. LangSmith records LLM traces in a tree view. Claudium does neither — it watches the agent's tool-call surface as it happens and visualizes it as a live, anatomical "brain" where each region maps to a tool or capability.
The intent is different too. Those tools are forensic ("why did this break?"). Claudium is ambient ("what is my AI doing right now?") plus metacognitive ("what could it be doing more cheaply?") — the live brain on one hand, the 6-hour insights detector on the other.
Does it work with agents other than Claude Code?
Yes. The watcher tails JSONL session logs and the hub accepts inbound events over WebSocket — so any agent runtime that can emit a tool-use record can drive the brain. Claude Code is the out-of-the-box path; bring-your-own-sender is a five-line patch documented in the sender-integration guide.
Why a brain visualization specifically?
Because activity-by-region is the right unit. Anatomical brain regions are a familiar metaphor for "areas of competency" — language, motor, memory — and they map cleanly onto the tools an AI agent uses (Read = visual cortex, Write = motor, Bash = action planning, and so on).
Lists and tree views don't convey rhythm or focus the way a glowing 3D brain does. You can tell at a glance whether your agent is in deep flow on one region or thrashing across ten. We chose visual immediacy over data-density on purpose.
privacy
Privacy & security
Exactly what leaves your machine, what we store, and what we never see.
Does any of my code or prompts leave my machine?
No. Only metadata travels — tool name, region label, token count, and the file path that was touched. We never ingest file contents, prompts, or model outputs.
A PII / secret filter on the hub also drops anything that looks like a key, token, or password (from a file path or argument) before any other viewer can see it. That filter ships as the lib/redact module and is unit-tested on every commit.
Are you SOC 2 compliant?
Not yet. We're working on the controls — audit logging, encryption at rest, replay-protected sender auth (HMAC + nonce), and per-org RLS are all already in production. A formal audit lands when we've been in market long enough to have 12 months of evidence to show.
In the meantime, the privacy posture is documented end-to-end in the docs: what we collect, what we store, what we never see. If you need an MSA or DPA before that audit, contact us — we already have customer-friendly templates.
What happens when I delete my account?
Account deletion fans out to every row tagged with your org_id — events, turns, patterns, insights, billing artefacts. Audit logs of the deletion itself are retained for 30 days for fraud-prevention purposes, then purged.
If you self-host, deletion is your operator's call — the schema supports the cascade via foreign keys on org_id.
What about secrets that accidentally show up in file paths or arguments?
Caught before they're persisted. The lib/redact filter runs on every event before it reaches the database and replaces any pattern that looks like an API key, JWT, OAuth token, AWS key, or generic high-entropy string with a [REDACTED:kind] tag. The same filter runs on file paths too — so /Users/me/keys/secret.pem won't leak the basename if it matches a key pattern.
setup
Setup & integration
What it takes to get the brain alive against your own agents.
How long does setup take?
Five minutes for the Claude Code path. Install the watcher, point CLAUDE_DIR at your projects folder, run npm run hub — the brain starts moving on the next tool call.
For a bring-your-own-sender integration, budget an afternoon — the sender contract is documented and the reference implementation is ~60 lines of JavaScript.
Do I have to change how I use Claude Code?
No. The watcher tails the session logs Claude Code already writes — you don't configure anything inside Claude itself. Open Claudium in a browser tab and the brain reflects whatever sessions are running.
What if I'm running multiple agents at once?
They all stream into the same brain. Region activity is the union of every active session, so you can tell at a glance how many concurrent tasks your team is running and where their effort is going.
Per-session filtering lands in a future view — for now the brain is org-wide.
Can I integrate with my CI/CD?
Yes — anywhere your CI can hit a webhook or run a node process can be a sender. Some teams pipe their CI agents into Claudium specifically so the brain shows test-run activity alongside developer activity.
A formal CI plugin is on the roadmap but not shipped yet.
pricing
Pricing & billing
Plans, limits, and how billing actually works.
Is there a free tier?
Yes. The Free plan covers one contributor and 10,000 events per month — enough for an individual developer's daily Claude Code use. No credit card required.
What counts as an "event"?
One tool call. Read, Edit, Bash, Grep, WebSearch — any single action the agent takes. A typical Claude Code session burns 50–200 events.
We bill on events rather than seats so an inactive team-mate doesn't inflate your bill, and a developer who lives in Claude Code doesn't get throttled by a per-seat ceiling.
Can I upgrade or downgrade at any time?
Yes, instantly via Stripe Customer Portal. Upgrades take effect immediately; downgrades take effect at the end of the current billing cycle (no proration loss). Cancel any time — you keep access through the end of the cycle you've paid for.
Is there an annual discount?
Yes — 15% off the Team plan if you pay yearly. The toggle is in Settings → Workspace when you choose your plan.
What does Enterprise include?
Custom event volume, SSO (SAML or OIDC), audit-log export, dedicated single-tenant deployment if you need it, a custom MSA + DPA, and priority response SLA. Talk to us — enterprise@helloclaudium.com — and we'll quote based on volume.
What happens if I go over my event quota?
You'll see a banner in the brain and an email at 80% + 100%. We never hard-stop — your sessions keep recording so you don't lose visibility — but the next billing cycle will auto-upgrade you to the matching tier unless you cancel the auto-upgrade before then.
self-host
Self-hosting & deployment
For teams who want the whole stack on their own infrastructure.
Can I self-host?
Yes. The whole stack is open source — clone the repo, run npm install, point CLAUDE_DIR at your projects folder, and you're live on localhost.
For team deployments, the docs cover Render (the easiest path), bare-metal with Caddy on-demand TLS, and Docker. Enterprise customers get a hardened image with SSO + audit log baked in.
Do I need a Postgres database?
Strictly speaking no — the hub runs in "env-var mode" without a database, which gives you the live brain but skips persistence (no events history, no patterns, no insights, no team workspaces). Set DATABASE_URL + AUTO_MIGRATE=1 to unlock the full feature set.
pgvector is required for the pattern + insight worker (the embedding column lives in events). Render's Postgres ships with it pre-installed; on bare metal it's `CREATE EXTENSION vector;`.
Do I need to provide OpenAI API keys?
Only if you want the AI-assist features — the docs assistant on /help and the embedding-based pattern detector. Without OPENAI_API_KEY, the brain still works, the insights worker still runs, but the AI-grounded answers on /help fall back to keyword search.
Can I run Claudium at my own URL?
Yes — Settings → Custom domain lets an owner or admin claim a hostname like claudium.teleperson.com. The hub validates the hostname, gives you the exact CNAME record to add at your DNS provider, and a "Verify DNS" button to confirm propagation.
TLS is operator-side — Cloudflare proxy is zero-config (turn on the orange cloud), or self-hosted Caddy on-demand TLS works via the /api/tls/allow endpoint. The docs walk through both recipes end-to-end.
How do updates work?
Self-hosted: git pull + npm run migrate (or AUTO_MIGRATE=1 if you trust the migration set). The release-notes archive at /release-notes is auto-generated nightly from main's commit log so you can see what changed before pulling.
Managed: zero-action — we ship to Render continuously.
intelligence
Insights & intelligence
How the brain learns about your team's patterns — and what stays inside your workspace.
How does the insights detector work?
Every six hours, a worker reads your org's recent events and turns through a set of transparent heuristics — file re-read counts, session-token spikes, more landing as we learn what patterns matter — and writes any matches into your org's insights table.
Each detector is a pure JS function in lib/insight-detect.js. No machine learning is involved in v1; the rules are auditable and you can read exactly what each one looks for.
What's the difference between Patterns and Insights?
Patterns are repeated tool-call sequences your team uses ("Bash → Read → Edit, 12 times this week"). They're the descriptive layer — what does my team actually do.
Insights are prescriptive — they look for inefficiencies in those patterns and suggest cheaper next moves. Patterns describe; insights recommend.
I just signed up — when will I see patterns + insights?
Patterns need a handful of sessions before they emerge — usually 24–48 hours of normal use. Insights need roughly the same lookback (events from the last seven days) and re-detect every six hours, so figure on a day or two for the first row to appear.
The /insights page handles the empty state gracefully: a calm "quiet so far — that's a good sign" rather than a broken-looking dashboard.
Do insights from other Claudium customers help my org?
No. Each detector runs strictly inside one org's data — there's no shared model and no cross-tenant signal. We made this trade-off explicitly: a shared model would have more data to work with, but the privacy posture would be weaker. Trust matters more than marginal accuracy for the surfaces we're building.
team
Team & workspace
Multi-user, roles, invites, and how your team shares a brain.
How do I invite teammates?
From the brain → Invite. Type their email; they get a one-time-password sign-in link via Resend. No password to set, no provisioning step. They land in your workspace as a member.
What roles exist?
Three: owner (one per workspace), admin (any number), member (any number). Owners and admins manage billing, invitations, the custom domain, and member roles. Members can use the brain + see insights + change their own profile.
Can I be in multiple workspaces?
Yes. Sign in with the same email — you'll land in your primary workspace (highest-role, oldest-membership). An explicit "switch workspace" UI lands in a future commit; for now the hub picks the most-privileged membership automatically.