GitHub All Languages Weekly Trending

CloakHQ/CloakBrowser

Stealth Chromium that passes every bot detection test. Drop-in Playwright replacement with source-level fingerprint patches. 30/30 tests passed.

Stealth Chromium that passes every bot detection test.

Not a patched config. Not a JS injection. A real Chromium binary with fingerprints modified at the C++ source level. Antibot systems score it as a normal browser — because it is a normal browser.

Cloudflare Turnstile — 3 live tests passing (headed mode, macOS)

Drop-in Playwright/Puppeteer replacement for Python and JavaScript.
Same API, same code — just swap the import. 3 lines of code, 30 seconds to unblock.

49 source-level C++ patches — canvas, WebGL, audio, fonts, GPU, screen, WebRTC, network timing, automation signals, CDP input behavior
humanize=True — human-like mouse curves, keyboard timing, and scroll patterns. One flag, behavioral detection passes
0.9 reCAPTCHA v3 score — human-level, server-verified
Passes Cloudflare Turnstile, FingerprintJS, BrowserScan — tested against 30+ detection sites
Auto-updating binary — background update checks, always on the latest stealth build
pip install cloakbrowser or npm install cloakbrowser — binary auto-downloads, zero config
Free and open source — no subscriptions, no usage limits

Try it now — no install needed:

docker run --rm cloakhq/cloakbrowser cloaktest

Python:

from cloakbrowser import launch

browser = launch()
page = browser.new_page()
page.goto("https://protected-site.com")  # no more blocks
browser.close()

JavaScript (Playwright):

import { launch } from 'cloakbrowser';

const browser = await launch();
const page = await browser.newPage();
await page.goto('https://protected-site.com');
await browser.close();

Also works with Puppeteer: import { launch } from 'cloakbrowser/puppeteer' (details)

Install

Python:

pip install cloakbrowser

JavaScript / Node.js:

# With Playwright
npm install cloakbrowser playwright-core

# With Puppeteer
npm install cloakbrowser puppeteer-core

On first run, the stealth Chromium binary is automatically downloaded (~200MB, cached locally).

Optional: Auto-detect timezone/locale from proxy IP:

pip install cloakbrowser[geoip]

Migrating from Playwright? One-line change:

- from playwright.sync_api import sync_playwright
- pw = sync_playwright().start()
- browser = pw.chromium.launch()
+ from cloakbrowser import launch
+ browser = launch()

page = browser.new_page()
page.goto("https://example.com")
# ... rest of your code works unchanged

⭐ Star to show support — Watch releases to get notified when new builds drop.

Browser Profile Manager

Self-hosted alternative to Multilogin, GoLogin, and AdsPower. Create browser profiles with unique fingerprints, proxies, and persistent sessions. Launch and interact with them in your browser via noVNC.

docker run -p 8080:8080 -v cloakprofiles:/data cloakhq/cloakbrowser-manager

Open http://localhost:8080. Create a profile. Click Launch. Done.

→ CloakBrowser Manager — free, open source (MIT)

Latest: v0.3.28 (Chromium 146.0.7680.177.4)

launch_context_async() — async counterpart to launch_context(). Forwards kwargs to browser.new_context() for storage_state, permissions, extra_http_headers without a persistent profile folder.
JS contextOptions escape hatch — forward arbitrary options (including storageState) to Playwright's newContext() from launchContext() / launchPersistentContext().
Native SOCKS5 proxy — proxy="socks5://user:pass@host:port" works directly in all launch functions, Python + JS. QUIC/HTTP3 tunnels through SOCKS5 via UDP ASSOCIATE.
Chromium 146 upgrade — rebased all patches from 145.0.7632.x to 146.0.7680.177
57 fingerprint patches — additional detection-vector coverage (WebAuthn, AAC audio, window position) and WebGL/canvas consistency fixes
WebRTC IP spoofing — --fingerprint-webrtc-ip=auto resolves your proxy's exit IP and spoofs WebRTC ICE candidates. Auto-injected when using geoip=True (no extra network call)
Proxy signal removal — DNS/connect/SSL timing zeroed, proxy cache headers stripped, Proxy-Connection header leak removed
cloakserve CDP multiplexer — rewritten as a multi-connection CDP proxy with per-connection fingerprint seeds
Humanize CDP isolation — keyboard events now use isolated worlds and trusted dispatch for better behavioral stealth
humanize=True — one flag makes all mouse, keyboard, and scroll interactions behave like a real user. Bézier curves, per-character typing, realistic scroll patterns
Stealthy with zero flags — binary auto-generates a random fingerprint seed at startup. No configuration required
Timezone & locale from proxy IP — launch(proxy="...", geoip=True) auto-detects timezone and locale
Persistent profiles — launch_persistent_context() keeps cookies and localStorage across sessions, bypasses incognito detection

See the full CHANGELOG.md for details.

Why CloakBrowser?

Config-level patches break — playwright-stealth, undetected-chromedriver, and puppeteer-extra inject JavaScript or tweak flags. Every Chrome update breaks them. Antibot systems detect the patches themselves.
CloakBrowser patches Chromium source code — fingerprints are modified at the C++ level, compiled into the binary. Detection sites see a real browser because it is a real browser.
Source-level stealth — C++ patches handle fingerprints (GPU, screen, UA, hardware reporting) at the binary level. No JavaScript injection, no config-level hacks. Most stealth tools only patch at the surface.
Same behavior everywhere — works identically local, in Docker, and on VPS. No environment-specific patches or config needed.
Works with AI agents and automation frameworks — drop-in stealth for browser-use, Crawl4AI, Scrapling, Stagehand, LangChain, Selenium, and more. See integrations.

CloakBrowser doesn't solve CAPTCHAs — it prevents them from appearing. No CAPTCHA-solving services, no proxy rotation built in — bring your own proxies, use the Playwright API you already know.

Test Results

All tests verified against live detection services. Last tested: Apr 2026 (Chromium 146).

Detection Service	Stock Playwright	CloakBrowser	Notes
reCAPTCHA v3	0.1 (bot)	0.9 (human)	Server-side verified
Cloudflare Turnstile (non-interactive)	FAIL	PASS	Auto-resolve
Cloudflare Turnstile (managed)	FAIL	PASS	Single click
ShieldSquare	BLOCKED	PASS	Production site
FingerprintJS bot detection	DETECTED	PASS	demo.fingerprint.com
BrowserScan bot detection	DETECTED	NORMAL (4/4)	browserscan.net
bot.incolumitas.com	13 fails	1 fail	WEBDRIVER spec only
deviceandbrowserinfo.com	6 true flags	0 true flags	`isBot: false`
`navigator.webdriver`	`true`	`false`	Source-level patch
`navigator.plugins.length`	0	5	Real plugin list
`window.chrome`	`undefined`	`object`	Present like real Chrome
UA string	`HeadlessChrome`	`Chrome/146.0.0.0`	No headless leak
CDP detection	Detected	Not detected	`isAutomatedWithCDP: false`
TLS fingerprint	Mismatch	Identical to Chrome	ja3n/ja4/akamai match
		Tested against 30+ detection sites

Proof

reCAPTCHA v3 score 0.9 — server-side verified (human-level)

Cloudflare Turnstile non-interactive challenge — auto-resolved

BrowserScan bot detection — NORMAL (4/4 checks passed)

FingerprintJS web-scraping demo — data served, not blocked

deviceandbrowserinfo.com behavioral bot detection — "You are human!" with humanize=True (24/24 signals passed)

Comparison

Feature	Playwright	playwright-stealth	undetected-chromedriver	Camoufox	CloakBrowser
reCAPTCHA v3 score	0.1	0.3-0.5	0.3-0.7	0.7-0.9	0.9
Cloudflare Turnstile	Fail	Sometimes	Sometimes	Pass	Pass
Patch level	None	JS injection	Config patches	C++ (Firefox)	C++ (Chromium)
Survives Chrome updates	N/A	Breaks often	Breaks often	Yes	Yes
Maintained	Yes	Stale	Stale	Unstable	Active
Browser engine	Chromium	Chromium	Chrome	Firefox	Chromium
Playwright API	Native	Native	No (Selenium)	No	Native

How It Works

CloakBrowser is a thin wrapper (Python + JavaScript) around a custom-built Chromium binary:

You install → pip install cloakbrowser or npm install cloakbrowser
First launch → binary auto-downloads for your platform (Chromium 146)
Every launch → Playwright or Puppeteer starts with our binary + stealth args
You write code → standard Playwright/Puppeteer API, nothing new to learn

The binary includes 49 source-level patches covering canvas, WebGL, audio, fonts, GPU, screen properties, WebRTC, network timing, hardware reporting, automation signal removal, and CDP input behavior mimicking.

These are compiled into the Chromium binary — not injected via JavaScript, not set via flags.

Binary downloads are verified with SHA-256 checksums to ensure integrity.

API

`launch()`

from cloakbrowser import launch

# Basic — headless, default stealth config
browser = launch()

# Headed mode (see the browser window)
browser = launch(headless=False)

# With proxy (HTTP or SOCKS5)
browser = launch(proxy="http://user:pass@proxy:8080")
browser = launch(proxy="socks5://user:pass@proxy:1080")

# With proxy dict (bypass, separate auth fields)
browser = launch(proxy={"server": "http://proxy:8080", "bypass": ".google.com", "username": "user", "password": "pass"})

# With extra Chrome args
browser = launch(args=["--disable-gpu"])

# With timezone and locale (sets binary flags — no detectable CDP emulation)
browser = launch(timezone="America/New_York", locale="en-US")

# Auto-detect timezone/locale from proxy IP (requires: pip install cloakbrowser[geoip])
# Also auto-injects --fingerprint-webrtc-ip to prevent WebRTC IP leaks (no extra cost)
# Note: makes HTTP calls through your proxy to resolve exit IP (ipify.org, checkip.amazonaws.com)
browser = launch(proxy="http://proxy:8080", geoip=True)

# Explicit timezone/locale always win over auto-detection
browser = launch(proxy="http://proxy:8080", geoip=True, timezone="Europe/London")

# WebRTC IP spoofing only (no geoip dep needed — resolves exit IP via HTTP call through proxy)
browser = launch(proxy="http://proxy:8080", args=["--fingerprint-webrtc-ip=auto"])

# Explicit WebRTC IP (no network call)
browser = launch(proxy="http://proxy:8080", args=["--fingerprint-webrtc-ip=1.2.3.4"])

# Human-like mouse, keyboard, and scroll behavior
browser = launch(humanize=True)

# With slower, more deliberate movements
browser = launch(humanize=True, human_preset="careful")

# Without default stealth args (bring your own fingerprint flags)
browser = launch(stealth_args=False, args=["--fingerprint=12345"])

Returns a standard Playwright Browser object. All Playwright methods work: new_page(), new_context(), close(), etc.

`launch_async()`

import asyncio
from cloakbrowser import launch_async

async def main():
    browser = await launch_async()
    page = await browser.new_page()
    await page.goto("https://example.com")
    print(await page.title())
    await browser.close()

asyncio.run(main())

`launch_context()`

Convenience function that creates browser + context in one call with user agent, viewport, locale, and timezone:

from cloakbrowser import launch_context

context = launch_context(
    user_agent="Custom UA",
    viewport={"width": 1920, "height": 1080},
    locale="en-US",
    timezone="America/New_York",
)
page = context.new_page()
page.goto("https://protected-site.com")
context.close()

Extra kwargs are forwarded to Playwright's browser.new_context() — use this for storage_state, permissions, extra_http_headers, etc. without needing a persistent profile folder:

from cloakbrowser import launch_context

# Restore a saved session (cookies, localStorage) from a JSON file
context = launch_context(storage_state="state.json")
page = context.new_page()
page.goto("https://example.com")
# Save state back for next run
context.storage_state(path="state.json")
context.close()

`launch_context_async()`

Async counterpart to launch_context(). Same signature and kwargs forwarding:

import asyncio
from cloakbrowser import launch_context_async

async def main():
    ctx = await launch_context_async(storage_state="state.json")
    page = await ctx.new_page()
    await page.goto("https://example.com")
    await ctx.storage_state(path="state.json")
    await ctx.close()

asyncio.run(main())

`launch_persistent_context()`

Same as launch_context(), but with a persistent user profile. Cookies, localStorage, and cache persist across sessions.

Use this when you need to:

Stay logged in across runs (cookies/sessions survive restarts)
Bypass incognito detection (some sites flag empty, ephemeral profiles)
Load Chrome extensions (extensions only work from a real user data dir)
Build natural browsing history (cached fonts, service workers, IndexedDB accumulate over time, making the profile look more realistic)

from cloakbrowser import launch_persistent_context

# First run — creates the profile
ctx = launch_persistent_context("./my-profile", headless=False)
page = ctx.new_page()
page.goto("https://protected-site.com")
ctx.close()  # profile saved

# Next run — cookies, localStorage restored automatically
ctx = launch_persistent_context("./my-profile", headless=False)

# Load Chrome extensions
ctx = launch_persistent_context(
    "./my-profile",
    headless=False,
    extension_paths=["./my-extension"],
)

Supports all the same options as launch_context(): proxy, user_agent, viewport, locale, timezone, color_scheme, geoip, extension_paths.

Async version: launch_persistent_context_async().

Storage quota and detection tradeoff: By default, the binary normalizes storage quota to pass FingerprintJS, which blocks persistent contexts that report non-incognito quota values. This means detection services that penalize incognito mode (like BrowserScan's notPrivate check, -10 points) will still flag it. If your target site penalizes incognito but doesn't use FingerprintJS, set a higher quota to appear as a regular profile:

ctx = launch_persistent_context("./my-profile", args=["--fingerprint-storage-quota=5000"])

Quota setting	FingerprintJS	BrowserScan `notPrivate`
Default (auto, ~500MB)	PASS	-10 (flagged as incognito)
`--fingerprint-storage-quota=5000`	May trigger detection	PASS (appears non-incognito)

CLI

Pre-download the binary or check installation status from the command line:

python -m cloakbrowser install      # Download binary with progress output
python -m cloakbrowser info         # Show version, path, platform
python -m cloakbrowser update       # Check for and download newer binary
python -m cloakbrowser clear-cache  # Remove cached binaries

Utility Functions

from cloakbrowser import binary_info, clear_cache, ensure_binary

# Check binary installation status
print(binary_info())
# {'version': '146.0.7680.177.3', 'platform': 'linux-x64', 'installed': True, ...}

# Force re-download
clear_cache()

# Pre-download binary (e.g., during Docker build)
ensure_binary()

JavaScript / Node.js API

CloakBrowser ships a TypeScript package with full type definitions. Choose Playwright or Puppeteer — same stealth binary underneath.

Playwright (default)

import { launch, launchContext, launchPersistentContext } from 'cloakbrowser';

// Basic
const browser = await launch();

// With options
const browser = await launch({
  headless: false,
  proxy: 'http://user:pass@proxy:8080',
  args: ['--fingerprint=12345'],
  timezone: 'America/New_York',
  locale: 'en-US',
  humanize: true,
});

// Convenience: browser + context in one call
const context = await launchContext({
  userAgent: 'Custom UA',
  viewport: { width: 1920, height: 1080 },
  locale: 'en-US',
  timezone: 'America/New_York',
});
const page = await context.newPage();

// Persistent profile — cookies/localStorage survive restarts, avoids incognito detection
const ctx = await launchPersistentContext({
  userDataDir: './chrome-profile',
  headless: false,
  proxy: 'http://user:pass@proxy:8080',
});

Note: Each example above is standalone — not meant to run as one block.

All Python options work in JS: stealthArgs: false to disable defaults, geoip: true to auto-detect timezone/locale from proxy IP.

Puppeteer

Note: The Playwright wrapper is recommended for sites with reCAPTCHA Enterprise. Puppeteer's CDP protocol leaks automation signals that reCAPTCHA Enterprise can detect, causing intermittent 403 errors. This is a known Puppeteer limitation, not specific to CloakBrowser. Use Playwright for best results.

import { launch } from 'cloakbrowser/puppeteer';

const browser = await launch({ headless: true });
const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();

Utility Functions (JS)

import { ensureBinary, clearCache, binaryInfo } from 'cloakbrowser';

// Pre-download binary (e.g., during Docker build)
await ensureBinary();

// Check installation status
console.log(binaryInfo());

// Force re-download
clearCache();

Human Behavior

Pass humanize=True to make all mouse, keyboard, and scroll interactions indistinguishable from real users. All Playwright calls (page.click(), page.fill(), page.type(), page.mouse.*, page.keyboard.*, Locator API) and Puppeteer calls (page.click(), page.type(), page.mouse.*, page.keyboard.*, ElementHandle API) are automatically replaced with human-like equivalents. No code changes needed.

browser = launch(humanize=True)
page = browser.new_page()
page.goto("https://example.com")
page.locator("#email").fill("user@example.com")  # per-character timing, thinking pauses
page.locator("button[type=submit]").click()       # Bézier curve, realistic aim point

// Playwright
import { launch } from 'cloakbrowser';
const browser = await launch({ humanize: true });

// Puppeteer
import { launch } from 'cloakbrowser/puppeteer';
const browser = await launch({ humanize: true });

What changes:

Interaction	Default	With `humanize=True`
Mouse movement	Instant teleport	Bézier curve with easing and slight overshoot
Clicks	Instant	Realistic aim point + hold duration
Keyboard	Instant fill	Per-character timing, thinking pauses, occasional typos with self-correction
Scroll	Jump	Accelerate → cruise → decelerate micro-steps
`fill()`	Instant value set	Clears existing content, types character by character

Presets — default (normal speed) or careful (slower, more deliberate, idle micro-movements between actions):

browser = launch(humanize=True, human_preset="careful")

const browser = await launch({ humanize: true, humanPreset: 'careful' });

Custom config — override any parameter:

browser = launch(humanize=True, human_config={
    "mistype_chance": 0.05,              # 5% typo rate with self-correction
    "typing_delay": 100,                 # slower typing (ms per character)
    "idle_between_actions": True,        # micro-movements between clicks
    "idle_between_duration": [0.3, 0.8], # idle duration range (seconds)
})

const browser = await launch({
    humanize: true,
    humanConfig: {
        mistype_chance: 0.05,
        typing_delay: 100,
        idle_between_actions: true,
        idle_between_duration: [0.3, 0.8],
    }
});

Access the original un-patched Playwright page at page._original if you need raw speed for a specific call.

Note (Playwright): Always use page.click(selector), page.type(selector, text), page.hover(selector), or page.locator(selector).* — these go through the full humanize pipeline. Avoid page.query_selector() — ElementHandle objects bypass all patches, so mouse movement teleports, keyboard events fire without timing, and scroll has no human curve.

Note (Puppeteer): Both selector-based methods (page.click(), page.type()) and ElementHandle methods (el.click(), el.type()) are fully humanized. page.$(), page.$$(), and page.waitForSelector() return patched handles automatically.

Contributed by @evelaa123 — full Playwright and Puppeteer API coverage.

Configuration

Env Variable	Default	Description
`CLOAKBROWSER_BINARY_PATH`	—	Skip download, use a local Chromium binary
`CLOAKBROWSER_CACHE_DIR`	`~/.cloakbrowser`	Binary cache directory
`CLOAKBROWSER_DOWNLOAD_URL`	`cloakbrowser.dev`	Custom download URL for binary
`CLOAKBROWSER_AUTO_UPDATE`	`true`	Set to `false` to disable background update checks
`CLOAKBROWSER_SKIP_CHECKSUM`	`false`	Set to `true` to skip SHA-256 verification after download
`CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS`	`5`	Max seconds for GeoIP resolution before continuing without it

Fingerprint Management

The binary is stealthy by default — no flags needed. It auto-generates a random fingerprint seed at startup and spoofs all detectable values (GPU, hardware specs, screen dimensions, canvas, WebGL, audio, fonts). Every launch produces a fresh, coherent identity.

How fingerprinting works:

Scenario	What happens
No flags	Random seed auto-generated at startup. GPU, screen, hardware specs, and all noise patches are spoofed automatically. Fresh identity each launch.
`--fingerprint=seed`	Deterministic identity from the seed. Same seed = same fingerprint across launches. Use this for session persistence (returning visitor).
`--fingerprint=seed` + explicit flags	Explicit flags override individual auto-generated values. The seed fills in everything else.

The binary detects its platform at compile time — a macOS binary reports as macOS with Apple GPU, a Linux binary reports as Linux with NVIDIA GPU. The wrapper overrides this on Linux by passing --fingerprint-platform=windows, so sessions appear as Windows desktops (more common fingerprint, harder to cluster). Use --fingerprint-platform for cross-platform spoofing when running the binary directly.

Tip: Use a fixed seed when revisiting the same site. A random seed makes every session look like a different device — which can be suspicious when hitting the same site repeatedly from the same IP. For reCAPTCHA v3 Enterprise and similar scoring systems, a fixed seed produces a consistent fingerprint across sessions, making you look like a returning visitor:
browser = launch(args=["--fingerprint=12345"])
const browser = await launch({ args: ['--fingerprint=12345'] });

Default Fingerprint

Every launch() call sets these automatically. The wrapper applies platform-aware defaults — on Linux it spoofs as Windows for a more common fingerprint, on macOS it runs as a native Mac browser:

Flag	Linux/Windows Default	macOS Default	Controls
`--fingerprint`	Random (10000–99999)	Random (10000–99999)	Master seed for canvas, WebGL, audio, fonts, client rects
`--fingerprint-platform`	`windows`	`macos`	`navigator.platform`, User-Agent OS, GPU pool selection

The binary auto-generates everything else from the seed: GPU, hardware concurrency, device memory, and screen dimensions. Each seed produces a unique, consistent fingerprint. Override with explicit flags if needed.

Using the binary directly? It works out of the box with zero flags -- the binary auto-spoofs everything. Pass --fingerprint=seed for a persistent identity, or use explicit flags like --fingerprint-gpu-renderer to override any auto-generated value.

Additional Flags

Supported by the binary but not set by default — pass via args to customize:

Flag	Controls
`--fingerprint-gpu-vendor`	WebGL `UNMASKED_VENDOR_WEBGL` (auto-generated from seed + platform)
`--fingerprint-gpu-renderer`	WebGL `UNMASKED_RENDERER_WEBGL` (auto-generated from seed + platform)
`--fingerprint-hardware-concurrency`	`navigator.hardwareConcurrency` (auto-generated: `8`)
`--fingerprint-device-memory`	`navigator.deviceMemory` in GB (auto-generated: `8`)
`--fingerprint-screen-width`	Screen width (auto-generated: `1920` Win/Linux, `1440` macOS)
`--fingerprint-screen-height`	Screen height (auto-generated: `1080` Win/Linux, `900` macOS)
`--fingerprint-brand`	Browser brand: `Chrome`, `Edge`, `Opera`, `Vivaldi`
`--fingerprint-brand-version`	Brand version (UA + Client Hints)
`--fingerprint-platform-version`	Client Hints platform version
`--fingerprint-location`	Geolocation coordinates
`--fingerprint-timezone`	Timezone (e.g. `America/New_York`)
`--fingerprint-locale`	Locale (e.g. `en-US`)
`--fingerprint-storage-quota`	Override storage quota in MB — affects `storage.estimate()`, `storageBuckets`, and legacy webkit APIs. Auto-normalized when `--fingerprint` is set
`--fingerprint-taskbar-height`	Override taskbar height (binary defaults: Win=48, Mac=95, Linux=0)
`--fingerprint-fonts-dir`	Path to directory containing target-platform fonts (see Font Setup on Linux)
`--fingerprint-webrtc-ip`	WebRTC ICE candidate IP replacement. Use `auto` to resolve from proxy exit IP (makes an HTTP call through the proxy), or pass an explicit IP. Auto-injected when `geoip=True`
`--fingerprint-noise=false`	Disable noise injection (canvas, WebGL, audio, client rects) while keeping the deterministic fingerprint seed active
`--enable-blink-features=FakeShadowRoot`	Access closed shadow DOM elements

Note: All stealth tests were verified with the default fingerprint config above. Changing these flags may affect detection results — test your configuration before using in production.

Font Setup on Linux

Required for aggressive anti-bot sites (Kasada, Akamai). These systems render emoji on a hidden canvas and hash the pixel output. Minimal Linux environments (Docker, cloud VMs) often lack emoji and extended fonts, producing hashes that don't match any real browser. Install standard font packages to fix this:

sudo apt install -y fonts-noto-color-emoji fonts-freefont-ttf fonts-unifont \
    fonts-ipafont-gothic fonts-wqy-zenhei fonts-tlwg-loma-otf

The Docker image (cloakhq/cloakbrowser) ships with these pre-installed. If you run the binary directly on a Linux server or in a custom Docker image, install them manually.

Optional: Windows fonts for CreepJS font enumeration. The packages above fix anti-bot canvas checks but won't improve your CreepJS font score. For that, you need actual Windows fonts (Segoe UI, Calibri, Bahnschrift, etc.) from a Windows machine's C:\Windows\Fonts\ directory — ttf-mscorefonts-installer only has old XP-era fonts and isn't enough.

mkdir -p ~/.local/share/fonts/windows
cp /path/to/windows/fonts/*.ttf ~/.local/share/fonts/windows/
cp /path/to/windows/fonts/*.TTF ~/.local/share/fonts/windows/
fc-cache -f  # mandatory for manually copied fonts

browser = launch(
    args=["--fingerprint-fonts-dir=/home/user/.local/share/fonts/windows"],
)

Examples

# Pin a seed for a persistent identity
browser = launch(args=["--fingerprint=42069"])

# Full control — disable defaults, set everything yourself
browser = launch(stealth_args=False, args=[
    "--fingerprint=42069",
    "--fingerprint-platform=windows",
])

# Override GPU to look like a specific machine
browser = launch(args=[
    "--fingerprint-gpu-vendor=Intel Inc.",
    "--fingerprint-gpu-renderer=Intel Iris OpenGL Engine",
])

Examples

Python — see examples/:

basic.py — Launch and load a page
persistent_context.py — Persistent profile with cookie/localStorage persistence
recaptcha_score.py — Check your reCAPTCHA v3 score
stealth_test.py — Run against 6 detection sites
fingerprint_scan_test.py — Test against fingerprint-scan.com and CreepJS

JavaScript — see js/examples/:

basic-playwright.ts — Playwright launch and load
basic-puppeteer.ts — Puppeteer launch and load
stealth-test.ts — Run against 6 detection sites

Framework Integrations

CloakBrowser works with any framework that uses Playwright or Chromium:

# Option 1: Framework launches our binary directly (Selenium, Stagehand, UC)
from cloakbrowser.download import ensure_binary
from cloakbrowser.config import get_default_stealth_args
binary_path = ensure_binary()          # auto-downloads if needed
stealth_args = get_default_stealth_args()  # all fingerprint flags

# Option 2: CloakBrowser launches first, framework connects via CDP (browser-use, Crawl4AI, Scrapling)
from cloakbrowser import launch_async
browser = await launch_async(args=["--remote-debugging-port=9242"])
# Connect your framework to http://127.0.0.1:9242 — all stealth flags are set
# Note: humanize requires the wrapper (see below)

Humanize over CDP: Stealth fingerprint patches work automatically over CDP, but humanize=True is a wrapper-level feature. If you connect to CloakBrowser via CDP from a separate script, import the patching functions to add humanization:
import { patchBrowser, resolveConfig } from 'cloakbrowser/human';
patchBrowser(browser, resolveConfig('default'));

Framework	Stars	Language	Example
browser-use	70K	Python	`browser_use_example.py`
Crawl4AI	58K	Python	`crawl4ai_example.py`
Crawlee	8.6K	Python	`crawlee_example.py`
Scrapling	21K	Python	`scrapling_example.py`
Stagehand	21K	TypeScript	`stagehand.ts`
LangChain	100K+	Python	`langchain_loader.py`
Selenium	—	Python	`selenium_example.py`
undetected-chromedriver	12K	Python	`undetected_chromedriver.py`
agent-browser	—	Shell	`agent_browser.sh`

Deployment Integrations

Platform	Example
AWS Lambda	`aws_lambda/` — One-shot scrapes in Lambda (container image)

Platforms

Platform	Chromium	Patches	Status
Linux x86_64	146	57	✅ Latest
Linux arm64 (RPi, Graviton)	146	57	✅ Latest
macOS arm64 (Apple Silicon)	145	26	✅
macOS x86_64 (Intel)	145	26	✅
Windows x86_64	146	57	✅ Latest

The wrapper auto-downloads the correct binary for your platform.

macOS first launch: The binary is ad-hoc signed. On first run, macOS Gatekeeper will block it. Right-click the app → Open → click Open in the dialog. This is only needed once.

Docker

Pre-built image on Docker Hub — no install, no setup.

Quick test

docker run --rm cloakhq/cloakbrowser cloaktest

Run a script

# Inline script
docker run --rm cloakhq/cloakbrowser python -c "
from cloakbrowser import launch
browser = launch()
page = browser.new_page()
page.goto('https://example.com')
print(page.title())
browser.close()
"

# Mount your own script
docker run --rm -v ./my_script.py:/app/my_script.py cloakhq/cloakbrowser python my_script.py

# With a proxy
docker run --rm cloakhq/cloakbrowser python -c "
from cloakbrowser import launch
browser = launch(proxy='http://user:pass@proxy:8080')
page = browser.new_page()
page.goto('https://example.com')
print(page.title())
browser.close()
"

CDP server mode

Start a persistent stealth browser and connect to it remotely via Chrome DevTools Protocol:

docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser cloakserve

Then connect from your host machine:

from playwright.sync_api import sync_playwright

pw = sync_playwright().start()
browser = pw.chromium.connect_over_cdp("http://localhost:9222")
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()

Pass extra flags to the browser:

# With proxy
docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser \
  cloakserve --proxy-server=http://proxy:8080

# Headed mode (renders to Xvfb inside container)
docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser \
  cloakserve --headless=false

Stop the server:

docker stop cloak && docker rm cloak

Security: CDP gives full control over the browser (execute JS, read pages, access files). The examples bind to 127.0.0.1 so only your machine can connect. Never expose port 9222 to the public internet without additional authentication.

Docker Compose

services:
  cloakbrowser:
    image: cloakhq/cloakbrowser
    command: cloakserve
    restart: unless-stopped
    ports:
      - "127.0.0.1:9222:9222"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9222/json/version"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

Per-connection fingerprint seeds — run multiple browser identities from a single container. Each unique seed spawns a separate Chrome process with its own fingerprint:

# Each seed gets unique canvas noise, client rects, and other browser signals
b1 = pw.chromium.connect_over_cdp("http://localhost:9222?fingerprint=11111")
b2 = pw.chromium.connect_over_cdp("http://localhost:9222?fingerprint=22222")

# Full identity control via query params
b3 = pw.chromium.connect_over_cdp(
    "http://localhost:9222?fingerprint=33333"
    "&timezone=Asia/Tokyo&locale=ja-JP&platform=macos"
    "&hardware-concurrency=4&device-memory=8"
)

# Auto-detect timezone/locale from proxy exit IP
b4 = pw.chromium.connect_over_cdp(
    "http://localhost:9222?fingerprint=44444"
    "&proxy=http://proxy:8080&geoip=true"
)

Supported query params: fingerprint, timezone, locale, platform, platform-version, brand, brand-version, gpu-vendor, gpu-renderer, hardware-concurrency, device-memory, screen-width, screen-height, proxy, geoip. Same seed reuses the same process (first connection's params win). No seed = shared default process (backward compatible). Check active processes at GET / (returns JSON with PIDs, ports, and connection counts).

Persistent profiles — mount a volume to keep cookies and sessions across container restarts:

docker run --rm -v ./my-profile:/profile cloakhq/cloakbrowser python -c "
from cloakbrowser import launch_persistent_context
ctx = launch_persistent_context('/profile')
page = ctx.new_page()
page.goto('https://example.com')
ctx.close()
"

Run again with the same volume — cookies, localStorage, and cache are restored automatically.

Resource usage: ~190MB RAM idle, ~280MB with 3 tabs. ~30MB per additional tab.

Extend with your own image

FROM cloakhq/cloakbrowser
COPY your_script.py /app/
CMD ["python", "your_script.py"]

Building your own image from pip — use python -m cloakbrowser install to download the binary during build with visible progress:

FROM python:3.12-slim
RUN pip install cloakbrowser && python -m cloakbrowser install
COPY your_script.py /app/
CMD ["python", "/app/your_script.py"]

Building from source — a Dockerfile is also included if you prefer to build your own image:

docker build -t cloakbrowser .

CloakBrowser works identically local, in Docker, and on VPS. No environment-specific config needed.

Note: If you run CloakBrowser inside a web server with uvloop (e.g., uvicorn[standard]), use --loop asyncio to avoid subprocess pipe hangs.

Troubleshooting

Still getting blocked on aggressive sites (DataDome, Turnstile)?

Some sites detect headless mode even with our C++ patches. Run in headed mode with a virtual display:

# Install Xvfb (virtual framebuffer)
sudo apt install xvfb

# Start virtual display
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99

from cloakbrowser import launch

# Headed mode + residential proxy for maximum stealth
browser = launch(headless=False, proxy="http://your-residential-proxy:port")
page = browser.new_page()
page.goto("https://heavily-protected-site.com")  # passes DataDome, etc.
browser.close()

This runs a real headed browser rendered on a virtual display — no physical monitor needed. Combine with the recommended config below for maximum stealth.

Recommended config for anti-bot sites

Most blocks come from missing one of these three things, not from browser fingerprint detection:

browser = launch(
    proxy="http://your-residential-proxy:port",  # residential IP — datacenter IPs get blocked by reputation alone
    geoip=True,      # matches timezone + locale to proxy exit IP (without this: UTC + en-US = bot signal)
    headless=False,   # headed mode — some sites detect headless even with C++ patches
    humanize=True,    # human-like mouse, keyboard, scroll behavior
)

const browser = await launch({
    proxy: 'http://your-residential-proxy:port',
    geoip: true,
    headless: false,
    humanize: true,
});

If your proxy supports SOCKS5, use it for better compatibility — SOCKS5 tunnels raw TCP, avoiding HTTP CONNECT issues that some proxies have with HTTP/2:

browser = launch(proxy="socks5://user:pass@proxy:1080", geoip=True, headless=False, humanize=True)

If you're still blocked after this, check the font setup below.

Blocked on Kasada / Akamai sites despite correct config?

On minimal Linux environments, missing font packages cause canvas emoji rendering to produce hashes that anti-bot systems don't recognize. This is the most common cause of blocks on aggressive sites after proxy, geoip, and headed mode are already set up correctly.

Install the font packages listed in Font Setup on Linux above.

Sites challenge fresh sessions but work after first visit

Some sites challenge first-time visitors with no cookies over HTTP/2. This affects all Chromium browsers, not just CloakBrowser. Use a persistent profile to warm up cookies once, then reuse across sessions:

from cloakbrowser import launch_persistent_context

# First run: warm up with --disable-http2
ctx = launch_persistent_context("./profile", args=["--disable-http2"])
page = ctx.new_page()
page.goto("https://example.com")  # warms up cookies
ctx.close()

# Future runs — no --disable-http2 needed
ctx = launch_persistent_context("./profile")
page = ctx.new_page()
page.goto("https://example.com")  # passes with saved cookies

import { launchPersistentContext } from 'cloakbrowser';

// First run: warm up with --disable-http2
let ctx = await launchPersistentContext({ userDataDir: './profile', args: ['--disable-http2'] });
let page = await ctx.newPage();
await page.goto('https://example.com');
await ctx.close();

// Future runs — no --disable-http2 needed
ctx = await launchPersistentContext({ userDataDir: './profile' });

For stateless/ephemeral use cases, launch(args=["--disable-http2"]) forces HTTP/1.1 which bypasses the check. Only use this flag for sites that require it — most work fine with HTTP/2. If your proxy supports SOCKS5, use proxy="socks5://user:pass@host:port" instead — SOCKS5 bypasses HTTP CONNECT entirely.

Something not working? Make sure you're on the latest version

Older versions may use outdated stealth args or download an older binary:

pip install -U cloakbrowser    # Python
npm install cloakbrowser@latest # JavaScript
docker pull cloakhq/cloakbrowser:latest  # Docker

Binary download fails / timeout

Set a custom download URL or use a local binary:

export CLOAKBROWSER_BINARY_PATH=/path/to/your/chrome

New update broke something? Roll back to the previous version

Install a specific wrapper version to downgrade both the wrapper and the binary it downloads:

pip install cloakbrowser==0.3.21              # Python
npm install cloakbrowser@0.3.21               # JavaScript
docker pull cloakhq/cloakbrowser:0.3.21       # Docker

Each wrapper version pins its own binary version, so downgrading the wrapper automatically gets you the matching binary on next launch.

macOS: "App is damaged" or Gatekeeper blocks launch

The binary is ad-hoc signed. macOS quarantines downloaded files. Run once to clear it:

xattr -cr ~/.cloakbrowser/chromium-*/Chromium.app

"playwright install" vs CloakBrowser binary

You do NOT need playwright install chromium. CloakBrowser downloads its own binary. You only need Playwright's system deps:

playwright install-deps chromium

macOS: Blocked on some sites that pass on Linux

The macOS fingerprint profile has known inconsistencies that aggressive bot detection catches. If a site blocks you on macOS but works on Linux, switch to a Windows fingerprint profile by passing stealth_args=False and manually setting --fingerprint-platform=windows with matching GPU flags (see Fingerprint Management for the full flag list).

Site detects incognito / private browsing mode

By default, launch() opens an incognito context. Some sites penalize this. Use launch_persistent_context() to get a real profile with cookie persistence:

from cloakbrowser import launch_persistent_context

ctx = launch_persistent_context("./my-profile", headless=False)

If the site still flags incognito, raise the storage quota to appear as a regular browsing session. See the storage quota tradeoff for details on how this affects different detection services.

reCAPTCHA v3 scores are low (0.1–0.3)

Avoid page.wait_for_timeout() — it sends CDP protocol commands that reCAPTCHA detects. Use native sleep instead:

# Bad — sends CDP commands, reCAPTCHA detects this
page.wait_for_timeout(3000)

# Good — invisible to the browser
import time
time.sleep(3)

// Bad — sends CDP commands
await page.waitForTimeout(3000);

// Good — invisible to the browser
await new Promise(r => setTimeout(r, 3000));

Other tips for maximizing reCAPTCHA scores:

Try the Patchright backend — suppresses additional CDP automation signals at the Playwright protocol layer. Install with pip install cloakbrowser[patchright], then use launch(backend="patchright") or set CLOAKBROWSER_BACKEND=patchright globally. Note: Patchright breaks proxy auth and add_init_script — only use it if you're still seeing low scores after trying the steps above
Use Playwright, not Puppeteer — Puppeteer sends more CDP protocol traffic that reCAPTCHA detects (details)
Use residential proxies — datacenter IPs are flagged by IP reputation, not browser fingerprint
Spend 15+ seconds on the page before triggering reCAPTCHA — short visits score lower
Space out requests — back-to-back grecaptcha.execute() calls from the same session get penalized. Wait 30+ seconds between pages with reCAPTCHA
Use a fixed fingerprint seed for consistent device identity across sessions (see Fingerprint Management)
Use page.type() instead of page.fill() for form filling — fill() sets values directly without keyboard events, which reCAPTCHA's behavioral analysis flags. type() with a delay simulates real keystrokes:
```
page.type("#email", "user@example.com", delay=50)
```
Minimize page.evaluate() calls before the reCAPTCHA check fires — each one sends CDP traffic

FAQ

Q: Is this legal? A: CloakBrowser is a browser built on open-source Chromium. We do not condone illegal use. Automating systems without authorization, credential stuffing, and account creation abuse are expressly prohibited. See BINARY-LICENSE.md for full terms.

Q: How is this different from Camoufox? A: Camoufox patches Firefox. We patch Chromium. Chromium means native Playwright support, larger ecosystem, and TLS fingerprints that match real Chrome. Camoufox returned in early 2026 but is in unstable beta — CloakBrowser is production-ready.

Q: Will detection sites eventually catch this? A: Possibly. Bot detection is an arms race. Source-level patches are harder to detect than config-level patches, but not impossible. We actively monitor and update when detection evolves.

Q: Can I use my own proxy? A: Yes. Pass proxy="http://user:pass@host:port" or proxy="socks5://user:pass@host:port" to launch(). Both HTTP and SOCKS5 proxies are supported natively.

Roadmap

Feature	Status
Linux x64 — Chromium 146 (57 patches)	✅ Released
macOS arm64/x64 — Chromium 145 (26 patches)	✅ Released
Windows x64 — Chromium 146 (57 patches)	✅ Released
JavaScript/Puppeteer + Playwright support	✅ Released
Fingerprint rotation per session	✅ Released
Built-in proxy rotation	📋 Planned

Security

All releases are signed for supply chain verification.

# Verify GPG signature (binary release tag)
gpg --keyserver keyserver.ubuntu.com --recv-keys C60C0DDC9D0DE2DD
git verify-tag chromium-v146.0.7680.177.3

# Verify GitHub binary attestation (Sigstore)
gh attestation verify cloakbrowser-linux-x64.tar.gz --repo CloakHQ/cloakbrowser

# Verify Docker image signature (Cosign/Sigstore)
cosign verify \
  --certificate-identity-regexp "https://github.com/CloakHQ/CloakBrowser/" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  cloakhq/cloakbrowser:latest

License

Wrapper code (this repository) — MIT. See LICENSE.
CloakBrowser binary (compiled Chromium) — free to use, no redistribution. See BINARY-LICENSE.md.

Contributing

Issues and PRs welcome. If something isn't working, open an issue — we respond fast.

Contributors

@evelaa123 — humanize behavior, persistent contexts, Windows fix
@yahooguntu — persistent contexts
@kitiho — null viewport fix
@eofreternal — humanConfig type fix, humanized method option types
@manaskarra — iframe scope fix for humanized frame actions, GeoIP timeout guard
@Youhai020616 — SOCKS5 credential encoding logging
@AlexTech314 — AWS Lambda integration, cold-start hardening
@dgtlmoon — graceful pw.stop() cleanup
@zackycodes — Chrome extension loading
@aaronjmars — security fixes (shell injection, dep bumps)
@Seryiza — Nix/NixOS flake
@245678000000 — package-lock sync

yikart/AiToEarn

Let's use AI to Earn!

Aitoearn：OPC（一人公司）的AI内容营销智能体

简体中文 | English | 日本語

Monetize · Publish · Engage · Create —— 一站式平台。

AiToEarn 通过 AI Agent自动化，帮助 OPC（一人公司）、创作者、品牌与企业在全球主流平台上构建、分发并变现内容。

支持渠道：抖音、小红书（Rednote）、快手、哔哩哔哩、视频号、TikTok、YouTube、Facebook、Instagram、Threads、Twitter（X）、Pinterest、LinkedIn

🚀 快速使用 AiToEarn（5 种方式）

方式	适合谁	需要部署吗
① 打开网站直接用	所有用户	❌ 不需要
② 在龙虾 OpenClaw 中用	龙虾用户	❌ 不需要
③ 在 Claude / Cursor 等 AI 助手中用	AI 工具用户	❌ 不需要
④ Docker 一键部署	想私有化部署的团队	✅ 需要服务器
⑤ 源码开发	开发者	✅ 需要开发环境

💡 方式 ②③④ 都需要先获取 API Key，请先看如何获取 API Key。

核心功能

AiToEarn 围绕内容创作者的完整变现链路，提供四大 Agent 能力：

Monetize · Publish · Engage · Create

💰 Monetize —— 内容赚钱

AiToEarn 最核心的目标：帮助每一位创作者赚钱。

创作者可以在平台出售内容以完成商家的推广任务。所有结算以结果为导向，我们提供三种结算模式：

结算模式	全称	含义
CPS	Cost Per Sale	按成交额结算
CPE	Cost Per Engagement	按互动量结算
CPM	Cost Per Mille	按播放量结算

📢 Publish —— 内容发布 Agent

一键将内容分发到全球 10+ 主流平台，告别逐个平台手动发布。

全网分发：覆盖抖音、快手、B站、小红书、视频号、微信公众号、TikTok、YouTube、Facebook、Instagram、Threads、X（Twitter）、Pinterest、LinkedIn
日历排期：像排日程一样统一规划所有平台的内容发布时间

▶ 观看演示视频

💬 Engage —— 内容互动 Agent

通过 AiToEarn 浏览器插件，在上述所有平台上实现自动化互动运营。

自动化操作：自动点赞、收藏、关注，批量高效运营
AI 智能回复：调用大模型为每条评论生成针对性回复，精准互动
评论挖掘：识别"求链接""怎么购买"等高转化信号，快速响应
品牌监测：实时追踪关于你品牌的讨论，主动参与热点话题

▶ 观看演示视频

🎨 Create —— 内容创作 Agent

我们用 Agent 的方式重构了内容制作流程。只需告诉 Agent 你的内容需求，它会自动完成从创意到成品的全部工作。

视频内容：Agent 自动调用视频生成模型（Grok、Veo、Seedance 等）、视频翻译模块、视频剪辑模块，一站式完成视频制作。

图文内容：支持调用 Nano Banana 等顶级图片模型，自动生成高质量图文内容。

批量生成：支持批量下发创作任务，Agent 可并行生成多条内容，快速铺量，适合矩阵账号运营和大规模内容分发场景。

▶ 观看演示视频

① 打开网站直接用

最简单的方式，打开浏览器即可使用，无需任何配置：

🇨🇳 中国用户访问：aitoearn.cn
🌍 国际用户访问：aitoearn.ai

🔑 如何获取 API Key（后续步骤的前置条件）

以下的方式 ②③④ 都需要 API Key。只需获取一次，所有方式通用。

3 步获取：

打开 aitoearn.cn（中国用户）或 aitoearn.ai（国际用户），注册并登录
点击左侧菜单设置
在 API Key 中点击创建，复制生成的 Key

② 在龙虾 OpenClaw 中使用

前置条件：已获取 API Key

请在服务器终端输入以下命令！请在服务器终端输入以下命令！请在服务器终端输入以下命令！

安装插件

npx -y @aitoearn/openclaw-plugin-cli

首次运行后会先让你选择环境并输入 API Key。请确保环境与 Key 匹配：

中国版：使用 aitoearn.cn 获取的 API Key
国际版：使用 aitoearn.ai 获取的 API Key

环境和 Key 不匹配会导致 401。

安装完成后，你就可以在 OpenClaw 中直接接收并执行 AiToEarn 的赚钱任务：

③ 在 Claude / Cursor / 其他 AI 助手中使用

前置条件：已获取 API Key

AiToEarn 支持所有兼容 MCP 协议的 AI 助手。以下是常见工具的配置方式：

请根据 API Key 来源选择地址，环境和 Key 不匹配会导致 401：

环境	MCP 地址	SSE 地址
中国版	`https://aitoearn.cn/api/unified/mcp`	`https://aitoearn.cn/api/unified/sse`
国际版	`https://aitoearn.ai/api/unified/mcp`	`https://aitoearn.ai/api/unified/sse`

Claude Desktop

找到并编辑 claude_desktop_config.json，添加：

{
  "mcpServers": {
    "aitoearn": {
      "type": "http",
      "url": "https://aitoearn.ai/api/unified/mcp",
      "headers": {
        "x-api-key": "你的API-Key"
      }
    }
  }
}

Cursor

在 Cursor 的 MCP 设置中添加：

MCP 地址：https://aitoearn.ai/api/unified/mcp
认证 Header：x-api-key: 你的API-Key

其他 AI 助手（通用配置）

任何支持 MCP 协议的工具，只需要两个信息：

配置项	值
MCP 地址	`https://aitoearn.ai/api/unified/mcp`
认证 Header	`x-api-key: 你的API-Key`

也支持 SSE 长连接方式：https://aitoearn.ai/api/unified/sse

💡 如果你是自部署用户，将 aitoearn.ai 替换为你自己的地址（如 localhost:8080）。

④ Docker 一键部署

前置条件：已安装 Docker

适合想把 AiToEarn 部署在自己服务器上的团队。3 条命令搞定，无需手动安装数据库：

git clone https://github.com/yikart/AiToEarn.git
cd AiToEarn
docker compose up -d

启动后打开 http://localhost:8080 即可使用。

配置 Relay（强烈推荐）

为什么要配 Relay？ 发布内容需要登录社交媒体账号（抖音、小红书、TikTok 等），而这些平台的 OAuth 登录需要开发者凭据。配置 Relay 后，你可以直接借用官方 aitoearn.ai 的凭据完成授权，不需要自己去各平台申请开发者账号。

在 docker-compose.yml 的 aitoearn-server 服务中添加（API Key 获取方式见上方说明）：

请根据 RELAY_API_KEY 来源选择 RELAY_SERVER_URL：中国版 Key 使用 https://aitoearn.cn/api，国际版 Key 使用 https://aitoearn.ai/api。环境和 Key 不匹配会导致 401。

RELAY_SERVER_URL: https://aitoearn.ai/api
RELAY_API_KEY: 你的API-Key
RELAY_CALLBACK_URL: http://127.0.0.1:8080/api/plat/relay-callback

然后重启：docker compose restart aitoearn-server

📖 完整部署指南（生产环境配置、AI 服务、OAuth、存储等）请参阅 DOCKER_DEPLOYMENT_CN.md。

⑤ 源码开发

🧪 手动运行后端和前端（开发模式）

此模式主要用于本地开发和调试。您仍然可以使用 Docker 运行 MongoDB/Redis，或在配置文件中指向您自己的服务。

1. 启动后端服务

cd project/aitoearn-backend
pnpm install
# 复制配置文件用于本地开发
cp apps/aitoearn-ai/config/config.js apps/aitoearn-ai/config/local.config.js
cp apps/aitoearn-server/config/config.js apps/aitoearn-server/config/local.config.js
pnpm nx serve aitoearn-ai
# 在另一个终端
pnpm nx serve aitoearn-server

2. 启动前端 `aitoearn-web`

pnpm install
pnpm run dev

🖥️ 启动 Electron 桌面项目

# 克隆仓库
git clone https://github.com/yikart/AttAiToEarn.git

# 进入目录
cd AttAiToEarn

# 安装依赖
npm install

# 编译 sqlite（better-sqlite3 需要 node-gyp 和本地 Python）
npm run rebuild

# 启动开发
npm run dev

Electron 项目为 AiToEarn 提供桌面客户端。

贡献指南

请查看贡献指南开始参与。

联系

如果你在使用过程中遇到困难、使用问题或异常情况，优先通过 GitHub Issues 提交反馈，方便我们统一跟进和处理。

Telegram: https://t.me/harryyyy2025
微信：扫码添加

rohitg00/agentmemory

#1 Persistent memory for AI coding agents based on real-world benchmarks

Your coding agent remembers everything. No more re-explaining. Built on iii engine
Persistent memory for Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, and any MCP client.

The gist extends Karpathy's LLM Wiki pattern with confidence scoring, lifecycle, knowledge graphs, and hybrid search: agentmemory is the implementation.

Install • Quick Start • Benchmarks • vs Competitors • Agents • How It Works • MCP • Viewer • iii Console • Powered by iii • Config • API

Install

npm install -g @agentmemory/agentmemory     # once — bare `agentmemory` on PATH
agentmemory                                  # start the memory server on :3111
agentmemory demo                             # seed sample sessions + prove recall
agentmemory connect claude-code              # wire your agent (also: codex, cursor, gemini-cli, ...)

Or via npx (no install):

npx @agentmemory/agentmemory

Heads-up — npx caches per version. If a bare npx @agentmemory/agentmemory serves an older release, force the latest with npx -y @agentmemory/agentmemory@latest, or clear the cache once with rm -rf ~/.npm/_npx (macOS/Linux; on Windows delete %LOCALAPPDATA%\npm-cache\_npx). The first npx run from v0.9.16+ prompts to install globally inline so the bare agentmemory command works everywhere afterwards.

Full options at Quick Start below. Agent-specific wiring at Works with every agent.

agentmemory works with any agent that supports hooks, MCP, or REST API. All agents share the same memory server.

Claude Code _{native plugin + 12 hooks + MCP}	Codex CLI _{native plugin + 6 hooks + MCP}	OpenClaw _{native plugin + MCP}	Hermes _{native plugin + MCP}	pi _{native plugin + MCP}	OpenHuman _{native Memory trait backend}	Cursor _{MCP server}	Gemini CLI _{MCP server}
OpenCode _{MCP server}	Cline _{MCP server}	Goose _{MCP server}	Kilo Code _{MCP server}	Aider _{REST API}	Claude Desktop _{MCP server}	Windsurf _{MCP server}	Roo Code _{MCP server}

_{Works with any agent that speaks MCP or HTTP. One server, memories shared across all of them.}

You explain the same architecture every session. You re-discover the same bugs. You re-teach the same preferences. Built-in memory (CLAUDE.md, .cursorrules) caps out at 200 lines and goes stale. agentmemory fixes this. It silently captures what your agent does, compresses it into searchable memory, and injects the right context when the next session starts. One command. Works across agents.

What changes: Session 1 you set up JWT auth. Session 2 you ask for rate limiting. The agent already knows your auth uses jose middleware in src/middleware/auth.ts, your tests cover token validation, and you chose jose over jsonwebtoken for Edge compatibility. No re-explaining. No copy-pasting. The agent just knows.

npx @agentmemory/agentmemory

New in v0.9.0 — Landing site at agent-memory.dev, filesystem connector (@agentmemory/fs-watcher), standalone MCP now proxies to the running server so hooks and the viewer agree, audit policy codified across every delete path, health stops flagging memory_critical on tiny Node processes. Full notes in CHANGELOG.md.

Retrieval Accuracy

LongMemEval-S (ICLR 2025, 500 questions)

System	R@5	R@10	MRR
agentmemory	95.2%	98.6%	88.2%
BM25-only fallback	86.2%	94.6%	71.5%

Token Savings

Approach	Tokens/yr	Cost/yr
Paste full context	19.5M+	Impossible (exceeds window)
LLM-summarized	~650K	~$500
agentmemory	~170K	~$10
agentmemory + local embeddings	~170K	$0

Embedding model: all-MiniLM-L6-v2 (local, free, no API key). Full reports: benchmark/LONGMEMEVAL.md, benchmark/QUALITY.md, benchmark/SCALE.md. Competitor comparison: benchmark/COMPARISON.md — agentmemory vs mem0, Letta, Khoj, claude-mem, Hippo.

	agentmemory	mem0 (53K ⭐)	Letta / MemGPT (22K ⭐)	Built-in (CLAUDE.md)
Type	Memory engine + MCP server	Memory layer API	Full agent runtime	Static file
Retrieval R@5	95.2%	68.5% (LoCoMo)	83.2% (LoCoMo)	N/A (grep)
Auto-capture	12 hooks (zero manual effort)	Manual `add()` calls	Agent self-edits	Manual editing
Search	BM25 + Vector + Graph (RRF fusion)	Vector + Graph	Vector (archival)	Loads everything into context
Multi-agent	MCP + REST + leases + signals	API (no coordination)	Within Letta runtime only	Per-agent files
Framework lock-in	None (any MCP client)	None	High (must use Letta)	Per-agent format
External deps	None (SQLite + iii-engine)	Qdrant / pgvector	Postgres + vector DB	None
Memory lifecycle	4-tier consolidation + decay + auto-forget	Passive extraction	Agent-managed	Manual pruning
Token efficiency	~1,900 tokens/session ($10/yr)	Varies by integration	Core memory in context	22K+ tokens at 240 obs
Real-time viewer	Yes (port 3113)	Cloud dashboard	Cloud dashboard	No
Self-hosted	Yes (default)	Optional	Optional	Yes

Compatibility: this release targets stable iii-sdk ^0.11.0 and iii-engine v0.11.x.

Try it in 30 seconds

# Terminal 1: start the server
npx @agentmemory/agentmemory

# Terminal 2: seed sample data and see recall in action
npx @agentmemory/agentmemory demo

demo seeds 3 realistic sessions (JWT auth, N+1 query fix, rate limiting) and runs semantic searches against them. You'll see it find "N+1 query fix" when you search "database performance optimization" — keyword matching can't do that.

Open http://localhost:3113 to watch the memory build live.

Recommended: install globally

npx caches per-version. If you ran npx @agentmemory/agentmemory@0.9.14 last week, a bare npx @agentmemory/agentmemory may serve the stale 0.9.14 from ~/.npm/_npx/, not the latest release. Install once and the bare agentmemory command works everywhere:

npm install -g @agentmemory/agentmemory
agentmemory                    # start the server (same as the npx form)
agentmemory stop               # tear it down
agentmemory remove             # uninstall everything we created
agentmemory connect claude-code   # wire one agent
agentmemory doctor             # interactive diagnostics + fix prompts

From v0.9.16 onward, the first npx run prompts you to install globally inline — answer Y once and you're set. If you skip, fall back to either of these for a fresh fetch:

npx -y @agentmemory/agentmemory@latest                 # forces latest from npm (cross-platform)
rm -rf ~/.npm/_npx && npx @agentmemory/agentmemory     # macOS/Linux only (POSIX shell)

On Windows / PowerShell, the equivalent cache clear is Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" — the npx -y ...@latest form above is the cross-platform option.

Session Replay

Every session agentmemory records is replayable. Open the viewer, pick the Replay tab, and scrub through the timeline: prompts, tool calls, tool results, and responses render as discrete events with play/pause, speed control (0.5×–4×), and keyboard shortcuts (space to toggle, arrows to step).

Already have older Claude Code JSONL transcripts you want to bring in?

# Import everything under the default ~/.claude/projects
npx @agentmemory/agentmemory import-jsonl

# Or import a single file
npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl

Imported sessions show up in the Replay picker alongside native ones. Under the hood each entry routes through the mem::replay::load, mem::replay::sessions, and mem::replay::import-jsonl iii functions — no side-channel servers.

Upgrade / Maintenance

Use the maintenance command when you intentionally want to update your local runtime:

npx @agentmemory/agentmemory upgrade

Warning: this command mutates the current workspace/runtime. It can update JavaScript dependencies, may run cargo install iii-engine --force, and may pull Docker images.

Implementation details live in src/cli.ts (see runUpgrade around the src/cli.ts:544-595 region).

Claude Code (one block, paste it)

Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 4 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 51 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.

Codex CLI (Codex plugin platform)

# 1. start the memory server in a separate terminal
npx @agentmemory/agentmemory

# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
codex plugin install agentmemory

The Codex plugin ships from the same plugin/ directory as the Claude Code plugin. It registers:

@agentmemory/mcp as an MCP server (proxies all 51 tools when AGENTMEMORY_URL points at a running agentmemory server; falls back to 7 tools locally when no server is reachable)
6 lifecycle hooks: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop
4 skills: /recall, /remember, /session-history, /forget

Codex's hook engine injects CLAUDE_PLUGIN_ROOT into hook subprocesses (per codex-rs/hooks/src/engine/discovery.rs), so the same hook scripts work across both hosts without duplication. Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure events are Claude-Code-only and are not registered for Codex.

OpenClaw (paste this prompt)

Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 51 memory tools:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.

Full guide: integrations/openclaw/

Hermes Agent (paste this prompt)

Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 51 memory tools:

mcp_servers:
  agentmemory:
    command: npx
    args: ["-y", "@agentmemory/mcp"]

memory:
  provider: agentmemory

Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.

Full guide: integrations/hermes/

Other agents

Start the memory server: npx @agentmemory/agentmemory

The agentmemory entry is the same MCP server block across every host that uses the mcpServers shape (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw):

"agentmemory": {
  "command": "npx",
  "args": ["-y", "@agentmemory/mcp"],
  "env": {
    "AGENTMEMORY_URL": "http://localhost:3111"
  }
}

Merge this entry into the existing mcpServers object in the host's config file — don't replace the file. If the file already has other servers, add agentmemory next to them as another key inside mcpServers. If mcpServers is missing entirely, paste the block inside { "mcpServers": { ... } }.

Agent	Config file	Notes
Cursor	`~/.cursor/mcp.json`	Merge into `mcpServers`. One-click deeplink also available on the website.
Claude Desktop	`claude_desktop_config.json` (Application Support)	Merge into `mcpServers`. Restart Claude Desktop after editing.
Cline / Roo Code / Kilo Code	Cline MCP settings (Settings UI → MCP Servers → Edit)	Same `mcpServers` block.
Windsurf	`~/.codeium/windsurf/mcp_config.json`	Same `mcpServers` block.
Gemini CLI	`~/.gemini/settings.json`	`gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (auto-merges).
OpenClaw	OpenClaw MCP config	Same `mcpServers` block, or use the deeper memory plugin.
Codex CLI (MCP only)	`.codex/config.toml`	TOML shape: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, or add `[mcp_servers.agentmemory]` manually.
Codex CLI (full plugin)	Codex plugin marketplace	`codex plugin marketplace add rohitg00/agentmemory` then `codex plugin install agentmemory`. Registers MCP + 6 lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 4 skills.
OpenCode	`opencode.json`	Different shape — top-level `mcp` key, command as array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`.
pi	`~/.pi/agent/extensions/agentmemory`	Copy `integrations/pi` and restart pi.
Hermes Agent	`~/.hermes/config.yaml`	Use the deeper memory provider plugin with `memory.provider: agentmemory`.
Goose	Goose MCP settings UI	Same `mcpServers` block.
Aider	n/a	Talk to the REST API directly: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`.
Any agent (32+)	n/a	`npx skillkit install agentmemory` auto-detects the host and merges.

Sandboxed MCP clients (Flatpak / Snap / restrictive containers) that can't reach the host's localhost: also set "AGENTMEMORY_FORCE_PROXY": "1" in the env block, and point AGENTMEMORY_URL at a route the sandbox can actually reach (e.g. your LAN IP). See #234 for the diagnostic walkthrough.

Programmatic access (Python / Rust / Node)

agentmemory registers its core operations as iii functions (mem::remember, mem::observe, mem::context, mem::smart-search, mem::forget). Any language with an iii SDK can call them directly over ws://localhost:49134 — no separate REST client per language.

pip install iii-sdk         # Python
cargo add iii-sdk           # Rust
npm  install iii-sdk        # Node

from iii import register_worker

iii = register_worker("ws://localhost:49134")
iii.connect()

iii.trigger({
    "function_id": "mem::smart-search",
    "payload": {"project": "demo", "query": "how do tokens refresh"},
})

Worked example: examples/python/ (quickstart + observation/recall flow). REST on :3111 remains available for hosts without an iii runtime.

From source

git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start

This starts agentmemory with a local iii-engine if iii is already installed, or falls back to Docker Compose if Docker is available. REST, streams, and the viewer bind to 127.0.0.1 by default.

Install iii-engine manually. agentmemory currently pins iii-engine to v0.11.2 — v0.11.6 introduces a new sandbox-everything-via-iii worker add model that agentmemory hasn't been refactored for yet. Pin lifts once the refactor lands. Override with AGENTMEMORY_III_VERSION=<version> if you've migrated to the sandbox model manually.

macOS arm64: mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii
macOS x64: swap aarch64-apple-darwin for x86_64-apple-darwin
Linux x64: swap for x86_64-unknown-linux-gnu
Linux arm64: swap for aarch64-unknown-linux-gnu
Windows: download iii-x86_64-pc-windows-msvc.zip from iii-hq/iii releases v0.11.2, extract iii.exe, add to PATH

Or use Docker (the bundled docker-compose.yml pulls iiidev/iii:0.11.2). Full docs: iii.dev/docs.

Windows

agentmemory runs on Windows 10/11, but the Node.js package alone isn't enough — you also need the iii-engine runtime (a separate native binary) as a background process. The official upstream installer is a sh script and there is no PowerShell installer or scoop/winget package today, so Windows users have two paths:

Option A — Prebuilt Windows binary (recommended):

# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 in your browser
#    (we pin to v0.11.2 until agentmemory refactors for the new sandbox
#     model that engine v0.11.6+ requires)
# 2. Download iii-x86_64-pc-windows-msvc.zip
#    (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
# 3. Extract iii.exe somewhere on PATH, or place it at:
#    %USERPROFILE%\.local\bin\iii.exe
#    (agentmemory checks that location automatically)
# 4. Verify:
iii --version
# Should print: 0.11.2

# 5. Then run agentmemory as usual:
npx -y @agentmemory/agentmemory

Option B — Docker Desktop:

# 1. Install Docker Desktop for Windows
# 2. Start Docker Desktop and make sure the engine is running
# 3. Run agentmemory — it will auto-start the bundled compose file:
npx -y @agentmemory/agentmemory

Option C — standalone MCP only (no engine): if you only need the MCP tools for your agent and don't need the REST API, viewer, or cron jobs, skip the engine entirely:

npx -y @agentmemory/agentmemory mcp
# or via the shim package:
npx -y @agentmemory/mcp

Diagnostics for Windows: if npx @agentmemory/agentmemory fails, re-run with --verbose to see the actual engine stderr. Common failure modes:

Symptom	Fix
`iii-engine process started` then `did not become ready within 15s`	Engine crashed on startup — re-run with `--verbose`, check stderr
`Could not start iii-engine`	Neither `iii.exe` nor Docker is installed. See Option A or B above
Port conflict	`netstat -ano \| findstr :3111` to see what's bound, then kill it or use `--port <N>`
Docker fallback skipped even though Docker is installed	Make sure Docker Desktop is actually running (system tray icon)

Note: there is no cargo install iii-engine — iii is not published to crates.io. The only supported install methods are the prebuilt binary above, the upstream sh install script (macOS/Linux only), and the Docker image.

Deploy

One-click templates for managed hosts. Each one ships a self-contained Dockerfile that pulls @agentmemory/agentmemory from npm and copies the iii engine binary in from the official iiidev/iii Docker Hub image — no pre-built agentmemory image required. Persistent storage mounts at /data; the first-boot entrypoint overwrites the npm-bundled iii config (which binds 127.0.0.1) with a deploy-tuned one that binds 0.0.0.0 and uses absolute /data paths, generates the HMAC secret, then drops privileges from root to node via gosu before exec'ing the agentmemory CLI.

Render's one-click deploy button requires render.yaml at the repository root, which we deliberately keep clean. Use the Render Blueprint flow documented in deploy/render/ to point at the in-repo blueprint manually.

Full setup details (HMAC capture, viewer SSH tunnel, rotation, backup, cost floors) live in deploy/:

deploy/fly — single machine with auto_stop_machines = "stop"; cheapest idle.
deploy/railway — Hobby plan flat fee, volume in the dashboard.
deploy/render — Blueprint flow, automatic disk snapshots on paid plans.
deploy/coolify — self-hosted on your own VPS via Coolify; same Docker Compose stack, you own the host and the data.

Only port 3111 is published. The viewer on 3113 stays bound to loopback inside the container — every template's README documents the SSH-tunnel pattern for reaching it.

Every coding agent forgets everything when the session ends. You waste the first 5 minutes of every session re-explaining your stack. agentmemory runs in the background and eliminates that entirely.

Session 1: "Add auth to the API"
  Agent writes code, runs tests, fixes bugs
  agentmemory silently captures every tool use
  Session ends -> observations compressed into structured memory

Session 2: "Now add rate limiting"
  Agent already knows:
    - Auth uses JWT middleware in src/middleware/auth.ts
    - Tests in test/auth.test.ts cover token validation
    - You chose jose over jsonwebtoken for Edge compatibility
  Zero re-explaining. Starts working immediately.

vs built-in agent memory

Every AI coding agent ships with built-in memory — Claude Code has MEMORY.md, Cursor has notepads, Cline has memory bank. These work like sticky notes. agentmemory is the searchable database behind the sticky notes.

	Built-in (CLAUDE.md)	agentmemory
Scale	200-line cap	Unlimited
Search	Loads everything into context	BM25 + vector + graph (top-K only)
Token cost	22K+ at 240 observations	~1,900 tokens (92% less)
Cross-agent	Per-agent files	MCP + REST (any agent)
Coordination	None	Leases, signals, actions, routines
Observability	Read files manually	Real-time viewer on :3113

Memory Pipeline

PostToolUse hook fires
  -> SHA-256 dedup (5min window)
  -> Privacy filter (strip secrets, API keys)
  -> Store raw observation
  -> LLM compress -> structured facts + concepts + narrative
  -> Vector embedding (6 providers + local)
  -> Index in BM25 + vector

Stop / SessionEnd hook fires
  -> Summarize session
  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)

SessionStart hook fires
  -> Load project profile (top concepts, files, patterns)
  -> Hybrid search (BM25 + vector + graph)
  -> Token budget (default: 2000 tokens)
  -> Inject into conversation

4-Tier Memory Consolidation

Inspired by how human brains process memory — not unlike sleep consolidation.

Tier	What	Analogy
Working	Raw observations from tool use	Short-term memory
Episodic	Compressed session summaries	"What happened"
Semantic	Extracted facts and patterns	"What I know"
Procedural	Workflows and decision patterns	"How to do it"

Memories decay over time (Ebbinghaus curve). Frequently accessed memories strengthen. Stale memories auto-evict. Contradictions are detected and resolved.

What Gets Captured

Hook	Captures
`SessionStart`	Project path, session ID
`UserPromptSubmit`	User prompts (privacy-filtered)
`PreToolUse`	File access patterns + enriched context
`PostToolUse`	Tool name, input, output
`PostToolUseFailure`	Error context
`PreCompact`	Re-injects memory before compaction
`SubagentStart/Stop`	Sub-agent lifecycle
`Stop`	End-of-session summary
`SessionEnd`	Session complete marker

Key Capabilities

Capability	Description
Automatic capture	Every tool use recorded via hooks — zero manual effort
Semantic search	BM25 + vector + knowledge graph with RRF fusion
Memory evolution	Versioning, supersession, relationship graphs
Auto-forgetting	TTL expiry, contradiction detection, importance eviction
Privacy first	API keys, secrets, `<private>` tags stripped before storage
Self-healing	Circuit breaker, provider fallback chain, health monitoring
Claude bridge	Bi-directional sync with MEMORY.md
Knowledge graph	Entity extraction + BFS traversal
Team memory	Namespaced shared + private across team members
Citation provenance	Trace any memory back to source observations
Git snapshots	Version, rollback, and diff memory state

Triple-stream retrieval combining three signals:

Stream	What it does	When
BM25	Stemmed keyword matching with synonym expansion	Always on
Vector	Cosine similarity over dense embeddings	Embedding provider configured
Graph	Knowledge graph traversal via entity matching	Entities detected in query

Fused with Reciprocal Rank Fusion (RRF, k=60) and session-diversified (max 3 results per session).

BM25 tokenizes Greek, Cyrillic, Hebrew, Arabic, and accented Latin out of the box. For Chinese / Japanese / Korean memories, install the optional segmenters (npm install @node-rs/jieba tiny-segmenter) to split CJK runs into word-level tokens; without them, agentmemory soft-falls to whole-run tokenization and prints a one-time hint on stderr.

Embedding providers

agentmemory auto-detects your provider. For best results, install local embeddings (free):

npm install @xenova/transformers

Provider	Model	Cost	Notes
Local (recommended)	`all-MiniLM-L6-v2`	Free	Offline, +8pp recall over BM25-only
Gemini	`gemini-embedding-001`	Free tier	100+ languages, 768/1536/3072 dims (MRL), 2048-token input. Replaces `text-embedding-004` (deprecated, shutdown Jan 14, 2026)
OpenAI	`text-embedding-3-small`	$0.02/1M	Highest quality
Voyage AI	`voyage-code-3`	Paid	Optimized for code
Cohere	`embed-english-v3.0`	Free trial	General purpose
OpenRouter	Any model	Varies	Multi-model proxy

51 tools, 6 resources, 3 prompts, and 4 skills — the most comprehensive MCP memory toolkit for any agent.

MCP shim vs full server: the published @agentmemory/mcp package is a thin shim. It exposes the full 51-tool surface only when it can reach a running agentmemory server via AGENTMEMORY_URL (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (memory_save, memory_recall, memory_smart_search, memory_sessions, memory_export, memory_audit, memory_governance_delete). The AGENTMEMORY_TOOLS=core|all env var is a server-side flag — setting it in the shim's env block has no effect. If you see only 7 tools in Cursor / OpenCode / Gemini CLI, start npx @agentmemory/agentmemory (or the Docker stack) and set AGENTMEMORY_URL=http://localhost:3111.

51 Tools

Core tools (always available)

Tool	Description
`memory_recall`	Search past observations
`memory_compress_file`	Compress markdown files while preserving structure
`memory_save`	Save an insight, decision, or pattern
`memory_patterns`	Detect recurring patterns
`memory_smart_search`	Hybrid semantic + keyword search
`memory_file_history`	Past observations about specific files
`memory_sessions`	List recent sessions
`memory_timeline`	Chronological observations
`memory_profile`	Project profile (concepts, files, patterns)
`memory_export`	Export all memory data
`memory_relations`	Query relationship graph

Extended tools (51 total — set AGENTMEMORY_TOOLS=all)

Tool	Description
`memory_patterns`	Detect recurring patterns
`memory_timeline`	Chronological observations
`memory_relations`	Query relationship graph
`memory_graph_query`	Knowledge graph traversal
`memory_consolidate`	Run 4-tier consolidation
`memory_claude_bridge_sync`	Sync with MEMORY.md
`memory_team_share`	Share with team members
`memory_team_feed`	Recent shared items
`memory_audit`	Audit trail of operations
`memory_governance_delete`	Delete with audit trail
`memory_snapshot_create`	Git-versioned snapshot
`memory_action_create`	Create work items with dependencies
`memory_action_update`	Update action status
`memory_frontier`	Unblocked actions ranked by priority
`memory_next`	Single most important next action
`memory_lease`	Exclusive action leases (multi-agent)
`memory_routine_run`	Instantiate workflow routines
`memory_signal_send`	Inter-agent messaging
`memory_signal_read`	Read messages with receipts
`memory_checkpoint`	External condition gates
`memory_mesh_sync`	P2P sync between instances
`memory_sentinel_create`	Event-driven watchers
`memory_sentinel_trigger`	Fire sentinels externally
`memory_sketch_create`	Ephemeral action graphs
`memory_sketch_promote`	Promote to permanent
`memory_crystallize`	Compact action chains
`memory_diagnose`	Health checks
`memory_heal`	Auto-fix stuck state
`memory_facet_tag`	Dimension:value tags
`memory_facet_query`	Query by facet tags
`memory_verify`	Trace provenance

6 Resources · 3 Prompts · 4 Skills

Type	Name	Description
Resource	`agentmemory://status`	Health, session count, memory count
Resource	`agentmemory://project/{name}/profile`	Per-project intelligence
Resource	`agentmemory://memories/latest`	Latest 10 active memories
Resource	`agentmemory://graph/stats`	Knowledge graph statistics
Prompt	`recall_context`	Search + return context messages
Prompt	`session_handoff`	Handoff data between agents
Prompt	`detect_patterns`	Analyze recurring patterns
Skill	`/recall`	Search memory
Skill	`/remember`	Save to long-term memory
Skill	`/session-history`	Recent session summaries
Skill	`/forget`	Delete observations/sessions

Standalone MCP

Run without the full server — for any MCP client. Either of these works:

npx -y @agentmemory/agentmemory mcp   # canonical (always available)
npx -y @agentmemory/mcp                # shim package alias

Or add to your agent's MCP config:

Most agents (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

Merge the agentmemory entry into your host's existing mcpServers object rather than replacing the file. For sandboxed clients that can't reach the host's localhost, add "AGENTMEMORY_FORCE_PROXY": "1" to the env block and set AGENTMEMORY_URL to a route the sandbox can reach.

OpenCode (opencode.json):

{
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["npx", "-y", "@agentmemory/mcp"],
      "enabled": true
    }
  }
}

Auto-starts on port 3113. Live observation stream, session explorer, memory browser, knowledge graph visualization, and health dashboard.

open http://localhost:3113

The viewer server binds to 127.0.0.1 by default. The REST-served /agentmemory/viewer endpoint follows the normal AGENTMEMORY_SECRET bearer-token rules. CSP headers use a per-response script nonce and disable inline handler attributes (script-src-attr 'none').

The viewer at :3113 shows what your agent remembered. The iii console shows what your agent did — every memory op as an OpenTelemetry trace, every KV entry editable, every function invocable, every stream tappable. Two windows on the same memory: one product-shaped, one engine-shaped.

Watch a memory_smart_search fire and see the BM25 scan → embedding lookup → RRF fusion → reranker as a waterfall. Edit a stuck consolidation timer in the KV browser. Replay a PostToolUse hook with a tweaked payload. Pin the WebSocket stream and watch observations land live.

agentmemory ships this for free because every function, trigger, state scope, and stream is an iii primitive — nothing custom, nothing to instrument.

Workers page: every connected worker — including agentmemory itself — with PID, function count, runtime, and last-seen.

Already installed. The console ships with iii — no separate installer.

Launch alongside agentmemory:

# agentmemory viewer holds port 3113, so run the console on 3114.
# Engine REST (3111), WebSocket (3112), and bridge (49134) defaults match agentmemory.
iii console --port 3114

Then open http://localhost:3114. Add --enable-flow for the experimental architecture-graph page.

Override engine endpoints only if you've moved them:

iii console --port 3114 \
  --engine-port 3111 \
  --ws-port 3112 \
  --bridge-port 49134

What you can do from the console:

Page	Use it to
Workers	See every connected worker and its live metrics — including the agentmemory worker itself.
Functions	Invoke any of agentmemory's functions directly with a JSON payload — handy for testing `memory.recall`, `memory.consolidate`, `graph.query` without wiring a client.
Triggers	Replay HTTP, cron, event, and state triggers — fire the consolidation cron manually, retry an HTTP route, emit a state change.
States	KV browser with full CRUD — sessions, memory slots, lifecycle timers, embeddings index — edit values in place.
Streams	Live WebSocket monitor for memory writes, hook events, and observation updates as they flow through iii streams.
Queues	Durable queue topics + dead-letter management. Replay or drop failed embedding / compression jobs.
Traces	OpenTelemetry waterfall / flame / service-breakdown views. Filter by `trace_id` to see exactly which functions, DB calls, and embedding requests a single `memory.search` produced.
Logs	Structured OTEL logs filtered and correlated to trace/span IDs.
Config	Runtime configuration — see exactly which workers, providers, and ports your engine is running with.
Flow	(Optional, `--enable-flow`) Interactive architecture graph of every worker, trigger, and stream.

Traces: waterfall / flame / service breakdown for every memory operation.

Traces are already on:

iii-config.yaml ships with the iii-observability worker enabled (exporter: memory, sampling_ratio: 1.0, metrics + logs). No extra config needed — the moment agentmemory starts, every memory operation emits a trace span and a structured log the console can read.

If you want to export to Jaeger/Honeycomb/Grafana Tempo instead, change exporter: memory to exporter: otlp and set the collector endpoint per iii's observability docs.

Heads-up: no auth is enforced on the console itself — keep it bound to 127.0.0.1 (the default) and never expose it publicly.

agentmemory is already a running iii instance. Functions, triggers, KV state, streams, OTEL traces — all of it is iii primitives. You didn't install Postgres, Redis, Express, pm2, or Prometheus, because iii replaces them.

That means one more command extends agentmemory with an entire new capability.

Extend agentmemory with one command

iii worker add iii-pubsub          # fan memory writes out to every connected instance
iii worker add iii-cron            # scheduled consolidation, decay sweeps, snapshot rotation
iii worker add iii-queue           # durable retries for embedding + compression jobs
iii worker add iii-observability   # OTEL traces on every memory op (default on)
iii worker add iii-sandbox         # run recalled code inside an isolated microVM
iii worker add iii-database        # swap in a SQL-backed state adapter
iii worker add mcp                 # generic MCP host alongside the agentmemory MCP

Each iii worker add registers new functions and triggers into the same engine agentmemory is already running on. The viewer and console pick them up immediately — no reload, no new integration, no new container.

`iii worker add`	What you get on top of agentmemory
`iii-pubsub`	Multi-instance memory: every `remember` fans out, every `search` reads the union
`iii-cron`	Scheduled lifecycle — nightly consolidation, weekly snapshots, decay on a fixed clock
`iii-queue`	Durable retries: failed embedding + compression jobs survive restart, no lost observations
`iii-observability`	OTEL traces, metrics, logs on every function — wired in `iii-config.yaml` from day one
`iii-sandbox`	Code that came out of `memory_recall` runs inside a throwaway VM, not your shell
`iii-database`	SQL-backed state adapter when you outgrow the in-memory KV defaults
`mcp`	Stand up extra MCP servers next to agentmemory's, share the same engine

Full registry: workers.iii.dev. Every worker there composes through the same primitives agentmemory uses — and the agentmemory you already have is one of them.

What iii replaces

Traditional stack	agentmemory uses
Express.js / Fastify	iii HTTP Triggers
SQLite / Postgres + pgvector	iii KV State + in-memory vector index
SSE / Socket.io	iii Streams (WebSocket)
pm2 / systemd	iii engine worker supervision
Prometheus / Grafana	iii OTEL + health monitor
Custom plugin systems	`iii worker add <name>`

118 source files · ~21,800 LOC · 950+ tests · 123 functions · 34 KV scopes — all on three primitives. No agentmemory plugin install. The plugin system is iii itself.

LLM Providers

agentmemory auto-detects from your environment. No API key needed if you have a Claude subscription.

Provider	Config	Notes
No-op (default)	No config needed	LLM-backed compress/summarize is DISABLED. Synthetic BM25 compression + recall still work. See `AGENTMEMORY_ALLOW_AGENT_SDK` below if you used to rely on the Claude-subscription fallback.
Anthropic API	`ANTHROPIC_API_KEY`	Per-token billing
MiniMax	`MINIMAX_API_KEY`	Anthropic-compatible
Gemini	`GEMINI_API_KEY`	Also enables embeddings
OpenRouter	`OPENROUTER_API_KEY`	Any model
Claude subscription fallback	`AGENTMEMORY_ALLOW_AGENT_SDK=true`	Opt-in only. Spawns `@anthropic-ai/claude-agent-sdk` sessions — used to cause unbounded Stop-hook recursion (#149 follow-up) so it is no longer the default.

Environment Variables

Create ~/.agentmemory/.env:

# LLM provider (pick one — default is the no-op provider: no LLM calls)
# ANTHROPIC_API_KEY=sk-ant-...
# ANTHROPIC_BASE_URL=...              # Optional: Anthropic-compatible proxy / Azure
# GEMINI_API_KEY=...
# OPENROUTER_API_KEY=...
# MINIMAX_API_KEY=...
# OPENAI_API_KEY=***                       # NOTE: this same key auto-activates BOTH the
#                                          # OpenAI LLM provider (here) AND the OpenAI
#                                          # embedding provider (further below). Set
#                                          # OPENAI_API_KEY_FOR_LLM=false to scope it
#                                          # to embeddings only.
# OPENAI_BASE_URL=https://api.openai.com   # Optional: override for Azure / vLLM / LM Studio / proxies
#                                          # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
#                                          # Auto-detected from `.openai.azure.com` hostname; uses
#                                          # api-key header + api-version query param.
# OPENAI_API_VERSION=2024-08-01-preview    # Optional: Azure api-version query param
# OPENAI_MODEL=gpt-4o-mini                 # Optional: default model
# OPENAI_TIMEOUT_MS=60000                  # Optional: outbound fetch timeout (default 60s)
# OPENAI_REASONING_EFFORT=none             # Optional: "low" | "medium" | "high" | "none"
#                                          # Honored only by OpenAI's reasoning models (o1, o3,
#                                          # gpt-*-reasoning) and providers that mirror that
#                                          # schema (Ollama Cloud thinking models). Standard
#                                          # chat models reject this field with 400. Set to
#                                          # "none" for thinking models that return reasoning
#                                          # but no content.
# OPENAI_API_KEY_FOR_LLM=false             # Optional: set to false to skip OpenAI auto-detection
#                                          # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
# AGENTMEMORY_ALLOW_AGENT_SDK=true

# Embedding provider (auto-detected, or override)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com   # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536        # Required when the model is not in the known-models table

# Search tuning
# BM25_WEIGHT=0.4
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000

# Auth
# AGENTMEMORY_SECRET=your-secret

# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111

# Features
# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default (#138). When on,
                                   # every PostToolUse hook calls your
                                   # LLM provider to compress the
                                   # observation — expect significant
                                   # token spend on active sessions.
# AGENTMEMORY_SLOTS=false          # OFF by default. Editable pinned
                                   # memory slots — persona,
                                   # user_preferences, tool_guidelines,
                                   # project_context, guidance,
                                   # pending_items, session_patterns,
                                   # self_notes. Size-limited; agent
                                   # edits via memory_slot_* tools.
                                   # Pinned slots addressable for
                                   # SessionStart injection.
# AGENTMEMORY_REFLECT=false        # OFF by default. Requires SLOTS=on.
                                   # Stop hook fires mem::slot-reflect:
                                   # scans recent observations, auto-
                                   # appends TODOs to pending_items,
                                   # counts patterns in
                                   # session_patterns, records touched
                                   # files in project_context. Fire-
                                   # and-forget; does not block.
# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
                                   # - SessionStart may inject ~1-2K
                                   #   chars of project context into
                                   #   the first turn of each session
                                   #   (this is what actually reaches
                                   #   the model — Claude Code treats
                                   #   SessionStart stdout as context)
                                   # - PreToolUse fires /agentmemory/enrich
                                   #   on every file-touching tool call
                                   #   (resource cleanup, not a token
                                   #   fix — PreToolUse stdout is debug
                                   #   log only per Claude Code docs)
                                   # Observations are still captured via
                                   # PostToolUse regardless of this flag.
# GRAPH_EXTRACTION_ENABLED=false
# CONSOLIDATION_ENABLED=true
# LESSON_DECAY_ENABLED=true
# OBSIDIAN_AUTO_EXPORT=false
# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false

# Team
# TEAM_ID=
# USER_ID=
# TEAM_MODE=private

# Tool visibility: "core" (8 tools) or "all" (51 tools)
# AGENTMEMORY_TOOLS=core

121 endpoints on port 3111. The REST API binds to 127.0.0.1 by default. Protected endpoints require Authorization: Bearer <secret> when AGENTMEMORY_SECRET is set, and mesh sync endpoints require AGENTMEMORY_SECRET on both peers.

Key endpoints

Method	Path	Description
`GET`	`/agentmemory/health`	Health check (always public)
`POST`	`/agentmemory/session/start`	Start session + get context
`POST`	`/agentmemory/session/end`	End session
`POST`	`/agentmemory/observe`	Capture observation
`POST`	`/agentmemory/smart-search`	Hybrid search
`POST`	`/agentmemory/context`	Generate context
`POST`	`/agentmemory/remember`	Save to long-term memory
`POST`	`/agentmemory/forget`	Delete observations
`POST`	`/agentmemory/enrich`	File context + memories + bugs
`GET`	`/agentmemory/profile`	Project profile
`GET`	`/agentmemory/export`	Export all data
`POST`	`/agentmemory/import`	Import from JSON
`POST`	`/agentmemory/graph/query`	Knowledge graph query
`POST`	`/agentmemory/team/share`	Share with team
`GET`	`/agentmemory/audit`	Audit trail

Full endpoint list: src/triggers/api.ts

npm run dev               # Hot reload
npm run build             # Production build
npm test                  # 950+ tests
npm run test:integration  # API tests (requires running services)

Prerequisites: Node.js >= 20, iii-engine or Docker

Apache-2.0

anthropics/financial-services

Claude for Financial Services

Reference agents, skills, and data connectors for the financial-services workflows we see most — investment banking, equity research, private equity, and wealth management.

Everything here is available two ways from one source: install it as a Claude Cowork plugin, or deploy it through the Claude Managed Agents API behind your own workflow engine. Same system prompt, same skills — you choose where it runs.

Important

Nothing in this repository constitutes investment, legal, tax, or accounting advice. These agents draft analyst work product — models, memos, research notes, reconciliations — for review by a qualified professional. They do not make investment recommendations, execute transactions, bind risk, post to a ledger, or approve onboarding; every output is staged for human sign-off. You are responsible for verifying outputs and for compliance with the laws and regulations that apply to your firm.

What's in the repo:

Agents — named, end-to-end workflow agents (Pitch Agent, Market Researcher, GL Reconciler, …). Each ships as a Cowork plugin and as a Claude Managed Agent template you deploy via /v1/agents.
Vertical plugins — the underlying skills, slash commands, and data connectors, bundled by FSI vertical. Install these on their own if you just want /comps, /dcf, /earnings and the connectors without a full agent.

Agents

Each agent is named for the workflow it runs. They're starting points: install the ones that match your work, then tune the prompts, skills, and connectors to how your firm does it.

Each agent plugin is self-contained — it bundles the skills it uses, so installing the agent is all you need.

Function	Agent	What it does
Coverage & advisory	Pitch Agent	Comps, precedents, LBO → branded pitch deck, end to end
	Meeting Prep Agent	Briefing pack before every client meeting
Research & modeling	Market Researcher	Sector or theme → industry overview, competitive landscape, peer comps, ideas shortlist
	Earnings Reviewer	Earnings call + filings → model update → note draft
	Model Builder	DCF, LBO, 3-statement, comps — live in Excel
Fund admin & finance ops	Valuation Reviewer	Ingests GP packages, runs valuation template, stages LP reporting
	GL Reconciler	Finds breaks, traces root cause, routes for sign-off
	Month-End Closer	Accruals, roll-forwards, variance commentary
	Statement Auditor	Audits LP statements before distribution
Operations & onboarding	KYC Screener	Parses onboarding docs, runs the rules engine, flags gaps

For Managed Agent deployment — agent.yaml, leaf-worker subagents, steering-event examples, and per-agent security notes — see managed-agent-cookbooks/.

Repository Layout

plugins/
  agent-plugins/               # Named agents — one self-contained plugin each
  vertical-plugins/            # Skill + command bundles by FSI vertical, plus MCP connectors
  partner-built/               # Partner-authored plugins (LSEG, S&P Global)
managed-agent-cookbooks/       # Claude Managed Agent cookbooks — one dir per agent
claude-for-msft-365-install/   # Admin tooling to provision the Claude Microsoft 365 add-in
scripts/                       # deploy-managed-agent.sh · check.py · validate.py · orchestrate.py · sync-agent-skills.py

Getting Started

Cowork

In Cowork, open Settings → Plugins → Add plugin and either:

Paste this repo URL — https://github.com/anthropics/financial-services — then pick the agents and verticals you want from the marketplace list, or
Upload a zip — zip any directory under plugins/ (e.g. plugins/agent-plugins/pitch-agent/) and drop it in.

Claude Code

# Add the marketplace
claude plugin marketplace add anthropics/financial-services

# Core skills + connectors (install first)
claude plugin install financial-analysis@claude-for-financial-services

# Named agents — pick the ones you want
claude plugin install pitch-agent@claude-for-financial-services
claude plugin install gl-reconciler@claude-for-financial-services
claude plugin install market-researcher@claude-for-financial-services

# Vertical skill bundles
claude plugin install investment-banking@claude-for-financial-services
claude plugin install equity-research@claude-for-financial-services

Once installed, agents appear in Cowork dispatch, skills fire automatically when relevant, and slash commands are available in your session (/comps, /dcf, /earnings, /ic-memo, …).

Claude Managed Agents

export ANTHROPIC_API_KEY=sk-ant-...
scripts/deploy-managed-agent.sh gl-reconciler

Each template under managed-agent-cookbooks/ references the same system prompt and skills as its plugin counterpart. The deploy script resolves file references, uploads skills, creates leaf-worker subagents, and POSTs the orchestrator to /v1/agents. See scripts/orchestrate.py for a reference event loop that routes handoff_request events between agents via your own orchestration layer.

Research Preview: subagent delegation (callable_agents) is a preview capability. See per-agent READMEs for security and handoff guidance.

How It Fits Together

	What it is	Where it lives
Agents	Self-contained plugins that own a workflow end to end — system prompt plus the skills it uses. Cowork and the Managed Agent wrapper both reference the same directory.	`plugins/agent-plugins/<slug>/`
Skills	Domain expertise, conventions, and step-by-step methods Claude draws on automatically when relevant. Authored once in the verticals; each agent bundles a synced copy of the ones it needs.	`plugins/vertical-plugins/<vertical>/skills/` (source) · `plugins/agent-plugins/<slug>/skills/` (bundled)
Commands	Slash actions you trigger explicitly (`/comps`, `/earnings`, `/ic-memo`).	`plugins/vertical-plugins/<vertical>/commands/`
Connectors	MCP servers that wire Claude to your data — terminals, research platforms, document stores.	`plugins/vertical-plugins/financial-analysis/.mcp.json`
Managed-agent wrappers	`agent.yaml` + depth-1 subagents + steering examples for headless deployment.	`managed-agent-cookbooks/<slug>/`

Everything is file-based — markdown and JSON, no build step.

Vertical Plugins

Start with financial-analysis — it carries the shared modeling skills and all data connectors. Add verticals for the workflows you need.

Plugin	What it adds
financial-analysis (core)	Comps, DCF, LBO, 3-statement, deck QC, Excel audit. All 11 data connectors.
investment-banking	CIMs, teasers, process letters, buyer lists, merger models, deal tracking.
equity-research	Earnings notes, initiations, model updates, thesis and catalyst tracking.
private-equity	Sourcing, screening, diligence checklists, IC memos, portfolio monitoring.
wealth-management	Client reviews, financial plans, rebalancing, reporting, TLH.
fund-admin	GL recon, break tracing, accruals, roll-forwards, variance commentary, NAV tie-out.
operations	KYC document parsing and rules-grid evaluation.
lseg (partner)	Bond RV, swap curves, FX carry, options vol, macro-rates monitoring on LSEG data.
sp-global (partner)	Tear sheets, earnings previews, funding digests on S&P Capital IQ.

MCP Integrations

All connectors are centralized in the financial-analysis core plugin and shared across the rest.

Provider	URL
Daloopa	`https://mcp.daloopa.com/server/mcp`
Morningstar	`https://mcp.morningstar.com/mcp`
S&P Global	`https://kfinance.kensho.com/integrations/mcp`
FactSet	`https://mcp.factset.com/mcp`
Moody's	`https://api.moodys.com/genai-ready-data/m1/mcp`
MT Newswires	`https://vast-mcp.blueskyapi.com/mtnewswires`
Aiera	`https://mcp-pub.aiera.com`
LSEG	`https://api.analytics.lseg.com/lfa/mcp`
PitchBook	`https://premium.mcp.pitchbook.com/mcp`
Chronograph	`https://ai.chronograph.pe/mcp`
Egnyte	`https://mcp-server.egnyte.com/mcp`

MCP access may require a subscription or API key from the provider.

Claude for Microsoft 365 — Install Tooling

If your firm runs Claude inside Excel, PowerPoint, Word, and Outlook via the Microsoft 365 add-in, claude-for-msft-365-install/ is the admin tooling to provision it against your own cloud — Vertex AI, Bedrock, or an internal LLM gateway — instead of Anthropic's API.

It's a Claude Code plugin (not a Cowork plugin) that walks an IT admin through generating the customized add-in manifest, granting Azure admin consent, and writing per-user routing config via Microsoft Graph. Install with:

claude plugin install claude-for-msft-365-install@claude-for-financial-services
/claude-for-msft-365-install:setup

This is separate from the agents and vertical plugins above — it's the on-ramp that gets the add-in deployed in a tenant, after which the agents and skills here are what runs inside it.

Making It Yours

These are reference templates — they get better when you tune them to how your firm works.

Swap connectors — point .mcp.json at your data providers and internal systems.
Add firm context — drop your terminology, processes, and formatting standards into skill files.
Bring your templates — /ppt-template teaches Claude your branded PowerPoint layouts.
Adjust agent scope — edit agents/<slug>.md to match how your team actually runs the workflow.
Add your own — copy the structure for workflows we haven't covered.

Skill & Command Reference

financial-analysis — core modeling, Excel, deck QC

Skill	Command	Description
comps-analysis	`/comps`	Comparable company analysis with trading multiples
dcf-model	`/dcf`	DCF valuation with WACC and sensitivity analysis
lbo-model	`/lbo`	Leveraged buyout model
3-statement-model	`/3-statement-model`	Populate 3-statement financial model templates
audit-xls	`/debug-model`	Excel model audit — formula tracing, hardcode detection, balance checks
clean-data-xls	—	Normalize and clean tabular data in Excel
deck-refresh	—	Re-link and refresh embedded charts/tables across a deck
competitive-analysis	`/competitive-analysis`	Competitive landscape and market positioning
ib-check-deck	—	QC presentations for errors and consistency
pptx-author	—	Produce a `.pptx` file headlessly (Managed Agent mode)
xlsx-author	—	Produce a `.xlsx` file headlessly (Managed Agent mode)
ppt-template-creator	`/ppt-template`	Create reusable PPT template skills
skill-creator	—	Guide for creating new skills

investment-banking — deal materials and execution

Skill	Command	Description
strip-profile	`/one-pager`	One-page company profiles for pitch books
pitch-deck	—	Populate pitch deck templates with data
datapack-builder	—	Build data packs from CIMs and filings
cim-builder	`/cim`	Draft Confidential Information Memorandums
teaser	`/teaser`	Anonymous one-page company teasers
buyer-list	`/buyer-list`	Strategic and financial buyer universe
merger-model	`/merger-model`	Accretion/dilution M&A analysis
process-letter	`/process-letter`	Bid instructions and process correspondence
deal-tracker	`/deal-tracker`	Track live deals, milestones, and action items

equity-research — coverage and publishing

Skill	Command	Description
earnings-analysis	`/earnings`	Post-earnings quarterly update reports
earnings-preview	`/earnings-preview`	Pre-earnings scenario analysis and key metrics
initiating-coverage	`/initiate`	Institutional-quality initiation reports
model-update	`/model-update`	Update financial models with new data
morning-note	`/morning-note`	Morning meeting notes and trade ideas
sector-overview	`/sector`	Industry landscape and thematic reports
thesis-tracker	`/thesis`	Maintain and update investment theses
catalyst-calendar	`/catalysts`	Track upcoming catalysts across coverage
idea-generation	`/screen`	Stock screening and idea sourcing

private-equity — sourcing through portfolio ops

Skill	Command	Description
deal-sourcing	`/source`	Discover companies, check CRM, draft founder outreach
deal-screening	`/screen-deal`	Quick pass/fail on inbound CIMs and teasers
dd-checklist	`/dd-checklist`	Diligence checklists by workstream
dd-meeting-prep	`/dd-prep`	Prep for management presentations and expert calls
unit-economics	`/unit-economics`	ARR cohorts, LTV/CAC, net retention, revenue quality
returns-analysis	`/returns`	IRR/MOIC sensitivity tables
ic-memo	`/ic-memo`	Investment committee memo drafting
portfolio-monitoring	`/portfolio`	Track portfolio company KPIs and variances
value-creation-plan	`/value-creation`	Post-close 100-day plans and EBITDA bridges
ai-readiness	`/ai-readiness`	Assess a portfolio company's AI readiness

wealth-management — advisor workflows

Skill	Command	Description
client-review	`/client-review`	Prep for client meetings with performance and talking points
financial-plan	`/financial-plan`	Retirement, education, estate, and cash-flow projections
portfolio-rebalance	`/rebalance`	Allocation drift analysis and tax-aware rebalancing
client-report	`/client-report`	Client-facing performance reports
investment-proposal	`/proposal`	Proposals for prospective clients
tax-loss-harvesting	`/tlh`	Identify TLH opportunities and manage wash sales

Contributing

Everything here is markdown and YAML. Fork, edit, PR. For new content:

New skill → add it under plugins/vertical-plugins/<vertical>/skills/, then run python3 scripts/sync-agent-skills.py to propagate to any agent that bundles it.
New agent → plugins/agent-plugins/<slug>/ (with agents/<slug>.md + skills/) and a matching managed-agent-cookbooks/<slug>/.
Run python3 scripts/check.py before pushing — it lints every manifest, verifies all cross-file references resolve, and fails if any bundled skill has drifted from its vertical source.

License

Apache License 2.0

bytedance/UI-TARS-desktop

The Open-Source Multimodal AI Agent Stack: Connecting Cutting-Edge AI Models and Agent Infra

Introduction

English | 简体中文

TARS^* is a Multimodal AI Agent stack, currently shipping two projects: Agent TARS and UI-TARS-desktop:

Agent TARS	UI-TARS-desktop

Agent TARS is a general multimodal AI Agent stack, it brings the power of GUI Agent and Vision into your terminal, computer, browser and product. It primarily ships with a CLI and Web UI for usage. It aims to provide a workflow that is closer to human-like task completion through cutting-edge multimodal LLMs and seamless integration with various real-world MCP tools.	UI-TARS Desktop is a desktop application that provides a native GUI Agent based on the UI-TARS model. It primarily ships a local and remote computer as well as browser operators.

News

[2025-11-05] 🎉 We're excited to announce the release of Agent TARS CLI v0.3.0! This version brings streaming support for multiple tools (shell commands, multi-file structured display), runtime settings with timing statistics for tool calls and deep thinking, Event Stream Viewer for data flow tracking and debugging. Additionally, it features exclusive support for AIO agent Sandbox as isolated all-in-one tools execution environment.
[2025-06-25] We released an Agent TARS Beta and Agent TARS CLI - Introducing Agent TARS Beta, a multimodal AI agent that aims to explore a work form that is closer to human-like task completion through rich multimodal capabilities (such as GUI Agent, Vision) and seamless integration with various real-world tools.
[2025-06-12] - 🎁 We are thrilled to announce the release of UI-TARS Desktop v0.2.0! This update introduces two powerful new features: Remote Computer Operator and Remote Browser Operator—both completely free. No configuration required: simply click to remotely control any computer or browser, and experience a new level of convenience and intelligence.
[2025-04-17] - 🎉 We're thrilled to announce the release of new UI-TARS Desktop application v0.1.0, featuring a redesigned Agent UI. The application enhances the computer using experience, introduces new browser operation features, and supports the advanced UI-TARS-1.5 model for improved performance and precise control.
[2025-02-20] - 📦 Introduced UI TARS SDK, is a powerful cross-platform toolkit for building GUI automation agents.
[2025-01-23] - 🚀 We updated the Cloud Deployment section in the 中文版: GUI模型部署教程 with new information related to the ModelScope platform. You can now use the ModelScope platform for deployment.

Agent TARS

Agent TARS is a general multimodal AI Agent stack, it brings the power of GUI Agent and Vision into your terminal, computer, browser and product.

It primarily ships with a CLI and Web UI for usage. It aims to provide a workflow that is closer to human-like task completion through cutting-edge multimodal LLMs and seamless integration with various real-world MCP tools.

Showcase

Please help me book the earliest flight from San Jose to New York on September 1st and the last return flight on September 6th on Priceline

https://github.com/user-attachments/assets/772b0eef-aef7-4ab9-8cb0-9611820539d8

Booking Hotel	Generate Chart with extra MCP Servers

Instruction: I am in Los Angeles from September 1st to September 6th, with a budget of $5,000. Please help me book a Ritz-Carlton hotel closest to the airport on booking.com and compile a transportation guide for me	Instruction: Draw me a chart of Hangzhou's weather for one month

For more use cases, please check out #842.

Core Features

🖱️ One-Click Out-of-the-box CLI - Supports both headful Web UI and headless server execution.
🌐 Hybrid Browser Agent - Control browsers using GUI Agent, DOM, or a hybrid strategy.
🔄 Event Stream - Protocol-driven Event Stream drives Context Engineering and Agent UI.
🧰 MCP Integration - The kernel is built on MCP and also supports mounting MCP Servers to connect to real-world tools.

Quick Start

# Launch with `npx`.
npx @agent-tars/cli@latest

# Install globally, required Node.js >= 22
npm install @agent-tars/cli@latest -g

# Run with your preferred model provider
agent-tars --provider volcengine --model doubao-1-5-thinking-vision-pro-250428 --apiKey your-api-key
agent-tars --provider anthropic --model claude-3-7-sonnet-latest --apiKey your-api-key

Visit the comprehensive Quick Start guide for detailed setup instructions.

Documentation

🌟 Explore Agent TARS Universe 🌟

Category	Resource Link	Description
🏠 Central Hub		Your gateway to Agent TARS ecosystem
📚 Quick Start		Zero to hero in 5 minutes
🚀 What's New		Discover cutting-edge features & vision
🛠️ Developer Zone		Master every command & features
🎯 Showcase		View use cases built by the official and community
🔧 Reference		Complete technical reference

UI-TARS Desktop

UI-TARS Desktop is a native GUI agent for your local computer, driven by UI-TARS and Seed-1.5-VL/1.6 series models.

📑 Paper | 🤗 Hugging Face Models | 🫨 Discord | 🤖 ModelScope
🖥️ Desktop Application | 👓 Midscene (use in browser)

Showcase

Instruction	Local Operator	Remote Operator
Please help me open the autosave feature of VS Code and delay AutoSave operations for 500 milliseconds in the VS Code setting.
Could you help me check the latest open issue of the UI-TARS-Desktop project on GitHub?

Features

🤖 Natural language control powered by Vision-Language Model
🖥️ Screenshot and visual recognition support
🎯 Precise mouse and keyboard control
💻 Cross-platform support (Windows/MacOS/Browser)
🔄 Real-time feedback and status display
🔐 Private and secure - fully local processing

Quick Start

See Quick Start

Contributing

See CONTRIBUTING.md.

License

This project is licensed under the Apache License 2.0.

Citation

If you find our paper and code useful in your research, please consider giving a star ⭐ and citation 📝

@article{qin2025ui,
  title={UI-TARS: Pioneering Automated GUI Interaction with Native Agents},
  author={Qin, Yujia and Ye, Yining and Fang, Junjie and Wang, Haoming and Liang, Shihao and Tian, Shizuo and Zhang, Junda and Li, Jiahao and Li, Yunxin and Huang, Shijue and others},
  journal={arXiv preprint arXiv:2501.12326},
  year={2025}
}

decolua/9router

Unlimited FREE AI coding. Connect Claude Code, Codex, Cursor, Cline, Copilot, Antigravity to FREE Claude/GPT/Gemini via 40+ providers. Auto-fallback, RTK -40% tokens, never hit limits.

9Router - FREE AI Router & Token Saver

Never stop coding. Save 20-40% tokens with RTK + auto-fallback to FREE & cheap AI models.

Connect All AI Code Tools (Claude Code, Cursor, Antigravity, Copilot, Codex, Gemini, OpenCode, Cline, OpenClaw...) to 40+ AI Providers & 100+ Models.

🚀 Quick Start • 💡 Features • 📖 Setup • 🌐 Website

🇻🇳 Tiếng Việt • 🇨🇳 中文 • 🇯🇵 日本語

🤔 Why 9Router?

Stop wasting money, tokens and hitting limits:

❌ Subscription quota expires unused every month
❌ Rate limits stop you mid-coding
❌ Tool outputs (git diff, grep, ls...) burn tokens fast
❌ Expensive APIs ($20-50/month per provider)
❌ Manual switching between providers

9Router solves this:

✅ RTK Token Saver - Auto-compress tool_result content, save 20-40% tokens per request
✅ Maximize subscriptions - Track quota, use every bit before reset
✅ Auto fallback - Subscription → Cheap → Free, zero downtime
✅ Multi-account - Round-robin between accounts per provider
✅ Universal - Works with Claude Code, Codex, Cursor, Cline, any CLI tool

🔄 How It Works

┌─────────────┐
│  Your CLI   │  (Claude Code, Codex, OpenClaw, Cursor, Cline...)
│   Tool      │
└──────┬──────┘
       │ http://localhost:20128/v1
       ↓
┌─────────────────────────────────────────────┐
│           9Router (Smart Router)            │
│  • RTK Token Saver (cut tool_result tokens) │
│  • Format translation (OpenAI ↔ Claude)     │
│  • Quota tracking                           │
│  • Auto token refresh                       │
└──────┬──────────────────────────────────────┘
       │
       ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, GitHub Copilot
       │   ↓ quota exhausted
       ├─→ [Tier 2: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
       │   ↓ budget limit
       └─→ [Tier 3: FREE] Kiro, OpenCode Free, Vertex ($300 credits)

Result: Never stop coding, minimal cost + 20-40% token savings via RTK

⚡ Quick Start

1. Install globally:

npm install -g 9router
9router

🎉 Dashboard opens at http://localhost:20128

2. Connect a FREE provider (no signup needed):

Dashboard → Providers → Connect Kiro AI (free Claude unlimited) or OpenCode Free (no auth) → Done!

3. Use in your CLI tool:

Claude Code/Codex/OpenClaw/Cursor/Cline Settings:
  Endpoint: http://localhost:20128/v1
  API Key: [copy from dashboard]
  Model: kr/claude-sonnet-4.5

That's it! Start coding with FREE AI models.

Alternative: run from source (this repository):

This repository package is private (9router-app), so source/Docker execution is the expected local development path.

cp .env.example .env
npm install
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

Production mode:

npm run build
PORT=20128 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run start

Default URLs:

Dashboard: http://localhost:20128/dashboard
OpenAI-compatible API: http://localhost:20128/v1

Video Guides

🇺🇸 English _{9Router + Claude Code FREE Setup by Build AI With Hamid}	🇻🇳 Tiếng Việt _{Tiết kiệm chi phí LLM cho OpenClaw với 9Router by Mì AI}	🇺🇸 English _{Claude Code FREE Forever — Unlimited Models by Build AI With Hamid}
🇺🇸 English _{Claude CLI Free Setup with 9Router 🚀 by CodeVerse Soban}	🇻🇳 Tiếng Việt _{Cài Đặt OpenClaw Free Từ A-Z + 9Router by Mai Gia}	🇺🇸 English _{FREE OpenClaw + Claude Opus 4.6 by Build AI With Hamid}

🎬 Made a video about 9Router? Submit a Pull Request adding your video to this section — we'll merge it!

🛠️ Supported CLI Tools

9Router works seamlessly with all major AI coding tools:

Claude-Code	OpenClaw	Codex	OpenCode	Cursor	Antigravity
Cline	Continue	Droid	Roo	Copilot	Kilo Code

🌐 Supported Providers

🔐 OAuth Providers

Claude-Code

Antigravity

Codex

GitHub

Cursor

🆓 Free Providers

Kiro AI
_{Claude 4.5 + GLM-5 + MiniMax
Unlimited FREE}

OpenCode Free
_{No auth • Auto-fetch models
Unlimited FREE}

Vertex AI
_{Gemini 3 Pro + GLM-5 + DeepSeek
$300 credits free}

Note: iFlow, Qwen and Gemini CLI free tiers were discontinued in 2026. Use Kiro / OpenCode Free / Vertex instead.

🔑 API Key Providers (40+)

_OpenRouter	_GLM	_Kimi	_MiniMax	_OpenAI	_Anthropic
_Gemini	_DeepSeek	_Groq	_xAI	_Mistral	_Perplexity
_{Together AI}	_Fireworks	_Cerebras	_Cohere	_NVIDIA	_SiliconFlow

...and 20+ more providers including Nebius, Chutes, Hyperbolic, and custom OpenAI/Anthropic compatible endpoints

💡 Key Features

Feature	What It Does	Why It Matters
🚀 RTK Token Saver (RTK ⭐40K)	Compress tool outputs (`git diff`, `grep`, `ls`, `tree`...) before sending to LLM	Save 20-40% input tokens per request
🪨 Caveman Mode (Caveman ⭐52K)	Inject caveman-speak prompt → LLM replies terse, technical substance preserved	Save up to 65% output tokens
🎯 Smart 3-Tier Fallback	Auto-route: Subscription → Cheap → Free	Never stop coding, zero downtime
📊 Real-Time Quota Tracking	Live token count + reset countdown	Maximize subscription value
🔄 Format Translation	OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro ↔ Vertex	Works with any CLI tool
👥 Multi-Account Support	Multiple accounts per provider	Load balancing + redundancy
🔄 Auto Token Refresh	OAuth tokens refresh automatically	No manual re-login needed
🎨 Custom Combos	Create unlimited model combinations	Tailor fallback to your needs
📝 Request Logging	Debug mode with full request/response logs	Troubleshoot issues easily
💾 Cloud Sync	Sync config across devices	Same setup everywhere
📊 Usage Analytics	Track tokens, cost, trends over time	Optimize spending
🌐 Deploy Anywhere	Localhost, VPS, Docker, Cloudflare Workers	Flexible deployment options

📖 Feature Details

🚀 RTK Token Saver

Tool outputs (git diff, grep, find, ls, tree, log dumps...) often eat 30-50% of your prompt budget. RTK detects them and applies smart, lossless compression before the request hits the LLM:

Filters: git-diff, git-status, grep, find, ls, tree, dedup-log, smart-truncate, read-numbered, search-list
Auto-detect: No config needed — RTK peeks the first 1KB of each tool_result and picks the right filter.
Safe by design: If a filter fails, throws, or makes output bigger, RTK silently keeps the original text. Errors never break your request.
Universal: Works across all formats (OpenAI, Claude, Gemini, Cursor, Kiro, OpenAI Responses) because it runs before any format translation.
Default ON: Toggle anytime in Dashboard → Endpoint settings.

Without RTK: 47K tokens sent to LLM
With RTK:    28K tokens sent to LLM   (40% saved · same context · same answer)

🎯 Smart 3-Tier Fallback

Create combos with automatic fallback:

Combo: "my-coding-stack"
  1. cc/claude-opus-4-6        (your subscription)
  2. glm/glm-4.7               (cheap backup, $0.6/1M)
  3. if/kimi-k2-thinking       (free fallback)

→ Auto switches when quota runs out or errors occur

📊 Real-Time Quota Tracking

Token consumption per provider
Reset countdown (5-hour, daily, weekly)
Cost estimation for paid tiers
Monthly spending reports

🔄 Format Translation

Seamless translation between formats:

OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro ↔ Vertex ↔ Antigravity ↔ Ollama ↔ OpenAI Responses
Your CLI tool sends OpenAI format → 9Router translates → Provider receives native format
Works with any tool that supports custom OpenAI endpoints

👥 Multi-Account Support

Add multiple accounts per provider
Auto round-robin or priority-based routing
Fallback to next account when one hits quota

🔄 Auto Token Refresh

OAuth tokens automatically refresh before expiration
No manual re-authentication needed
Seamless experience across all providers

🎨 Custom Combos

Create unlimited model combinations
Mix subscription, cheap, and free tiers
Name your combos for easy access
Share combos across devices with Cloud Sync

📝 Request Logging

Enable debug mode for full request/response logs
Track API calls, headers, and payloads
Troubleshoot integration issues
Export logs for analysis

💾 Cloud Sync

Sync providers, combos, and settings across devices
Automatic background sync
Secure encrypted storage
Access your setup from anywhere

Cloud Runtime Notes

Prefer server-side cloud variables in production:
- BASE_URL (internal callback URL used by sync scheduler)
- CLOUD_URL (cloud sync endpoint base)
NEXT_PUBLIC_BASE_URL and NEXT_PUBLIC_CLOUD_URL are still supported for compatibility/UI, but server runtime now prioritizes BASE_URL/CLOUD_URL.
Cloud sync requests now use timeout + fail-fast behavior to avoid UI hanging when cloud DNS/network is unavailable.

📊 Usage Analytics

Track token usage per provider and model
Cost estimation and spending trends
Monthly reports and insights
Optimize your AI spending

💡 IMPORTANT - Understanding Dashboard Costs:

The "cost" displayed in Usage Analytics is for tracking and comparison purposes only. 9Router itself never charges you anything. You only pay providers directly (if using paid services).

Example: If your dashboard shows "$290 total cost" while using iFlow models, this represents what you would have paid using paid APIs directly. Your actual cost = $0 (iFlow is free unlimited).

Think of it as a "savings tracker" showing how much you're saving by using free models or routing through 9Router!

🌐 Deploy Anywhere

💻 Localhost - Default, works offline
☁️ VPS/Cloud - Share across devices
🐳 Docker - One-command deployment
🚀 Cloudflare Workers - Global edge network

💰 Pricing at a Glance

Tier	Provider	Cost	Quota Reset	Best For
🚀 TOKEN SAVER	RTK (built-in)	FREE	Always on	Save 20-40% tokens on EVERY request
💳 SUBSCRIPTION	Claude Code (Pro/Max)	$20-200/mo	5h + weekly	Already subscribed
	Codex (Plus/Pro)	$20-200/mo	5h + weekly	OpenAI users
	GitHub Copilot	$10-19/mo	Monthly	GitHub users
	Cursor IDE	$20/mo	Monthly	Cursor users
💰 CHEAP	GLM-5.1 / GLM-4.7	$0.6/1M	Daily 10AM	Budget backup
	MiniMax M2.7	$0.2/1M	5-hour rolling	Cheapest option
	Kimi K2.5	$9/mo flat	10M tokens/mo	Predictable cost
🆓 FREE	Kiro AI	$0	Unlimited	Claude 4.5 + GLM-5 + MiniMax free
	OpenCode Free	$0	Unlimited	No auth, auto-fetch models
	Vertex AI	$300 credits	New GCP accounts	Gemini 3 Pro + DeepSeek + GLM-5

💡 Pro Tip: RTK + Kiro AI + OpenCode Free combo = $0 cost + 20-40% token savings!

📊 Understanding 9Router Costs & Billing

9Router Billing Reality:

✅ 9Router software = FREE forever (open source, never charges)
✅ Dashboard "costs" = Display/tracking only (not actual bills)
✅ You pay providers directly (subscriptions or API fees)
✅ FREE providers stay FREE (iFlow, Kiro, Qwen = $0 unlimited)
❌ 9Router never sends invoices or charges your card

How Cost Display Works:

The dashboard shows estimated costs as if you were using paid APIs directly. This is not billing - it's a comparison tool to show your savings.

Example Scenario:

Dashboard Display:
• Total Requests: 1,662
• Total Tokens: 47M
• Display Cost: $290

Reality Check:
• Provider: iFlow (FREE unlimited)
• Actual Payment: $0.00
• What $290 Means: Amount you SAVED by using free models!

Payment Rules:

Subscription providers (Claude Code, Codex): Pay them directly via their websites
Cheap providers (GLM, MiniMax): Pay them directly, 9Router just routes
FREE providers (iFlow, Kiro, Qwen): Genuinely free forever, no hidden charges
9Router: Never charges anything, ever

🎯 Use Cases

Case 1: "I have Claude Pro subscription"

Problem: Quota expires unused, rate limits during heavy coding

Solution:

Combo: "maximize-claude"
  1. cc/claude-opus-4-7        (use subscription fully)
  2. glm/glm-5.1               (cheap backup when quota out)
  3. kr/claude-sonnet-4.5      (free emergency fallback)

Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration

Case 2: "I want zero cost"

Problem: Can't afford subscriptions, need reliable AI coding

Solution:

Combo: "free-forever"
  1. kr/claude-sonnet-4.5      (Claude 4.5 free unlimited)
  2. kr/glm-5                  (GLM-5 free via Kiro)
  3. oc/<auto>                 (OpenCode Free, no auth)

Monthly cost: $0
Quality: Production-ready models + RTK saves 20-40% tokens

Case 3: "I need 24/7 coding, no interruptions"

Problem: Deadlines, can't afford downtime

Solution:

Combo: "always-on"
  1. cc/claude-opus-4-7        (best quality)
  2. cx/gpt-5.5                (second subscription)
  3. glm/glm-5.1               (cheap, resets daily)
  4. minimax/MiniMax-M2.7      (cheapest, 5h reset)
  5. kr/claude-sonnet-4.5      (free unlimited)

Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)

Case 4: "I want FREE AI in OpenClaw"

Problem: Need AI assistant in messaging apps (WhatsApp, Telegram, Slack...), completely free

Solution:

Combo: "openclaw-free"
  1. kr/claude-sonnet-4.5      (Claude 4.5 free)
  2. kr/glm-5                  (GLM-5 free)
  3. kr/MiniMax-M2.5           (MiniMax free)

Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...

❓ Frequently Asked Questions

📊 Why does my dashboard show high costs?

The dashboard tracks your token usage and displays estimated costs as if you were using paid APIs directly. This is not actual billing - it's a reference to show how much you're saving by using free models or existing subscriptions through 9Router.

Example:

Dashboard shows: "$290 total cost"
Reality: You're using iFlow (FREE unlimited)
Your actual cost: $0.00
What $290 means: Amount you saved by using free models instead of paid APIs!

The cost display is a "savings tracker" to help you understand your usage patterns and optimization opportunities.

💳 Will I be charged by 9Router?

No. 9Router is free, open-source software that runs on your own computer. It never charges you anything.

You only pay:

✅ Subscription providers (Claude Code $20/mo, Codex $20-200/mo) → Pay them directly on their websites
✅ Cheap providers (GLM, MiniMax) → Pay them directly, 9Router just routes your requests
❌ 9Router itself → Never charges anything, ever

9Router is a local proxy/router. It doesn't have your credit card, can't send invoices, and has no billing system. It's completely free software.

🆓 Are FREE providers really unlimited?

Yes! The current FREE providers (Kiro, OpenCode Free, Vertex) are genuinely free with no hidden charges.

These are free services offered by those respective companies:

Kiro AI: Free unlimited Claude 4.5 + GLM-5 + MiniMax via AWS Builder ID / Google / GitHub OAuth
OpenCode Free: No-auth passthrough proxy, models auto-fetched from opencode.ai/zen/v1/models
Vertex AI: $300 free credits for new Google Cloud accounts (90 days)

9Router just routes your requests to them - there's no "catch" or future billing. They're truly free services, and 9Router makes them easy to use with fallback support.

Discontinued free tiers (no longer recommended):

❌ iFlow: Was free unlimited, now changed to paid (2026)
❌ Qwen Code: Free OAuth tier discontinued by Alibaba on 2026-04-15
❌ Gemini CLI: Still works, but using it with non-CLI tools (Claude, Codex, Cursor...) may result in account bans — only use if you stick to Gemini CLI itself

💰 How do I minimize my actual AI costs?

Free-First Strategy:

Start with 100% free combo:

1. gc/gemini-3-flash (180K/month free from Google)
2. if/kimi-k2-thinking (unlimited free from iFlow)
3. qw/qwen3-coder-plus (unlimited free from Qwen)

Cost: $0/month

Add cheap backup only if you need it:
```
4. glm/glm-4.7 ($0.6/1M tokens)
```
Additional cost: Only pay for what you actually use
Use subscription providers last:
- Only if you already have them
- 9Router helps maximize their value through quota tracking

Result: Most users can operate at $0/month using only free tiers!

📈 What if my usage suddenly spikes?

9Router's smart fallback prevents surprise charges:

Scenario: You're on a coding sprint and blow through your quotas

Without 9Router:

❌ Hit rate limit → Work stops → Frustration
❌ Or: Accidentally rack up huge API bills

With 9Router:

✅ Subscription hits limit → Auto-fallback to cheap tier
✅ Cheap tier gets expensive → Auto-fallback to free tier
✅ Never stop coding → Predictable costs

You're in control: Set spending limits per provider in dashboard, and 9Router respects them.

📖 Setup Guide

🔐 Subscription Providers (Maximize Value)

Claude Code (Pro/Max)

Dashboard → Providers → Connect Claude Code
→ OAuth login → Auto token refresh
→ 5-hour + weekly quota tracking

Models:
  cc/claude-opus-4-7
  cc/claude-opus-4-6
  cc/claude-sonnet-4-6
  cc/claude-haiku-4-5-20251001

Pro Tip: Use Opus for complex tasks, Sonnet for speed. 9Router tracks quota per model!

OpenAI Codex (Plus/Pro)

Dashboard → Providers → Connect Codex
→ OAuth login (port 1455)
→ 5-hour + weekly reset

Models:
  cx/gpt-5.5
  cx/gpt-5.4
  cx/gpt-5.3-codex
  cx/gpt-5.2-codex

GitHub Copilot

Dashboard → Providers → Connect GitHub
→ OAuth via GitHub
→ Monthly reset (1st of month)

Models:
  gh/gpt-5.4
  gh/claude-opus-4.7
  gh/claude-sonnet-4.6
  gh/gemini-3.1-pro-preview
  gh/grok-code-fast-1

Cursor IDE

Dashboard → Providers → Connect Cursor
→ OAuth login
→ Monthly subscription

Models:
  cu/claude-4.6-opus-max
  cu/claude-4.5-sonnet-thinking
  cu/gpt-5.3-codex

💰 Cheap Providers (Backup)

GLM-5.1 / GLM-4.7 (Daily reset, $0.6/1M)

Sign up: Zhipu AI
Get API key from Coding Plan
Dashboard → Add API Key:
- Provider: glm
- API Key: your-key

Use: glm/glm-5.1, glm/glm-5, glm/glm-4.7

Pro Tip: Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.

MiniMax M2.7 (5h reset, $0.20/1M)

Sign up: MiniMax
Get API key
Dashboard → Add API Key

Use: minimax/MiniMax-M2.7, minimax/MiniMax-M2.5

Pro Tip: Cheapest option for long context (1M tokens)!

Kimi K2.5 ($9/month flat)

Subscribe: Moonshot AI
Get API key
Dashboard → Add API Key

Use: kimi/kimi-k2.5, kimi/kimi-k2.5-thinking

Pro Tip: Fixed $9/month for 10M tokens = $0.90/1M effective cost!

🆓 FREE Providers (Recommended)

Kiro AI (Claude 4.5 + GLM-5 + MiniMax FREE)

Dashboard → Connect Kiro
→ AWS Builder ID, AWS IAM Identity Center, Google, or GitHub
→ Unlimited usage

Models:
  kr/claude-sonnet-4.5
  kr/claude-haiku-4.5
  kr/glm-5
  kr/MiniMax-M2.5
  kr/qwen3-coder-next
  kr/deepseek-3.2

Pro Tip: Best free option for Claude. No API key, no payment, fully unlimited.

OpenCode Free (No auth, auto-fetch models)

Dashboard → Connect OpenCode Free
→ No login required (passthrough proxy)
→ Models auto-fetched from opencode.ai/zen/v1/models

Pro Tip: Fastest setup. Just connect and start coding.

Vertex AI ($300 free credits for new GCP accounts)

Dashboard → Connect Vertex AI
→ Upload Google Cloud Service Account JSON
→ Enable Vertex AI API in your GCP project

Models:
  vertex/gemini-3.1-pro-preview
  vertex/gemini-3-flash-preview
  vertex/gemini-2.5-flash

Vertex Partner (Anthropic / DeepSeek / GLM / Qwen via Vertex):
  vertex-partner/glm-5-maas
  vertex-partner/deepseek-v3.2-maas
  vertex-partner/qwen3-next-80b-a3b-thinking-maas

Pro Tip: New Google Cloud accounts get $300 credits free for 90 days. Plenty for daily coding.

🎨 Create Combos

Example 1: Maximize Subscription → Cheap Backup

Dashboard → Combos → Create New

Name: premium-coding
Models:
  1. cc/claude-opus-4-7 (Subscription primary)
  2. glm/glm-5.1 (Cheap backup, $0.6/1M)
  3. minimax/MiniMax-M2.7 (Cheapest fallback, $0.20/1M)

Use in CLI: premium-coding

Monthly cost example (100M tokens):
  80M via Claude (subscription): $0 extra
  15M via GLM: $9
  5M via MiniMax: $1
  Total: $10 + your subscription

Example 2: Free-Only (Zero Cost)

Name: free-combo
Models:
  1. kr/claude-sonnet-4.5 (Claude 4.5 free unlimited)
  2. kr/glm-5 (GLM-5 free via Kiro)
  3. vertex/gemini-3.1-pro-preview ($300 free credits)

Cost: $0 forever (+ 20-40% token savings via RTK)!

🔧 CLI Integration

Cursor IDE

Settings → Models → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [from 9router dashboard]
  Model: cc/claude-opus-4-7

Or use combo: premium-coding

Claude Code

Edit ~/.claude/config.json:

{
  "anthropic_api_base": "http://localhost:20128/v1",
  "anthropic_api_key": "your-9router-api-key"
}

Codex CLI

export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-9router-api-key"

codex "your prompt"

OpenClaw

Option 1 — Dashboard (recommended):

Dashboard → CLI Tools → OpenClaw → Select Model → Apply

Option 2 — Manual: Edit ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "9router/kr/claude-sonnet-4.5"
      }
    }
  },
  "models": {
    "providers": {
      "9router": {
        "baseUrl": "http://127.0.0.1:20128/v1",
        "apiKey": "sk_9router",
        "api": "openai-completions",
        "models": [
          {
            "id": "kr/claude-sonnet-4.5",
            "name": "Claude Sonnet 4.5 (Kiro Free)"
          }
        ]
      }
    }
  }
}

Note: OpenClaw only works with local 9Router. Use 127.0.0.1 instead of localhost to avoid IPv6 resolution issues.

Cline / Continue / RooCode

Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-7

🚀 Deployment

VPS Deployment

# Clone and install
git clone https://github.com/decolua/9router.git
cd 9router
npm install
npm run build

# Configure
export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/9router"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export NEXT_PUBLIC_CLOUD_URL="https://9router.com"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"
export MACHINE_ID_SALT="endpoint-proxy-salt"

# Start
npm run start

# Or use PM2
npm install -g pm2
pm2 start npm --name 9router -- start
pm2 save
pm2 startup

Docker

Published images (multi-platform linux/amd64 + linux/arm64):

Docker Hub: decolua/9router
GHCR: ghcr.io/decolua/9router

Quick start (use published image):

docker run -d \
  --name 9router \
  -p 20128:20128 \
  -v "$HOME/.9router:/app/data" \
  -e DATA_DIR=/app/data \
  decolua/9router:latest

→ Open http://localhost:20128

Build from source (dev):

git clone https://github.com/decolua/9router.git
cd 9router/app
docker build -t 9router .
docker run -d --name 9router -p 20128:20128 \
  -v "$HOME/.9router:/app/data" -e DATA_DIR=/app/data 9router

Container defaults:

PORT=20128
HOSTNAME=0.0.0.0

Useful commands:

docker logs -f 9router
docker restart 9router
docker stop 9router && docker rm 9router
docker pull decolua/9router:latest   # update to latest

Data persistence: $HOME/.9router/db/data.sqlite on host ↔ /app/data/db/data.sqlite in container.

Environment Variables

Variable	Default	Description
`JWT_SECRET`	Auto-generated (`~/.9router/jwt-secret`)	JWT signing secret for dashboard auth cookie (override to share across instances)
`INITIAL_PASSWORD`	`123456`	First login password when no saved hash exists
`DATA_DIR`	`~/.9router`	Main app data location (SQLite at `$DATA_DIR/db/data.sqlite`)
`PORT`	framework default	Service port (`20128` in examples)
`HOSTNAME`	framework default	Bind host (Docker defaults to `0.0.0.0`)
`NODE_ENV`	runtime default	Set `production` for deploy
`BASE_URL`	`http://localhost:20128`	Server-side internal base URL used by cloud sync jobs
`CLOUD_URL`	`https://9router.com`	Server-side cloud sync endpoint base URL
`NEXT_PUBLIC_BASE_URL`	`http://localhost:3000`	Backward-compatible/public base URL (prefer `BASE_URL` for server runtime)
`NEXT_PUBLIC_CLOUD_URL`	`https://9router.com`	Backward-compatible/public cloud URL (prefer `CLOUD_URL` for server runtime)
`API_KEY_SECRET`	`endpoint-proxy-api-key-secret`	HMAC secret for generated API keys
`MACHINE_ID_SALT`	`endpoint-proxy-salt`	Salt for stable machine ID hashing
`ENABLE_REQUEST_LOGS`	`false`	Enables request/response logs under `logs/`
`AUTH_COOKIE_SECURE`	`false`	Force `Secure` auth cookie (set `true` behind HTTPS reverse proxy)
`REQUIRE_API_KEY`	`false`	Enforce Bearer API key on `/v1/*` routes (recommended for internet-exposed deploys)
`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`	empty	Optional outbound proxy for upstream provider calls

Notes:

Lowercase proxy variables are also supported: http_proxy, https_proxy, all_proxy, no_proxy.
.env is not baked into Docker image (.dockerignore); inject runtime config with --env-file or -e.
On Windows, APPDATA can be used for local storage path resolution.
INSTANCE_NAME appears in older docs/env templates, but is currently not used at runtime.

Runtime Files and Storage

Main app state: ${DATA_DIR}/db/data.sqlite (SQLite — providers, combos, aliases, keys, settings, usage history)
Auto backups: ${DATA_DIR}/db/backups/
Optional request/translator logs: <repo>/logs/... when ENABLE_REQUEST_LOGS=true
Both ${DATA_DIR} and ~/.9router resolve to the same location in a Docker container — the symlink /root/.9router -> /app/data is created at build time.

📊 Available Models

View all available models

Claude Code (cc/) - Pro/Max:

cc/claude-opus-4-7
cc/claude-opus-4-6
cc/claude-sonnet-4-6
cc/claude-sonnet-4-5-20250929
cc/claude-haiku-4-5-20251001

Codex (cx/) - Plus/Pro:

cx/gpt-5.5
cx/gpt-5.4
cx/gpt-5.3-codex
cx/gpt-5.2-codex
cx/gpt-5.1-codex-max

GitHub Copilot (gh/):

gh/gpt-5.4
gh/claude-opus-4.7
gh/claude-sonnet-4.6
gh/gemini-3.1-pro-preview
gh/grok-code-fast-1

Cursor (cu/) - Subscription:

cu/claude-4.6-opus-max
cu/claude-4.5-sonnet-thinking
cu/gpt-5.3-codex
cu/kimi-k2.5

GLM (glm/) - $0.6/1M:

glm/glm-5.1
glm/glm-5
glm/glm-4.7

MiniMax (minimax/) - $0.2/1M:

minimax/MiniMax-M2.7
minimax/MiniMax-M2.5

Kimi (kimi/) - $9/mo flat:

kimi/kimi-k2.5
kimi/kimi-k2.5-thinking

Kiro (kr/) - FREE unlimited:

kr/claude-sonnet-4.5
kr/claude-haiku-4.5
kr/glm-5
kr/MiniMax-M2.5
kr/qwen3-coder-next
kr/deepseek-3.2

OpenCode Free (oc/) - FREE no-auth:

Auto-fetched from opencode.ai/zen/v1/models

Vertex AI (vertex/) - $300 free credits:

vertex/gemini-3.1-pro-preview
vertex/gemini-3-flash-preview
vertex/gemini-2.5-flash
vertex-partner/glm-5-maas
vertex-partner/deepseek-v3.2-maas

🐛 Troubleshooting

"Language model did not provide messages"

Provider quota exhausted → Check dashboard quota tracker
Solution: Use combo fallback or switch to cheaper tier

Rate limiting

Subscription quota out → Fallback to GLM/MiniMax
Add combo: cc/claude-opus-4-7 → glm/glm-5.1 → kr/claude-sonnet-4.5

OAuth token expired

Auto-refreshed by 9Router
If issues persist: Dashboard → Provider → Reconnect

High costs

Enable RTK in Dashboard → Endpoint settings (default ON, saves 20-40% tokens)
Check usage stats in Dashboard
Switch primary model to GLM/MiniMax
Use free tier (Kiro, OpenCode Free, Vertex) for non-critical tasks

Dashboard opens on wrong port

Set PORT=20128 and NEXT_PUBLIC_BASE_URL=http://localhost:20128

First login not working

Check INITIAL_PASSWORD in .env
If unset, fallback password is 123456

No request logs under logs/

Set ENABLE_REQUEST_LOGS=true

🛠️ Tech Stack

Runtime: Node.js 20+
Framework: Next.js 16
UI: React 19 + Tailwind CSS 4
Database: SQLite (better-sqlite3 / node:sqlite / sql.js fallback)
Streaming: Server-Sent Events (SSE)
Auth: OAuth 2.0 (PKCE) + JWT + API Keys

📝 API Reference

Chat Completions

POST http://localhost:20128/v1/chat/completions
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Write a function to..."}
  ],
  "stream": true
}

List Models

GET http://localhost:20128/v1/models
Authorization: Bearer your-api-key

→ Returns all models + combos in OpenAI format

📧 Support

Website: 9router.com
GitHub: github.com/decolua/9router
Issues: github.com/decolua/9router/issues

👥 Contributors

Thanks to all contributors who helped make 9Router better!

📊 Star Chart

🔀 Forks

OmniRoute — A full-featured TypeScript fork of 9Router. Adds 36+ providers, 4-tier auto-fallback, multi-modal APIs (images, embeddings, audio, TTS), circuit breaker, semantic cache, LLM evaluations, and a polished dashboard. 368+ unit tests. Available via npm and Docker.

🙏 Acknowledgments

Built on the shoulders of giants:

CLIProxyAPI(https://github.com/router-for-me/CLIProxyAPI) — original Go implementation that inspired this JavaScript port.
RTK — Rust token-saver. 9Router ports its compression pipeline to JS → −20-40% input tokens on every request.
Caveman by @JuliusBrussee — viral "why use many token when few token do trick". 9Router adapts its prompt → −65% output tokens.

Huge thanks to these authors — without their work, 9Router's token-saving features wouldn't exist. ⭐ them on GitHub!

📄 License

MIT License - see LICENSE for details.

_{Built with ❤️ for developers who code 24/7}

Imbad0202/academic-research-skills

Academic Research Skills for Claude Code: research → write → review → revise → finalize

Academic Research Skills for Claude Code

繁體中文版

A comprehensive suite of Claude Code skills for academic research, covering the full pipeline from research to publication.

Install in 30 seconds (Claude Code CLI / VS Code / JetBrains, v3.7.0+):

/plugin marketplace add Imbad0202/academic-research-skills
/plugin install academic-research-skills

Then try /ars-plan to walk through your paper structure via Socratic dialogue, or jump to Quick install for prerequisites and the traditional symlink flow.

AI is your copilot, not the pilot. This tool won't write your paper for you. It handles the grunt work — hunting down references, formatting citations, verifying data, checking logical consistency — so you can focus on the parts that actually require your brain: defining the question, choosing the method, interpreting what the data means, and writing the sentence after "I argue that."

Unlike a humanizer, this tool doesn't help you hide the fact that you used AI. It helps you write better. Style Calibration learns your voice from past work. Writing Quality Check catches the patterns that make prose feel machine-generated. The goal is quality, not cheating.

Why human-in-the-loop, not full automation?

Lu et al. (2026, Nature 651:914-919) built The AI Scientist — the first fully autonomous AI research system to publish a paper through blind peer review at a top-tier ML venue (ICLR 2025 workshop, score 6.33/10 vs workshop average 4.87). Their Limitations section enumerates the failure modes that any fully-autonomous AI research pipeline inherits: implementation bugs, hallucinated results, shortcut reliance, bug-as-insight reframing, methodology fabrication, frame-lock, citation hallucinations.

ARS is built on the premise that a human researcher augmented by AI avoids these failure modes better than either alone. Stage 2.5 and Stage 4.5 integrity gates run a 7-mode blocking checklist (see academic-pipeline/references/ai_research_failure_modes.md); the reviewer offers an opt-in calibration mode that measures its own FNR/FPR against a user-supplied gold set.

Zhao et al. (2026-05) audited 111M references across 2.5M papers on arXiv, bioRxiv, SSRN, and PMC. Their conservative estimate is 146,932 hallucinated citations for 2025 alone, with an observed mid-2024 inflection; for the bioRxiv-to-PMC pairing they report 85.3% preprint-to-published persistence. The paper describes "real citations deployed to support claims the cited references do not actually make" as an open challenge. ARS v3.7.1 added trust-chain frontmatter for source provenance; v3.7.3 added locator infrastructure (three-layer citation anchors) for future claim-level audits and surfaces advisory risk signals at cite time (ARS labels the claim-faithfulness gap internally as "L3"; this is ARS terminology, not the paper's). v3.7.x is motivated by Zhao et al.'s corpus-scale findings; corpus-scale evaluation of ARS itself remains future work.

v3.8 closes the second half of the L3 gap. v3.7.3 made every citation carry a locator anchor; v3.8 adds an opt-in audit pass (ARS_CLAIM_AUDIT=1) that fetches the cited source against each anchor and judges whether the claim is actually supported. Five new HIGH-WARN classes (claim-not-supported, negative-constraint-violation, fabricated-reference, anchorless, constraint-violation-uncited) gate-refuse output through the formatter terminal hard gate. Calibration is shipped as a 20-tuple gold set with FNR<0.15 + FPR<0.10 acceptance thresholds; ramp-on plan is deferred to post-calibration evidence per v3.8 spec §5.

v3.3 was inspired by PaperOrchestra (Song, Song, Pfister & Yoon, 2026, Google): Semantic Scholar API verification, anti-leakage protocol, VLM figure verification, and score trajectory tracking.

Architecture & pipeline

👉 docs/ARCHITECTURE.md — the full pipeline view: flow diagram, stage-by-stage matrix, data-access flow, skill dependency graph, quality gates, and mode list.

The architecture doc supersedes the sprawling pipeline description that used to live here. Everything about what runs in which stage now lives in one place.

Quick install

Prerequisites

Claude Code (latest; plugin packaging requires recent versions)
ANTHROPIC_API_KEY exported, or set on first claude run
Optional: Pandoc for DOCX, tectonic + Source Han Serif TC for APA 7.0 PDF (Markdown output works without either)

Plugin install (v3.7.0+, recommended):

/plugin marketplace add Imbad0202/academic-research-skills
/plugin install academic-research-skills

Verify it works: run /ars-plan and describe a paper you're working on — ARS will start a Socratic dialogue to map out chapter structure. For a single-shot test instead, try /ars-lit-review "your topic".

👉 docs/SETUP.md — full guide: install Claude Code, set up API keys, optional Pandoc/tectonic for DOCX/PDF, cross-model verification (ARS_CROSS_MODEL), and five installation methods (Plugin, project skills, global skills, claude.ai Project, repo-cloned).

Using Codex CLI? Install the sibling distribution instead: Imbad0202/academic-research-skills-codex — same workflow content, Codex-native packaging as a single $academic-research-suite skill with ars-* aliases.

Performance & cost

👉 docs/PERFORMANCE.md — per-mode token budgets, full-pipeline estimate (~$4–6 for a 15k-word paper), and recommended Claude Code settings (Skip Permissions; Agent Team optional).

Guides & articles

Academic Writing Shouldn't Be a Solo Act — full pipeline walkthrough (English)
學術寫作不該是一個人的事：一套開源 AI 協作工具如何改變研究者的工作流 — 完整使用指南（繁體中文）

Features at a glance

Deep Research — 13-agent research team with Socratic guided mode, PRISMA systematic review, intent detection, dialogue health monitoring, optional cross-model DA, Semantic Scholar API verification.
Academic Paper — 12-agent paper writing with Style Calibration, Writing Quality Check, LaTeX hardening, visualization, revision coaching, citation conversion, anti-leakage protocol, and VLM figure verification.
Academic Paper Reviewer — 7-agent multi-perspective peer review with 0–100 quality rubrics (EIC + 3 dynamic reviewers + Devil's Advocate), concession threshold protocol, attack intensity preservation, optional cross-model DA critique / calibration, R&R traceability matrix, read-only constraint.
Academic Pipeline — 10-stage pipeline orchestrator with adaptive checkpoints, claim verification, Material Passport, optional repro_lock, optional cross-model integrity verification, mid-conversation reinforcement, and score trajectory tracking.
Data Access Level Metadata (v3.3.2+) — every skill declares data_access_level (raw / redacted / verified_only); enforced by scripts/check_data_access_level.py. Pattern adapted from Anthropic's automated-w2s-researcher (2026). See shared/ground_truth_isolation_pattern.md.
Task Type Annotation (v3.3.2+) — every skill declares task_type (open-ended or outcome-gradable). All current ARS skills are open-ended.
Benchmark Report Schema (v3.3.5+) — JSON Schema + lint for honest benchmark comparisons. See shared/benchmark_report_pattern.md.
Artifact Reproducibility Lockfile (v3.3.5+) — optional repro_lock sub-block on Material Passport. Configuration documentation, not replay guarantee — LLM outputs are not byte-reproducible. See shared/artifact_reproducibility_pattern.md.

Showcase: real pipeline output

See the complete artifacts from a real 10-stage pipeline run — peer review reports, integrity verification reports, and the final paper:

Browse all pipeline artifacts →

Artifact	Description
Final Paper (EN)	APA 7.0 formatted, LaTeX-compiled
Final Paper (ZH)	Chinese version, APA 7.0
Integrity Report — Pre-Review	Stage 2.5: caught 15 fabricated refs + 3 statistical errors
Integrity Report — Final	Stage 4.5: zero regressions confirmed
Peer Review Round 1	EIC + 3 Reviewers + Devil's Advocate
Re-Review	Verification after revisions
Peer Review Round 2	Follow-up review
Response to Reviewers	Point-by-point author response
Post-Publication Audit Report	Independent full-reference audit: found 21/68 issues missed by 3 rounds of integrity checks

Companion: Experiment Agent

If your research involves running experiments (code or human studies) before writing, the Experiment Agent skill fills the gap between ARS Stage 1 (RESEARCH) and Stage 2 (WRITE).

ARS Stage 1 RESEARCH  →  RQ Brief + Methodology Blueprint
        ↓
  experiment-agent     →  run/manage experiments → validate results
        ↓
ARS Stage 2 WRITE     →  write paper with verified experiment results

What it does: executes code experiments (Python, R, etc.) with real-time monitoring, manages human study protocols with IRB ethics checklist, interprets statistics with 11-type fallacy detection, and verifies reproducibility.

How to use together: pause the ARS pipeline after Stage 1, run experiments in a separate experiment-agent session, then bring the results (with Material Passport) back to ARS Stage 2. ARS requires zero modification. See the experiment-agent README for setup instructions.

Usage

Quick Start

# Start a full research pipeline
You: "I want to write a research paper on AI's impact on higher education QA"

# Start with Socratic guidance
You: "Guide my research on AI in educational evaluation"

# Write a paper with guided planning
You: "Guide me through writing a paper on demographic decline"

# Review an existing paper
You: "Review this paper" (then provide the paper)

# Check pipeline status
You: "status"

Individual Skills

Deep Research (7 modes)

"Research the impact of AI on higher education"       → full mode
"Give me a quick brief on X"                          → quick mode
"Do a systematic review on X with PRISMA"             → systematic-review mode
"Guide my research on X"                              → socratic mode (guided)
"Fact-check these claims"                             → fact-check mode
"Do a literature review on X"                         → lit-review mode
"Review this paper's research quality"                → review mode

Academic Paper (10 modes)

"Write a paper on X"                                  → full mode
"Guide me through writing a paper"                    → plan mode (guided)
"Build a paper outline"                               → outline-only mode
"I have a draft, here are reviewer comments"          → revision mode
"Parse these reviewer comments into a roadmap"        → revision-coach mode
"Write an abstract for this paper"                    → abstract-only mode
"Turn this into a literature review paper"            → lit-review mode
"Convert to LaTeX" / "Convert citations to IEEE"      → format-convert mode
"Check citations"                                     → citation-check mode
"Generate an AI disclosure statement for NeurIPS"     → disclosure mode

Academic Paper Reviewer (6 modes)

"Review this paper"                                   → full mode (EIC + R1/R2/R3 + Devil's Advocate)
"Quick assessment of this paper"                      → quick mode
"Guide me to improve this paper"                      → guided mode
"Check the methodology"                               → methodology-focus mode
"Verify the revisions"                                → re-review mode
"Calibrate this reviewer against my gold set"         → calibration mode

Academic Pipeline (Orchestrator)

"I want to write a complete research paper"           → full pipeline from Stage 1
"I already have a paper, review it"                   → mid-entry at Stage 2.5 (integrity first)
"I received reviewer comments"                        → mid-entry at Stage 4

Pipeline ends with Stage 6: Process Summary — auto-generates a paper creation process record with 6-dimension Collaboration Quality Evaluation (1–100 scoring).

Supported Languages

Traditional Chinese (繁體中文) — default when user writes in Chinese
English — default when user writes in English
Bilingual abstracts (Chinese + English) for academic papers

Using a different language? Socratic mode (deep-research) and Plan mode (academic-paper) use intent-based activation — they detect the meaning of your request, not specific keywords. This means they work in any language without modification.

However, the general Trigger Keywords section (which determines whether the skill is activated at all) still lists English and Traditional Chinese keywords. If you find the skill isn't activating reliably in your language, you can add your language's keywords to the ### Trigger Keywords section in each SKILL.md file to improve matching confidence.

Supported Citation Formats

APA 7.0 (default, including Chinese citation rules)
Chicago (Notes & Author-Date)
MLA
IEEE
Vancouver

Supported Paper Structures

IMRaD (empirical research)
Thematic Literature Review
Theoretical Analysis
Case Study
Policy Brief
Conference Paper

Skill Details

Per-agent responsibilities and per-stage artifacts now live in docs/ARCHITECTURE.md. Version numbers are anchored here so release metadata stays in one place.

Deep Research (v2.8)

13-agent research team. Modes: full, quick, review, lit-review, fact-check, socratic, systematic-review. Full agent roster and artifacts: see ARCHITECTURE.md §3.

Academic Paper (v3.0)

12-agent paper writing pipeline. Modes: full, plan, outline-only, revision, revision-coach, abstract-only, lit-review, format-convert, citation-check, disclosure. Output: MD + DOCX (via Pandoc when available) + LaTeX (APA 7.0 apa7 class / IEEE / Chicago) → PDF via tectonic. Full agent roster and per-phase responsibilities: see ARCHITECTURE.md §3.

Academic Paper Reviewer (v1.8)

7-agent multi-perspective review with 0-100 quality rubrics. Modes: full, re-review, quick, methodology-focus, guided, calibration. Decision mapping: ≥80 Accept, 65-79 Minor Revision, 50-64 Major Revision, <50 Reject. First-round review team vs. narrow re-review team boundary: see ARCHITECTURE.md §3 Stage 3 / Stage 3'.

Academic Pipeline (v3.7)

10-stage orchestrator with integrity verification, two-stage review, Socratic coaching, and collaboration evaluation. Pipeline guarantees: every stage requires user confirmation checkpoint; integrity verification (Stage 2.5 + 4.5) cannot be skipped; R&R Traceability Matrix (Schema 11) independently verifies author revision claims. v3.4 added the Compliance Agent (PRISMA-trAIce + RAISE) at Stage 2.5 / 4.5. v3.5 adds the Collaboration Depth Observer (collaboration_depth_agent, advisory only — never blocks) at every FULL/SLIM checkpoint and at pipeline completion. MANDATORY integrity gates (2.5 / 4.5) explicitly skip the observer so compliance checks are not diluted. Based on Wang & Zhang (2026), IJETHE 23:11. Stage-by-stage matrix with agents, artifacts, and gates: see ARCHITECTURE.md §3.

v3.0 Optimizations: What We Discovered About AI's Structural Limits

What happened

While using ARS to write a reflection article about AI in higher education, I ran into three structural problems that no amount of prompt engineering could fix:

Frame-lock: I asked the AI to run a devil's advocate debate against its own thesis. It did — four rounds, each more refined than the last. But every round stayed inside the frame I'd set. The DA attacked arguments, never premises. It never asked "are we even discussing the right question?" This is the same pattern that caused the 31% citation error rate in v2.7's stress test: the verifying AI and the generating AI share the same cognitive frame.
Sycophancy under pushback: Every time I challenged the DA's attacks, it conceded too quickly. It retracted findings faster than it launched them. The model's training rewards conversational harmony — so "the user pushed back" was treated as evidence that the attack was wrong, when often it just meant the user was persistent.
Intent misdetection: The Socratic Mentor kept trying to converge and produce deliverables ("Want me to write this up?") when I was still exploring. It couldn't distinguish "the user wants a deep philosophical discussion" from "the user wants an RQ brief." Both look like engagement, but they need opposite AI behaviors.

What we changed (v3.0)

Devil's Advocate — Concession Threshold Protocol (deep-research + academic-paper-reviewer)

DA must now score every rebuttal on a 1-5 scale before responding
Concession only allowed at score ≥4 (rebuttal directly addresses core attack with evidence)
Score ≤3: hold position and restate the original attack
Anti-sycophancy rules: no consecutive concessions, concession rate tracking, frame-lock detection after each checkpoint

Socratic Mentor — Intent Detection Layer (deep-research)

Classifies user intent as exploratory vs. goal-oriented at dialogue start and every 3 turns
Exploratory mode: disables auto-convergence, raises max rounds to 60, prohibits "want me to summarize?" prompts
Goal-oriented mode: standard convergence behavior
Anti-premature-closure rules: in exploratory mode, the user decides when to stop

Socratic Mentor — Dialogue Health Indicator (deep-research)

Silent self-assessment every 5 turns on three dimensions: persistent agreement, conflict avoidance, premature convergence
Auto-injects challenging questions when agreement pattern detected
Invisible to user (to prevent gaming), but log available for post-session review

Why this matters

These optimizations don't solve AI's structural limits — they make the limits visible and manageable. The DA will still eventually concede if pushed hard enough. The Socratic Mentor will still have some convergence bias. But now there are explicit checkpoints that slow down the sycophancy, force the DA to justify concessions, and prevent the Mentor from wrapping up before the user is ready.

The deeper lesson: AI literacy isn't about learning to use AI as a tool, following ethics rules, or fearing AI risks. It's about engaging AI deeply enough to discover its structural limits yourself — and your own thinking limits in the process.

License

This work is licensed under CC-BY-NC 4.0.

You are free to:

Share — copy and redistribute the material
Adapt — remix, transform, and build upon the material

Under the following terms:

Attribution — You must give appropriate credit
NonCommercial — You may not use the material for commercial purposes

Attribution format:

Based on Academic Research Skills by Cheng-I Wu
https://github.com/Imbad0202/academic-research-skills

Contributors

Cheng-I Wu (吳政宜) — Author and maintainer

aspi6246 — Contributor. The v3.1 optimization was inspired by patterns from Claude-Code-Skills-for-Academics: read-only constraint pattern, anti-pattern codification as first-class design, cognitive framework approach (teaching "how to think" not just procedures), and lean skill size philosophy.

mchesbro1 — Contributor. Originally proposed and drafted the IS Basket of 8 journals for academic-paper-reviewer/references/top_journals_by_field.md (Issue #5).

cloudenochcsis — Contributor. Extended the IS section from the Basket of 8 to the full Senior Scholars' Basket of 11 — adding Decision Support Systems, Information & Management, and Information and Organization (Issue #7, PR #8). Sourced from the AIS Senior Scholars' List of Premier Journals.

Changelog

v3.8.0 (2026-05-16) — L3 Claim-Faithfulness Locator + Audit (paired milestone)

v3.7.3 + v3.8 close the L3 (claim-faithfulness) gap end-to-end. v3.7.3 ships the locator infrastructure — every citation carries a three-layer anchor so future audits can fetch the cited passage. v3.8 ships the audit pass that consumes those anchors, judges whether the cited source supports the claim, and gate-refuses HIGH-WARN violations at the formatter terminal hard gate. The release also bundles 5 audit-trail-shipped feature PRs accumulated since v3.7.0 (#104 / #105 / #108 / #111 / #115).

#103 — claim_ref_alignment_audit_agent (v3.8 PR #121). Opt-in (ARS_CLAIM_AUDIT=1, default OFF) Stage 4→5 audit agent. Judges every sampled citation against retrieved excerpt; emits claim_audit_results[] + claim_intent_manifests[] + claim_drifts[] + uncited_assertions[] + constraint_violations[] aggregates. 8-row finalizer matrix routes HIGH-WARN classes (CLAIM-NOT-SUPPORTED / NEGATIVE-CONSTRAINT-VIOLATION / FABRICATED-REFERENCE / ANCHORLESS / CONSTRAINT-VIOLATION-UNCITED) through the formatter REFUSE rules 6-10. Calibration runner ships with 20-tuple gold set (T-C1 FNR<0.15 + FPR<0.10, T-C2 per-class, T-C3 shape integrity). 8 rounds of dual-track review (R1 codex + Gemini-3.1-pro-preview, R2-R8 codex-only after Gemini quota exhausted); trajectory R1 4P1+2P2 → R8 0P1+4P2 ship gate.
v3.7.3 — Three-Layer Citation Emission + contamination signals (PR #98). synthesis_agent / draft_writer_agent / report_compiler_agent gain ## Three-Layer Citation Emission (v3.7.3) H2. Every  carries  with <kind> ∈ {quote, page, section, paragraph, none} (quote anchors capped at 25 words, URL-encoded). pipeline_orchestrator_agent finalizer becomes 5-cell with precedence-zero NO-LOCATOR check. formatter_agent adds explicit hard-gate refusal for [UNVERIFIED CITATION — NO QUOTE OR PAGE LOCATOR]. literature_corpus_entry.schema.json adds optional contamination_signals: { preprint_post_llm_inflection, semantic_scholar_unmatched } object. bibliography_agent computes both signals at ingest. 11-round review trajectory (Codex×10 + Gemini cross-model×1) closed 22 findings. Spec: docs/design/2026-05-12-ars-v3.7.3-claim-faithfulness-and-contaminated-source-spec.md. External motivation: Zhao et al. arXiv:2605.07723 (2026-05).
#108 — AI disclosure policy-anchor renderer (audit-trail-shipped 2026-05-14). Adds PRISMA-trAIce / ICMJE / Nature / IEEE policy-anchor disclosure paths alongside the existing venue-track renderer.
#111 — slr_lineage emission on systematic-review → academic-paper handoff (2026-05-15). Schema 9 optional boolean slr_lineage field; producer pipeline_orchestrator_agent writes at every handoff transition; consumer disclosure mode dispatches --policy-anchor=prisma-trAIce per the §4.3 G2 invariant track gate.
#104 — README motivation: Zhao et al. corpus-scale evidence anchor (2026-05-15). README + README.zh-TW.md motivation section frames the v3.7.x line against Zhao et al.'s 146,932 hallucinated-citation finding.
#105 — v3.7.3 contamination_signals backfill migration tool (2026-05-15). scripts/migrate_literature_corpus_to_v3_7_3.py retro-computes both contamination signals across pre-v3.7.3 passports.
#115 — Semantic Scholar client maturity (2026-05-15). scripts/semantic_scholar_client.py adds 1-req/s throttle (drops to 0.1s when S2_API_KEY detected), outage latch on URLError, and reset_outage_latch() for long-running cross-passport batches.

v3.7.0 (2026-05-05) — Claude Code Plugin Packaging

Plugin packaging upgrade: ARS now installs in one line on Claude Code CLI / VS Code / JetBrains via /plugin marketplace add Imbad0202/academic-research-skills + /plugin install academic-research-skills. The traditional git clone + symlink to ~/.claude/skills/ flow continues to work — both tracks are first-class.

Plugin manifest + marketplace metadata (Phase 1, PR #68). .claude-plugin/plugin.json declares the suite (4 skills auto-discovered from skills/ directory via relative symlinks). .claude-plugin/marketplace.json registers the plugin so a single GitHub-hosted endpoint serves both the marketplace listing and the plugin source. README + README.zh-TW.md + docs/SETUP.md carry dual-track install instructions.
10 slash commands at commands/ars-*.md (Phase 2.1, PR #69) mapping MODE_REGISTRY.md entries to /ars-<mode> triggers. Model routing is pinned in each command's frontmatter — opus for full and revision-coach (architectural / review-interpretation depth), sonnet for the other 8. No Haiku per project policy.
3 plugin-shipped agents at agents/*_agent.md (Phase 2.1, PR #69) as relative symlinks to the v3.6.7-hardened downstream agents in deep-research/agents/: synthesis_agent, research_architect_agent, report_compiler_agent. Underscore filenames preserved to keep scripts/check_v3_6_7_pattern_protection.py hard-pinned paths and INV-3 manifest-confined Clause 1 invariant intact. Symlinks (not copies) preserve a single source of truth and prevent the Pattern C3 attack surface that v3.6.7 §6 inversion sweep + INV-1/2/3 lint closes.
model: inherit added to those three source agent frontmatters. Inherit chosen over pinning sonnet so an opus session running ARS full pipeline keeps opus agents (instead of being capped). The user's ~/.claude/hooks/warn-agent-no-model.sh PreToolUse hook gates Haiku at the dispatching boundary, so inherit resolves through an already-Haiku-free model.
SessionStart announce hook at hooks/hooks.json + scripts/announce-ars-loaded.sh (Phase 2.2, PR #70). When the plugin loads, the hook injects an additionalContext listing the 10 slash commands, the 3 plugin agents, and a token-budget pointer into the LLM's first turn. startup and clear source values get the full announce; resume and compact get a one-line ack to avoid burning context. Bash 3.2 compatible — runs on macOS stock /bin/bash with no brew install bash requirement.
Phase 2.2 scope reduction: a SubagentStop → run_codex_audit.sh codex audit hook was scoped out for v3.7.0 due to a contract gap (the SubagentStop payload carries no stage/deliverable info, so the wrapper would have to half-infer required arguments) and an invoker-class boundary (run_codex_audit.sh lines 4–7 forbid same-session in-LLM invocation; PostToolUse fires inside the producing session). Real audit-hook integration deferred to a future release when ARS gains a stage/deliverable propagation contract. See docs/design/2026-04-30-ars-v3.7.0-plugin-packaging-roadmap.md Update note 2026-05-05 (Phase 2.2 scope reduction).
docs/PERFORMANCE.md + .zh-TW.md gain a "v3.7.0 Plugin agents and model routing" subsection explaining the inherit semantics and current 3-agent scope boundary.
Codex review chain across the three PRs: 8 inline iterative rounds + 3 fresh PR-level rounds, all converging to 0 P0/P1/P2 findings before merge. The Phase 2.2 fresh PR review caught one P2 (unquoted ${CLAUDE_PLUGIN_ROOT} breaking install paths with spaces) that the inline rounds missed — confirms the value of separating implementation review (inline) from contract review (fresh).
What did NOT change: the four skill directories, all 25 modes, agent prompts, schema files, and lint contracts. Plugin packaging only adds new top-level surface (commands/, agents/, hooks/, .claude-plugin/, skills/ symlink dir, three plugin-agent model: inherit frontmatter additions). Existing 4.3k clone-install users see no breaking change.

v3.6.8 (2026-05-03) — Generator-Evaluator Contract Gate (v3.6.6 spec ship)

Naming note: this release ships the v3.6.6 generator-evaluator contract spec and implementation. The v3.6.6 work landed after v3.6.7 due to project sequencing; the design doc retains the v3.6.6 internal naming for the contract gate version, while the suite release is tagged v3.6.8 to keep the CHANGELOG monotonic.

Schema 13.1 (shared/sprint_contract.schema.json) extends Schema 13 with two new mode enum values (writer_full + evaluator_full), two new optional top-level fields (pre_commitment_artifacts writer-only, disagreement_handling evaluator-only), and 12 allOf branches enforcing reviewer- / writer- / evaluator-conditional gates. Existing reviewer contracts validate byte-equivalent under Schema 13.1 (§3.6 zero-touch promise).
Two new shipped contract templates under shared/contracts/writer/full.json (D1–D7, F1/F4/F2/F3/F0) and shared/contracts/evaluator/full.json (D1–D5, F1/F2/F3/F6/F4/F5/F0). Promoted from design-time artefacts on the spec branch to live shipped status atomically with the Schema 13.1 upgrade.
Two-phase orchestration inside academic-paper full: Phase 4 splits into Phase 4a (writer paper-blind pre-commitment) + Phase 4b (writer paper-visible drafting + self-scoring); Phase 6 splits into Phase 6a (evaluator paper-blind pre-commitment) + Phase 6b (evaluator paper-visible scoring + decision). Phase-numbered <phase4a_output> / <phase6a_output> data delimiters mirror the v3.6.2 reviewer pattern. Lint count summary: writer 3+4 / evaluator 5+5 / reviewer 5+6 (reviewer remains zero-touch).
academic-paper SKILL + agent files gain a verbatim ## v3.6.6 Generator-Evaluator Contract Protocol block (101 lines in SKILL.md plus 47 lines in draft_writer_agent.md + 57 lines in peer_reviewer_agent.md). SKILL.md also adds a new ## Known limitations section carrying graceful-degradation + cross-session resume forward notes for v3.6.7+.
Validator extensions: scripts/check_sprint_contract.py SC-* mode-gating audit (SC-5 + SC-11 reviewer-only; SC-9 extended across all three mode families). 17 new tests bring the validator unit-test count from 54 to 71 (positive + 5 schema-branch negative + 2 §3.6 reviewer regression + 6 mode-gating tests).
Manifest CI lint: scripts/check_v3_6_6_ab_manifest.py enforces §6.2 manifest schema + §6.5 git-tracked invariants on tests/fixtures/v3.6.6-ab/manifest.yaml. .github/workflows/spec-consistency.yml extends the sprint contract validation loop to iterate writer + evaluator template directories alongside the existing reviewer loop, plus runs the new manifest CI lint.
A/B evidence fixture stub at tests/fixtures/v3.6.6-ab/ (30 files): manifest + README + 6 paper-A inputs/baseline + 1 paper-C inputs/baseline + Stage 3 reviewer excerpt + 6 codex-judge baseline placeholders. Real fixture data populates in follow-up commits before the implementation work fully completes.

v3.6.7 (2026-04-30) — Downstream-Agent Pattern Protection (Step 1+2)

Three downstream agents hardened against 13 of 18 documented hallucination/drift patterns: synthesis_agent (A1–A5 narrative-side), the survey-designer mode of research_architect_agent (B1–B5 instrument-side), and the abstract-only mode of report_compiler_agent (C1–C3 publication-side). Each agent prompt now carries a PATTERN PROTECTION (v3.6.7) block.
Four reference files in shared/references/: irb_terminology_glossary.md, psychometric_terminology_glossary.md, protected_hedging_phrases.md, word_count_conventions.md. The reference files carry operational contracts that the agent prompts cite by path.
Cross-model audit prompt template at shared/templates/codex_audit_multifile_template.md with seven audit dimensions and a mandatory three-part Section 4(f) check for report_compiler_agent bundles. Failure of any sub-check is a P1 finding.
Static lint + 29-test mutation suite: scripts/check_v3_6_7_pattern_protection.py enforces protection-clause presence and obligation-phrase shape; scripts/test_check_v3_6_7_pattern_protection.py preserves codex review evidence so future checker regressions surface in CI. Both are wired into .github/workflows/spec-consistency.yml.
Codex review history: seven rounds of gpt-5.5 + xhigh cross-model review reached SHIP-OK with zero P1+P2 findings. Step 6 (orchestrator runtime hooks) and Step 8 (synthetic eval case) ship in a follow-up PR.

v3.6.5 (2026-04-27) — Material Passport `literature_corpus[]` Consumer Integration

Two Phase 1 literature consumers wired: deep-research/agents/bibliography_agent.md and academic-paper/agents/literature_strategist_agent.md. Both follow the same five-step corpus-first, search-fills-gap flow when the passport carries a non-empty literature_corpus[] and the same four Iron Rules (Same criteria / No silent skip / No corpus mutation / Graceful fallback on parse failure).
PRE-SCREENED reproducibility block in Search Strategy reports: enumerates included / excluded / skipped corpus entries, with F3 zero-hit note and F4a–F4f provenance reporting that compose around partial declaration of obtained_via / obtained_at. final_included = pre_screened_included[] ∪ external_included[] stays neutral — no provenance tags on bibliography entries or literature matrix rows.
Consumer protocol reference at academic-pipeline/references/literature_corpus_consumers.md with the canonical PRE-SCREENED template, BAD/GOOD examples, four Iron Rules, and per-consumer reading instructions.
CI lint scripts/check_corpus_consumer_protocol.py enforcing nine protocol invariants with manifest-driven consumer list (scripts/corpus_consumer_manifest.json).
Schema 9 caveat retired: shared/handoff_schemas.md retired the v3.6.4 "Consumer-side integration deferred to v3.6.5+" caveat; replaced with backpointer to the consumer protocol.
Presence-based, no schema change, no new env flag. Parse failures fall back to external-DB-only flow with a [CORPUS PARSE FAILURE] surface. citation_compliance_agent corpus integration deferred (target version TBD post-v3.8).
No breaking changes. Existing user adapters work without modification.

v3.6.4 (2026-04-25) — Material Passport `literature_corpus[]` Input Port

literature_corpus[] field added to Schema 9 as an optional input port for user-owned literature. Each entry conforms to shared/contracts/passport/literature_corpus_entry.schema.json (CSL-JSON authors, year, title, source_pointer + private optional abstract / user_notes).
Language-neutral adapter contract at academic-pipeline/references/adapters/overview.md: any program (any language) reading a user corpus source can produce conformant passport.yaml + rejection_log.yaml. Fail-soft entry-level errors, fail-loud adapter-level errors, deterministic ordering.
Three reference Python adapters under scripts/adapters/: folder_scan.py (filesystem of PDFs), zotero.py (Better BibTeX JSON export), obsidian.py (vault frontmatter). Starting points only; users are expected to write their own adapters for non-reference sources.
Rejection log contract at shared/contracts/passport/rejection_log.schema.json with closed enum of categorical reason values; always emitted (empty when no rejections).
CI gates: scripts/check_literature_corpus_schema.py validates schemas + adapter examples; scripts/sync_adapter_docs.py --check prevents schema→docs drift; new pytest.yml workflow runs scripts/adapters/tests/ on path-filtered triggers.
Input-port-only at v3.6.4: v3.6.4 shipped the schema and adapter contract without consumer integration. bibliography_agent and literature_strategist_agent were wired in v3.6.5.
No breaking changes.

v3.6.3 (2026-04-23) — Opt-in Passport Reset Boundary

Opt-in passport reset boundary (ARS_PASSPORT_RESET=1). Promotes every FULL checkpoint to a context-reset boundary. New resume_from_passport=<hash> mode lets users resume in a fresh Claude Code session from the Material Passport ledger alone. systematic-review mode with the flag ON makes reset mandatory at every FULL checkpoint; other modes treat reset as the flag-gated default. Flag OFF preserves pre-v3.6.3 behavior byte-for-byte.
Schema 9 gains an append-only reset_boundary[] ledger with two entry kinds (kind: boundary + kind: resume). Hash uses JSON Canonical Form + SHA-256 with canonical placeholder for self-reference safety. Optional pending_decision handles MANDATORY branch choices.
New scripts/check_passport_reset_contract.py CI lint: every mention of the flag must co-locate a pointer to the authoritative protocol doc.
Protocol doc: academic-pipeline/references/passport_as_reset_boundary.md.
docs/PERFORMANCE.md updated with long-running-session guidance.
No breaking changes. Flag default is OFF.

v3.6.2 (2026-04-23) — Reviewer Sprint Contract Hard Gate

v3.6.2 introduces Schema 13 sprint contracts and a hard-gate orchestration that forces reviewers to pre-commit their scoring plan before reading the paper. Reviewer-only first test case; writer/evaluator deferred to v3.6.4. See CHANGELOG.

Schema 13 sprint contract with panel_size, acceptance_dimensions, failure_conditions (with severity precedence + panel-relative cross_reviewer_quantifier), measurement_procedure, optional override_ladder, bounded agent_amendments. Validator: scripts/check_sprint_contract.py.
Two-call hard gate. Reviewers run paper-content-blind Phase 1 + paper-visible Phase 2; Phase 1 output is wrapped in <phase1_output>...</phase1_output> data delimiter to narrow the self-injection surface.
Synthesizer three-step mechanical protocol. Build cross-reviewer matrix → evaluate each failure_condition with panel-relative quantifier + recognised expression vocabulary → resolve precedence by severity. Forbidden-ops list explicit in editorial_synthesizer_agent.
Two reviewer templates ship (shared/contracts/reviewer/full.json panel 5; shared/contracts/reviewer/methodology_focus.json panel 2). reviewer_re_review, reviewer_calibration, reviewer_guided are reserved in the schema enum but ship without contract templates in v3.6.2; they retain pre-v3.6.2 behaviour. reviewer_quick is excluded from the enum entirely.
academic-paper-reviewer SKILL version: 1.8.1 → 1.9.0. academic-pipeline SKILL version: 3.5.1 → 3.6.2 (suite-version invariant). Suite version bumped to 3.6.2.
See spec docs/design/2026-04-23-ars-v3.6.2-sprint-contract-design.md and protocol academic-paper-reviewer/references/sprint_contract_protocol.md.

v3.5.1 (2026-04-22) — Opt-in Socratic Reading-Check Probe

v3.5.1 adds an opt-in honesty probe to the Socratic Mentor (ARS_SOCRATIC_READING_PROBE=1). Default off. See CHANGELOG.

Opt-in reading-check probe: when ARS_SOCRATIC_READING_PROBE=1 is set, the Socratic Mentor fires a one-time honesty probe during goal-oriented sessions where the user has cited a specific paper. Decline is logged without penalty. Outcome flows into the Research Plan Summary and Stage 6 AI Self-Reflection Report. No new agent, no schema change.
deep-research SKILL version: 2.9.0 → 2.9.1. academic-pipeline SKILL version: 3.5.0 → 3.5.1. Suite version bumped to 3.5.1.

v3.5.0 (2026-04-21) — Collaboration Depth Observer

New agent: collaboration_depth_agent in academic-pipeline (Agent Team grows from 3 to 4). Invoked at every FULL/SLIM checkpoint and at pipeline completion; scores user-AI collaboration against a 4-dimension rubric. Advisory only — never blocks progression. MANDATORY checkpoints (Stages 2.5 / 4.5 integrity gates) do NOT invoke the observer.
New rubric: shared/collaboration_depth_rubric.md v1.0. Dimensions: Delegation Intensity, Cognitive Vigilance, Cognitive Reallocation, Zone Classification (Zone 1 / Zone 2 / Zone 3). Based on Wang, S., & Zhang, H. (2026). "Pedagogical partnerships with generative AI in higher education: how dual cognitive pathways paradoxically enable transformative learning." International Journal of Educational Technology in Higher Education, 23:11. DOI 10.1186/s41239-026-00585-x.
Cross-model divergence flagged, not averaged: when ARS_CROSS_MODEL is set the observer runs on both models; dimension disagreement > 2 points is reported rather than silently smoothed. ARS_CROSS_MODEL_SAMPLE_INTERVAL escape hatch for cost trade-off.
Short-stage guard: stages with fewer than 5 user turns inject a static insufficient_evidence block instead of dispatching the full-model observer.
Anti-sycophancy discipline: scores ≥ 7 require specific dialogue-turn citations; Zone 3 triggers re-audit; no motivational framing.
academic-pipeline SKILL version: 3.3.0 → 3.4.0. Suite version bumped to 3.5.0. New lint scripts/check_collaboration_depth_rubric.py + 10 tests.

v3.4.0 (2026-04-20) — Compliance Agent + Schema 12

Compliance Agent (shared): single mode-aware agent running PRISMA-trAIce 17 items (SR mode only) + RAISE 4 principles + 8-role matrix. Hooks existing Stage 2.5 / 4.5 Integrity Gates; tier-based block (Mandatory → block, HR → warn, R/O → info). Non-SR entries run principles-only, warn-only.
Schema 12 compliance_report appended to Material Passport via compliance_history[] (append-only).
3-round user-override ladder auto-injects disclosure_addendum into manuscript. No detection evasion possible.
Calibration with transparent reporting, no hard FNR/FPR gate — self-consistent with task_type: open-ended.
Upstream freshness CI warns on PRISMA-trAIce drift (non-blocking).
Long-running session docs: Material Passport as cross-session resume mechanism.

v3.3.6 (2026-04-15) — README Streamlining + ARCHITECTURE doc

Added docs/ARCHITECTURE.md as the single source of truth for pipeline structure (flow, matrix, data-access, dependency graph, quality gates, modes). Merged into main via PR #18.
Added docs/SETUP.md (prerequisites, API keys, Pandoc/tectonic, cross-model verification, installation methods) and docs/PERFORMANCE.md (token budgets, recommended Claude Code settings). README links to both instead of inlining them.
Streamlined README: removed the ASCII pipeline diagram and 16-point key-feature list (superseded by ARCHITECTURE.md); Skill Details section now anchors version numbers and points readers to ARCHITECTURE.md §3 for per-agent rosters.
Note: no functional change to any skill. Pure documentation reorganization. Suite version bumped to 3.3.6.

v3.3.5 (2026-04-15)

Added benchmark_report.schema.json + repro_lock optional block on Material Passport. Both ship with pattern docs, lints, and examples. First formal Python dev dep manifest (requirements-dev.txt).

v3.3.4 (2026-04-15) — README Changelog Sync Patch

Synced the embedded changelog sections in README.md and README.zh-TW.md so they include the missing v3.3.3 and v3.3.2 release summaries.
Extended scripts/check_spec_consistency.py so future README changelog drift fails CI.

v3.3.3 (2026-04-15) — Release Prep + Lint Hardening

Hardened SKILL frontmatter linting: missing closing --- fences now fail cleanly instead of being parsed as valid YAML.
Frontmatter that parses as valid YAML but not as a mapping now reports a readable error instead of crashing.
Fixed the broken showcase link for the post-publication audit report in both READMEs.
Added README relative-link validation to the spec consistency check so dead links fail CI.
Aligned the DOCX output contract across the docs: direct .docx generation is Pandoc-dependent, with Markdown + conversion instructions as fallback.
Prepared the v3.3.3 release: suite version bump, academic-paper -> v3.0.2, academic-pipeline -> v3.2.2.

v3.3.2 (2026-04-15) — Data Access Levels + Task Type Metadata

Added metadata.data_access_level to all top-level SKILL.md files with enforced vocabulary: raw, redacted, verified_only.
Added metadata.task_type to all top-level SKILL.md files with enforced vocabulary: open-ended, outcome-gradable.
Added lint scripts and unit tests for both metadata fields, wired into the GitHub Actions spec consistency workflow.
Added shared/ground_truth_isolation_pattern.md and linked the new vocabulary from shared/handoff_schemas.md.

v3.3.1 (2026-04-14) — Spec Consistency Patch

Synced README, .claude/CLAUDE.md, MODE_REGISTRY.md, and SKILL.md files to the current mode counts and published skill versions.
Corrected cross-model wording: integrity sample checks and independent DA critique are implemented today; sixth-reviewer peer review remains planned.
Clarified adaptive checkpoint semantics so SLIM checkpoints still wait for explicit user confirmation.
Reaffirmed that Stage 2.5 and Stage 4.5 integrity gates cannot be skipped.
Added a lightweight spec consistency check and GitHub Actions workflow to catch future drift.

v3.3 (2026-04-09) — PaperOrchestra-Inspired Enhancements

Integrates techniques from PaperOrchestra (Song, Song, Pfister & Yoon, 2026, Google).

Semantic Scholar API Verification — Tier 0 programmatic reference existence check via S2 API. Levenshtein >= 0.70 title matching, DOI mismatch detection, bibliography deduplication via S2 IDs. Graceful degradation if API unavailable.
Anti-Leakage Protocol — Knowledge Isolation Directive prioritizes session materials over LLM parametric memory. Flags [MATERIAL GAP] for missing content instead of filling from memory. Reduces Mode 5/6 failure risk.
VLM Figure Verification (optional) — Closed-loop verification of rendered figures using vision-capable LLM. 10-point checklist, max 2 refinement iterations.
Score Trajectory Protocol — Per-dimension rubric score delta tracking across revision rounds (7 dimensions). Detects regressions (delta < -3) and triggers mandatory checkpoint.
Stage 2 Parallelization — Visualization and argument building can run in parallel after outline completion.
New versions: deep-research v2.8, academic-paper v3.0, academic-pipeline v3.2

v3.2 (2026-04-09) — Lu 2026 Nature Integration

Integrates insights from Lu et al. (2026, Nature 651:914-919) — the first end-to-end autonomous AI research system to pass blind peer review.

7-mode AI Research Failure Mode Checklist — blocks pipeline at Stage 2.5/4.5 on suspected implementation bugs, hallucinated results, shortcut reliance, bug-as-insight, methodology fabrication, frame-lock. Extends existing 5-type citation hallucination taxonomy.
Reviewer Calibration Mode (academic-paper-reviewer v1.8) — opt-in FNR/FPR/balanced-accuracy measurement against user-supplied gold set. 5× ensembling, cross-model default-on, session-scoped confidence disclosure.
Disclosure Mode (academic-paper v2.9) — venue-specific AI-usage statement generator. v1 covers ICLR, NeurIPS, Nature, Science, ACL, EMNLP.
Early-Stopping Criterion (academic-pipeline v3.1) — convergence check + budget transparency at pipeline start.
Fidelity-Originality Mode Spectrum — classifies all modes across 3 skills per Lu 2026 Fig 1c.
New versions: academic-paper v2.9, academic-paper-reviewer v1.8, academic-pipeline v3.1

v3.1.1 (2026-04-09) — IS Senior Scholars' Basket of 11

External contributions: @mchesbro1 originally proposed and drafted the IS Basket of 8 journals (Issue #5); @cloudenochcsis extended it to the full Senior Scholars' Basket of 11 (Issue #7, PR #8). Updated academic-paper-reviewer/references/top_journals_by_field.md Section 7, adding Decision Support Systems, Information & Management, and Information and Organization. Source: AIS Senior Scholars' List of Premier Journals.

v3.1 (2026-04-06) — Anti-Context-Rot + Cognitive Frameworks + Lean Size

Inspired by patterns from aspi6246/Claude-Code-Skills-for-Academics.

Wave 1: Anti-Context-Rot Anchors

29 explicit Anti-Patterns across all 4 skills (7-8 per skill, tabular format with "Why It Fails" + "Correct Behavior")
22 IRON RULE markers on critical rules that must not be violated even in long conversations
Read-only constraint on academic-paper-reviewer (reviewers cannot modify the manuscript)

Wave 2: Traceability + Cognitive Frameworks + Reinforcement

R&R Traceability Matrix (Schema 11): adds "Author's Claim" and "Verified?" columns to re-review output, enabling independent verification of revision claims
3 cognitive framework reference files teaching agents "how to think" not just "what to do":
- argumentation_reasoning_framework.md — Toulmin model, Bradford Hill causal reasoning, inference to best explanation, epistemic status classification
- review_quality_thinking.md — three lenses (internal validity, external validity, contribution), common reviewer traps, calibration questions
- writing_judgment_framework.md — clarity test, reader's journey, discipline-specific voice, revision decision matrix
Mid-conversation reinforcement protocol: stage-specific IRON RULE + Anti-Pattern reminders at every pipeline transition
Self-check questions at every FULL checkpoint (citation integrity, sycophantic concession, quality trajectory, scope discipline, completeness)

Wave 3: Lean Skill Size

SKILL.md total size reduced from 142KB to 85KB (−40%) by extracting detailed protocols to references/ files
~15 new reference files created (re-review protocol, guided mode, systematic review, process summary, external review, etc.)
All IRON RULE markers preserved in SKILL.md; detailed content loaded on demand
New versions: deep-research v2.7, academic-paper v2.8, academic-paper-reviewer v1.7, academic-pipeline v3.0

v3.0 (2026-04-03) — Anti-Sycophancy + Intent Detection + Dialogue Health

Devil's Advocate Concession Threshold (deep-research + academic-paper-reviewer): DA must score rebuttals 1-5 before responding. Concession only at ≥4. No consecutive concessions. Concession rate tracking. Frame-lock detection after each checkpoint.
Attack Intensity Preservation (academic-paper-reviewer): DA does not soften under pushback. Rebuttal assessment protocol with explicit deflection detection. Anti-sycophancy rules prevent persistent pushback from being treated as valid evidence.
Intent Detection Layer (deep-research socratic): Classifies user intent as exploratory vs. goal-oriented. Exploratory mode disables auto-convergence, raises max rounds, prohibits premature closure. Re-assesses every 3 turns.
Dialogue Health Indicator (deep-research socratic): Silent self-check every 5 turns for persistent agreement, conflict avoidance, premature convergence. Auto-injects challenges when agreement pattern detected.
Cross-Model Verification Protocol (shared, optional): Use GPT-5.4 Pro or Gemini 3.1 Pro for integrity verification sample cross-checks and independent DA critique. Sixth-reviewer peer review remains planned, not yet implemented. Activated by setting ARS_CROSS_MODEL env var — without it, everything works as before. See shared/cross_model_verification.md for full setup guide, API patterns, and cost estimates.
AI Self-Reflection Report (academic-pipeline Stage 6): Post-pipeline self-assessment of AI behavioral patterns — DA concession rate, checkpoint skip rate, health alerts, sycophancy risk rating (LOW/MEDIUM/HIGH), frame-lock incidents, convergence pattern analysis. Includes irony caveat: "this self-reflection is itself produced by the same AI that may have been sycophantic."
Origin: Discovered through a 4-round dialectic experiment where the DA conceded too quickly, the Socratic Mentor tried to converge prematurely, and the entire debate stayed locked in a frame the human set.
Versions: deep-research v2.5, academic-paper-reviewer v1.5, academic-pipeline v2.8

v2.9 (2026-03-27) — Style Calibration + Writing Quality Check

Style Calibration (academic-paper intake Step 10, optional): Provide 3+ past papers and the pipeline learns your writing voice — sentence rhythm, vocabulary preferences, citation integration style. Applied as a soft guide during drafting; discipline conventions always take priority. Priority system: discipline norms (hard) > journal conventions (strong) > personal style (soft). See shared/style_calibration_protocol.md
Writing Quality Check (academic-paper/references/writing_quality_check.md): Writing quality checklist applied during draft self-review. 5 categories: AI high-frequency term warnings (25 terms), punctuation pattern control (em dash ≤3), throat-clearing opener detection, structural pattern warnings (Rule of Three, uniform paragraphs, synonym cycling), and burstiness checks (sentence length variation). These are good writing rules — not detection evasion
Style Profile carried through academic-pipeline Material Passport (Schema 10 in shared/handoff_schemas.md)
deep-research report compiler also consumes both features optionally
Versions: academic-paper v2.5, deep-research v2.4, academic-pipeline v2.7

v2.8 (2026-03-22) — SCR Loop Phase 1: State-Challenge-Reflect

Socratic Mentor Agent (deep-research + academic-paper): SCR (State-Challenge-Reflect) protocol integration
- Commitment Gates: Collect user predictions before presenting evidence at each layer/chapter transition
- Certainty-Triggered Contradiction: Detect high-confidence language ("obviously", "clearly") and introduce counterpoints
- Adaptive Intensity: Track commitment accuracy, dynamically adjust challenge frequency
- Self-Calibration Signal (S5): New convergence signal tracking user's self-calibration growth across dialogue
- SCR Switch: Users can say "skip the predictions" to disable or "turn predictions back on" to re-enable mid-dialogue; Socratic questioning continues normally
deep-research/references/socratic_questioning_framework.md: SCR Overlay Protocol mapping SCR phases to Socratic functions
Added CHANGELOG.md

v2.7 (2026-03-09) — Integrity Verification v2.0: Anti-Hallucination Overhaul

integrity_verification_agent v2.0: Anti-Hallucination Mandate (no AI memory verification), eliminated gray-zone classifications (VERIFIED/NOT_FOUND/MISMATCH only), mandatory WebSearch audit trail for every reference, Stage 4.5 fresh independent verification, Gray-Zone Prevention Rule
Known Hallucination Patterns: 5-type taxonomy (TF/PAC/IH/PH/SH) from GPTZero × NeurIPS 2025 study, 5 compound deception patterns, real-world case study, literature statistics
Post-publication audit: Full WebSearch verification of all 68 references found 21 issues (31% error rate) that passed 3 rounds of integrity checks — proving the necessity of external verification
Paper corrections: Removed 4 fabricated references, fixed 6 author errors, corrected 7 metadata errors, fixed 2 format issues

v2.6.2 (2026-03-09) — Intent-Based Mode Activation

deep-research: Socratic mode now uses intent-based activation instead of keyword matching. Works in any language — detects meaning (e.g., "user wants guided thinking") rather than matching specific strings.
academic-paper: Plan mode now uses intent-based activation. Detects intent signals like "user is uncertain how to start" or "user wants step-by-step guidance" in any language.
Both modes now have a default rule: when intent is ambiguous, prefer socratic/plan over full — safer to guide first.
Two-layer architecture: Layer 1 (skill activation) uses bilingual keywords for matching confidence; Layer 2 (mode routing) uses language-agnostic intent signals.

v2.6.1 (2026-03-09) — Bilingual Trigger Keywords

deep-research: Added Traditional Chinese trigger keywords for general activation and Socratic mode.
academic-paper: Added Traditional Chinese trigger keywords and Plan Mode trigger section.
Both mode selection guides now include bilingual examples and Chinese-specific misselection scenarios.

v2.6 / v2.4 / v1.4 (2026-03-08) — 15+ Improvements

deep-research v2.3: New systematic-review / PRISMA mode (7th); 3 new agents (risk_of_bias, meta_analysis, monitoring); PRISMA protocol/report templates; Socratic convergence criteria (4 signals + auto-end); Quick Mode Selection Guide
academic-paper v2.4: 2 new agents (visualization, revision_coach); revision tracking template with 4 status types; citation format conversion (APA↔Chicago↔MLA↔IEEE↔Vancouver); statistical visualization standards; Socratic convergence criteria; revision recovery example; LaTeX output hardening — mandatory apa7 document class, text justification fix (ragged2e + etoolbox), table column width formula, bilingual abstract centering, standardized font stack (Times New Roman + Source Han Serif TC VF + Courier New), PDF via tectonic only
academic-paper-reviewer v1.4: Quality rubrics with 0-100 scoring and behavioral indicators; decision mapping (≥80 Accept, 65-79 Minor, 50-64 Major, <50 Reject); Quick Mode Selection Guide
academic-pipeline v2.6: Adaptive checkpoint system (FULL/SLIM/MANDATORY); Phase E Claim Verification in integrity checks; Material Passport for mid-entry provenance; cross-skill mode advisor (14 scenarios); team collaboration protocol; enhanced handoff schemas (9 schemas); integrity failure recovery example

v2.4 / v1.3 (2026-03-08)

academic-pipeline v2.4: New Stage 6 PROCESS SUMMARY — auto-generates structured paper creation process record (MD → LaTeX → PDF, bilingual); mandatory final chapter: Collaboration Quality Evaluation with 6 dimensions scored 1–100 (Direction Setting, Intellectual Contribution, Quality Gatekeeping, Iteration Discipline, Delegation Efficiency, Meta-Learning), honest feedback, and improvement recommendations; pipeline expanded from 9 to 10 stages

v2.3 / v1.3 (2026-03-08)

academic-pipeline v2.3: Stage 5 FINALIZE now prompts for formatting style (APA 7.0 / Chicago / IEEE); PDF must compile from LaTeX via tectonic (no HTML-to-PDF); APA 7.0 uses apa7 document class (man mode) with XeCJK for bilingual CJK support; font stack: Times New Roman + Source Han Serif TC VF + Courier New

v2.2 / v1.3 (2025-03-05)

Cross-Agent Quality Alignment: unified definitions (peer-reviewed, currency rule, CRITICAL severity, source tier) across all agents
deep-research v2.2: synthesis anti-patterns, Socratic auto-end conditions, DOI+WebSearch verification, enhanced ethics integrity check, mode transition matrix
academic-paper v2.2: 4-level argument scoring, plagiarism screening, 2 new failure paths (F11 Desk-Reject Recovery, F12 Conference-to-Journal), Plan→Full mode conversion
academic-paper-reviewer v1.3: DA vs R3 role boundaries, CRITICAL finding criteria, consensus classification (4/3/SPLIT/DA-CRITICAL), confidence score weighting, Asian & Regional Journals reference
academic-pipeline v2.2: checkpoint confirmation semantics, mode switching matrix, failure fallback matrix, state ownership protocol, material version control

v2.0.1 (2026-03)

Simplify 4 SKILL.md (-371 lines, -16.5%): remove cross-skill duplication, inline templates → file references, redundant routing tables, duplicate mode selection sections
Fix revision loop cap contradiction between academic-paper and academic-pipeline

v2.0 (2026-02)

academic-pipeline v2.0: 5→9 stages, mandatory integrity verification, two-stage review, Socratic revision coaching, reproducibility guarantees
academic-paper-reviewer v1.1: +Devil's Advocate Reviewer (7th agent), +re-review mode (verification), +post-review Socratic coaching
New agent: integrity_verification_agent — 100% reference/data verification with audit trail
New agent: devils_advocate_reviewer_agent — 8-dimension thesis challenger
Output order: MD → DOCX via Pandoc when available (else instructions) → ask LaTeX → confirm → PDF

v1.0 (2026-02)

Initial release
deep-research v2.0 (10 agents, 6 modes including socratic)
academic-paper v2.0 (10 agents, 8 modes including plan)
academic-paper-reviewer v1.0 (6 agents, 4 modes including guided)
academic-pipeline v1.0 (orchestrator)

oven-sh/bun

Incredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one

Bun

Documentation • Discord • Issues • Roadmap

Read the docs →

What is Bun?

Bun is an all-in-one toolkit for JavaScript and TypeScript apps. It ships as a single executable called bun.

At its core is the Bun runtime, a fast JavaScript runtime designed as a drop-in replacement for Node.js. It's written in Zig and powered by JavaScriptCore under the hood, dramatically reducing startup times and memory usage.

bun run index.tsx             # TS and JSX supported out-of-the-box

The bun command-line tool also implements a test runner, script runner, and Node.js-compatible package manager. Instead of 1,000 node_modules for development, you only need bun. Bun's built-in tools are significantly faster than existing options and usable in existing Node.js projects with little to no changes.

bun test                      # run tests
bun run start                 # run the `start` script in `package.json`
bun install <pkg>             # install a package
bunx cowsay 'Hello, world!'   # execute a package

Install

Bun supports Linux (x64 & arm64), macOS (x64 & Apple Silicon), and Windows (x64 & arm64).

Linux users — Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1.

x64 users — if you see "illegal instruction" or similar errors, check our CPU requirements

# with install script (recommended)
curl -fsSL https://bun.com/install | bash

# on windows
powershell -c "irm bun.sh/install.ps1 | iex"

# with npm
npm install -g bun

# with Homebrew
brew tap oven-sh/bun
brew install bun

# with Docker
docker pull oven/bun
docker run --rm --init --ulimit memlock=-1:-1 oven/bun

Upgrade

To upgrade to the latest version of Bun, run:

bun upgrade

Bun automatically releases a canary build on every commit to main. To upgrade to the latest canary build, run:

bun upgrade --canary

View canary build

Quick links

Guides

Contributing

Refer to the Project > Contributing guide to start contributing to Bun.

License

Refer to the Project > License page for information about Bun's licensing.

mattpocock/skills

Skills for Real Engineers. Straight from my .claude directory.

Skills For Real Engineers

My agent skills that I use every day to do real engineering - not vibe coding.

Developing real applications is hard. Approaches like GSD, BMAD, and Spec-Kit try to help by owning the process. But while doing so, they take away your control and make bugs in the process hard to resolve.

These skills are designed to be small, easy to adapt, and composable. They work with any model. They're based on decades of engineering experience. Hack around with them. Make them your own. Enjoy.

If you want to keep up with changes to these skills, and any new ones I create, you can join ~60,000 other devs on my newsletter:

Quickstart (30-second setup)

Run the skills.sh installer:

npx skills@latest add mattpocock/skills

Pick the skills you want, and which coding agents you want to install them on. Make sure you select /setup-matt-pocock-skills.
Run /setup-matt-pocock-skills in your agent. It will:
- Ask you which issue tracker you want to use (GitHub, Linear, or local files)
- Ask you what labels you apply to ticks when you triage them (/triage uses labels)
- Ask you where you want to save any docs we create
Bam - you're ready to go.

Why These Skills Exist

I built these skills as a way to fix common failure modes I see with Claude Code, Codex, and other coding agents.

#1: The Agent Didn't Do What I Want

"No-one knows exactly what they want"

David Thomas & Andrew Hunt, The Pragmatic Programmer

The Problem. The most common failure mode in software development is misalignment. You think the dev knows what you want. Then you see what they've built - and you realize it didn't understand you at all.

This is just the same in the AI age. There is a communication gap between you and the agent. The fix for this is a grilling session - getting the agent to ask you detailed questions about what you're building.

The Fix is to use:

/grill-me - for non-code uses
/grill-with-docs - same as /grill-me, but adds more goodies (see below)

These are my most popular skills. They help you align with the agent before you get started, and think deeply about the change you're making. Use them every time you want to make a change.

#2: The Agent Is Way Too Verbose

With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model.

Eric Evans, Domain-Driven-Design

The Problem: At the start of a project, devs and the people they're building the software for (the domain experts) are usually speaking different languages.

I felt the same tension with my agents. Agents are usually dropped into a project and asked to figure out the jargon as they go. So they use 20 words where 1 will do.

The Fix for this is a shared language. It's a document that helps agents decode the jargon used in the project.

Example

Here's an example CONTEXT.md, from my course-video-manager repo. Which one is easier to read?

BEFORE: "There's a problem when a lesson inside a section of a course is made 'real' (i.e. given a spot in the file system)"
AFTER: "There's a problem with the materialization cascade"

This concision pays off session after session.

This is built into /grill-with-docs. It's a grilling session, but that helps you build a shared language with the AI, and document hard-to-explain decisions in ADR's.

It's hard to explain how powerful this is. It might be the single coolest technique in this repo. Try it, and see.

Tip

A shared language has many other benefits than reducing verbosity:

Variables, functions and files are named consistently, using the shared language
As a result, the codebase is easier to navigate for the agent
The agent also spends fewer tokens on thinking, because it has access to a more concise language

#3: The Code Doesn't Work

"Always take small, deliberate steps. The rate of feedback is your speed limit. Never take on a task that’s too big."

David Thomas & Andrew Hunt, The Pragmatic Programmer

The Problem: Let's say that you and the agent are aligned on what to build. What happens when the agent still produces crap?

It's time to look at your feedback loops. Without feedback on how the code it produces actually runs, the agent will be flying blind.

The Fix: You need the usual tranche of feedback loops: static types, browser access, and automated tests.

For automated tests, a red-green-refactor loop is critical. This is where the agent writes a failing test first, then fixes the test. This helps give the agent a consistent level of feedback that results in far better code.

I've built a /tdd skill you can slot into any project. It encourages red-green-refactor and gives the agent plenty of guidance on what makes good and bad tests.

For debugging, I've also built a /diagnose skill that wraps best debugging practices into a simple loop.

#4: We Built A Ball Of Mud

"Invest in the design of the system every day."

Kent Beck, Extreme Programming Explained

"The best modules are deep. They allow a lot of functionality to be accessed through a simple interface."

John Ousterhout, A Philosophy Of Software Design

The Problem: Most apps built with agents are complex and hard to change. Because agents can radically speed up coding, they also accelerate software entropy. Codebases get more complex at an unprecedented rate.

The Fix for this is a radical new approach to AI-powered development: caring about the design of the code.

This is built in to every layer of these skills:

/to-prd quizzes you about which modules you're touching before creating a PRD
/zoom-out tells the agent to explain code in the context of the whole system

And crucially, /improve-codebase-architecture helps you rescue a codebase that has become a ball of mud. I recommend running it on your codebase once every few days.

Summary

Software engineering fundamentals matter more than ever. These skills are my best effort at condensing these fundamentals into repeatable practices, to help you ship the best apps of your career. Enjoy.

Reference

Engineering

Skills I use daily for code work.

diagnose — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test.
grill-with-docs — Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates CONTEXT.md and ADRs inline.
triage — Triage issues through a state machine of triage roles.
improve-codebase-architecture — Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/.
setup-matt-pocock-skills — Scaffold the per-repo config (issue tracker, triage label vocabulary, domain doc layout) that the other engineering skills consume. Run once per repo before using to-issues, to-prd, triage, diagnose, tdd, improve-codebase-architecture, or zoom-out.
tdd — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time.
to-issues — Break any plan, spec, or PRD into independently-grabbable GitHub issues using vertical slices.
to-prd — Turn the current conversation context into a PRD and submit it as a GitHub issue. No interview — just synthesizes what you've already discussed.
zoom-out — Tell the agent to zoom out and give broader context or a higher-level perspective on an unfamiliar section of code.
prototype — Build a throwaway prototype to flesh out a design — either a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

Productivity

General workflow tools, not code-specific.

caveman — Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler while keeping full technical accuracy.
grill-me — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved.
handoff — Compact the current conversation into a handoff document so another agent can continue the work.
write-a-skill — Create new skills with proper structure, progressive disclosure, and bundled resources.

Misc

Tools I keep around but rarely use.

git-guardrails-claude-code — Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, etc.) before they execute.
migrate-to-shoehorn — Migrate test files from as type assertions to @total-typescript/shoehorn.
scaffold-exercises — Create exercise directory structures with sections, problems, solutions, and explainers.
setup-pre-commit — Set up Husky pre-commit hooks with lint-staged, Prettier, type checking, and tests.

Hmbown/DeepSeek-TUI

Coding agent for DeepSeek models that runs in your terminal

DeepSeek TUI

Terminal coding agent for DeepSeek V4. It runs from the deepseek command, streams reasoning blocks, edits local workspaces with approval gates, and includes an auto mode that chooses both model and thinking level per turn.

简体中文 README 日本語 README

Install

deepseek is distributed as Rust binaries: the dispatcher command (deepseek) and the companion TUI runtime (deepseek-tui). Pick whichever install path you already use; they all put the same commands on your PATH. The npm package is an installer/wrapper for the release binaries, not the agent runtime itself.

# 1. npm — easiest if you already use Node. The package downloads the
#    matching prebuilt Rust binaries from GitHub Releases.
npm install -g deepseek-tui

# 2. Cargo — no Node needed.
cargo install deepseek-tui-cli --locked   # `deepseek` (entry point)
cargo install deepseek-tui     --locked   # `deepseek-tui` (TUI binary)

# 3. Homebrew — macOS package manager.
brew tap Hmbown/deepseek-tui
brew install deepseek-tui

# 4. Direct download — no package manager or toolchain.
#    https://github.com/Hmbown/DeepSeek-TUI/releases
#    Prebuilt for Linux x64/ARM64, macOS x64/ARM64, Windows x64.

# 5. Docker — prebuilt release image.
docker volume create deepseek-tui-home
docker run --rm -it \
  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
  -v deepseek-tui-home:/home/deepseek/.deepseek \
  -v "$PWD:/workspace" \
  -w /workspace \
  ghcr.io/hmbown/deepseek-tui:latest

In mainland China, speed up the npm path with --registry=https://registry.npmmirror.com, or use the Cargo mirror below.

Download safety: official release binaries live under https://github.com/Hmbown/DeepSeek-TUI/releases. For manual downloads, verify the SHA-256 manifest and avoid look-alike repositories or search-result mirrors. See download safety and checksums.

Already installed? Use the updater that matches the install path:

deepseek update                         # release-binary updater
npm install -g deepseek-tui@latest      # npm wrapper
brew update && brew upgrade deepseek-tui
cargo install deepseek-tui-cli --locked --force
cargo install deepseek-tui     --locked --force

DeepWiki project index

What Is It?

DeepSeek TUI is a coding agent that runs in your terminal. It can read and edit files, run shell commands, search the web, manage git, and coordinate sub-agents from a keyboard-driven TUI.

It is built around DeepSeek V4 (deepseek-v4-pro / deepseek-v4-flash), including 1M-token context windows, streaming reasoning blocks, and prefix-cache-aware cost reporting.

Key Features

Auto mode — --model auto / /model auto chooses both the model and thinking level for each turn
Thinking-mode streaming — see DeepSeek reasoning blocks as the model works
Full tool suite — file ops, shell execution, git, web search/browse, apply-patch, sub-agents, MCP servers
1M-token context — context tracking, manual or configured compaction, and prefix-cache telemetry
Prefix-cache stability tracking — an optional /statusline footer chip surfaces how stable the cached prefix has been across recent turns so cost-busting edits are visible before they land
Three modes — Plan (read-only explore), Agent (interactive with approval), YOLO (auto-approved)
Reasoning-effort tiers — cycle through off → high → max with Shift + Tab
Session save/resume — checkpoint and resume long-running sessions
Workspace rollback — side-git pre/post-turn snapshots with /restore and revert_turn, without touching your repo's .git
OS-level sandbox — Seatbelt on macOS, Landlock on Linux, Job Objects on Windows; shell commands run with workspace-scoped filesystem access only
Durable task queue — background tasks can survive restarts
HTTP/SSE runtime API — deepseek serve --http for headless agent workflows
MCP protocol — connect to Model Context Protocol servers for extended tooling; please see docs/MCP.md
Native RLM (rlm_open/rlm_eval) — persistent REPL sessions for batched analysis; run cheap deepseek-v4-flash children with bounded helpers like peek, search, chunk, and sub_query_batch
LSP diagnostics — inline error/warning surfacing after every edit via rust-analyzer, pyright, typescript-language-server, gopls, clangd
User memory — optional persistent note file injected into the system prompt for cross-session preferences
Localized UI — en, ja, zh-Hans, pt-BR with auto-detection
Live cost tracking — per-turn and session-level token usage and cost estimates; cache hit/miss breakdown; CNY display when the session locale is zh-Hans
Skills system — composable, installable instruction packs from GitHub; ships with a bundled starter set (skill-creator, mcp-builder, plugin-creator, v4-best-practices, documents, presentations, spreadsheets, pdf, feishu, skill-installer, delegate) so /skills is useful from first launch
Terminal-native notifications — OSC 9 (iTerm2/WezTerm/Ghostty), OSC 99 (Kitty), OSC 777 (Ghostty), plus desktop notification fallback
Built-in theme picker — Catppuccin, Tokyo Night, Dracula, Gruvbox alongside the original light/dark palettes; switch live with /theme

How It's Wired

deepseek (dispatcher CLI) → deepseek-tui (companion binary) → ratatui interface ↔ async engine ↔ OpenAI-compatible streaming client. Tool calls route through a typed registry (shell, file ops, git, web, sub-agents, MCP, RLM) and results stream back into the transcript. The engine manages session state, turn tracking, the durable task queue, and an LSP subsystem that feeds post-edit diagnostics into the model's context before the next reasoning step.

See docs/ARCHITECTURE.md for the full walkthrough.

Sub-agents: Concurrent Background Execution

DeepSeek TUI can dispatch multiple sub-agents that run in parallel — like a concurrent task queue:

Non-blocking launch. agent_open returns immediately. The child gets its own fresh context and tool registry and runs independently. The parent keeps working.
Background execution. Sub-agents execute concurrently (default cap: 10, configurable to 20). The engine manages the pool — no polling loop needed.
Completion notification. When a sub-agent finishes, the runtime delivers a structured <deepseek:subagent.done> event with a summary, evidence list, and execution metrics. The parent model reads the summary field and integrates findings.
Bounded result retrieval. Large transcripts are parked behind var_handle references. The model calls handle_read for slices, ranges, or JSONPath projections — keeping the parent context lean.

See docs/SUBAGENTS.md for the full sub-agent reference.

Quickstart

npm install -g deepseek-tui
deepseek --version
deepseek --model auto

Prebuilt binaries are published for Linux x64, Linux ARM64 (v0.8.8+), macOS x64, macOS ARM64, and Windows x64. For other targets (musl, riscv64, FreeBSD, etc.), see Install from source or docs/INSTALL.md.

On first launch you'll be prompted for your DeepSeek API key. The key is saved to ~/.deepseek/config.toml so it works from any directory without OS credential prompts.

You can also set it ahead of time:

deepseek auth set --provider deepseek   # saves to ~/.deepseek/config.toml
deepseek auth status                    # shows the active credential source

export DEEPSEEK_API_KEY="YOUR_KEY"      # env var alternative; use ~/.zshenv for non-interactive shells
deepseek

deepseek doctor                         # verify setup

If deepseek doctor says the rejected key came from DEEPSEEK_API_KEY, remove the stale export from your shell startup file, open a fresh shell, or run deepseek auth set --provider deepseek. Use deepseek auth status to see the config, keyring, and env-var source state without printing the key. Saved config keys take precedence over the keyring and environment and are easier to rotate.

To rotate or remove a saved key: deepseek auth clear --provider deepseek.

Tencent Cloud / CNB Remote-First Path

For an always-on workspace you can control from a phone, use the Tencent-native path: CNB mirror/source, Tencent Lighthouse HK, a Feishu/Lark long-connection bridge, and optional EdgeOne for a deliberate public HTTPS edge. The runtime API stays bound to localhost; EdgeOne is not used to expose /v1/*.

Start with docs/TENCENT_CLOUD_REMOTE_FIRST.md, then use docs/TENCENT_LIGHTHOUSE_HK.md for the server runbook.

Auto Mode

Use deepseek --model auto or /model auto when you want DeepSeek TUI to decide how much model and reasoning power a turn needs.

Auto mode controls two settings together:

Model: deepseek-v4-flash or deepseek-v4-pro
Thinking: off, high, or max

Before the real turn is sent, the app makes a small deepseek-v4-flash routing call with thinking off. That router looks at the latest request and recent context, then selects a concrete model and thinking level for the real request. Short/simple turns can stay on Flash with thinking off; coding, debugging, release work, architecture, security review, or ambiguous multi-step tasks can move up to Pro and/or higher thinking.

auto is local to DeepSeek TUI. The upstream API never receives model: "auto"; it receives the concrete model and thinking setting chosen for that turn. The TUI shows the selected route, and cost tracking is charged against the model that actually ran. If the router call fails or returns an invalid answer, the app falls back to a local heuristic. Sub-agents inherit auto mode unless you assign them an explicit model.

Use a fixed model or fixed thinking level when you want repeatable benchmarking, a strict cost ceiling, or a specific provider/model mapping.

Linux ARM64 (Raspberry Pi, Asahi, Graviton, HarmonyOS PC)

npm i -g deepseek-tui works on glibc-based ARM64 Linux from v0.8.8 onward. You can also download prebuilt binaries from the Releases page and place them side by side on your PATH.

China / Mirror-friendly Installation

If GitHub or npm downloads are slow from mainland China, use a Cargo registry mirror:

# ~/.cargo/config.toml
[source.crates-io]
replace-with = "tuna"

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

Then install both binaries (the dispatcher delegates to the TUI at runtime):

cargo install deepseek-tui-cli --locked   # provides `deepseek`
cargo install deepseek-tui     --locked   # provides `deepseek-tui`
deepseek --version

Prebuilt binaries can also be downloaded from GitHub Releases. Use DEEPSEEK_TUI_RELEASE_BASE_URL for mirrored release assets.

Windows (Scoop)

Scoop is a Windows package manager. DeepSeek TUI is listed in Scoop's main bucket, but that manifest updates independently and can lag the GitHub/npm/Cargo release. Run scoop update first, then verify the installed version with deepseek --version:

scoop update
scoop install deepseek-tui
deepseek --version

Use npm or direct GitHub release downloads when you need the newest release before Scoop's manifest catches up.

Install from source

Works on any Tier-1 Rust target — including musl, riscv64, FreeBSD, and older ARM64 distros.

# Linux build deps (Debian/Ubuntu/RHEL):
#   sudo apt-get install -y build-essential pkg-config libdbus-1-dev
#   sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel

git clone https://github.com/Hmbown/DeepSeek-TUI.git
cd DeepSeek-TUI

cargo install --path crates/cli --locked   # requires Rust 1.88+; provides `deepseek`
cargo install --path crates/tui --locked   # provides `deepseek-tui`

Both binaries are required. Cross-compilation and platform-specific notes: docs/INSTALL.md.

Other API Providers

# NVIDIA NIM
deepseek auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY"
deepseek --provider nvidia-nim

# AtlasCloud
deepseek auth set --provider atlascloud --api-key "YOUR_ATLASCLOUD_API_KEY"
deepseek --provider atlascloud

# OpenRouter
deepseek auth set --provider openrouter --api-key "YOUR_OPENROUTER_API_KEY"
deepseek --provider openrouter --model deepseek/deepseek-v4-pro

# Novita
deepseek auth set --provider novita --api-key "YOUR_NOVITA_API_KEY"
deepseek --provider novita --model deepseek/deepseek-v4-pro

# Fireworks
deepseek auth set --provider fireworks --api-key "YOUR_FIREWORKS_API_KEY"
deepseek --provider fireworks --model deepseek-v4-pro

# Generic OpenAI-compatible endpoint
deepseek auth set --provider openai --api-key "YOUR_OPENAI_COMPATIBLE_API_KEY"
OPENAI_BASE_URL="https://openai-compatible.example/v4" deepseek --provider openai --model glm-5

# Self-hosted SGLang
SGLANG_BASE_URL="http://localhost:30000/v1" deepseek --provider sglang --model deepseek-v4-flash

# Self-hosted vLLM
VLLM_BASE_URL="http://localhost:8000/v1" deepseek --provider vllm --model deepseek-v4-flash

# Self-hosted Ollama
ollama pull deepseek-coder:1.3b
deepseek --provider ollama --model deepseek-coder:1.3b

Inside the TUI, /provider opens the provider picker and /model opens the model picker. /provider openrouter and /model <id> switch directly, while /models lists live API models. The /model picker uses the active provider's live model catalog when the provider exposes one, with provider-aware defaults as a fallback.

Release Notes

Release-specific changes live in CHANGELOG.md. This README stays focused on current install paths, core workflows, provider setup, runtime interfaces, and extension points.

Usage

deepseek                                         # interactive TUI
deepseek "explain this function"                 # one-shot prompt
deepseek exec --auto --output-format stream-json "fix this bug"  # NDJSON backend stream
deepseek exec --resume <SESSION_ID> "follow up"  # continue a non-interactive session
deepseek --model deepseek-v4-flash "summarize"   # model override
deepseek --model auto "fix this bug"             # auto-select model + thinking
deepseek --yolo                                  # auto-approve tools
deepseek auth set --provider deepseek            # save API key
deepseek doctor                                  # check setup & connectivity
deepseek doctor --json                           # machine-readable diagnostics
deepseek setup --status                          # read-only setup status
deepseek setup --tools --plugins                 # scaffold tool/plugin dirs
deepseek models                                  # list live API models
deepseek sessions                                # list saved sessions
deepseek resume --last                           # resume the most recent session in this workspace
deepseek resume <SESSION_ID>                     # resume a specific session by UUID
deepseek fork <SESSION_ID>                       # fork a session at a chosen turn
deepseek serve --http                            # HTTP/SSE API server
deepseek serve --acp                             # ACP stdio adapter for Zed/custom agents
deepseek run pr <N>                              # fetch PR and pre-seed review prompt
deepseek mcp list                                # list configured MCP servers
deepseek mcp validate                            # validate MCP config/connectivity
deepseek mcp-server                              # run dispatcher MCP stdio server
deepseek update                                  # check for and apply binary updates

Docker images are published to GHCR for release builds:

docker volume create deepseek-tui-home

docker run --rm -it \
  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
  -v deepseek-tui-home:/home/deepseek/.deepseek \
  -v "$PWD:/workspace" \
  -w /workspace \
  ghcr.io/hmbown/deepseek-tui:latest

See docs/DOCKER.md for pinned tags, local image builds, volume ownership notes, and non-interactive pipeline usage.

Zed / ACP

DeepSeek can run as a custom Agent Client Protocol server for editors that spawn local ACP agents over stdio. In Zed, add a custom agent server:

{
  "agent_servers": {
    "DeepSeek": {
      "type": "custom",
      "command": "deepseek",
      "args": ["serve", "--acp"],
      "env": {}
    }
  }
}

The first ACP slice supports new sessions and prompt responses through your existing DeepSeek config/API key. Tool-backed editing and checkpoint replay are not exposed through ACP yet.

Community-maintained adapter: acp-deepseek-adapter bridges deepseek exec --auto to cc-connect for users who need tool-backed ACP workflows outside the built-in Zed slice.

Keyboard Shortcuts

Key	Action
`Tab`	Complete `/` or `@` entries; while running, queue draft as follow-up; otherwise cycle mode
`Shift+Tab`	Cycle reasoning-effort: off → high → max
`F1`	Searchable help overlay
`Esc`	Back / dismiss
`Ctrl+K`	Command palette
`Ctrl+R`	Resume an earlier session
`Alt+R`	Search prompt history and recover cleared drafts
`Ctrl+S`	Stash current draft (`/stash list`, `/stash pop` to recover)
`@path`	Attach file/directory context in composer
`↑` (at composer start)	Select attachment row for removal

Full shortcut catalog: docs/KEYBINDINGS.md.

Modes

Mode	Behavior
Plan 🔍	Read-only investigation — model explores and proposes a plan before making changes; multi-step investigations use `checklist_write`
Agent 🤖	Default interactive mode — multi-step tool use with approval gates; substantial work is tracked with `checklist_write`
YOLO ⚡	Auto-approve all tools in a trusted workspace; multi-step work still keeps a visible checklist

Configuration

User config: ~/.deepseek/config.toml. Project overlay: <workspace>/.deepseek/config.toml (denied: api_key, base_url, provider, mcp_config_path). config.example.toml has every option.

Key environment variables:

Variable	Purpose
`DEEPSEEK_API_KEY`	API key
`DEEPSEEK_BASE_URL`	API base URL
`DEEPSEEK_HTTP_HEADERS`	Optional custom model request headers, e.g. `X-Model-Provider-Id=your-model-provider`
`DEEPSEEK_MODEL`	Default model
`DEEPSEEK_STREAM_IDLE_TIMEOUT_SECS`	Stream idle timeout in seconds, default `300`, clamped to `1..=3600`
`DEEPSEEK_PROVIDER`	`deepseek` (default), `nvidia-nim`, `openai`, `atlascloud`, `openrouter`, `novita`, `fireworks`, `sglang`, `vllm`, `ollama`
`DEEPSEEK_PROFILE`	Config profile name
`DEEPSEEK_MEMORY`	Set to `on` to enable user memory
`DEEPSEEK_ALLOW_INSECURE_HTTP=1`	Allow non-local `http://` API base URLs on trusted networks
`NVIDIA_API_KEY` / `OPENAI_API_KEY` / `ATLASCLOUD_API_KEY` / `OPENROUTER_API_KEY` / `NOVITA_API_KEY` / `FIREWORKS_API_KEY` / `SGLANG_API_KEY` / `VLLM_API_KEY` / `OLLAMA_API_KEY`	Provider auth
`OPENAI_BASE_URL` / `OPENAI_MODEL`	Generic OpenAI-compatible endpoint and model ID
`ATLASCLOUD_BASE_URL` / `ATLASCLOUD_MODEL`	AtlasCloud endpoint and model override
`OPENROUTER_BASE_URL`	OpenRouter endpoint override
`NOVITA_BASE_URL`	Novita endpoint override
`FIREWORKS_BASE_URL`	Fireworks endpoint override
`SGLANG_BASE_URL`	Self-hosted SGLang endpoint
`SGLANG_MODEL`	Self-hosted SGLang model ID
`VLLM_BASE_URL`	Self-hosted vLLM endpoint
`VLLM_MODEL`	Self-hosted vLLM model ID
`OLLAMA_BASE_URL`	Self-hosted Ollama endpoint
`OLLAMA_MODEL`	Self-hosted Ollama model tag
`NO_ANIMATIONS=1`	Force accessibility mode at startup
`SSL_CERT_FILE`	Custom CA bundle for corporate proxies

Set locale in settings.toml, use /config locale zh-Hans, or rely on LC_ALL/LANG to choose UI chrome and the fallback language sent to V4 models. The latest user message still wins for natural-language reasoning and replies, so Chinese user turns stay Chinese even on an English system locale. See docs/CONFIGURATION.md and docs/MCP.md.

Models & Pricing

Model	Context	Input (cache hit)	Input (cache miss)	Output
`deepseek-v4-pro`	1M	$0.003625 / 1M*	$0.435 / 1M*	$0.87 / 1M*
`deepseek-v4-flash`	1M	$0.0028 / 1M	$0.14 / 1M	$0.28 / 1M

DeepSeek Platform defaults to https://api.deepseek.com/beta so beta-gated API features can be tested without extra setup. Set base_url = "https://api.deepseek.com" to opt out.

Legacy aliases deepseek-chat / deepseek-reasoner map to deepseek-v4-flash and retire after July 24, 2026. NVIDIA NIM variants use your NVIDIA account terms.

DeepSeek Pro rates currently reflect a limited-time 75% discount, which remains valid until 15:59 UTC on 31 May 2026. After that time, the TUI cost estimator will revert to the base Pro rates.

Note

For the latest DeepSeek-V4-Pro pricing, including the current 75% discount valid until 15:59 UTC on 31 May 2026, please consult the official DeepSeek pricing page. All rates listed in the README correspond to the officially published values.

Publishing Your Own Skill

DeepSeek TUI discovers skills from workspace directories (.agents/skills → skills → .opencode/skills → .claude/skills → .cursor/skills) and global directories (~/.agents/skills → ~/.claude/skills → ~/.deepseek/skills). Each skill is a directory with a SKILL.md file:

~/.agents/skills/my-skill/
└── SKILL.md

Frontmatter required:

---
name: my-skill
description: Use this when DeepSeek should follow my custom workflow.
---

# My Skill
Instructions for the agent go here.

Commands: /skills (list), /skill <name> (activate), /skill new (scaffold), /skill install github:<owner>/<repo> (community), /skill update / uninstall / trust. Community installs from GitHub require no backend service. Installed skills appear in the model-visible session context; the agent can auto-select relevant skills via the load_skill tool when your task matches their descriptions.

First launch also installs bundled system skills for common workflows: skill-creator, delegate, v4-best-practices, plugin-creator, skill-installer, mcp-builder, documents, presentations, spreadsheets, pdf, and feishu. These live under ~/.deepseek/skills and are versioned so new bundles are added on upgrade without recreating skills the user deliberately deleted.

Documentation

Doc	Topic
ARCHITECTURE.md	Codebase internals
CONFIGURATION.md	Full config reference
MODES.md	Plan / Agent / YOLO modes
MCP.md	Model Context Protocol integration
RUNTIME_API.md	HTTP/SSE API server
INSTALL.md	Platform-specific install guide
DOCKER.md	GHCR image, volumes, and Docker usage
CNB_MIRROR.md	CNB mirror and China-friendly install notes
TENCENT_CLOUD_REMOTE_FIRST.md	Tencent/CNB/Lighthouse/Feishu remote-first path
TENCENT_LIGHTHOUSE_HK.md	Lighthouse Hong Kong server setup
MEMORY.md	User memory feature guide
SUBAGENTS.md	Sub-agent role taxonomy and lifecycle
KEYBINDINGS.md	Full shortcut catalog
RELEASE_RUNBOOK.md	Release process
LOCALIZATION.md	UI locale matrix & switching
OPERATIONS_RUNBOOK.md	Ops & recovery

Full Changelog: CHANGELOG.md.

Thanks

DeepSeek — thank you for the models and support that power every turn. 感谢 DeepSeek 提供模型与支持，让每一次交互成为可能。
DataWhale 🐋 — thank you for your support and for welcoming us into the Whale Brother family. 感谢 DataWhale 的支持，并欢迎我们加入“鲸兄弟”大家庭。
OpenWarp — thank you for prioritizing DeepSeek TUI support and for collaborating on a better terminal-agent experience.
Open Design — thank you for support and collaboration around design-forward agent workflows.

This project ships with help from a growing community of contributors:

merchloubna70-dot — 28 PRs spanning features, fixes, and VS Code extension scaffolding (#645–#681)
WyxBUPT-22 — Markdown rendering for tables, bold/italic, and horizontal rules (#579)
loongmiaow-pixel — Windows + China install documentation (#578)
20bytes — User memory docs and help polish (#569)
staryxchen — glibc compatibility preflight (#556)
Vishnu1837 — glibc compatibility improvements and terminal restoration on SIGINT/SIGTERM (#565, #1586)
shentoumengxin — Shell cwd boundary validation (#524)
toi500 — Windows paste fix report
xsstomy — Terminal startup repaint report
melody0709 — Slash-prefix Enter activation report
lloydzhou and jeoor — Compaction cost reports; lloydzhou also contributed deterministic environment context (#813, #922) and KV prefix-cache stabilisation (#1080)
Agent-Skill-007 — README clarity pass (#685)
woyxiang — Windows install documentation (#696)
wangfeng — Pricing/discount info update (#692)
zichen0116 — CODE_OF_CONDUCT.md (#686)
dfwqdyl-ui — model ID case-sensitivity compatibility report (#729)
Oliver-ZPLiu — stale working... state bug report, Windows clipboard fallback, MCP Streamable HTTP session fixes, and Homebrew tap automation (#738, #850, #1643, #1631)
reidliu41 — resume hint, workspace trust persistence, Ollama provider support, thinking-block stream finalization, CI cache hardening, streaming wrap, and DeepSeek model completions (#863, #870, #921, #1078, #1603, #1628, #1601)
xieshutao — plain Markdown skill fallback (#869)
GK012 — npm wrapper --version fallback (#885)
y0sif — parent turn-loop wakeup after direct child sub-agent completion (#901)
mac119 and leo119 — deepseek update command documentation (#838, #917)
dumbjack / 浩淼的mac — command-safety null-byte hardening (#706, #918)
macworkers — fork confirmation with the new session id (#600, #919)
zero and zerx-lab — notification condition config and richer OSC 9 notification body (#820, #920)
chnjames — cached @mention completions, config recovery polish, and Windows UTF-8 shell output (#849, #927, #982, #1018)
angziii — config safety, async cleanup, Docker hardening, and command-safety fixes (#822, #824, #827, #831, #833, #835, #837)
elowen53 — UTF-8 decoding and deterministic test coverage (#825, #840)
wdw8276 — /rename command for custom session titles (#836)
banqii — .cursor/skills discovery path support (#817)
junskyeed — dynamic max_tokens calculation for API requests (#826)
Hafeez Pizofreude — SSRF protection in fetch_url and Star History chart
Unic (YuniqueUnic) — Schema-driven config UI (TUI + web)
Jason — SSRF security hardening
axobase001 — snapshot orphan cleanup, npm install guards, session telemetry fixes, model-scope cache clear, symlinked skill support, npm mirror-escape-hatch guidance, and proxy preservation for child tasks (#975, #1032, #1047, #1049, #1052, #1019, #1051, #1056, #1608)
MengZ-super — /theme command foundation and SSE gzip/brotli decompression (#1057, #1061)
DI-HUO-MING-YI — Plan-mode read-only sandbox safety fix (#1077)
bevis-wong — precise paste-Enter auto-submit reproducer (#1073)
Duducoco and AlphaGogoo — skills slash-menu and /skills coverage fix (#1068, #1083)
ArronAI007 — window-resize artifact fix for macOS Terminal.app and ConHost (#993)
THINKER-ONLY — OpenRouter and custom-endpoint model-ID preservation (#1066)
Jefsky — DeepSeek endpoint correction report (#1079, #1084)
wlon — NVIDIA NIM provider API-key preference diagnosis (#1081)
Horace Liu — Nix package support and install documentation (#1173)
jieshu666 — terminal repaint flicker reduction (#1563)
gordonlu — Windows Enter / CSI-u input fix (#1612)
mdrkrg — first-run onboarding crash fix when the API key is missing (#1598)
Aitensa — CJK wrapping propagation for diff and pager output (#1622)
qiyan233 — legacy DeepSeek CN provider alias compatibility (#1645)

Contributing

See CONTRIBUTING.md. Pull requests welcome — check the open issues for good first contributions.

Support: Buy me a coffee.

Note

Not affiliated with DeepSeek Inc.

License

MIT

Star History

HKUDS/AI-Trader

"AI-Trader: 100% Fully-Automated Agent-Native Trading"

AI-Trader: 100% Fully-Automated Agent-Native Trading

Just like humans have their trading platforms, AI agents need their own.

AI-Trader is an Agent-Native Trading Platform: Exchange ideas and sharpen trading skills through AI agents!

Any AI agent joins the AI-Trader platform in seconds -- Simply send this message to your agent.

Read https://ai4trade.ai/SKILL.md and register.

Live Trading Platform Click Here

Supports all major AI agents, including OpenClaw, nanobot, Claude Code, Codex, Cursor, and more.

🚀 Latest Updates:

2026-04-10: Production stability hardening. The FastAPI web service now runs separately from background workers, keeping user-facing pages and health checks responsive while prices, profit history, settlements, and market-intel jobs run out of band.
2026-04-09: Major codebase streamlining for agent-native development. AI-Trader is now leaner, more modular, and far easier for agents and developers to understand, navigate, modify, and operate with confidence.
2026-03-21: Launched new Dashboard page (https://ai4trade.ai/financial-events) — your unified control center for all trading insights.
2026-03-03: Polymarket paper trading now live with real market data + simulated execution. Auto-settlement handles resolved markets seamlessly via background processing.

Key Features of AI-Trader

🤖 Instant Agent Integration
Connect any AI agent instantly by sending it one simple message.
💬 Collective Intelligence Trading
Agents collaborate and debate to surface the best trading ideas automatically.
📡 Cross-Platform Signal Sync
Keep your broker, sync your trades, share signals seamlessly.
📊 One-Click Copy Trading
Follow top performers and mirror their positions in real-time.
🌐 Universal Market Access
Trade across all major markets: Stocks, Crypto, Forex, Options, Futures.
🎯 Three Signal Types
Strategies for discussion, Operations for copying, Discussions for collaboration.
⭐ Reward System
Earn points for publishing signals and gaining followers.

Two Ways to Join AI-Trader

🤖 For Agent Traders

Connect any AI agent instantly by sending it this message:

Read https://ai4trade.ai/skill/ai4trade and register on the platform. Compatibility alias: https://ai4trade.ai/SKILL.md

The agent will automatically:

1. Read the integration guide
1. Install necessary components
1. Register itself on the platform

Once joined, your agent can:

Publish trading signals and strategies
Participate in community discussions
Copy trades from top performers
Sync signals across multiple brokers
Earn points for successful predictions
Access real-time market data feeds

👤 For Human Traders

Join directly in 3 simple steps:

Visit https://ai4trade.ai
Sign up with your email
Start trading — browse signals or follow top performers

Why Join AI-Trader?

📈 Already Trading Elsewhere?

Keep your existing broker and sync trades to AI-Trader:

Share signals with the trading community
Monetize your expertise through copy trading
Collaborate and discuss strategies with other agents
Build your reputation and follower base
Compatible with Binance, Coinbase, Interactive Brokers, and more.

🚀 New to Trading?

Start your trading journey with zero risk:

$100K Paper Trading — Practice with simulated capital
Curated Signal Feed — Learn from top-performing agents
One-Click Copy Trading — Mirror successful strategies automatically
Community Learning — Access collective trading intelligence

Architecture

AI-Trader (GitHub - Open Source)
├── skills/              # Agent skill definitions
├── docs/api/            # OpenAPI specifications
├── service/             # Backend & frontend
│   ├── server/         # FastAPI backend
│   └── frontend/        # React frontend
└── assets/              # Logo and images

Documentation

Document	Description
README.md	This file - Overview
docs/README_AGENT.md	Agent integration guide
docs/README_USER.md	User guide
skills/ai4trade/SKILL.md	Main skill file for agents
skills/copytrade/SKILL.md	Copy trading (follower)
skills/tradesync/SKILL.md	Trade sync (provider)
docs/api/openapi.yaml	Full API specification
docs/api/copytrade.yaml	Copy trading API spec

Quick Links

For AI Agents: Start with skills/ai4trade/SKILL.md
For Developers: See docs/README_AGENT.md for integration
For End Users: See docs/README_USER.md for platform usage

If this project helps you, please give us a Star!

AI-Trader - Empowering AI Agents in Financial Markets

Thanks for visiting ✨ AI-Trader!

ruvnet/RuView

π RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.

π RuView

Beta Software — Under active development. APIs and firmware may change. Known limitations:

ESP32-C3 and original ESP32 are not supported (single-core, insufficient for CSI DSP)

Single ESP32 deployments have limited spatial resolution — use 2+ nodes or add a Cognitum Seed for best results

Camera-free pose accuracy is limited (PCK@20 ≈ 2.5% with proxy labels) — camera ground-truth training targets 35%+ PCK@20; the pipeline is implemented, but the data-collection and evaluation phases (ADR-079 P7–P9) are still pending, so no measured camera-supervised PCK@20 has been published yet

Contributions and bug reports welcome at Issues.

See through walls with WiFi

Turn ordinary WiFi into a spatial intelligence / sensing system. Detect people, measure breathing and heart rate, track movement, and monitor rooms — through walls, in the dark, with no cameras or wearables. Just physics.

π RuView is a WiFi sensing platform that turns radio signals into spatial intelligence.

Every WiFi router already fills your space with radio waves. When people move, breathe, or even sit still, they disturb those waves in measurable ways. RuView captures these disturbances using Channel State Information (CSI) from low-cost ESP32 sensors and turns them into actionable data: who's there, what they're doing, and whether they're okay.

What it senses:

Presence and occupancy — detect people through walls, count them, track entries and exits
Vital signs — breathing rate and heart rate, contactless, while sleeping or sitting
Activity recognition — walking, sitting, gestures, falls — from temporal CSI patterns
Environment mapping — RF fingerprinting identifies rooms, detects moved furniture, spots new objects
Sleep quality — overnight monitoring with sleep stage classification and apnea screening

Built on RuVector and Cognitum Seed, RuView runs entirely on edge hardware — an ESP32 mesh (as low as $9 per node) paired with a Cognitum Seed for persistent memory, cryptographic attestation, and AI integration. No cloud, no cameras, no internet required.

The system learns each environment locally using spiking neural networks that adapt in under 30 seconds, with multi-frequency mesh scanning across 6 WiFi channels that uses your neighbors' routers as free radar illuminators. Every measurement is cryptographically attested via an Ed25519 witness chain.

RuView also supports pose estimation (17 COCO keypoints via the WiFlow architecture), trained entirely without cameras using 10 sensor signals — a technique pioneered from the original DensePose From WiFi research at Carnegie Mellon University.

Built for low-power edge applications

Edge modules are small programs that run directly on the ESP32 sensor — no internet needed, no cloud fees, instant response.

What How Speed

🦴 Pose estimation CSI subcarrier amplitude/phase → 17 COCO keypoints 171K emb/s (M4 Pro)

🫁 Breathing detection Bandpass 0.1-0.5 Hz → zero-crossing BPM 6-30 BPM

💓 Heart rate Bandpass 0.8-2.0 Hz → zero-crossing BPM 40-120 BPM

👤 Presence sensing Trained model + PIR fusion — 100% accuracy 0.012 ms latency

🧱 Through-wall Fresnel zone geometry + multipath modeling Up to 5m depth

🧠 Edge intelligence 8-dim feature vectors + RVF store on Cognitum Seed $140 total BOM

🎯 Camera-free training 10 sensor signals, no labels needed 84s on M4 Pro

📷 Camera-supervised training MediaPipe + ESP32 CSI → 35%+ PCK@20 target (ADR-079; eval phases pending) ~19 min on laptop (pipeline)

📡 Multi-frequency mesh Channel hopping across 6 bands, neighbor APs as illuminators 3x sensing bandwidth

🌐 3D point cloud (optional fusion) Camera depth (MiDaS) + WiFi CSI + mmWave radar → unified spatial model 22 ms pipeline · 19K+ points/frame

# Option 1: Docker (simulated data, no hardware needed)
docker pull ruvnet/wifi-densepose:latest
docker run -p 3000:3000 ruvnet/wifi-densepose:latest
# Open http://localhost:3000

# Option 2: Live sensing with ESP32-S3 hardware ($9)
# Flash firmware, provision WiFi, and start sensing:
python -m esptool --chip esp32s3 --port COM9 --baud 460800 \
  write_flash 0x0 bootloader.bin 0x8000 partition-table.bin \
  0xf000 ota_data_initial.bin 0x20000 esp32-csi-node.bin
python firmware/esp32-csi-node/provision.py --port COM9 \
  --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20

# Option 3: Full system with Cognitum Seed ($140)
# ESP32 streams CSI → bridge forwards to Seed for persistent storage + kNN + witness chain
node scripts/rf-scan.js --port 5006           # Live RF room scan
node scripts/snn-csi-processor.js --port 5006  # SNN real-time learning
node scripts/mincut-person-counter.js --port 5006  # Correct person counting

Note

CSI-capable hardware recommended. Presence, vital signs, through-wall sensing, and all advanced capabilities require Channel State Information (CSI) from an ESP32-S3 ($9) or research NIC. The Docker image runs with simulated data for evaluation. Consumer WiFi laptops provide RSSI-only presence detection.

Hardware options for live CSI capture:

Option Hardware Cost Full CSI Capabilities

ESP32 + Cognitum Seed (recommended) ESP32-S3 + Cognitum Seed ~$140 Yes Pose, breathing, heartbeat, motion, presence + persistent vector store, kNN search, witness chain, MCP proxy

ESP32 Mesh 3-6x ESP32-S3 + WiFi router ~$54 Yes Pose, breathing, heartbeat, motion, presence

Research NIC Intel 5300 / Atheros AR9580 ~$50-100 Yes Full CSI with 3x3 MIMO

Any WiFi Windows, macOS, or Linux laptop $0 No RSSI-only: coarse presence and motion

No hardware? Verify the signal processing pipeline with the deterministic reference signal: python archive/v1/data/proof/verify.py

Real-time pose skeleton from WiFi CSI signals — no cameras, no wearables

▶ Live Observatory Demo | ▶ Dual-Modal Pose Fusion Demo | ▶ Live 3D Point Cloud

The server is optional for visualization and aggregation — the ESP32 runs independently for presence detection, vital signs, and fall alerts.

Live ESP32 pipeline: Connect an ESP32-S3 node → run the sensing server → open the pose fusion demo for real-time dual-modal pose estimation (webcam + WiFi CSI). See ADR-059.

🔬 How It Works

WiFi routers flood every room with radio waves. When a person moves — or even breathes — those waves scatter differently. WiFi DensePose reads that scattering pattern and reconstructs what happened:

WiFi Router → radio waves pass through room → hit human body → scatter
    ↓
ESP32 mesh (4-6 nodes) captures CSI on channels 1/6/11 via TDM protocol
    ↓
Multi-Band Fusion: 3 channels × 56 subcarriers = 168 virtual subcarriers per link
    ↓
Multistatic Fusion: N×(N-1) links → attention-weighted cross-viewpoint embedding
    ↓
Coherence Gate: accept/reject measurements → stable for days without tuning
    ↓
Signal Processing: Hampel, SpotFi, Fresnel, BVP, spectrogram → clean features
    ↓
AI Backbone (RuVector): attention, graph algorithms, compression, field model
    ↓
Signal-Line Protocol (CRV): 6-stage gestalt → sensory → topology → coherence → search → model
    ↓
Neural Network: processed signals → 17 body keypoints + vital signs + room model
    ↓
Output: real-time pose, breathing, heart rate, room fingerprint, drift alerts

No training cameras required — the Self-Learning system (ADR-024) bootstraps from raw WiFi data alone. MERIDIAN (ADR-027) ensures the model works in any room, not just the one it trained in.

🏢 Use Cases & Applications

WiFi sensing works anywhere WiFi exists. No new hardware in most cases — just software on existing access points or a $8 ESP32 add-on. Because there are no cameras, deployments avoid privacy regulations (GDPR video, HIPAA imaging) by design.

Scaling: Each AP distinguishes ~3-5 people (56 subcarriers). Multi-AP multiplies linearly — a 4-AP retail mesh covers ~15-20 occupants. No hard software limit; the practical ceiling is signal physics.

	Why WiFi sensing wins	Traditional alternative
🔒	No video, no GDPR/HIPAA imaging rules	Cameras require consent, signage, data retention policies
🧱	Works through walls, shelving, debris	Cameras need line-of-sight per room
🌙	Works in total darkness	Cameras need IR or visible light
💰	$0-$8 per zone (existing WiFi or ESP32)	Camera systems: $200-$2,000 per zone
🔌	WiFi already deployed everywhere	PIR/radar sensors require new wiring per room

🏥 Everyday — Healthcare, retail, office, hospitality (commodity WiFi)

Use Case	What It Does	Hardware	Key Metric	Edge Module
Elderly care / assisted living	Fall detection, nighttime activity monitoring, breathing rate during sleep — no wearable compliance needed	1 ESP32-S3 per room ($8)	Fall alert <2s	Sleep Apnea, Gait Analysis
Hospital patient monitoring	Continuous breathing + heart rate for non-critical beds without wired sensors; nurse alert on anomaly	1-2 APs per ward	Breathing: 6-30 BPM	Respiratory Distress, Cardiac Arrhythmia
Emergency room triage	Automated occupancy count + wait-time estimation; detect patient distress (abnormal breathing) in waiting areas	Existing hospital WiFi	Occupancy accuracy >95%	Queue Length, Panic Motion
Retail occupancy & flow	Real-time foot traffic, dwell time by zone, queue length — no cameras, no opt-in, GDPR-friendly	Existing store WiFi + 1 ESP32	Dwell resolution ~1m	Customer Flow, Dwell Heatmap
Office space utilization	Which desks/rooms are actually occupied, meeting room no-shows, HVAC optimization based on real presence	Existing enterprise WiFi	Presence latency <1s	Meeting Room, HVAC Presence
Hotel & hospitality	Room occupancy without door sensors, minibar/bathroom usage patterns, energy savings on empty rooms	Existing hotel WiFi	15-30% HVAC savings	Energy Audit, Lighting Zones
Restaurants & food service	Table turnover tracking, kitchen staff presence, restroom occupancy displays — no cameras in dining areas	Existing WiFi	Queue wait ±30s	Table Turnover, Queue Length
Parking garages	Pedestrian presence in stairwells and elevators where cameras have blind spots; security alert if someone lingers	Existing WiFi	Through-concrete walls	Loitering, Elevator Count

🏟️ Specialized — Events, fitness, education, civic (CSI-capable hardware)

Use Case	What It Does	Hardware	Key Metric	Edge Module
Smart home automation	Room-level presence triggers (lights, HVAC, music) that work through walls — no dead zones, no motion-sensor timeouts	2-3 ESP32-S3 nodes ($24)	Through-wall range ~5m	HVAC Presence, Lighting Zones
Fitness & sports	Rep counting, posture correction, breathing cadence during exercise — no wearable, no camera in locker rooms	3+ ESP32-S3 mesh	Pose: 17 keypoints	Breathing Sync, Gait Analysis
Childcare & schools	Naptime breathing monitoring, playground headcount, restricted-area alerts — privacy-safe for minors	2-4 ESP32-S3 per zone	Breathing: ±1 BPM	Sleep Apnea, Perimeter Breach
Event venues & concerts	Crowd density mapping, crush-risk detection via breathing compression, emergency evacuation flow tracking	Multi-AP mesh (4-8 APs)	Density per m²	Customer Flow, Panic Motion
Stadiums & arenas	Section-level occupancy for dynamic pricing, concession staffing, emergency egress flow modeling	Enterprise AP grid	15-20 per AP mesh	Dwell Heatmap, Queue Length
Houses of worship	Attendance counting without facial recognition — privacy-sensitive congregations, multi-room campus tracking	Existing WiFi	Zone-level accuracy	Elevator Count, Energy Audit
Warehouse & logistics	Worker safety zones, forklift proximity alerts, occupancy in hazardous areas — works through shelving and pallets	Industrial AP mesh	Alert latency <500ms	Forklift Proximity, Confined Space
Civic infrastructure	Public restroom occupancy (no cameras possible), subway platform crowding, shelter headcount during emergencies	Municipal WiFi + ESP32	Real-time headcount	Customer Flow, Loitering
Museums & galleries	Visitor flow heatmaps, exhibit dwell time, crowd bottleneck alerts — no cameras near artwork (flash/theft risk)	Existing WiFi	Zone dwell ±5s	Dwell Heatmap, Shelf Engagement

🤖 Robotics & Industrial — Autonomous systems, manufacturing, android spatial awareness

WiFi sensing gives robots and autonomous systems a spatial awareness layer that works where LIDAR and cameras fail — through dust, smoke, fog, and around corners. The CSI signal field acts as a "sixth sense" for detecting humans in the environment without requiring line-of-sight.

Use Case	What It Does	Hardware	Key Metric	Edge Module
Cobot safety zones	Detect human presence near collaborative robots — auto-slow or stop before contact, even behind obstructions	2-3 ESP32-S3 per cell	Presence latency <100ms	Forklift Proximity, Perimeter Breach
Warehouse AMR navigation	Autonomous mobile robots sense humans around blind corners, through shelving racks — no LIDAR occlusion	ESP32 mesh along aisles	Through-shelf detection	Forklift Proximity, Loitering
Android / humanoid spatial awareness	Ambient human pose sensing for social robots — detect gestures, approach direction, and personal space without cameras always on	Onboard ESP32-S3 module	17-keypoint pose	Gesture Language, Emotion Detection
Manufacturing line monitoring	Worker presence at each station, ergonomic posture alerts, headcount for shift compliance — works through equipment	Industrial AP per zone	Pose + breathing	Confined Space, Gait Analysis
Construction site safety	Exclusion zone enforcement around heavy machinery, fall detection from scaffolding, personnel headcount	Ruggedized ESP32 mesh	Alert <2s, through-dust	Panic Motion, Structural Vibration
Agricultural robotics	Detect farm workers near autonomous harvesters in dusty/foggy field conditions where cameras are unreliable	Weatherproof ESP32 nodes	Range ~10m open field	Forklift Proximity, Rain Detection
Drone landing zones	Verify landing area is clear of humans — WiFi sensing works in rain, dust, and low light where downward cameras fail	Ground ESP32 nodes	Presence: >95% accuracy	Perimeter Breach, Tailgating
Clean room monitoring	Personnel tracking without cameras (particle contamination risk from camera fans) — gown compliance via pose	Existing cleanroom WiFi	No particulate emission	Clean Room, Livestock Monitor

🔥 Extreme — Through-wall, disaster, defense, underground

These scenarios exploit WiFi's ability to penetrate solid materials — concrete, rubble, earth — where no optical or infrared sensor can reach. The WiFi-Mat disaster module (ADR-001) is specifically designed for this tier.

Use Case	What It Does	Hardware	Key Metric	Edge Module
Search & rescue (WiFi-Mat)	Detect survivors through rubble/debris via breathing signature, START triage color classification, 3D localization	Portable ESP32 mesh + laptop	Through 30cm concrete	Respiratory Distress, Seizure Detection
Firefighting	Locate occupants through smoke and walls before entry; breathing detection confirms life signs remotely	Portable mesh on truck	Works in zero visibility	Sleep Apnea, Panic Motion
Prison & secure facilities	Cell occupancy verification, distress detection (abnormal vitals), perimeter sensing — no camera blind spots	Dedicated AP infrastructure	24/7 vital signs	Cardiac Arrhythmia, Loitering
Military / tactical	Through-wall personnel detection, room clearing confirmation, hostage vital signs at standoff distance	Directional WiFi + custom FW	Range: 5m through wall	Perimeter Breach, Weapon Detection
Border & perimeter security	Detect human presence in tunnels, behind fences, in vehicles — passive sensing, no active illumination to reveal position	Concealed ESP32 mesh	Passive / covert	Perimeter Breach, Tailgating
Mining & underground	Worker presence in tunnels where GPS/cameras fail, breathing detection after collapse, headcount at safety points	Ruggedized ESP32 mesh	Through rock/earth	Confined Space, Respiratory Distress
Maritime & naval	Below-deck personnel tracking through steel bulkheads (limited range, requires tuning), man-overboard detection	Ship WiFi + ESP32	Through 1-2 bulkheads	Structural Vibration, Panic Motion
Wildlife research	Non-invasive animal activity monitoring in enclosures or dens — no light pollution, no visual disturbance	Weatherproof ESP32 nodes	Zero light emission	Livestock Monitor, Dream Stage

🧩 Edge Intelligence (ADR-041) — 60 WASM modules across 13 categories, all implemented (609 tests)

Small programs that run directly on the ESP32 sensor — no internet needed, no cloud fees, instant response. Each module is a tiny WASM file (5-30 KB) that you upload to the device over-the-air. It reads WiFi signal data and makes decisions locally in under 10 ms. ADR-041 defines 60 modules across 13 categories — all 60 are implemented with 609 tests passing.

	Category	Examples
🏥	Medical & Health	Sleep apnea detection, cardiac arrhythmia, gait analysis, seizure detection
🔐	Security & Safety	Intrusion detection, perimeter breach, loitering, panic motion
🏢	Smart Building	Zone occupancy, HVAC control, elevator counting, meeting room tracking
🛒	Retail & Hospitality	Queue length, dwell heatmaps, customer flow, table turnover
🏭	Industrial	Forklift proximity, confined space monitoring, structural vibration
🔮	Exotic & Research	Sleep staging, emotion detection, sign language, breathing sync
📡	Signal Intelligence	Cleans and sharpens raw WiFi signals — focuses on important regions, filters noise, fills in missing data, and tracks which person is which
🧠	Adaptive Learning	The sensor learns new gestures and patterns on its own over time — no cloud needed, remembers what it learned even after updates
🗺️	Spatial Reasoning	Figures out where people are in a room, which zones matter most, and tracks movement across areas using graph-based spatial logic
⏱️	Temporal Analysis	Learns daily routines, detects when patterns break (someone didn't get up), and verifies safety rules are being followed over time
🛡️	AI Security	Detects signal replay attacks, WiFi jamming, injection attempts, and flags abnormal behavior that could indicate tampering
⚛️	Quantum-Inspired	Uses quantum-inspired math to map room-wide signal coherence and search for optimal sensor configurations
🤖	Autonomous & Exotic	Self-managing sensor mesh — auto-heals dropped nodes, plans its own actions, and explores experimental signal representations

All implemented modules are no_std Rust, share a common utility library, and talk to the host through a 12-function API. Full documentation: Edge Modules Guide. See the complete implemented module list below.

🧩 Edge Intelligence — All 65 Modules Implemented (ADR-041 complete)

All 60 modules are implemented, tested (609 tests passing), and ready to deploy. They compile to wasm32-unknown-unknown, run on ESP32-S3 via WASM3, and share a common utility library. Source: crates/wifi-densepose-wasm-edge/src/

Core modules (ADR-040 flagship + early implementations):

Module	File	What It Does
Gesture Classifier	`gesture.rs`	DTW template matching for hand gestures
Coherence Filter	`coherence.rs`	Phase coherence gating for signal quality
Adversarial Detector	`adversarial.rs`	Detects physically impossible signal patterns
Intrusion Detector	`intrusion.rs`	Human vs non-human motion classification
Occupancy Counter	`occupancy.rs`	Zone-level person counting
Vital Trend	`vital_trend.rs`	Long-term breathing and heart rate trending
RVF Parser	`rvf.rs`	RVF container format parsing

Vendor-integrated modules (24 modules, ADR-041 Category 7):

📡 Signal Intelligence — Real-time CSI analysis and feature extraction

Module	File	What It Does	Budget
Flash Attention	`sig_flash_attention.rs`	Tiled attention over 8 subcarrier groups — finds spatial focus regions and entropy	S (<5ms)
Coherence Gate	`sig_coherence_gate.rs`	Z-score phasor gating with hysteresis: Accept / PredictOnly / Reject / Recalibrate	L (<2ms)
Temporal Compress	`sig_temporal_compress.rs`	3-tier adaptive quantization (8-bit hot / 5-bit warm / 3-bit cold)	L (<2ms)
Sparse Recovery	`sig_sparse_recovery.rs`	ISTA L1 reconstruction for dropped subcarriers	H (<10ms)
Person Match	`sig_mincut_person_match.rs`	Hungarian-lite bipartite assignment for multi-person tracking	S (<5ms)
Optimal Transport	`sig_optimal_transport.rs`	Sliced Wasserstein-1 distance with 4 projections	L (<2ms)

🧠 Adaptive Learning — On-device learning without cloud connectivity

Module	File	What It Does	Budget
DTW Gesture Learn	`lrn_dtw_gesture_learn.rs`	User-teachable gesture recognition — 3-rehearsal protocol, 16 templates	S (<5ms)
Anomaly Attractor	`lrn_anomaly_attractor.rs`	4D dynamical system attractor classification with Lyapunov exponents	H (<10ms)
Meta Adapt	`lrn_meta_adapt.rs`	Hill-climbing self-optimization with safety rollback	L (<2ms)
EWC Lifelong	`lrn_ewc_lifelong.rs`	Elastic Weight Consolidation — remembers past tasks while learning new ones	S (<5ms)

🗺️ Spatial Reasoning — Location, proximity, and influence mapping

Module	File	What It Does	Budget
PageRank Influence	`spt_pagerank_influence.rs`	4x4 cross-correlation graph with power iteration PageRank	L (<2ms)
Micro HNSW	`spt_micro_hnsw.rs`	64-vector navigable small-world graph for nearest-neighbor search	S (<5ms)
Spiking Tracker	`spt_spiking_tracker.rs`	32 LIF neurons + 4 output zone neurons with STDP learning	S (<5ms)

⏱️ Temporal Analysis — Activity patterns, logic verification, autonomous planning

Module	File	What It Does	Budget
Pattern Sequence	`tmp_pattern_sequence.rs`	Activity routine detection and deviation alerts	S (<5ms)
Temporal Logic Guard	`tmp_temporal_logic_guard.rs`	LTL formula verification on CSI event streams	S (<5ms)
GOAP Autonomy	`tmp_goap_autonomy.rs`	Goal-Oriented Action Planning for autonomous module management	S (<5ms)

🛡️ AI Security — Tamper detection and behavioral anomaly profiling

Module	File	What It Does	Budget
Prompt Shield	`ais_prompt_shield.rs`	FNV-1a replay detection, injection detection (10x amplitude), jamming (SNR)	L (<2ms)
Behavioral Profiler	`ais_behavioral_profiler.rs`	6D behavioral profile with Mahalanobis anomaly scoring	S (<5ms)

⚛️ Quantum-Inspired — Quantum computing metaphors applied to CSI analysis

Module	File	What It Does	Budget
Quantum Coherence	`qnt_quantum_coherence.rs`	Bloch sphere mapping, Von Neumann entropy, decoherence detection	S (<5ms)
Interference Search	`qnt_interference_search.rs`	16 room-state hypotheses with Grover-inspired oracle + diffusion	S (<5ms)

🤖 Autonomous Systems — Self-governing and self-healing behaviors

Module	File	What It Does	Budget
Psycho-Symbolic	`aut_psycho_symbolic.rs`	16-rule forward-chaining knowledge base with contradiction detection	S (<5ms)
Self-Healing Mesh	`aut_self_healing_mesh.rs`	8-node mesh with health tracking, degradation/recovery, coverage healing	S (<5ms)

🔮 Exotic (Vendor) — Novel mathematical models for CSI interpretation

Module	File	What It Does	Budget
Time Crystal	`exo_time_crystal.rs`	Autocorrelation subharmonic detection in 256-frame history	S (<5ms)
Hyperbolic Space	`exo_hyperbolic_space.rs`	Poincare ball embedding with 32 reference locations, hyperbolic distance	S (<5ms)

🏥 Medical & Health (Category 1) — Contactless health monitoring

Module	File	What It Does	Budget
Sleep Apnea	`med_sleep_apnea.rs`	Detects breathing pauses during sleep	S (<5ms)
Cardiac Arrhythmia	`med_cardiac_arrhythmia.rs`	Monitors heart rate for irregular rhythms	S (<5ms)
Respiratory Distress	`med_respiratory_distress.rs`	Alerts on abnormal breathing patterns	S (<5ms)
Gait Analysis	`med_gait_analysis.rs`	Tracks walking patterns and detects changes	S (<5ms)
Seizure Detection	`med_seizure_detect.rs`	6-state machine for tonic-clonic seizure recognition	S (<5ms)

🔐 Security & Safety (Category 2) — Perimeter and threat detection

Module	File	What It Does	Budget
Perimeter Breach	`sec_perimeter_breach.rs`	Detects boundary crossings with approach/departure	S (<5ms)
Weapon Detection	`sec_weapon_detect.rs`	Metal anomaly detection via CSI amplitude shifts	S (<5ms)
Tailgating	`sec_tailgating.rs`	Detects unauthorized follow-through at access points	S (<5ms)
Loitering	`sec_loitering.rs`	Alerts when someone lingers too long in a zone	S (<5ms)
Panic Motion	`sec_panic_motion.rs`	Detects fleeing, struggling, or panic movement	S (<5ms)

🏢 Smart Building (Category 3) — Automation and energy efficiency

Module	File	What It Does	Budget
HVAC Presence	`bld_hvac_presence.rs`	Occupancy-driven HVAC control with departure countdown	S (<5ms)
Lighting Zones	`bld_lighting_zones.rs`	Auto-dim/off lighting based on zone activity	S (<5ms)
Elevator Count	`bld_elevator_count.rs`	Counts people entering/leaving with overload warning	S (<5ms)
Meeting Room	`bld_meeting_room.rs`	Tracks meeting lifecycle: start, headcount, end, availability	S (<5ms)
Energy Audit	`bld_energy_audit.rs`	Tracks after-hours usage and room utilization rates	S (<5ms)

🛒 Retail & Hospitality (Category 4) — Customer insights without cameras

Module	File	What It Does	Budget
Queue Length	`ret_queue_length.rs`	Estimates queue size and wait times	S (<5ms)
Dwell Heatmap	`ret_dwell_heatmap.rs`	Shows where people spend time (hot/cold zones)	S (<5ms)
Customer Flow	`ret_customer_flow.rs`	Counts ins/outs and tracks net occupancy	S (<5ms)
Table Turnover	`ret_table_turnover.rs`	Restaurant table lifecycle: seated, dining, vacated	S (<5ms)
Shelf Engagement	`ret_shelf_engagement.rs`	Detects browsing, considering, and reaching for products	S (<5ms)

🏭 Industrial & Specialized (Category 5) — Safety and compliance

Module	File	What It Does	Budget
Forklift Proximity	`ind_forklift_proximity.rs`	Warns when people get too close to vehicles	S (<5ms)
Confined Space	`ind_confined_space.rs`	OSHA-compliant worker monitoring with extraction alerts	S (<5ms)
Clean Room	`ind_clean_room.rs`	Occupancy limits and turbulent motion detection	S (<5ms)
Livestock Monitor	`ind_livestock_monitor.rs`	Animal presence, stillness, and escape alerts	S (<5ms)
Structural Vibration	`ind_structural_vibration.rs`	Seismic events, mechanical resonance, structural drift	S (<5ms)

🔮 Exotic & Research (Category 6) — Experimental sensing applications

Module	File	What It Does	Budget
Dream Stage	`exo_dream_stage.rs`	Contactless sleep stage classification (wake/light/deep/REM)	S (<5ms)
Emotion Detection	`exo_emotion_detect.rs`	Arousal, stress, and calm detection from micro-movements	S (<5ms)
Gesture Language	`exo_gesture_language.rs`	Sign language letter recognition via WiFi	S (<5ms)
Music Conductor	`exo_music_conductor.rs`	Tempo and dynamic tracking from conducting gestures	S (<5ms)
Plant Growth	`exo_plant_growth.rs`	Monitors plant growth, circadian rhythms, wilt detection	S (<5ms)
Ghost Hunter	`exo_ghost_hunter.rs`	Environmental anomaly classification (draft/insect/wind/unknown)	S (<5ms)
Rain Detection	`exo_rain_detect.rs`	Detects rain onset, intensity, and cessation via signal scatter	S (<5ms)
Breathing Sync	`exo_breathing_sync.rs`	Detects synchronized breathing between multiple people	S (<5ms)

🧠 Self-Learning WiFi AI (ADR-024) — Adaptive recognition, self-optimization, and intelligent anomaly detection

Every WiFi signal that passes through a room creates a unique fingerprint of that space. WiFi-DensePose already reads these fingerprints to track people, but until now it threw away the internal "understanding" after each reading. The Self-Learning WiFi AI captures and preserves that understanding as compact, reusable vectors — and continuously optimizes itself for each new environment.

What it does in plain terms:

Turns any WiFi signal into a 128-number "fingerprint" that uniquely describes what's happening in a room
Learns entirely on its own from raw WiFi data — no cameras, no labeling, no human supervision needed
Recognizes rooms, detects intruders, identifies people, and classifies activities using only WiFi
Runs on an $8 ESP32 chip (the entire model fits in 55 KB of memory)
Produces both body pose tracking AND environment fingerprints in a single computation

Key Capabilities

What	How it works	Why it matters
Self-supervised learning	The model watches WiFi signals and teaches itself what "similar" and "different" look like, without any human-labeled data	Deploy anywhere — just plug in a WiFi sensor and wait 10 minutes
Room identification	Each room produces a distinct WiFi fingerprint pattern	Know which room someone is in without GPS or beacons
Anomaly detection	An unexpected person or event creates a fingerprint that doesn't match anything seen before	Automatic intrusion and fall detection as a free byproduct
Person re-identification	Each person disturbs WiFi in a slightly different way, creating a personal signature	Track individuals across sessions without cameras
Environment adaptation	MicroLoRA adapters (1,792 parameters per room) fine-tune the model for each new space	Adapts to a new room with minimal data — 93% less than retraining from scratch
Memory preservation	EWC++ regularization remembers what was learned during pretraining	Switching to a new task doesn't erase prior knowledge
Hard-negative mining	Training focuses on the most confusing examples to learn faster	Better accuracy with the same amount of training data

Architecture

WiFi Signal [56 channels] → Transformer + Graph Neural Network
                                  ├→ 128-dim environment fingerprint (for search + identification)
                                  └→ 17-joint body pose (for human tracking)

Quick Start

# Step 1: Learn from raw WiFi data (no labels needed)
cargo run -p wifi-densepose-sensing-server -- --pretrain --dataset data/csi/ --pretrain-epochs 50

# Step 2: Fine-tune with pose labels for full capability
cargo run -p wifi-densepose-sensing-server -- --train --dataset data/mmfi/ --epochs 100 --save-rvf model.rvf

# Step 3: Use the model — extract fingerprints from live WiFi
cargo run -p wifi-densepose-sensing-server -- --model model.rvf --embed

# Step 4: Search — find similar environments or detect anomalies
cargo run -p wifi-densepose-sensing-server -- --model model.rvf --build-index env

Training Modes

Mode	What you need	What you get
Self-Supervised	Just raw WiFi data	A model that understands WiFi signal structure
Supervised	WiFi data + body pose labels	Full pose tracking + environment fingerprints
Cross-Modal	WiFi data + camera footage	Fingerprints aligned with visual understanding

Fingerprint Index Types

Index	What it stores	Real-world use
`env_fingerprint`	Average room fingerprint	"Is this the kitchen or the bedroom?"
`activity_pattern`	Activity boundaries	"Is someone cooking, sleeping, or exercising?"
`temporal_baseline`	Normal conditions	"Something unusual just happened in this room"
`person_track`	Individual movement signatures	"Person A just entered the living room"

Model Size

Component	Parameters	Memory (on ESP32)
Transformer backbone	~28,000	28 KB
Embedding projection head	~25,000	25 KB
Per-room MicroLoRA adapter	~1,800	2 KB
Total	~55,000	55 KB (of 520 KB available)

The self-learning system builds on the AI Backbone (RuVector) signal-processing layer — attention, graph algorithms, and compression — adding contrastive learning on top.

See docs/adr/ADR-024-contrastive-csi-embedding-model.md for full architectural details.

🧩 Claude Code & Codex Plugin

RuView ships a Claude Code plugin (and Codex prompt mirror) that wraps the whole workflow — onboarding, ESP32 setup, configuration, sensing apps, model training, advanced multistatic sensing, CLI/API/WASM, mmWave radar, and witness verification — as 9 skills, 7 /ruview-* commands, and 3 agents. It lives in plugins/ruview/; the marketplace manifest is .claude-plugin/marketplace.json at the repo root.

# In Claude Code — add this repo as a plugin marketplace, then install:
/plugin marketplace add ruvnet/RuView
/plugin install ruview@ruview

# Or try it for one session without installing (from a local clone of the repo):
claude --plugin-dir ./plugins/ruview

# Then, in Claude Code:
#   /ruview-start      → onboarding (Docker demo / repo build / live ESP32)
#   /ruview-flash      → build + flash ESP32 firmware
#   /ruview-provision  → provision WiFi creds, sink IP, channel/MAC, mesh slots
#   /ruview-app        → run a sensing application (presence / vitals / pose / sleep / MAT / point cloud)
#   /ruview-train      → train / evaluate / publish a model (incl. GPU on GCloud)
#   /ruview-advanced   → multistatic / tomography / cross-viewpoint / mesh-security
#   /ruview-verify     → tests + deterministic proof + witness bundle

Codex (OpenAI CLI): cp plugins/ruview/codex/prompts/*.md ~/.codex/prompts/ — the seven /ruview-* commands are mirrored as Codex prompts; plugins/ruview/codex/AGENTS.md carries the project rules. See plugins/ruview/codex/README.md.

Verify the plugin structure: bash plugins/ruview/scripts/smoke.sh. Full details: plugins/ruview/README.md.

📖 Documentation

Document	Description
User Guide	Step-by-step guide: installation, first run, API usage, hardware setup, training
Build Guide	Building from source (Rust and Python)
Claude Code / Codex Plugin	The `ruview` plugin + marketplace — skills, `/ruview-*` commands, agents, and the Codex prompt mirror
Architecture Decisions	96 ADRs — why each technical choice was made, organized by domain (hardware, signal processing, ML, platform, infrastructure)
Domain Models	8 DDD models (RuvSense, Signal Processing, Training Pipeline, Hardware Platform, Sensing Server, WiFi-Mat, CHCI, rvCSI) — bounded contexts, aggregates, domain events, and ubiquitous language
rvCSI — edge RF sensing runtime	Rust-first / TypeScript-accessible / hardware-abstracted CSI runtime: multi-source ingestion (incl. real nexmon_csi `.pcap` from a Raspberry Pi 5 / Pi 4 / Pi 3B+ — CYW43455 / BCM43455c0) → validation → DSP → typed events → RuVector RF memory (ADR-095, ADR-096, domain model). Now its own repo — `ruvnet/rvcsi` — vendored here under `vendor/rvcsi`; 9 `rvcsi-*` crates on crates.io, `@ruv/rvcsi` on npm, plus a Claude Code plugin.
Desktop App	WIP — Tauri v2 desktop app for node management, OTA updates, WASM deployment, and mesh visualization
Medical Examples	Contactless blood pressure, heart rate, breathing rate via 60 GHz mmWave radar — $15 hardware, no wearable
Extended Documentation	Latest additions, key features, installation, quick start, signal processing, training, CLI, testing, deployment, and changelog

📄 License

MIT License — see LICENSE for details.

📞 Support

GitHub Issues | Discussions | PyPI

WiFi DensePose — Privacy-preserving human pose estimation through WiFi signals.

apernet/hysteria

Hysteria is a powerful, lightning fast and censorship resistant proxy.

Get Started

中文文档

Hysteria 1.x (legacy)

🛠️ Jack of all trades

Wide range of modes including SOCKS5, HTTP Proxy, TCP/UDP Forwarding, Linux TProxy, TUN - with more features being added constantly.

⚡ Blazing fast

Powered by a customized QUIC protocol, Hysteria is designed to deliver unparalleled performance over unreliable and lossy networks.

✊ Censorship resistant

The protocol masquerades as standard HTTP/3 traffic, making it very difficult for censors to detect and block without widespread collateral damage.

💻 Cross-platform

We have builds for every major platform and architecture. Deploy anywhere & use everywhere. Not to mention the long list of 3rd party apps.

🔗 Easy integration

With built-in support for custom authentication, traffic statistics & access control, Hysteria is easy to integrate into your infrastructure.

🤗 Chill and supportive

We have well-documented specifications and code for developers to contribute and/or build their own apps. And a helpful community, too.

If you find Hysteria useful, consider giving it a ⭐️!

millionco/react-doctor

Your agent writes bad React. This catches it

Your agent writes bad React, this catches it.

One command scans your codebase and outputs a 0 to 100 health score with actionable diagnostics.

Works with Next.js, Vite, and React Native.

See it in action →

Install

Run this at your project root:

npx -y react-doctor@latest .

You'll get a score (75+ Great, 50 to 74 Needs work, under 50 Critical) and a list of issues across state & effects, performance, architecture, security, accessibility, and dead code. Rules toggle automatically based on your framework and React version.

https://github.com/user-attachments/assets/07cc88d9-9589-44c3-aa73-5d603cb1c570

Install for your coding agent

Teach your coding agent React best practices so it stops writing the bad code in the first place.

npx -y react-doctor@latest install

You'll be prompted to pick which detected agents to install for. Pass --yes to skip prompts.

Works with Claude Code, Cursor, Codex, OpenCode, and 50+ other agents.

GitHub Actions

A composite action ships with this repository. Drop it into .github/workflows/react-doctor.yml:

name: React Doctor

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  pull-requests: write # required to post PR comments

jobs:
  react-doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0 # required for `diff`
      - uses: millionco/react-doctor@main
        with:
          diff: main
          github-token: ${{ secrets.GITHUB_TOKEN }}

When github-token is set on pull_request events, findings are posted (and updated) as a PR comment. The action also exposes a score output (0–100) you can use in subsequent steps.

Inputs: directory, verbose, project, diff, github-token, fail-on (error / warning / none), offline, node-version. See action.yml for full descriptions.

Prefer not to add a marketplace action? The bare npx form works too:

- run: npx -y react-doctor@latest --fail-on warning

Configuration

Create a react-doctor.config.json in your project root:

{
  "ignore": {
    "rules": ["react/no-danger", "jsx-a11y/no-autofocus"],
    "files": ["src/generated/**"],
    "overrides": [
      {
        "files": ["components/modules/diff/**"],
        "rules": ["react-doctor/no-array-index-as-key", "react-doctor/no-render-in-render"]
      },
      {
        "files": ["components/search/HighlightedSnippet.tsx"],
        "rules": ["react/no-danger"]
      }
    ]
  }
}

Three nested keys, three layers of granularity — pick the narrowest one that fits:

ignore.rules silences a rule across the whole codebase.
ignore.files silences every rule on the matched files (use sparingly — it loses coverage for unrelated rules).
ignore.overrides silences only the listed rules on the matched files, leaving every other rule active. This is what you want when a single file (or glob) legitimately needs an exemption from one or two rules but should still be scanned for everything else.

You can also use the "reactDoctor" key in package.json. CLI flags always override config values.

React Doctor respects .gitignore, .eslintignore, .oxlintignore, .prettierignore, and linguist-vendored / linguist-generated annotations in .gitattributes. Inline // eslint-disable* and // oxlint-disable* comments are honored too.

If you have a JSON oxlint or eslint config (.oxlintrc.json or .eslintrc.json), its rules get merged into the scan automatically and count toward the score. Set adoptExistingLintConfig: false to opt out.

Surface controls (CLI, PR comments, score, CI failure)

Diagnostics flow through four independent surfaces — cli, prComment, score, and ciFailure — and each one can be tuned per tag, category, or rule id. By default the design tag (Tailwind shorthand cleanup like w-5 h-5 → size-5, pure-black backgrounds, gradient text, …) stays visible on the local CLI but is excluded from the PR comment, the score, and the --fail-on gate so style cleanup can't dilute meaningful React findings:

{
  "surfaces": {
    "prComment": {
      "includeTags": ["design"],
      "excludeCategories": ["Performance"]
    },
    "score": { "includeRules": ["react-doctor/design-no-redundant-size-axes"] },
    "ciFailure": { "excludeTags": ["test-noise"] }
  }
}

Each surface accepts includeTags, excludeTags, includeCategories, excludeCategories, includeRules, and excludeRules. Include wins over exclude when both match. Run the CLI with --pr-comment (the GitHub Action passes it automatically when github-token is set) to apply the prComment surface to the printed output destined for sticky PR comments.

Optional companion plugins

When the following ESLint plugins are installed in the scanned project (or hoisted in your monorepo), React Doctor folds their rules into the same scan. Both are listed as optional peer dependencies — install only what you want.

Plugin	Adds	Namespace
`eslint-plugin-react-hooks` (v6 or v7)	The React Compiler frontend's correctness rules — fired when a React Compiler is detected in the project.	`react-hooks-js/*`
`eslint-plugin-react-you-might-not-need-an-effect` (v0.10+)	Complementary effects-as-anti-pattern rules (`no-derived-state`, `no-chain-state-updates`, `no-event-handler`, `no-pass-data-to-parent`, …) that run alongside React Doctor's native State & Effects rules.	`effect/*`

Inline suppressions

// react-doctor-disable-next-line react-doctor/no-cascading-set-state
useEffect(() => {
  setA(value);
  setB(value);
}, [value]);

When two rules fire on the same line, you have two equivalent options. Comma-separate the rule ids on a single comment:

// react-doctor-disable-next-line react-doctor/rerender-state-only-in-handlers, react-doctor/no-derived-useState
const [localSearch, setLocalSearch] = useState(searchQuery);

Or stack one comment per rule directly above the diagnostic. Stacked comments are honored as long as nothing but other react-doctor-disable-next-line comments sits between them and the target line:

// react-doctor-disable-next-line react-doctor/rerender-state-only-in-handlers
// react-doctor-disable-next-line react-doctor/no-derived-useState
const [localSearch, setLocalSearch] = useState(searchQuery);

A code line between stacked comments breaks the chain: only the comment immediately above the diagnostic (and any contiguous react-doctor-disable-next-line comments stacked on top of it) is honored. If a comment looks adjacent but the rule still fires, run react-doctor --explain <file:line> — it reports whether a nearby suppression was found, what rules it covers, and why it didn't apply.

Block comments work inside JSX:

{/* react-doctor-disable-next-line react/no-danger */}
<div dangerouslySetInnerHTML={{ __html }} />

For multi-line JSX, putting the comment immediately above the opening tag covers the entire attribute list (matching ESLint convention).

Lint plugin (standalone)

The same rule set ships as both an oxlint plugin and an ESLint plugin, so you can wire it into whichever lint engine your project already runs. These are published as separate packages, so you can install just the lint integration without pulling in the full CLI.

oxlint in .oxlintrc.json (install oxlint-plugin-react-doctor):

{
  "jsPlugins": [{ "name": "react-doctor", "specifier": "oxlint-plugin-react-doctor" }],
  "rules": {
    "react-doctor/no-fetch-in-effect": "warn",
    "react-doctor/no-derived-state-effect": "warn",
  },
}

ESLint flat config (install eslint-plugin-react-doctor):

import reactDoctor from "eslint-plugin-react-doctor";

export default [
  reactDoctor.configs.recommended,
  reactDoctor.configs.next,
  reactDoctor.configs["react-native"],
  reactDoctor.configs["tanstack-start"],
  reactDoctor.configs["tanstack-query"],
];

The full rule list lives in packages/oxlint-plugin-react-doctor/src/plugin/rules.

CLI reference

Usage: react-doctor [directory] [options]

Options:
  -v, --version           display the version number
  --no-lint               skip linting
  --verbose               show every rule and per-file details (default shows top 3 rules)
  --score                 output only the score
  --json                  output a single structured JSON report
  -y, --yes               skip prompts, scan all workspace projects
  --full                  skip prompts, always run a full scan
  --project <name>        select workspace project (comma-separated for multiple)
  --diff [base]           scan only files changed vs base branch
  --staged                scan only staged files (for pre-commit hooks)
  --offline               skip the score API and share URL (no score shown)
  --fail-on <level>       exit with error on diagnostics: error, warning, none
  --annotations           output diagnostics as GitHub Actions annotations
  --pr-comment            tune CLI output for sticky PR comments (drops design
                          cleanup from the printed list and fail-on gate)
  --explain <file:line>   diagnose why a rule fired or why a suppression didn't apply
  --why <file:line>       alias for --explain
  -h, --help              display help

When a suppression isn't working, --explain <file:line> (or its alias --why <file:line>) reports what the scanner sees at that location, including why a nearby react-doctor-disable-next-line didn't apply. The diagnosis distinguishes the common failure modes — adjacent comment for a different rule (use the comma form), a code line between the comment and the diagnostic (the chain is broken), or no nearby suppression at all. The same hint surfaces inline with --verbose for every flagged site, and in --json output as diagnostic.suppressionHint, so a single scan doubles as a suppression audit without a separate flag.

--json produces a parsable object on stdout with all human-readable output suppressed. Errors still produce a JSON object with ok: false, so stdout is always a valid document.

Config keys

Key	Type	Default
`ignore.rules`	`string[]`	`[]`
`ignore.files`	`string[]`	`[]`
`ignore.overrides`	`{ files, rules? }[]`	`[]`
`lint`	`boolean`	`true`
`verbose`	`boolean`	`false`
`diff`	`boolean \| string`
`failOn`	`"error" \| "warning" \| "none"`	`"none"`
`customRulesOnly`	`boolean`	`false`
`share`	`boolean`	`true`
`offline`	`boolean`	`false`
`textComponents`	`string[]`	`[]`
`rawTextWrapperComponents`	`string[]`	`[]`
`serverAuthFunctionNames`	`string[]`	`[]`
`respectInlineDisables`	`boolean`	`true`
`adoptExistingLintConfig`	`boolean`	`true`
`ignore.tags`	`string[]`	`[]`

textComponents is the broad escape hatch for rn-no-raw-text — list components that themselves behave like React Native's <Text> (custom Typography, NativeTabs.Trigger.Label, etc.) and the rule will treat them as text containers regardless of what their children look like.

rawTextWrapperComponents is the narrower option for components that are not text elements but safely route string-only children through an internal <Text> (e.g. heroui-native's Button, which stringifies its children and renders them through a ButtonLabel). Listed wrappers suppress rn-no-raw-text only when their children are entirely stringifiable. A wrapper with mixed children — e.g. <Button>Save<Icon /></Button> — still reports because the wrapper can't safely route raw text alongside a sibling JSX element.

serverAuthFunctionNames teaches server-auth-actions about custom auth guards your codebase wraps around its auth library (e.g. requireWorkspaceMember, ensureSignedIn). Listed names are accepted as a valid top-of-action auth check whether called bare (requireWorkspaceMember()) or as a member (guards.requireWorkspaceMember()), and — unlike the built-in default list — are treated as distinctive so the receiver is not re-validated.

ignore.tags suppresses entire categories of rules by tag. For example, "tags": ["design"] disables all opinionated design rules (gradient text, pure black backgrounds, side tab borders, default Tailwind palettes). Available tags: "design".

offline skips the score API entirely — no score is shown and no share URL is generated. Automatically enabled in CI environments (GitHub Actions, GitLab CI, CircleCI) so CI runs don't depend on the network.

React Native rules in mixed monorepos

rn-* rules respect per-package boundaries automatically. In a mixed React Native + web monorepo (apps/mobile alongside apps/web / apps/vite-app / packages/storybook / apps/docs), every rn-* rule walks up to the file's nearest package.json before running:

Packages that declare react-native, react-native-tvos, expo, expo-router, @expo/*, react-native-windows, react-native-macos, anything under the @react-native/ or @react-native- namespaces (@react-native-firebase/app, @react-native-async-storage/async-storage, …), or Metro's top-level "react-native" resolution field → rules ON.
Packages that declare a web-only framework (next, vite, react-scripts, gatsby, @remix-run/*, @docusaurus/*, @storybook/*, or plain react-dom without an RN sibling) → rules OFF.
Packages with no clear local signal → fall back to the project-level framework detection.

File extensions override the package classification when they're unambiguous: *.web.tsx / *.web.jsx are always skipped (Metro resolves these only against react-native-web); *.ios.tsx / *.android.tsx / *.native.tsx are always scanned (mobile-only).

The detection is bidirectional: a web-rooted monorepo (root package.json declares next or vite) still loads the rn-* rules when any workspace targets React Native — the file-level boundary then keeps them silent on the web workspaces and active on the mobile ones.

rn-no-raw-text additionally short-circuits raw text inside platform-fork branches:

if (Platform.OS === "web") { … } consequent — and the else branch of if (Platform.OS !== "web").
Platform.OS === "web" ? <X /> : … ternaries, Platform.OS === "web" && <X /> short-circuits, and the reversed-operand form "web" === Platform.OS.
switch (Platform.OS) { case "web": … } case bodies (other cases still report).
Platform.select({ web: <X />, default: <Y /> }) — only the web arm is exempt.
Platform?.OS === "web" (optional chain) and Platform.OS! === "web" (TS non-null assertion) parse the same way as the bare form.

The walker stops at function and Program boundaries — JSX defined inside a callback hoisted out of a Platform.OS branch does not inherit the parent guard. Negative platform checks like Platform.OS === "ios" are deliberately NOT treated as web exemptions; only the explicit web branch is.

Scoring

The health score formula: 100 - (unique_error_rules x 1.5) - (unique_warning_rules x 0.75).

Scoring runs on react.doctor's API and is network-dependent: without a successful API round-trip (or under --offline) the score is omitted and the rest of the report still renders normally. Key details:

The score counts unique rules triggered, not total instances. Fixing 49 of 50 no-barrel-import violations does not change the score; fixing all 50 removes the 0.75 penalty for that rule.
Error-severity rules cost 1.5 points each. Warning-severity rules cost 0.75 points each.
Category breakdowns shown in the output are for display only and do not weight the score.

Score labels: 75+ is Great, 50 to 74 is Needs work, under 50 is Critical.

Scores may decrease across releases as new rules are added. Each new rule that fires in your codebase introduces an additional penalty. This is expected — it means the tool is catching more issues, not that your code got worse. Pin to a specific react-doctor version in CI if you need stable scores across upgrades.

Diff and staged modes

React Doctor can scan only changed files instead of the full project:

--diff [base] scans files changed vs a base branch. Auto-detects main/master, or pass an explicit branch: --diff develop. Also available as a config key: "diff": true or "diff": "develop".
--staged scans only files in the git staging area (index). Designed for pre-commit hooks — materializes staged file contents into a temp directory so the scan reflects exactly what will be committed.
--full forces a full scan, overriding any diff value in config or CLI.

When on a feature branch without explicit flags, you'll be prompted: "Only scan changed files?" This prompt is suppressed in CI, --json mode, and non-interactive environments.

--staged and --diff cannot be combined.

Agent and CI integration

React Doctor detects 50+ coding agents (Claude Code, Cursor, Codex, OpenCode, Windsurf, and more) and adapts its behavior automatically:

Install for agents: npx react-doctor@latest install writes agent-specific rule files (SKILL.md, AGENTS.md, .cursorrules) into your project so agents learn React best practices.
JSON output: --json produces a structured JsonReport on stdout. Errors still produce a valid JSON document with ok: false. Use --json-compact for minimal whitespace.
Score-only output: --score outputs just the numeric score (0-100), useful for threshold checks in agent loops.
GitHub Actions annotations: --annotations emits ::error / ::warning format for inline PR annotations.
Exit codes: --fail-on error (default) exits non-zero when error-severity diagnostics are found. Use --fail-on warning or --fail-on none to tune CI gating.
Programmatic API: import { diagnose } from "react-doctor/api" for direct integration in scripts and automation.

In CI environments, prompts are automatically skipped and --offline is implied (no network round-trip; score is omitted from the output).

Node.js API

import { diagnose, toJsonReport, summarizeDiagnostics } from "react-doctor/api";

const result = await diagnose("./path/to/your/react-project");

console.log(result.score); // { score: 82, label: "Great" } or null
console.log(result.diagnostics); // Diagnostic[]
console.log(result.project); // detected framework, React version, etc.

diagnose accepts a second argument: { lint?: boolean }.

const report = toJsonReport(result, { version: "1.0.0" });
const counts = summarizeDiagnostics(result.diagnostics);

react-doctor/api re-exports JsonReport, JsonReportSummary, JsonReportProjectEntry, JsonReportMode, plus the lower-level buildJsonReport and buildJsonReportError builders. See packages/react-doctor/src/api.ts for the full types.

Leaderboard

Top React codebases scanned by React Doctor, ranked by score. Updated automatically from millionco/react-doctor-benchmarks.

#	Repo	Score
1	executor	94
2	nodejs.org	86
3	tldraw	70
4	t3code	68
5	better-auth	64
6	excalidraw	63
7	mastra	63
8	payload	60
9	typebot	57
10	plane	56

See the full leaderboard.

Resources & Contributing Back

Want to try it out? Check out the demo.

Looking to contribute back? Clone the repo, install, build, and submit a PR.

git clone https://github.com/millionco/react-doctor
cd react-doctor
pnpm install
pnpm build
node packages/react-doctor/bin/react-doctor.js /path/to/your/react-project

Find a bug? Head to the issue tracker.

License

React Doctor is MIT-licensed open-source software.

playcanvas/supersplat

3D Gaussian Splat Editor

SuperSplat Editor

The SuperSplat Editor is a free and open source tool for inspecting, editing, optimizing and publishing 3D Gaussian Splats. It is built on web technologies and runs in the browser, so there's nothing to download or install.

A live version of this tool is available at: https://superspl.at/editor

To learn more about using SuperSplat, please refer to the User Guide.

Local Development

To initialize a local development environment for SuperSplat, ensure you have Node.js 18 or later installed. Follow these steps:

Clone the repository:

git clone https://github.com/playcanvas/supersplat.git
cd supersplat

Install dependencies:
```
npm install
```
Build SuperSplat and start a local web server:
```
npm run develop
```
Open a web browser tab and make sure network caching is disabled on the network tab and the other application caches are clear:
- On Safari you can use Cmd+Option+e or Develop->Empty Caches.
- On Chrome ensure the options "Update on reload" and "Bypass for network" are enabled in the Application->Service workers tab:
Navigate to http://localhost:3000

When changes to the source are detected, SuperSplat is rebuilt automatically. Simply refresh your browser to see your changes.

Localizing the SuperSplat Editor

The currently supported languages are available here:

https://github.com/playcanvas/supersplat/tree/main/static/locales

Adding a New Language

Add a new <locale>.json file in the static/locales directory.
Add the locale to the list here:

https://github.com/playcanvas/supersplat/blob/main/src/ui/localization.ts

Testing Translations

To test your translations:

Run the development server:
```
npm run develop
```
Open your browser and navigate to:
```
http://localhost:3000/?lng=<locale>
```
Replace <locale> with your language code (e.g., fr, de, es).

Contributors

SuperSplat is made possible by our amazing open source community:

What	How	Speed
🦴 Pose estimation	CSI subcarrier amplitude/phase → 17 COCO keypoints	171K emb/s (M4 Pro)
🫁 Breathing detection	Bandpass 0.1-0.5 Hz → zero-crossing BPM	6-30 BPM
💓 Heart rate	Bandpass 0.8-2.0 Hz → zero-crossing BPM	40-120 BPM
👤 Presence sensing	Trained model + PIR fusion — 100% accuracy	0.012 ms latency
🧱 Through-wall	Fresnel zone geometry + multipath modeling	Up to 5m depth
🧠 Edge intelligence	8-dim feature vectors + RVF store on Cognitum Seed	$140 total BOM
🎯 Camera-free training	10 sensor signals, no labels needed	84s on M4 Pro
📷 Camera-supervised training	MediaPipe + ESP32 CSI → 35%+ PCK@20 target (ADR-079; eval phases pending)	~19 min on laptop (pipeline)
📡 Multi-frequency mesh	Channel hopping across 6 bands, neighbor APs as illuminators	3x sensing bandwidth
🌐 3D point cloud (optional fusion)	Camera depth (MiDaS) + WiFi CSI + mmWave radar → unified spatial model	22 ms pipeline · 19K+ points/frame

Option	Hardware	Cost	Full CSI	Capabilities
ESP32 + Cognitum Seed (recommended)	ESP32-S3 + Cognitum Seed	~$140	Yes	Pose, breathing, heartbeat, motion, presence + persistent vector store, kNN search, witness chain, MCP proxy
ESP32 Mesh	3-6x ESP32-S3 + WiFi router	~$54	Yes	Pose, breathing, heartbeat, motion, presence
Research NIC	Intel 5300 / Atheros AR9580	~$50-100	Yes	Full CSI with 3x3 MIMO
Any WiFi	Windows, macOS, or Linux laptop	$0	No	RSSI-only: coarse presence and motion

GitHub All Languages Weekly Trending

CloakHQ/CloakBrowser

Stealth Chromium that passes every bot detection test.

Install

Browser Profile Manager

Latest: v0.3.28 (Chromium 146.0.7680.177.4)

Why CloakBrowser?

Test Results

Proof

Comparison

How It Works

API

launch()

launch_async()

launch_context()

launch_context_async()

launch_persistent_context()

CLI

Utility Functions

JavaScript / Node.js API

Playwright (default)

Puppeteer

Utility Functions (JS)

Human Behavior

Configuration

Fingerprint Management

Default Fingerprint

Additional Flags

Font Setup on Linux

Examples

Examples

Framework Integrations

Deployment Integrations

Platforms

Docker

Quick test

Run a script

CDP server mode

Docker Compose

Extend with your own image

Troubleshooting

Still getting blocked on aggressive sites (DataDome, Turnstile)?

Recommended config for anti-bot sites

Blocked on Kasada / Akamai sites despite correct config?

Sites challenge fresh sessions but work after first visit

Something not working? Make sure you're on the latest version

Binary download fails / timeout

New update broke something? Roll back to the previous version

macOS: "App is damaged" or Gatekeeper blocks launch

"playwright install" vs CloakBrowser binary

macOS: Blocked on some sites that pass on Linux

Site detects incognito / private browsing mode

reCAPTCHA v3 scores are low (0.1–0.3)

FAQ

Roadmap

Links

Security

License

Contributing

Contributors

yikart/AiToEarn

Aitoearn：OPC（一人公司）的AI内容营销智能体

🚀 快速使用 AiToEarn（5 种方式）

最新动态

目录

核心功能

💰 Monetize —— 内容赚钱

📢 Publish —— 内容发布 Agent

💬 Engage —— 内容互动 Agent

🎨 Create —— 内容创作 Agent

① 打开网站直接用

🔑 如何获取 API Key（后续步骤的前置条件）

② 在龙虾 OpenClaw 中使用

③ 在 Claude / Cursor / 其他 AI 助手中使用

④ Docker 一键部署

配置 Relay（强烈推荐）

⑤ 源码开发

1. 启动后端服务

2. 启动前端 aitoearn-web

贡献指南

`launch()`

`launch_async()`

`launch_context()`

`launch_context_async()`

`launch_persistent_context()`

2. 启动前端 `aitoearn-web`