clauth

Manage multiple Claude CLI account profiles. Switch between accounts, track per-profile usage stats, launch Claude with per-directory profile memory, and build a persistent knowledge wiki that compounds across sessions (Hive Mind). Use the CLI or the built-in web UI.

Install

npm install -g @cloudomium/clauth

Requires the Claude CLI to be installed.

Quick Start

# Create profiles for your accounts
clauth add work
clauth add personal

# Launch Claude with a profile — it will prompt to log in on first use
clauth launch work

# Or just run clauth to get an interactive selector
clauth

Commands

clauth

Running clauth with no arguments opens an interactive profile selector. Navigate with arrow keys (or j/k), press enter to select, q to quit.

The selector remembers which profile you last used in the current directory and pre-selects it.

clauth add <name>

Create a new profile. Profile names can contain letters, numbers, hyphens, and underscores.

clauth add work
# ✓ Created profile "work"

clauth remove <name>

Delete a profile and all its data. Prompts for confirmation before deleting.

clauth remove work
# Delete profile "work" and all its data? [y/N]

clauth launch [name]

Launch Claude CLI with the given profile. If no name is provided, it uses the profile last used in the current directory (or the globally last-used profile).

# Launch a specific profile
clauth launch work

# Launch the last-used profile for this directory
clauth launch

You can pass extra arguments to the Claude CLI after --:

clauth launch work -- --model sonnet

clauth config <name>

View or update per-profile configuration.

# View current config
clauth config work

# Enable --dangerously-skip-permissions for a profile
clauth config work --skip-permissions
clauth config work --no-skip-permissions

# Enable Hive Mind for a profile (see below)
clauth config work --hive-mind
clauth config work --no-hive-mind

clauth stats [name]

Show usage statistics. Without a name, shows a summary table for all profiles. With a name, shows detailed stats including token usage by model and activity charts.

# Overview of all profiles
clauth stats

# Detailed stats for a specific profile
clauth stats work

Detailed view includes:

• Session and message counts
• Token usage broken down by model (input, output, cache)
• 14-day message activity chart
• 7-day bar chart

clauth setup

Interactive wizard that walks you through creating profiles and configuring them.

clauth setup

clauth ui

Launch the clauth web UI in your browser. A local, graphical interface for browsing the Hive Mind wiki, feeding knowledge, querying, managing profiles, and viewing stats.

clauth ui                  # random free port, opens browser
clauth ui --port 3030      # specific port
clauth ui --no-open        # don't auto-open browser (useful for SSH tunneling)

The server binds only to 127.0.0.1 (localhost) — never exposed to the network.

Features available in the UI:

• Dashboard — overview of wiki pages, profile status, recent activity
• Hive browser — navigate wiki pages by category with rendered markdown
• Feed — textarea or drag-drop file upload for ingest
• Query — chat-like interface for read-only questions
• Graph — visual knowledge graph (Cytoscape.js) showing links between pages
• Profiles — toggle skip-permissions and hive-mind per profile
• Stats — real charts for token usage and activity

clauth hive [prompt]

Feed knowledge into the Hive Mind wiki, query it, or browse it. See the Hive Mind section below for the full picture.

# Feed knowledge manually (ingest)
clauth hive "decided to use Postgres for project X because we need transactions"

# Query the wiki (read-only)
clauth hive --query "what databases am I using across projects?"

# Health-check the wiki (find contradictions, orphans, broken links)
clauth hive --lint

# Ingest a file (markdown, text, PDF)
clauth hive --file meeting-notes.md
clauth hive --file report.pdf "focus on the client requirements section"

# Browse the wiki (instant, no LLM)
clauth hive --index           # print the content catalog
clauth hive --log             # print the last 10 log entries
clauth hive --log 30          # print the last 30 entries
clauth hive --open            # open the wiki directory in your file manager
clauth hive --obsidian        # open the wiki in Obsidian (requires Obsidian 1.0+)

# Reset knowledge (destructive, prompts for confirmation)
clauth hive --reset clauth              # drop one project's pages + its index entry
clauth hive --reset clients/mmi         # drop a single client page
clauth hive --reset people/muge-gunduz  # drop a single person page
clauth hive --reset                     # wipe the entire wiki and rescaffold it empty
clauth hive --reset -y                  # skip the confirmation prompt

# Session analysis queue
clauth hive --queue                     # what is waiting, what failed, what ran last
clauth hive --catchup                   # analyse queued sessions now
clauth hive --sessions 20               # pick from this project's recent sessions to add
clauth hive --queue --retry-failed      # requeue sessions that gave up
clauth hive --queue --clear-failed      # drop them

# Questions the wiki has for you
clauth hive --questions                 # answer them (Enter skips, d dismisses, q quits)
clauth hive --questions --clear         # dismiss all open questions

# Maintenance
clauth hive --synthesize                # extract cross-project patterns into concepts/
clauth hive --lint                      # find contradictions, stale claims, broken links

You are not expected to remember when to run these two. clauth watches for the moments they matter and tells you at launch — see When clauth asks for you.

Hive Mind

A personal knowledge wiki that the LLM builds and maintains for you. It captures decisions, problems, tradeoffs, architecture, and context from your Claude Code sessions and makes them available to future sessions.

The wiki is a folder of markdown files at ~/.clauth/hive/ — open it in Obsidian for a visual knowledge graph.

Enable it

clauth config <profile> --hive-mind

When enabled, clauth asks at the end of each session whether to add it to the wiki:

  Add this session to hive? [Y/n]

Enter queues it; the analysis then runs in the background and the terminal returns immediately. Declining is safe — the session log stays on disk, so clauth hive --sessions (scoped to the current project) can list recent sessions and add any you skipped by mistake.

Control the prompt per profile:

clauth config work --analyze ask      # prompt each time (default)
clauth config work --analyze always   # queue everything, never prompt
clauth config work --analyze never    # never queue

Queued work survives interruption: if the background worker is killed, the session stays in the queue and is picked up next time. A session that fails repeatedly is set aside after 3 attempts rather than retried forever. Pending and failed counts appear in the launch banner and in the web UI dashboard.

Two feed paths

1. Automatic — Claude Code sessions are analyzed after they end. Decisions, problems, tradeoffs, and architecture are extracted and filed into the appropriate wiki pages.

2. Manual — clauth hive "<prompt>" feeds knowledge directly. Useful for decisions made in meetings, context from Slack, corrections, or anything that didn't come from a session. Also supports file ingest via --file.

Categories

The wiki organizes knowledge across six categories:

Category	What goes here
projects/	Per-project technical knowledge (decisions, architecture, problems)
concepts/	Cross-project patterns, tools, techniques
clients/	Customer profiles, ownership, requirements
company/	Internal organization — team, processes, strategy
personal/	Health, interests, goals, habits
people/	Contacts, collaborators, stakeholders

Pages use YAML frontmatter and relative markdown links. Obsidian-compatible out of the box.

Context injection — a map, not a dump

When you launch a session in a project that has wiki pages, clauth injects a knowledge map into Claude's system prompt: one line per page saying what kind of knowledge it holds, plus the client and people pages your project links to, plus every other project as a single line.

Page contents are not injected. The session starts knowing where things are, not what they say — it opens the pages it needs with Read or Grep, and ignores the rest.

This keeps the cost of a session flat as the wiki grows. On a 9-page project, the old approach injected ~18,000 tokens of prior context into every session before you typed anything; the map is ~500 and capped, no matter how large the wiki gets.

The map is built from each page's summary frontmatter field — deterministically, in code, with no LLM call. The schema makes that field mandatory, so the analyzer fills it in as it writes.

When clauth asks for you

A wiki you never open cannot tell you it needs something. Maintenance commands that only run when you remember they exist are maintenance commands that never run — so clauth watches for the moments that matter and surfaces them at launch, the one screen you see every time:

  ╭──────────────────╮
  │  ▶ work          │
  │  hive-mind · 2 questions │
  ╰──────────────────╯
  clauth hive --synthesize  — 2 projects, concepts/ still empty

Three signals, all computed from files with no LLM call:

• Open questions appear as a count, answered with clauth hive --questions.
• --synthesize is offered the moment you have two or more projects and concepts/ is still empty — the cross-project knowledge is the point of the wiki, and nothing else would tell you the threshold was crossed. It goes quiet as soon as concepts/ has anything.
• Broken links are reported when a page has been moved, split, or deleted out from under the links pointing at it. clauth hive --reset also checks immediately, since deleting a project is what most often breaks them — every concepts/ page cites at least two projects by rule, so removing one project can dangle all of them at once.

Nothing here nags: each signal is silent unless it is true, and the synthesis one stops for good once acted on.

When the wiki asks you something

Some knowledge is not in your sessions at all. Synthesis can see that two projects solved the same problem differently — but the reason one went one way is usually in your head and nowhere else, and that reason is the part worth keeping.

So the analyzer is allowed to ask. It never blocks on the answer: the page is written either way, with the gap marked in place:

> **Rationale unrecorded** — Why did mmiProductHUB go single-table where spinneys used table-per-entity?

and the question goes to a queue. Answer them whenever you like:

clauth hive --questions

  2 questions from the hive

  [1/2] concepts/dynamodb-gsi-discipline.md
  Why did mmiProductHUB go single-table where spinneys used table-per-entity?
  → would change: whether the page reads as one recommendation or two valid choices
  >

Type an answer, press Enter to skip it for now, d to dismiss it for good, q to stop. Answers are folded into the wiki in one background pass — the marker is replaced by the knowledge, written as prose, with the question thrown away. Open questions show in the launch banner, alongside the queue counts.

The bar for asking is deliberately high: the analyzer may only ask when the answer exists in no source it can read and would change what it writes, at most 3 per run, never twice. A question is cheap for the model and expensive for you — the same asymmetry that made the old blocking analyzer fail.

The schema

The wiki has its own CLAUDE.md at ~/.clauth/hive/CLAUDE.md that governs how the LLM maintains it — page format, operation rules, create-vs-update logic. It's co-evolved over time. To refresh it from the latest clauth version: delete the file and run any clauth command to regenerate.

Design lineage — Karpathy's LLM wiki

Hive Mind is a direct implementation of the LLM wiki pattern proposed by Andrej Karpathy (gist). The core idea: instead of RAG rediscovering answers from raw documents on every query, an LLM maintains a persistent, compounding wiki where cross-references and synthesis already reflect everything it has read. The pattern has three layers — immutable raw sources, an LLM-owned wiki, and a schema that disciplines how the LLM maintains it — plus three workflows: ingest, query, and lint.

Where Hive Mind stays faithful to the pattern:

• Three layers, intact. Raw sources (session logs), the LLM-owned wiki (~/.clauth/hive/), and the governing schema (hive/CLAUDE.md) map one-to-one onto Karpathy's model.
• Schema as the disciplined maintainer. The gist warns that without a schema the LLM "behaves like a generic chatbot." Hive Mind's CLAUDE.md encodes page format, the six categories, and explicit create-vs-update rules — exactly this role.
• LLM-only writes; humans curate. Wiki pages are never hand-edited in the normal flow; the LLM owns synthesis while you direct what gets fed in.
• index.md + log.md navigation. Surfaced as clauth hive --index and --log, mirroring the gist's catalog-and-chronicle pair.
• The lint workflow. clauth hive --lint performs the health check Karpathy describes — contradictions, orphans, broken links, stale claims — and the same warning applies: skip it and "hallucinations slowly become the ground truth."
• Deterministic vs. LLM split. --index / --log / --open browse the wiki with zero LLM calls, keeping token spend for synthesis and judgment, as the gist recommends.

Where Hive Mind deliberately diverges — adapted for its goal of a passive, personal knowledge base:

• Source capture is inverted — and automated. Karpathy's pattern assumes humans curate the raw sources and direct ingestion. Hive Mind's distinctive bet is the opposite: the primary "raw source" is your coding sessions themselves, ingested automatically by a post-session analyzer. The wiki compounds passively, without you stopping to file anything — at the cost of trading away human-in-the-loop curation, which makes the --lint discipline more load-bearing, not less. (The manual clauth hive "<text>" / --file path preserves the classic human-curated flow alongside it.)
• Closed-loop context injection. The gist focuses on read/write within the wiki. Hive Mind adds a step beyond it: accumulated project knowledge is re-injected into future sessions via --append-system-prompt, so the wiki doesn't just answer queries — it silently primes the next session. This turns "compounding artifact" into a closed feedback loop specific to the coding-agent setting.
• The wiki can ask back. In the gist, knowledge only ever flows toward the wiki. Hive Mind adds a reverse channel: when synthesis hits something derivable from no source — typically why two projects diverged — it queues a question rather than guessing or dropping the finding, and you answer it later via clauth hive --questions. This is the one place the pattern needs a human, and it stays non-blocking: the page is always written, with the gap marked.
• Query is read-only by design. Karpathy suggests queries should file valuable discoveries back into the wiki. Hive Mind keeps --query side-effect-free so reading never mutates the knowledge base; new knowledge enters only through the (automatic or manual) ingest paths, where it's subject to the schema's create-vs-update discipline. This is a deliberate trade — predictability over maximal compounding.

How It Works

Profiles are stored under ~/.clauth/. Each profile gets its own directory that acts as an isolated Claude configuration directory.

• default — automatically created, points to your existing ~/.claude config
• Other profiles — stored as ~/.clauth/<name>/ and launched with CLAUDE_CONFIG_DIR set accordingly
• hive — reserved name for the Hive Mind wiki directory (not a profile)

When you launch a profile, clauth:

1. Records it as the last-used profile for the current directory (~/.clauth/folders.json)
2. Sets CLAUDE_CONFIG_DIR to the profile's directory (except for default)
3. If Hive Mind is enabled, injects the knowledge map (not page contents) via --append-system-prompt
4. Spawns claude with any configured flags and passthrough arguments
5. After the session exits, if Hive Mind is enabled, asks whether to keep it (per the profile's analyze setting) and queues it for background analysis

Directory Structure

~/.clauth/
  ├── default/          # metadata for the default profile
  │   └── clauth.json   # per-profile config (e.g. skipPermissions, hiveMind)
  ├── work/             # full Claude config dir for "work"
  │   ├── clauth.json
  │   ├── credentials.json
  │   └── ...
  ├── personal/
  │   └── ...
  ├── hive/             # Hive Mind wiki (see above)
  │   ├── CLAUDE.md     # schema — how the LLM maintains the wiki
  │   ├── index.md      # content catalog
  │   ├── log.md        # chronological record of ingests and queries
  │   ├── projects/
  │   ├── concepts/
  │   ├── clients/
  │   ├── company/
  │   ├── personal/
  │   └── people/
  ├── hive-backups/     # timestamped wiki snapshots (last 3 kept per kind)
  ├── hive-queue.json   # sessions waiting for / failed analysis
  ├── folders.json      # directory → profile mapping
  └── .last             # globally last-used profile name

License

MIT