Skip to content
Back to search

Klear-Team-Brain

Turn your team's AI coding sessions, GitHub code, and docs into one shared, searchable memory — a self-hosted git truth store you query right from your editor over MCP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/asklear--klear-team-brain/badge.svg)](/listings/asklear--klear-team-brain)

HTML

<a href="/listings/asklear--klear-team-brain"><img src="/api/listings/asklear--klear-team-brain/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**Prerequisites:** Node 22+, and an MCP-capable editor/CLI (Claude Code or Codex) to ask from.

> **No npm/SaaS install — it's self-hosted by design.** There's no public package or hosted service: clone this repo to run the server (or to trial it locally), and your teammates pull the client straight from *your* server with `curl …/get | bash` — see [Deploy for your team](#deploy-for-your-team).

Try it locally first (≈5 min — no VPS, no HTTPS, no invite token)

Want to kick the tires before standing up a server? Run the whole thing on your own machine as a single user:

git clone https://github.com/Asklear/Klear-Team-Brain.git && cd Klear-Team-Brain
npm install
npm run quickstart        # one-time: mint a local identity + token, point the client at localhost, wire up MCP
npm run server            # starts the truth store on http://127.0.0.1:8787 — leave this running

Then, **in a second terminal**, capture your local sessions:

npm run sync -- --once    # capture once (or `npm run sync` to keep watching in the background)

Now ask from your editor, or open `http://127.0.0.1:8787/` to browse. Everything stays on your machine. Prefer a containerized server? Use `docker compose up -d` — see [DEPLOY.md](./DEPLOY.md#docker).

Deploy for your team

1. **Stand up a server** (one small VPS) — manually or with one command via `docker compose`. See [DEPLOY.md](./DEPLOY.md) — install Node, clone, set `TRUTH_DIR`, add a roster + tokens, put HTTPS in front, run as a service. 2. **Onboard each member** — point the client at your server:

   curl -fsSL https://your-server.example.com/get | bash   # downloads the client + registers the `brain` command
   brain join <YOUR_INVITE_TOKEN>                           # verify + pick workspaces + wire up MCP + first sync + install resident

3. **Start using it** — ask from your editor, or open `https://your-server.example.com/` to browse the dashboard.

Once onboarded, the collector watches your AI sessions in the background and uploads each one as it stabilizes — **no manual steps after that.**

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 224 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Klear-Team-Brain
  2. [![CI](https://github.com/Asklear/Klear-Team-Brain/actions/workflows/ci.yml/badge.svg)](https://github.com/Asklear/Klear-Team-Brain/actions/workflows/ci.yml)
  3. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
  4. [![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org)
  5. > **Your team's collective memory for AI-assisted coding.** Self-hosted, ultra-light, zero extra effort for the people doing the work.
  6. English | [中文](./README.zh-CN.md)
  7. ---
  8. ## The problem
  9. Your team codes with Claude Code / Codex — but **the context that actually matters (the reasoning, the why-it-changed, the dead ends) is trapped in each person's local AI chat, and it's gone the moment they close the tab.** So:
  10. - *"Why was this feature designed this way?"* — not in any PR; the discussion happened inside someone's chat, not the commit message.
  11. - *"Who's working on this refactor, and how far along is it?"* — you ask around, or wait for standup.
  12. - A teammate goes on leave or quits, and **last week's reasoning leaves with them.**
  13. Knowledge depends on "ask the right person." The moment they're busy or gone, the context breaks.
  14. **Klear-Team-Brain automatically pools your whole team's AI sessions into one shared memory**, fused with live GitHub code state and your team's docs. Then you ask straight from your editor, or browse in a web UI:
  15. > *"Where did the auth refactor land?"*
  16. > *"How was the billing schema decided?"*
  17. > *"Who's been touching the ETL this week?"*
  18. You get an answer synthesized across the team's **sessions + code + docs**, with citations. **People doing the work do nothing; people who want to understand just ask — or open the dashboard.**
  19. ![Truth-store overview — team progress, what needs attention, docs, and activity at a glance](assets/gui-overview.png)
  20. ---
  21. ## Highlights
  22. - **Zero-effort capture** — everyone keeps using CC/Codex; a background collector flows sessions into the memory automatically, no manual steps.
  23. - **Two ways to query** — ① ask in natural language from your editor (MCP); ② browse a web dashboard (filter sessions by person/repo/time, see progress and usage stats).
  24. - **Ultra-light, self-hosted** — the server is just **one git repo + one Node process + a static frontend**: no database, no queue, no vector store. **One small VPS (runs fine on low memory)** is enough. Queries run on `git grep` with **zero server-side LLM calls** — the understanding happens in the agent inside your editor.
  25. - **Privacy-first** — only allowlisted directories upload; secrets are redacted client-side before upload; all data stays on your own infrastructure.
  26. ---
  27. ## Quick start
  28. **Prerequisites:** Node 22+, and an MCP-capable editor/CLI (Claude Code or Codex) to ask from.
  29. > **No npm/SaaS install — it's self-hosted by design.** There's no public package or hosted service: clone this repo to run the server (or to trial it locally), and your teammates pull the client straight from *your* server with `curl …/get | bash` — see [Deploy for your team](#deploy-for-your-team).
  30. ### Try it locally first (≈5 min — no VPS, no HTTPS, no invite token)
  31. Want to kick the tires before standing up a server? Run the whole thing on your own machine as a single user:
  32. ```bash
  33. git clone https://github.com/Asklear/Klear-Team-Brain.git && cd Klear-Team-Brain
  34. npm install
  35. npm run quickstart # one-time: mint a local identity + token, point the client at localhost, wire up MCP
  36. npm run server # starts the truth store on http://127.0.0.1:8787 — leave this running
  37. ```
  38. Then, **in a second terminal**, capture your local sessions:
  39. ```bash
  40. npm run sync -- --once # capture once (or `npm run sync` to keep watching in the background)
  41. ```
  42. Now ask from your editor, or open `http://127.0.0.1:8787/` to browse. Everything stays on your machine. Prefer a containerized server? Use `docker compose up -d` — see [DEPLOY.md](./DEPLOY.md#docker).
  43. ### Deploy for your team
  44. 1. **Stand up a server** (one small VPS) — manually or with one command via `docker compose`. See [DEPLOY.md](./DEPLOY.md) — install Node, clone, set `TRUTH_DIR`, add a roster + tokens, put HTTPS in front, run as a service.
  45. 2. **Onboard each member** — point the client at your server:
  46. ```bash
  47. curl -fsSL https://your-server.example.com/get | bash # downloads the client + registers the `brain` command
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 74 on GitHub
  48. brain join <YOUR_INVITE_TOKEN> # verify + pick workspaces + wire up MCP + first sync + install resident
  49. ```
  50. 3. **Start using it** — ask from your editor, or open `https://your-server.example.com/` to browse the dashboard.
  51. Once onboarded, the collector watches your AI sessions in the background and uploads each one as it stabilizes — **no manual steps after that.**
  52. ---
  53. ## Two ways to query
  54. ### ① Ask from your editor (MCP)
  55. With MCP wired up, ask in plain language inside CC / Codex (*"where did the auth refactor land?"*). The agent treats the memory as a **read-only folder** and uses a handful of Unix-style primitives to locate, read, and synthesize — all tied together by a truth-store-relative `path`:
  56. | Tool | What it does |
  57. |---|---|
  58. | `grep` | Search content (regex full-text via git grep). Defaults to redacted transcripts; `raw=true` includes raw jsonl. |
  59. | `find` | Find files by name/glob (complementary to grep: one searches content, one searches names). |
  60. | `read` | Read any file by path (paginate large files with offset/limit). |
  61. | `ls` | Inspect structure: which spaces exist, branches, session counts. |
  62. | `sessions` | Find sessions by person + work time (who did what, in a given window). |
  63. | `stats` | Aggregate token usage / session counts / turns by day/week/person/repo/tool. |
  64. | `log` | Activity timeline (the git history; narrow by space/author/since). |
  65. | `read_github` | Reach out to GitHub / GitLab / Gitea (incl. self-hosted) for live code state or a file's current contents (code itself isn't stored). |
  66. Server-side queries run via `git grep` / `git ls-files` / `git log` / `fs` — **execFile, no shell, locked inside `TRUTH_DIR`, read-only** — with **zero server-side LLM calls**.
  67. > **Wiring other editors:** the MCP server is a stdio server; the command is always `<node> <install-dir>/mcp/server.mjs` (`brain mcp` prints your exact path). Add that as a stdio MCP server in Claude Code, Codex, or any MCP-capable client (Gemini CLI / Cursor / Cline / opencode…).
  68. >
  69. > **Remote / cloud agents (HTTP transport):** an agent that can't run the local stdio binary can mount the memory over HTTP instead — same tools, no local install. Point any MCP client at `POST https://your-server/mcp` with your member token as a `Bearer` header.
  70. >
  71. > Claude Code:
  72. > ```bash
  73. > claude mcp add --transport http team-brain https://your-server/mcp \
  74. > --header "Authorization: Bearer <your-member-token>"
  75. > ```
  76. > Cursor / Cline / any `mcp.json`:
  77. > ```json
  78. > { "mcpServers": { "team-brain": {
  79. > "type": "http",
  80. > "url": "https://your-server/mcp",
  81. > "headers": { "Authorization": "Bearer <your-member-token>" }
  82. > } } }
  83. > ```
  84. > Smoke-test from a shell (the endpoint accepts plain JSON-RPC — no special `Accept` header needed):
  85. > ```bash
  86. > curl -s https://your-server/mcp -H "Authorization: Bearer <token>" \
  87. > -H "Content-Type: application/json" \
  88. > -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
  89. > ```
  90. > It's a stateless, one-shot endpoint (POST in, JSON out — no session, no server-side LLM); multi-turn context stays on the calling agent's side.
  91. ### ② Browse the web UI
  92. The server hosts a **static dashboard** at `/` (nothing extra to deploy) — for people who'd rather scan than type: see overall team progress, filter sessions by person/repo/time, view token-usage and activity stats, and skim mirrored docs.
  93. **Browse sessions** — filter by person/repo/time, sorted by recent activity:
  94. ![Browse sessions — filter by person / repo / time](assets/gui-sessions.png)
  95. **Usage stats** — aggregate tokens, sessions, and turns by day/week/person/repo/tool:
  96. ![Stats — aggregate tokens / sessions / turns by work time](assets/gui-stats.png)
  97. ---
  98. ## How it works
  99. ```
  100. each machine (client) your server (self-hosted)
  101. ┌────────────────────────┐ ┌──────────────────────────────────┐
  102. │ ① collector client/sync │ gzip+token │ ② server/server.mjs (HTTP, HTTPS │
  103. │ resident, watches AI │ ──────────▶ │ via a proxy like Caddy) │
  104. │ sessions; gated to the │ │ /ingest → git truth store │
  105. │ allowlisted circle │ │ TRUTH_DIR + 4h repo poll → │
  106. │ │ │ code-state │
  107. │ query A: ask in editor │ search+fetch│ /grep /find /read /ls /log │
  108. │ query B: open the web UI │ ◀────────── │ + static dashboard hosted at / │
  109. └────────────────────────┘ └──────────────────────────────────┘
  110. ```
  111. The memory is a single **git repository** fusing three sources — **each captured where it naturally lives:**
  112. | What you want to know | Lives mainly in | How it enters the memory |
  113. |---|---|---|
  114. | **Progress · reasoning** | CC/Codex sessions | distilled + redacted, stored as full-text transcript |
  115. | **Code state** | GitHub / GitLab / Gitea (incl. self-hosted) | not stored; fetched on demand + 4h poll into `code-state` |
  116. | **Goals · decisions (human-written)** | Team docs (Feishu/Lark wiki · Notion · Google Docs) | one-way mirror of doc bodies; grep/read it, edit at the source |
  117. > **Design trade-off:** only the "truth" (raw material + metadata) is kept clean and complete — because it's expensive and can't be rebuilt; "views" (queries / indexes / the dashboard) are swappable and throwaway. Sessions enter **distilled** (inline images stripped, giant tool outputs truncated — signal, not bytes); the byte-exact original stays on the producer's machine (`~/.codex` / `~/.claude`).
  118. ---
  119. ## Privacy & security
  120. - **Scope gate:** a session is uploaded only if its working directory is under your machine's `upload_folders` allowlist — inside the circle is shared by default, outside is private by default.
  121. - **Redaction:** secrets/tokens + home-directory paths are stripped **client-side before upload**, with second passes when the server projects the `.md` and at the `/read` exit. Each producer can also keep a **personal redaction wordlist** (client names, code names…) that's stripped before anything leaves their machine.
  122. - **Producer transparency & control:** run `brain viewer` for a local console (127.0.0.1, only you can see it) that shows, per session, exactly what was uploaded vs skipped — and lets you exclude individual sessions, **retract** ones already in the shared store, or add personal redaction terms.
  123. - **Credentials never stored:** member tokens, GitHub PATs, and doc-source credentials all live server-side and are gitignored; the roster (no secrets) can be committed.
  124. - **The memory is the whole value — never push it to a public remote, and back it up.** Self-host on infrastructure open only to your circle.
  125. > **Status:** early, self-hosted, single-tenant. You run your own server; nothing leaves your infrastructure.
  126. ---
  127. ## Optional: mirror team docs (Lark / Feishu)
  128. If your team keeps human-written docs (goals, decisions, notes) in a Lark/Feishu **wiki**, the server can one-way **mirror** those doc bodies into the memory, so the asking agent can `grep`/`read` them alongside sessions and code. Set it up once:
  129. 1. **Create a custom app** in the Lark/Feishu developer console (an *enterprise custom app*); note its **App ID** + **App Secret**.
  130. 2. **Enable read scopes** under *Permissions*: `docx:document.readonly`, `drive:drive.readonly`, `wiki:wiki.readonly`, then publish a version and have an admin approve it. (No search scope needed — the mirror is searched locally.)
  131. 3. **Authorize the app on the whole wiki — the non-obvious step, and the one that actually gates access.** A tenant-token app can only see wikis it's been explicitly added to, and the console won't let you add an app directly. Instead:
  132. 1. Create a group / chat.
  133. 2. Add **this app's bot** to that group — it must be the bot of the *same* App ID (adding the wrong bot is the most common failure).
  134. 3. In the wiki, go to **Settings → Members → Roles & permissions → Admins → Add admin** and add **that group**.
  135. The app then has read access to the *entire* wiki (propagation takes ~1–2 minutes).
  136. 4. **Drop credentials on the server:** copy `feishu.example.yaml` → `feishu.yaml` (secret → gitignored), fill in `app_id` / `app_secret`, and restart. Leave it out entirely and the doc layer stays quietly off.
  137. 5. **Verify:** after a poll cycle, the docs appear under `feishu/<wiki>__<id>/…` in the memory, searchable via `grep`.
  138. > China Feishu (`open.feishu.cn`) and international Lark (`open.larksuite.com`) are isolated platforms — create the app on whichever one your team uses. Create a **new** wiki later? Repeat step 3 for it, or the brain won't see it.
  139. ### Other doc sources (Notion · Google Docs)
  140. Doc mirroring is **provider-pluggable** — the same sync engine (`server/docsync.mjs`) backs every source, so each one is just a small adapter (`core/<provider>.mjs` + `server/<provider>docs.mjs`). Two more ship today, both gated by their own `*.yaml` (leave it out → that layer stays off) and both following the same "share with the bot, then it mirrors" model:
  141. - **Notion** — create an *internal integration* at <https://www.notion.so/my-integrations> (read-only); **share** the pages/databases with it (page → ••• → *Connections*); copy `notion.example.yaml` → `notion.yaml`, fill `api_token`, restart. Pages land under `notion/<workspace>/…`.
  142. - **Google Docs** — create a *service account* (enable the Drive API), download its JSON key, and **share** the docs/folders with the service account's email (read-only); copy `google.example.yaml` → `google.yaml`, point it at the key, restart. Docs land under `google/<workspace>/…`. (Auth is a self-signed JWT — no extra SDK.)
  143. Unshared pages/docs stay invisible (the share is the real access gate); sub-pages and folder contents inherit. After a poll cycle everything is searchable via `grep`.
  144. > Confluence can follow the same adapter shape — contributions welcome.
  145. ---
  146. ## Changelog
  147. What changed in each release: [Changelog](./docs/CHANGELOG.en.md) ([中文](./docs/CHANGELOG.zh-CN.md)).
  148. ## Non-goals
  149. It aggregates and helps you understand what's in CC/Codex sessions + GitHub + docs. It is **not** an IM, a project manager, or a code host, and doesn't replace them.
  150. ## Contributing
  151. Issues and PRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) and [SECURITY.md](./SECURITY.md). This project is developed internally and mirrored here; external contributions are reviewed and merged upstream, then flow back out.
  152. ## License
  153. [Apache-2.0](./LICENSE) © Asklear

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.