1 / 10
01  ·  Introduction

The SME your team never had.

Kluris turns your AI agents into a subject matter expert that never sleeps and never quits — built collaboratively with you, one approved entry at a time.

Two surfaces · one brain · seven beats

Terminal You, at the shell

The kluris CLI. You run these yourself — install, create a brain, regenerate the MRI and validate links; every command keeps the brain in step with your team.

kluris create
Inside your AI agent The agent, with the kluris skill loaded

A named slash command per brain — /kluris-<name> — followed by whatever you want to say. Run it while your agent is open on a project so it can read the code. Every registered brain installs as its own named skill, even when it's the only one.

/kluris-acme learn the auth flow

The seven beats ahead

Beat 1

Set up

Beat 2

Teach

Beat 3

See

Beat 4

Use

Beat 5

Grow

Beat 6

Self-improve

Beat 7

Capture session

Use ← → or Space to navigate  ·  1–9 to jump to the first nine slides.

02  ·  Beat 1 · Set up

Install kluris. Create a brain.

A brain is a git repo of curated markdown that every AI agent on your team reads as a subject matter expert. One command to install. One wizard to create your first one.

macOS · Linux Terminal
$ curl -fsSL https://kluris.ngvoicu.dev/install.sh | sh
# open a new terminal, then:
$ kluris doctor
Windows · PowerShell Terminal
> irm https://kluris.ngvoicu.dev/install.ps1 | iex
# from cmd.exe: powershell -ExecutionPolicy ByPass -c "irm https://kluris.ngvoicu.dev/install.ps1 | iex"
# open a new terminal, then:
> kluris doctor

No admin rights: one binary in ~/.kluris/bin, added to your PATH, so open a new terminal after installing. macOS, Linux and Windows, Intel/x86_64 and ARM. Update with kluris self-update, uninstall with kluris self-uninstall (your brains stay), and pin a release with KLURIS_VERSION=3.2.3.

kluris create — interactive wizard Terminal
$ kluris create

Create a new brain

  Brain name (lowercase, hyphens ok): acme
  What does this brain cover? (one sentence): Shared brain for ACME projects
  Location [~]: ~/Projects
  Brain type (product-group, personal, product, research, blank) [product-group]:
  Git setup (1=local, 2=with remote, 3=no git) [1]: 1
  Default branch [main]:

  Install specmint companions for this brain?
    [1] specmint-core      (spec-driven-development companion)
    [2] specmint-tdd       (spec-driven-development with test-driven-development focus)
    [3] core + tdd
    [4] skip
    [5] specmint-core-html (spec-driven-development with canonical SPEC.html)
    [6] specmint-tdd-html  (TDD-focused specs with canonical SPEC.html)
    [7] all
  Choice [4]: 3
Brain created: acme (product-group)
  Path: ~/Projects/acme
  Lobes: 3

Agent skill installed: kluris-acme
  Claude/Codex/Antigravity/etc: /kluris-acme
  Hermes: /skill kluris-acme  (or start with `hermes -s kluris-acme`)
  Created a new Hermes profile later? Run `kluris doctor` to refresh Kluris skills.
The folder kluris just created · product-group defaults
acme/
├── kluris.yml              # gitignored — your local config
├── brain.md                # root directory, auto-generated
├── glossary.md             # domain terms, hand-edited
├── README.md               # usage guide
├── .gitignore
├── projects/
│   ├── map.md              # lobe index, auto-generated
│   └── (your neurons go here)
├── infrastructure/
│   ├── map.md
│   └── (your neurons go here)
└── knowledge/
    ├── map.md
    └── (your neurons go here)

Scaffolded defaults for the product-group brain type. You add, rename, or remove lobes as your team grows.

Every brain is a git repo. Your knowledge is markdown. Nothing is magic.

03  ·  Beat 2 · Teach

Teach the brain what your team knows.

Open your AI agent in a project. Two steps make every future session smoother — first wire kluris in so every coding agent that lands in the repo finds the brain, then have the agent learn the project end-to-end. Lobes are folders you create to group related ideas; neurons are the markdown files inside them. The brain only ever grows with content you approved.

Step 1 · Wire kluris in · runs once per project In your AI agent · in a project
> /kluris-acme setup this project

Surveying CLAUDE.md and AGENTS.md...

CLAUDE.md: missing — propose creating
AGENTS.md: missing — propose creating

Proposed ## Knowledge base section
(same in both files):
──────────────────────
  ## Knowledge base

  Read and write to the
  **acme** brain through kluris
  (never edit brain files by hand).
  Use the /kluris-acme skill —
  search, learn, remember, create.
──────────────────────

[a]pprove  [e]dit  [s]kip: a

✓ CLAUDE.md created
✓ AGENTS.md created (same block)
Step 2 · Learn the project · analyzes code, proposes neurons In your AI agent · in a project
> /kluris-acme learn everything
                      about this project

Reading: src/, package.json, README,
schema/, .github/, docs/...

Proposing 12 neurons across 4 lobes:
  › projects/btb-core/auth-flow.md
  › projects/btb-core/data-model.md
  › projects/btb-core/api-shape.md
  › infrastructure/docker-builds.md
  › knowledge/raw-sql-no-jpa.md
  ... 7 more

Walking through, one at a time:

Neuron 1 / 12
Proposing: projects/btb-core/auth-flow.md
──────────────────────
# Auth flow

Keycloak OIDC. Frontend obtains JWT,
passes it to backend as Bearer token.
Backend validates via JWKS. Refresh
at 80% TTL.

Related: [clerk-vs-keycloak.md]
──────────────────────

[a]pprove  [e]dit  [s]kip: 

Wired

The same ## Knowledge base block goes in CLAUDE.md and AGENTS.md — every coding agent in the repo finds the brain on the way in.

Grounded

The agent only writes what you approved. Each neuron is a markdown file with a clear path, frontmatter, and body — inspectable before it lands.

Compounding

Teach once. Every agent on every laptop reads the same source of truth tomorrow — a real subject matter expert, on demand.

04  ·  Beat 3 · See

See the whole brain.

One command. A local, interactive map you can share.

kluris mri — one self-contained HTML file Terminal
$ kluris mri

MRI complete — /home/user/ngvoicu-sme/brain-mri.html
  Open: file:///home/user/ngvoicu-sme/brain-mri.html
  42 nodes, 242 edges

Open the link in any browser. Commit it, email it,
drop it in Slack — it runs anywhere, no server.
kluris mri root view of a brain — its lobes and the glossary as C4-style boxes with synapse counts on the lines between them, the file tree on the left, and the Find and Recent panels on the right
The root view — each lobe as a box, synapse counts on the lines between them.

The header counts the brain (29 neurons · 242 synapses here), the file tree on the left collapses, and Find on the right searches neurons, paths, lobes, tags, and YAML, with the most recently updated neurons listed beneath. Click a folder to drill in; click a neuron to open it.

kluris mri neuron detail — one neuron open in a modal: back and forward buttons and its title at the top, its path and tags, buttons for the connected neurons, the rendered markdown, and the file tree on the left
The neuron view — rendered markdown on the right, connected neurons as buttons along the top, the file tree on the left.

One click on any neuron box opens it in a modal, fully rendered, with its path, tags and connected-neuron buttons above the text and back and forward buttons to retrace your steps, so you can walk a topic in seconds. This is what agents see — now visible to you.

The MRI opens on the brain's lobes as C4-style boxes, with the synapse counts between them. Click a folder to drill into its sublobes, click a neuron to read it rendered, and use the breadcrumb or back and forward buttons to walk out again. Lines between neurons are synapses — cross-links agents follow to load related context. A pre-digested brain means agents spend far fewer tokens orienting to a codebase than without one.

05  ·  Beat 4 · Use

Ask the brain. Get grounded answers.

Every agent on your team can search and query across the brain. The agent shows you exactly which neurons it read — no hallucinations, no vibe.

search · ranked, in your own words In your AI agent · in a project
> /kluris-acme how does the app refresh its token?

→ kluris search "token refresh" --brain acme

3 result(s) for 'token refresh' in acme

  233  Auth flow
        projects/btb-core/auth-flow.md
        The web app refreshes the access token at
        80% of its lifetime...
  115  Keycloak setup
        infrastructure/keycloak-setup.md
   31  JWT signing key rotation
        knowledge/jwt-rotation.md

→ reading the top hit, section "Token refresh"
/kluris-acme what do we know · natural language Q&A In your AI agent · in a project
> /kluris-acme what do we know about Docker?

Reading:
  infrastructure/docker-builds.md
  infrastructure/environments.md

You build multi-stage Dockerfiles with
BuildKit. Images go to ghcr.io/zeespire/.
Prod uses Coolify on Hetzner with Cloudflare
Tunnel (zero public ports).

Search

Ranked hits across neurons, glossary, and brain.md, scored per ## section, so each hit points at the heading where the answer is. Word forms and accents don't matter. The agent opens only what answers the question.

What do we know

Natural-language Q&A. Ask it anything about the brain; it cites the neurons it read so you can verify.

Context sharing

Onboarding, pairing, code review — every teammate who clones the brain sees the same answer tomorrow.

For anything non-trivial, prefix with /kluris-acme use brain knowledge and codebase and let's ... — write a spec for OAuth sign-in, implement auth — the agent grounds the work in both surfaces: documented decisions and the actual current shape of the code.

+  ·  Bonus · Pair with Specmint
×

Plan with context you didn't have to re-derive.

Kluris is the brain. Specmint turns a feature request into a persistent spec built from deep research and iterative interviews. Pair them and the research phase starts half-done — grounded in your code and the knowledge your team already agreed to.

1 · Shorter research

Forge reads your repo and consults the brain. Decisions the team already made don't get re-discovered from the code.

2 · Sharper interviews

Phase 2 stops asking what the brain already knows. Questions get surgical — the non-obvious trade-offs only you can decide.

3 · Traceable decisions

Every spec decision references a neuron. Six months later you know why — not just what — the code looks the way it does.

/kluris-acme — write a spec, grounded in code + brain In your AI agent · in a project
> /kluris-acme write a spec to add OAuth sign-in with GitHub

Phase 1a · Codebase research
  ● Reading src/auth/ (14 files)
  ● Reading config/GlobalExceptionHandler.kt

Phase 1b · Brain research   ← the Kluris bit
  ● /kluris-acme what do we know about auth
    → knowledge/auth-decisions.md
    → projects/btb-core/auth-flow.md
    → knowledge/jwt-rotation.md

Phase 2 · Interview
  Q1. Brain says you chose Keycloak for cost.
       Should GitHub OAuth live behind Keycloak
       as an IdP, or alongside it?
  Q2. Auth-flow neuron says refresh-at-80% TTL.
       Same cadence for the GitHub session?

Phase 3 · Spec written
  ✓ .specs/github-oauth-signin/SPEC.md
  ✓ 3 phases · 14 tasks · 4 decisions logged
  ✓ Every decision references a neuron

Enable Specmint Companions

Easiest

Enable during kluris create — they ship bundled.

When the wizard asks "Install specmint companions for this brain?", answer [3] core + tdd and the companions are live the moment your brain exists.

Or add them later, per brain

specmint-core

Spec-first

Research · Interview · Spec · Implement. The workflow shown above.

kluris companion add specmint-core

specmint-tdd

Red · Green · Refactor

Same forge flow, with strict TDD — a failing test before any implementation.

kluris companion add specmint-tdd

specmint-core-html

Canonical HTML

Spec-first workflow where .specs/<id>/SPEC.html is the source of truth.

kluris companion add specmint-core-html

specmint-tdd-html

HTML + RGR

Canonical SPEC.html with TEST/IMPL pairs, red-green-refactor state, and TDD log.

kluris companion add specmint-tdd-html

Companions are bundled with kluris — no separate plugin install. Each is a folder (SKILL.md plus its references/, and assets/ for the HTML pair) that kluris copies to ~/.kluris/companions/<name>/. The generated /kluris-<name> skill only references it, and kluris doctor refreshes it.

07  ·  Beat 5 · Grow

Your brain grows with your team.

Add lobes, add neurons, keep going — all through the agent.

/kluris-acme · add a new lobe In your AI agent · in a project
> /kluris-acme add a compliance lobe for SOC2
         and GDPR notes

Proposing new lobe: compliance/
  ✓ will create compliance/map.md
  ✓ will link into brain.md

[a]pprove  [c]ancel: 
/kluris-acme · add a neuron in the new lobe In your AI agent · in a project
> /kluris-acme remember that SOC2 audit evidence
         lives in the compliance-evidence/ bucket,
         rotated yearly

Proposing: compliance/soc2-evidence.md
──────────────────────────────────────
# SOC2 audit evidence

Evidence artifacts live in the
`compliance-evidence/` S3 bucket. Rotation is
annual. Access is restricted to the security team.
──────────────────────────────────────

[a]pprove  [e]dit  [s]kip: 

Lobes are folders, neurons are markdown files inside them — but you don't create them by hand. Ask the agent. It proposes the structure, shows you the diff, and writes it only after you approve. Nesting works the same way: "add a sublobe for the endpoints of acme-api" and the agent puts it in the right place.

Run kluris dream to regenerate maps after structural changes. The agent commits what you approved with kluris commit, which pulls and pushes. Have more than one brain? Each installs as /kluris-<name> and everything above works the same. In the terminal, --brain NAME picks one (kluris asks when you don't); --brain all fans out dream, status, mri, sync and companion.

Together · one brain, many people

Everyone writes to the same brain. Clone it, run kluris register, and every command that opens it keeps it in step: reads pull your teammates’ commits first. The agent reads, writes what you approved, then runs kluris commit, which pulls, commits exactly those files and pushes. Edits to different files, the generated maps, dates, related and tags, and changes to different parts of a neuron merge on their own.

When two people changed the same line, the merge waits for a person: your file stays as you wrote it, nothing is pushed, and there are never conflict markers: the agent shows you both versions, asks which to keep, writes it and finishes the merge with kluris commit --merge. kluris dream commits the brain’s own housekeeping, and commits left waiting go out in one background push.

the same line, settled by a person In your AI agent · in a project
→ kluris commit --brain acme --paths knowledge/auth.md
Committed 0eefccb in acme: kluris: update knowledge/auth.md
  knowledge/auth.md
kluris: acme: 1 conflict (knowledge/auth.md) in merge e46c333aabf0; 1 commit to push

  yours     Access tokens live 30 minutes, signed with RS256.
  teammate  Access tokens live 20 minutes, signed with RS256.
Which one do we keep? [y]ours  [t]eammate’s: t

→ kluris commit --brain acme --merge e46c333aabf0 --paths knowledge/auth.md
Committed c981616 in acme: kluris: sync (resolved)
  knowledge/auth.md
kluris: acme: pushed
08  ·  Beat 6 · Self-improve

Let the brain review itself.

Ask the agent to audit the brain. It reads across every neuron, spots connections you never wrote, and proposes new synapses — you approve each one before anything changes.

the brain reviewing itself In your AI agent · in a project
> /kluris-acme review this brain and create more synapses

Reading 34 neurons across 3 lobes...

Found 14 connections you haven't written yet:
  › projects/btb/auth-flow.md       ↔ knowledge/jwt-rotation.md
  › infrastructure/docker-builds.md ↔ infrastructure/environments.md
  › knowledge/use-raw-sql.md        ↔ projects/btb/reporting.md
  › projects/btb/import.md          ↔ infrastructure/keycloak-setup.md
  ... 10 more

Proposed update · projects/btb/auth-flow.md
──────────────────────────────────────
  ---
  title: Auth flow
  related:
    - ./clerk-vs-keycloak.md
    - ../knowledge/jwt-rotation.md   (new)
  ---
──────────────────────────────────────

[a]pprove all  [o]ne-by-one  [s]kip: o

Stepping through 14 proposed synapses...

✓ 12 applied · 2 skipped
✓ bidirectional links written
✓ maps regenerated

Grounded

The agent only proposes synapses between neurons that already exist — no hallucinated references.

Reviewed

You approve every change — one-shot, one-by-one, or skip — before anything is written to disk.

Compounding

Re-run it monthly. As the brain grows, the agent finds new patterns and your knowledge graph gets denser.

09  ·  Beat 7 · Capture session

Close the loop on every pairing session.

At the end of a long pairing session — research, debugging, decisions, gotchas — sweep the conversation into the brain in one step. The agent replays the chat, pulls every brain-worthy fact, and walks you through proposed neurons one at a time. No retyping. Same approval flow.

/kluris-acme remember from this session · the sweep In your AI agent · in a project
> /kluris-acme remember everything
                      from this session

Replaying the conversation...
Identifying brain-worthy items:

  › Decision: use TIMESTAMPTZ for every timestamp column
  › Convention: API errors must include error_code alongside message
  › Gotcha: Cloudflare Tunnel blocks port 587 — use 465 SMTPS
  › Stakeholder: legal flagged session-token storage for review
  ... 3 more candidates

Routing each to the right lobe...

Item 1 / 7
Proposing: knowledge/timestamps-tz.md
──────────────────────────────────────
# Use TIMESTAMPTZ for every timestamp column

Decided 2026-05-12. Standardized on
TIMESTAMPTZ over TIMESTAMP in every
schema change. Reason: avoids the
silent UTC drift gotcha when servers
or clients sit in different timezones.

Related: [../projects/btb-core/data-model.md]
──────────────────────────────────────

[a]pprove  [e]dit  [s]kip: a

✓ 5 of 7 captured, 2 skipped, 0 edited
→ kluris commit · kluris: acme: pushed

No retyping

You don't repeat decisions to the agent — it already heard them. The sweep extracts what's worth keeping and skips ephemeral debugging.

Same approval

Each candidate goes through the standard approve · edit · skip flow. Nothing lands without your sign-off.

Compounds

Tomorrow's agents start their session with what last week's agents learned. Pairing sessions become permanent team knowledge.

Or capture a single decision in one line: /kluris-acme remember we chose raw SQL over JPA. Same flow, just narrower.

10  ·  The shortest recap you'll read

Your AI agents, finally on your team.

Kluris is a tiny idea that compounds: a git repo becomes a brain, a brain becomes a subject matter expert, and that expert shows up in every agent on every laptop every morning — grounded in what your team actually knows.

What you installed

One small binary.

One install line, no admin rights  ·  nothing to host, nothing to log into.

What you built

A living brain.

Lobes  ·  neurons  ·  synapses  ·  all markdown, all git-tracked.

What changed

Your agents, smarter.

A skill in ~/.agents/skills/ for Cursor, Codex, Devin, OpenCode, Kilo Code, Junie and others, plus its own copy for Claude Code, Hermes, Antigravity CLI and Copilot.

Want to see the whole loop in action?

See a real brain built, screenshot by screenshot.

22 frames from a real session: create the brain · add the first project with your AI agent · explore it with the MRI · review the brain · use it daily for features and answers. Repeat phases 2 and 3 for every project in the same domain.

Open the walkthrough

Start now

From zero to a smarter team.

start here Terminal
$ curl -fsSL https://kluris.ngvoicu.dev/install.sh | sh   # Windows: irm https://kluris.ngvoicu.dev/install.ps1 | iex
# open a new terminal, then:
$ kluris create                         # new brain from scratch
  # — or — 
$ git clone git@github.com:team/brain.git ~/brains/team && kluris register ~/brains/team   # join a team brain
→ agent skills auto-install · open any repo · type /kluris-acme in chat

Open source · MIT · Free forever · Yours, always.

kluris · a guided tour  ·  kluris.ngvoicu.dev  ·  source

Use ← → or Space to navigate · 1–9 to jump.