GitHub All Languages Monthly Trending

calesthio/OpenMontage

World's first open-source, agentic video production system. 12 pipelines, 52 tools, 500+ agent skills. Turn your AI coding assistant into a full video production studio.

OpenMontage

The first open-source, agentic video production system.

Paste A Video · Quick Start · Try These Prompts · Pipelines · How It Works · Sponsors · Providers · Review Guide · Agent Guide

Follow The Build

Start From A Video You Already Love

Starting from a reference video is often faster than starting from a blank prompt.

OpenMontage can start from a YouTube video, Short, Reel, TikTok, or local clip and turn it into a grounded production plan:

Paste a reference video
The agent analyzes transcript, pacing, scenes, keyframes, and style
You get 2-3 differentiated concepts, an honest tool path, cost estimates, and a sample before full production

"Here's a YouTube Short I love. Make me something like this, but about quantum computing."

What you get back is not "best guess prompt spaghetti." You get:

What it keeps from the reference: pacing, hook style, structure, tone
What it changes: topic, visual treatment, angle, narration approach
What it will cost at your target duration, before asset generation starts
What it will actually look like with your currently available tools

Works with Claude Code, Cursor, Copilot, Windsurf, Codex — any AI coding assistant that can read files and run code.

Watch It Happen — The Backlot Living Storyboard

Chat tells you what the agent said. Backlot shows you what the production is actually doing — a local board that fills itself in as the pipeline runs. Stages light up, the script lands as a screenplay page, scene cards shimmer while assets generate, and every provider decision and dollar spent is on the wall.

When a production starts, the agent opens it for you automatically. No setup, no reporting — the board derives everything from the project files the pipeline already writes.

The storyboard is now a real approval gate. Asset generation pauses on a scene-by-scene contact sheet — takes, prompts, per-asset cost, quality scores — so you approve the visuals before the render, not after it's too late:

Creative gates hold until you answer. The board shows what's waiting and why; you reply in chat:

Every production on your machine, live-first, in the library:

python -m backlot open                  # the library — every project on disk
python -m backlot open <project-id>     # one production's live board
python scripts/backlot_simulate_run.py  # no production yet? watch a simulated one live

And when a run is done, hit ▶ REPLAY RUN — the whole production replays from its timestamps, scrubbable end to end. See backlot/README.md for how it works.

Quick Start

Prerequisites

Python 3.10+ — python.org
FFmpeg — brew install ffmpeg / sudo apt install ffmpeg / ffmpeg.org
Node.js 18+ — nodejs.org
An AI coding assistant — Claude Code, Cursor, Copilot, Windsurf, or Codex

Install & Run

git clone https://github.com/calesthio/OpenMontage.git
cd OpenMontage
make setup

Open the project in your AI coding assistant and tell it what you want:

"Make a 60-second animated explainer about how neural networks learn"

Or if you want the real-footage path:

"Make a 75-second documentary montage about city life in the rain. Use real footage only, no narration, elegiac tone, with music."

That's it. The agent researches your topic with live web search, generates AI images, writes and narrates the script with voice direction, finds royalty-free background music automatically, burns in word-level subtitles, and renders the final video. Before you see anything, the system runs a multi-point self-review — ffprobe validation, frame sampling, audio level analysis, delivery promise verification, and subtitle checks. Every provider selection is scored across 7 dimensions with an auditable decision log. Every creative decision gets your approval.

No make? macOS/Linux: python3 -m venv .venv && source .venv/bin/activate && python -m pip install -r requirements.txt && cd remotion-composer && npm install && cd .. && python -m pip install piper-tts && cp .env.example .env

Windows PowerShell: py -3 -m venv .venv; .\.venv\Scripts\Activate.ps1; python -m pip install -r requirements.txt; cd remotion-composer; npm install; cd ..; python -m pip install piper-tts; Copy-Item .env.example .env

Windows: If npm install fails with ERR_INVALID_ARG_TYPE, use npx --yes npm install instead.

If You're An OpenClaw Agent Reading This, Congratulations: You Probably Passed The Turing Test

This repo is built for agentic operation. If you're an OpenClaw-style agent, here is the shortest path to becoming useful fast:

Read the contract first Start with AGENT_GUIDE.md, then PROJECT_CONTEXT.md.
Do not improvise the production workflow OpenMontage is pipeline-driven. Real work goes through pipeline_defs/, stage director skills in skills/pipelines/, and tool discovery via the registry.

Check the actual capability envelope Run:

python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.support_envelope(), indent=2))"
python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.provider_menu(), indent=2))"

Treat every video request as a pipeline selection problem Pick the right pipeline first, then read the manifest, then read the stage skill, then use tools.

Add API Keys (optional — more keys = more tools)

# .env — every key is optional, add what you have

# Image + video gateway:
FAL_KEY=your-key               # FLUX images + Google Veo, Kling, MiniMax video + Recraft images

# Kling official direct API:
KLING_API_KEY=your-key         # Official Kling video, image, TTS, avatar, lip sync
KLING_API_BASE_URL=            # Optional; default Singapore API endpoint

# Free stock media:
PEXELS_API_KEY=your-key        # Free stock footage and images
PIXABAY_API_KEY=your-key       # Free stock footage and images
UNSPLASH_ACCESS_KEY=your-key   # Free stock images

# Music:
SUNO_API_KEY=your-key          # Full songs, instrumentals, any genre

# Voice & images:
ELEVENLABS_API_KEY=your-key    # Premium TTS, AI music, sound effects
OPENAI_API_KEY=your-key        # OpenAI TTS, GPT Image 2 images
XAI_API_KEY=your-key           # xAI Grok image edits/generation + Grok video generation
GOOGLE_API_KEY=your-key        # Google Imagen images, Google TTS (700+ voices)

# More video providers:
HEYGEN_API_KEY=your-key        # HeyGen — VEO, Sora, Runway, Kling via single gateway
RUNWAY_API_KEY=your-key        # Runway Gen-4 direct

Have a GPU? Unlock free local video generation

make install-gpu

# Then add to .env:
VIDEO_GEN_LOCAL_ENABLED=true
VIDEO_GEN_LOCAL_MODEL=wan2.1-1.3b  # or wan2.1-14b, hunyuan-1.5, ltx2-local, cogvideo-5b

What You Get With Zero API Keys

You don't need paid API keys to make real videos. Out of the box, make setup gives you:

Capability	Free Tool	What It Does
Narration	Piper TTS	Free offline text-to-speech — real human-sounding narration
Open footage	Archive.org + NASA + Wikimedia Commons	Free/open archival footage, educational media, and documentary texture
Extra stock	Pexels + Unsplash + Pixabay	Free stock footage/images (developer keys are free to get)
Composition (React)	Remotion	React-based rendering — spring-animated image scenes, text cards, stat cards, charts, TikTok-style word-level captions, TalkingHead
Composition (HTML/GSAP)	HyperFrames	HTML/CSS/GSAP rendering — kinetic typography, product promos, launch reels, registry blocks, website-to-video, rigged SVG character animation
Post-production	FFmpeg	Encoding, subtitle burn-in, audio mixing, color grading
Subtitles	Built-in	Auto-generated captions with word-level timing

OpenMontage picks between Remotion and HyperFrames at proposal time (locked as render_runtime). Remotion is the default for data-driven explainers and anything using the existing React scene stack; HyperFrames is the default for motion-graphics-heavy briefs that express naturally as HTML + GSAP, including the character-animation pipeline's SVG/GSAP rig output. See skills/core/hyperframes.md for the full decision matrix.

Two free-ish paths:

Image-based video: Piper narrates your script, images provide the visuals, and Remotion animates them into a polished edit.
Local character animation: SVG rigs, pose libraries, GSAP timelines, and HyperFrames render cartoon character acting to projects/<project-name>/renders/final.mp4.
Real-footage video: the documentary montage pipeline builds a CLIP-searchable corpus from Archive.org, NASA, Wikimedia Commons, and optional free-key sources like Pexels and Unsplash, then cuts together actual motion footage into a finished video.

If you want the second one, prompt for a documentary montage, tone poem, or stock-footage collage, and explicitly say use real footage only.

Try These Prompts

Copy any of these into your AI coding assistant after setup. Each one runs a full production pipeline.

Start from a reference video

"Here's a YouTube short I love. Make me something like this, but about CRISPR for high school students."

"Analyze this Reel and give me 3 original variants I could make for my own product launch."

"I like the pacing and hook in this video. Keep that energy, but turn it into a 45-second explainer about black holes."

Zero keys needed

"Make a 45-second animated explainer about why the sky is blue"

"Create a 60-second video about the history of the internet, with narration and captions"

"Make a data-driven explainer about coffee consumption around the world"

Free real-footage documentary path

"Make a 90-second documentary montage about what a city feels like at 4am. Use real footage only, no narration, elegiac tone."

"Create a 60-second Adam-Curtis-style archival collage about 1950s consumer optimism. Prefer Archive.org and Wikimedia footage."

"Cut together a dreamlike montage about coming home in the rain using real stock footage only. Music yes, narration no."

With an image/video provider configured (~$0.15–$1.50)

"Create a 30-second Ghibli-style animated video of a magical floating library in the clouds at golden hour"

"Make a 30-second anime-style animation of an underwater temple with bioluminescent coral and ancient ruins"

"Create an animated explainer about how CRISPR gene editing works, using AI-generated visuals"

"Make a product launch teaser for a fictional smart water bottle called AquaPulse"

Full setup (~$1–$3)

"Create a cinematic 30-second trailer for a sci-fi concept: humanity receives a warning from 1000 years in the future"

"Make a 90-second animated explainer about quantum computing for middle school students, with a fun narrator voice and custom soundtrack"

Want more? See the full Prompt Gallery for tested prompts with expected costs and output examples, or run make demo to render zero-key demo videos instantly.

Pipelines

Each pipeline is a complete production workflow, from idea to finished video.

Pipeline	What It Produces	Best For
Animated Explainer	AI-generated explainer with research, narration, visuals, music	Educational content, tutorials, topic breakdowns
Animation	Motion graphics, kinetic typography, animated sequences	Social media, product demos, abstract concepts
Avatar Spokesperson	Avatar-driven presenter videos	Corporate comms, training, announcements
Cinematic	Trailer, teaser, and mood-driven edits	Brand films, teasers, promotional content
Clip Factory	Batch of ranked short-form clips from one long source	Repurposing long content for social media
Documentary Montage	Thematic montage cut from a CLIP-indexed corpus of free stock footage and open archives (Pexels, Archive.org, NASA, Wikimedia, Unsplash)	Video essays, mood pieces, retrieval-first B-roll edits, real-footage videos without paid generation APIs
Hybrid	Source footage + AI-generated support visuals	Enhancing existing footage with graphics
Localization & Dub	Subtitle, dub, and translate existing video	Multi-language distribution
Podcast Repurpose	Podcast highlights to video	Podcast marketing, audiogram videos
Screen Demo	Polished software screen recordings and walkthroughs	Product demos, tutorials, documentation
Talking Head	Footage-led speaker videos	Presentations, vlogs, interviews

Every pipeline follows the same structured flow:

research -> proposal -> script -> scene_plan -> assets -> edit -> compose

Each stage has a dedicated director skill — a markdown instruction file that teaches the agent exactly how to execute that stage. The agent reads the skill, uses the tools, self-reviews, checkpoints state, and asks for human approval at creative decision points.

Web research is a first-class stage. Before writing a single word of script, the agent searches YouTube, Reddit, Hacker News, news sites, and academic sources. It gathers data points, audience questions, trending angles, and visual references — then cites everything in a structured research brief. Your videos are grounded in real, current information, not hallucinated facts.

Why OpenMontage?

Most AI video tools give you a single clip from a prompt. OpenMontage gives you an end-to-end production pipeline — the same structured process a real production team follows, automated by your AI agent.

Most "free AI video" stacks quietly mean "animate still images." OpenMontage can do that too, but it can also build a finished video from real footage pulled from free/open sources, ranked semantically, edited intentionally, and rendered as a proper timeline.

Edit your own talking-head footage. Generate a fully animated explainer from scratch. Cut a 2-hour podcast into a dozen social clips. Translate and dub your content into 10 languages. Build a cinematic brand teaser from stock footage and AI-generated scenes. If a production team can make it, OpenMontage can orchestrate it.

12 production pipelines — explainers, talking heads, screen demos, cinematic trailers, animations, podcasts, localization, documentary montages, and more
52 production tools — spanning video generation, image creation, text-to-speech, music, audio mixing, subtitles, enhancement, and analysis
400+ agent skills — production skills, pipeline directors, creative techniques, quality checklists, and deep technology knowledge packs that teach the agent how to use every tool like an expert
Reference-driven creation — paste a video you like and the agent turns it into a grounded, differentiated production plan instead of forcing you to invent the perfect prompt from scratch
Real-footage documentary creation without paid video models — build actual edited videos from free/open motion footage and archival sources, not just Ken Burns over images
Live web research built in — before writing a single word of script, the agent runs 15-25+ web searches across YouTube, Reddit, news sites, and academic sources to ground your video in real, current data
Both free/local AND cloud providers — every capability supports open-source local alternatives alongside premium APIs. Use what you have.
No vendor lock-in — swap providers freely. The scored selector ranks every provider across 7 dimensions (task fit, output quality, control, reliability, cost efficiency, latency, continuity) and picks the best match automatically.
Production-grade quality gates — delivery promise enforcement blocks slideshow-looking renders, pre-compose validation catches broken plans before wasting GPU time, and mandatory post-render self-review (ffprobe + frame extraction + audio analysis) ensures the agent never presents garbage. Every provider choice, style decision, and fallback gets logged in an auditable decision trail.
Budget governance built in — cost estimation before execution, spend caps, per-action approval thresholds. No surprise bills.

How It Works

OpenMontage uses an agent-first architecture. There is no code orchestrator. Your AI coding assistant IS the orchestrator.

You: "Make an explainer video about how black holes form"
 |
 v
Agent reads pipeline manifest (YAML) -- stages, tools, review criteria, success gates
 |
 v
Agent reads stage director skill (Markdown) -- HOW to execute each stage
 |
 v
Agent calls Python tools -- scored provider selection ranks every tool across 7 dimensions
 |
 v
Agent self-reviews using reviewer skill -- schema validation, playbook compliance, quality checks
 |
 v
Agent checkpoints state (JSON) -- resumable, with decision log and cost snapshot
 |
 v
Agent presents for your approval -- you stay in control at every creative decision
 |
 v
Pre-compose validation gate -- delivery promise, slideshow risk, renderer governance
 |
 v
Render (Remotion or FFmpeg) -- composition engine matched to visual grammar
 |
 v
Post-render self-review -- ffprobe, frame extraction, audio analysis, promise verification
 |
 v
Final video output -- only if self-review passes

Python provides tools and persistence. All creative decisions, orchestration logic, review criteria, and quality standards live in readable instruction files (YAML manifests + Markdown skills) that you can inspect and customize. Every decision is logged with alternatives considered, confidence scores, and the reasoning behind each choice.

Architecture

OpenMontage/
├── tools/              # 48 Python tools (the agent's hands)
│   ├── video/          # 13 video gen tools + compose, stitch, trim
│   ├── audio/          # 4 TTS providers + Suno/ElevenLabs music, mixing, enhancement
│   ├── graphics/       # 9 image/graphics generation tools + diagrams, code snippets, math
│   ├── enhancement/    # Upscale, bg remove, face enhance, color grade
│   ├── analysis/       # Transcription, scene detect, frame sampling
│   ├── avatar/         # Talking head, lip sync
│   └── subtitle/       # SRT/VTT generation
│
├── pipeline_defs/      # YAML pipeline manifests (the agent's playbook)
├── skills/             # Markdown skill files (the agent's knowledge)
│   ├── pipelines/      # Per-pipeline stage director skills
│   ├── creative/       # Creative technique skills
│   ├── core/           # Core tool skills
│   └── meta/           # Reviewer, checkpoint protocol
│
├── schemas/            # 15 JSON Schemas (contract validation)
├── styles/             # Visual style playbooks (YAML)
├── remotion-composer/  # React/Remotion video composition engine
├── lib/                # Core infrastructure (config, checkpoints, pipeline loader)
└── tests/              # Contract tests, QA integration tests, eval harness

Three-Layer Knowledge Architecture

Layer 1: tools/ + pipeline_defs/     "What exists" — executable capabilities + orchestration
Layer 2: skills/                     "How to use it" — OpenMontage conventions and quality bars
Layer 3: .agents/skills/             "How it works" — external technology knowledge packs

Each tool declares which Layer 3 skills it relies on. The agent reads Layer 1 to know what's available, Layer 2 to know how OpenMontage wants it used, and Layer 3 for deep technical knowledge when needed.

Supported Providers

Full setup guide with pricing and free tiers: docs/PROVIDERS.md

Video Generation — 15 providers

Provider	Type	Notes
Kling (fal.ai)	Cloud API	High quality, fast via fal.ai gateway
Kling Official	Cloud API	Official direct API with separate `kling_official` provider
Runway Gen-4	Cloud API	Cinematic quality, Gen-3 Alpha Turbo / Gen-4 Turbo / Gen-4 Aleph
Google Veo 3	Cloud API	Long-form, cinematic. Via fal.ai or HeyGen.
Grok Imagine Video	Cloud API	Strong reference-image video and xAI-native short-form generation
Higgsfield	Cloud API	Multi-model orchestrator with Soul ID for character consistency
MiniMax	Cloud API	Cost-effective
HeyGen	Cloud API	Multi-model gateway
WAN 2.1	Local GPU	Free, 1.3B and 14B variants
Hunyuan	Local GPU	Free, high quality
CogVideo	Local GPU	Free, 2B and 5B variants
LTX-Video	Local GPU / Modal	Free locally, or self-hosted cloud
Pexels	Stock	Free stock footage
Pixabay	Stock	Free stock footage
Wikimedia Commons	Stock	Free/open stock footage and archival video

Image Generation — 11 tools/providers

Provider	Type	Notes
FLUX	Cloud API	State-of-the-art quality
Google Imagen	Cloud API	Imagen 4 — high-quality, multiple aspect ratios
Grok Imagine Image	Cloud API	Strong image edits, style transfer, and multi-image compositing
GPT Image 2	Cloud API	OpenAI's image model
Recraft	Cloud API	Design-focused generation
Kling Official	Cloud API	Official direct API for Kling image generation and reference workflows
Local Diffusion	Local GPU	Stable Diffusion, free
Pexels	Stock	Free stock images
Pixabay	Stock	Free stock images
Unsplash	Stock	Free stock images
ManimCE	Local	Mathematical animations

Text-to-Speech — 5 providers

Provider	Type	Notes
ElevenLabs	Cloud API	Premium voice quality
Google TTS	Cloud API	700+ voices, 50+ languages — best for localization
Kling Official TTS	Cloud API	Official Kling narration when a `voice_id` is known
OpenAI TTS	Cloud API	Fast, affordable
Piper	Local	Completely free, offline

Music, Sound & Post-Production

Music & Sound:

Provider	Type	Notes
Suno AI	Cloud API	Full song generation with vocals, lyrics, any genre. Up to 8 minutes.
ElevenLabs Music	Cloud API	AI music generation
ElevenLabs SFX	Cloud API	Sound effect generation

Post-Production (always available, always free):

Tool	What It Does
FFmpeg	Video composition, encoding, subtitle burn-in, audio muxing
Video Stitch	Multi-clip assembly, crossfades, picture-in-picture, spatial layouts
Video Trimmer	Precision cutting and extraction
Audio Mixer	Multi-track mixing, ducking, fades
Audio Enhance	Noise reduction, normalization
Color Grade	LUT-based color grading
Subtitle Gen	SRT/VTT generation from timestamps

Enhancement:

Tool	What It Does
Upscale	Real-ESRGAN image/video upscaling
Background Remove	rembg / U2Net background removal
Face Enhance	Face quality enhancement
Face Restore	CodeFormer / GFPGAN face restoration

Analysis:

Tool	What It Does
Transcriber	WhisperX speech-to-text with word-level timestamps
Scene Detect	Automatic scene boundary detection
Frame Sampler	Intelligent frame extraction
Video Understand	CLIP/BLIP-2 vision-language analysis

Avatar & Lip Sync:

Tool	What It Does
Talking Head	SadTalker / MuseTalk avatar animation
Lip Sync	Wav2Lip audio-driven lip synchronization
Kling Avatar	Official Kling cloud avatar presenter generation
Kling Lip Sync	Official Kling cloud lip-sync with explicit face selection

Composition & Rendering:

Engine	Type	What It Does
Remotion	Local (Node.js)	React-based programmatic video — spring-animated image scenes, stat reveals, section titles, hero cards, TikTok-style word-by-word captions, scene transitions (fade/slide/wipe/flip), Google Fonts, audio with fade curves, and the TalkingHead avatar composition. When no video generation providers are configured, the agent generates still images and Remotion turns them into fully animated video.
HyperFrames	Local (Node.js ≥ 22)	HTML/CSS/GSAP programmatic video — kinetic typography, product promos, launch reels, custom motion graphics, registry blocks (data charts, grain overlays, shader transitions), website-to-video workflows, and rigged SVG character animation. Consumed via `npx hyperframes`; no monorepo checkout needed.
FFmpeg	Local	Core video assembly, encoding, subtitle burn, audio muxing, color grading

Runtime is chosen at proposal (render_runtime) and locked through edit_decisions. Silent swaps between runtimes are a governance violation — see skills/core/hyperframes.md.

Style System

Style playbooks define the visual language for your productions:

Playbook	Best For
Clean Professional	Corporate, educational, SaaS
Flat Motion Graphics	Social media, TikTok, startups
Minimalist Diagram	Technical deep-dives, architecture

Playbooks control typography, color palettes, motion styles, audio profiles, and quality rules. The agent reads the playbook and applies it consistently across all generated assets.

Platform Output Profiles

Built-in render profiles for every major platform:

Profile	Resolution	Aspect Ratio
YouTube Landscape	1920x1080	16:9
YouTube 4K	3840x2160	16:9
YouTube Shorts	1080x1920	9:16
Instagram Reels	1080x1920	9:16
Instagram Feed	1080x1080	1:1
TikTok	1080x1920	9:16
LinkedIn	1920x1080	16:9
Cinematic	2560x1080	21:9

Production Governance

OpenMontage treats video production like real engineering — with quality gates, audit trails, and enforcement at every stage.

Quality Gates

Human approval gates are enforced, not suggested — proposal, script, scene plan, generated assets, and publish all pause for your sign-off. The checkpoint writer rejects a "completed" gated stage without recorded approval, and every superseded checkpoint is archived so the audit trail (including gate transitions) survives revisions. Review happens visually on the Backlot board.
Pre-compose validation — blocks render if the delivery promise is violated (e.g. "motion-led" video with 80% still images), slideshow risk score is critical, or renderer family is missing. Catches broken plans before wasting GPU time.
Post-render self-review — after every render, the runtime runs ffprobe validation, extracts frames at 4 positions to check for black frames and broken overlays, analyzes audio levels for silence and clipping, verifies the delivery promise was honored, and checks subtitle presence. If the review fails, the video is not presented.
Slideshow risk scoring — 6-dimension analysis (repetition, decorative visuals, weak motion, shot intent, typography overreliance, unsupported cinematic claims) prevents "animated PowerPoint" outputs.
Source media inspection — when users supply their own footage, the system probes every file (resolution, codec, audio channels, duration) and builds planning implications before a single creative decision is made. No hallucinating content from filenames.

Scored Provider Selection

Every tool selection (video generation, image generation, TTS, music) runs through a 7-dimension scoring engine: task fit (30%), output quality (20%), control features (15%), reliability (15%), cost efficiency (10%), latency (5%), continuity (5%). The winning provider and its score are logged in the decision trail with all alternatives considered.

Selectors normalize loose brief context before scoring. If the agent only knows something like "Pixar-style animated short with character consistency," the selector expands that into scorer-friendly intent and style signals instead of requiring a perfectly pre-shaped task_context.

Selector outputs also surface the chosen provider's agent_skills, so the agent can immediately read the right Layer 3 provider skill before writing prompts.

Decision Audit Trail

Every major creative and technical choice — provider selection, style/playbook choice, music track, voice selection, renderer family, any fallback or downgrade — is logged with alternatives considered, confidence scores, and reasoning. The cumulative decision log persists across all stages so you can trace exactly why the output looks the way it does.

Budget Controls

Estimate before execution — see what it will cost
Reserve budget — lock funds before the call
Reconcile after — record actual spend
Configurable modes — observe (track only), warn (log overruns), cap (hard limit)
Per-action approval — pause for confirmation above a threshold (default: $0.50)
Total budget cap — default $10, fully configurable

No surprise bills. The agent tells you what it will cost before it spends.

Agent Compatibility

OpenMontage works with any AI coding assistant that can read files and execute Python. Dedicated instruction files are included for:

Platform	Config File
Claude Code	`CLAUDE.md`
Cursor	`CURSOR.md` + `.cursor/rules/`
GitHub Copilot	`COPILOT.md` + `.github/copilot-instructions.md`
Codex	`CODEX.md`
Windsurf	`.windsurfrules`

All platform files point to the shared AGENT_GUIDE.md (operating guide and agent contract) and PROJECT_CONTEXT.md (architecture reference).

Coming soon: Local LLM support via Ollama and LM Studio — run the full production pipeline without any cloud LLM.

Contributing

OpenMontage is built to be extended. The two most common contributions:

Adding a New Tool

Create a Python file in the appropriate tools/ subdirectory
Inherit from BaseTool and implement the tool contract
The registry auto-discovers it — no manual registration needed
Add a skill file if the tool needs usage guidance

Adding a New Pipeline

Create a YAML manifest in pipeline_defs/
Create stage director skills in skills/pipelines/<your-pipeline>/
Reference existing tools — or add new ones if needed

See docs/ARCHITECTURE.md for the full technical reference, docs/PROVIDERS.md for the complete provider guide (setup, pricing, free tiers), and AGENT_GUIDE.md for the agent contract.

Join the Community

We use GitHub Discussions to share work and ideas:

Show and Tell — Share videos you've made, prompts that worked well, or creative workflows you've discovered
Ideas — Suggest new pipelines, tools, style playbooks, or integrations
Q&A — Ask questions about setup, pipelines, or troubleshooting

Made something cool? Post it in Show and Tell — we'd love to see what you build.

Contact

For updates, releases, and behind-the-scenes build notes, follow @calesthioailabs.

For bugs, feature requests, and workflow discussions, use GitHub Issues and GitHub Discussions so everything stays visible and actionable.

Testing

# Run contract tests (no API keys needed)
make test-contracts

# Run all tests
make test

Star History

License

GNU AGPLv3

OpenMontage — Production-grade video with real quality enforcement, orchestrated by your AI assistant.

If this project looks useful to you, a ⭐ would really mean a lot — it helps others discover it too.

If you'd like to go further, sponsor the project — OpenMontage is built nights and weekends, and your support makes that sustainable.

DeusData/codebase-memory-mcp

High-performance code intelligence MCP server. Indexes codebases into a persistent knowledge graph — average repo in milliseconds. 158 languages, sub-ms queries, 99% fewer tokens. Single static binary, zero dependencies.

codebase-memory-mcp

The fastest and most efficient code intelligence engine for AI coding agents. Full-indexes an average repository in milliseconds, the Linux kernel (28M LOC, 75K files) in 3 minutes. Answers structural queries in under 1ms. Ships as a single static binary for macOS, Linux, and Windows — download, run install, done.

High-quality parsing through tree-sitter AST analysis across all 158 languages, enhanced with Hybrid LSP semantic type resolution for Python, TypeScript / JavaScript / JSX / TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust, and Perl — producing a persistent knowledge graph of functions, classes, call chains, HTTP routes, and cross-service links. 15 MCP tools. Zero dependencies. Plug and play across 43 supported automatic/conditional client surfaces.

Research — The design and benchmarks behind this project are described in the preprint Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP (arXiv:2603.27277). Evaluated across 31 real-world repositories: 83% answer quality, 10× fewer tokens, 2.1× fewer tool calls vs. file-by-file exploration.

Security & Trust — This tool reads your codebase and writes to your agent configuration files. That is what it is designed to do. If you prefer to audit before running, the full source is here — every release binary is signed, checksummed, and scanned by 70+ antivirus engines. All processing happens 100% locally; your code never leaves your machine. Found a security issue? We want to know — see SECURITY.md. Security is Priority #1 for us.

Built-in 3D graph visualization (UI variant) — explore your knowledge graph at localhost:9749

Why codebase-memory-mcp

Extreme indexing speed — Linux kernel (28M LOC, 75K files) in 3 minutes. RAM-first pipeline: LZ4 compression, in-memory SQLite, fused Aho-Corasick pattern matching. Memory released after indexing.
Plug and play — single static binary for macOS (arm64/amd64), Linux (arm64/amd64), and Windows (amd64). No Docker, no runtime dependencies, no API keys. Download → install → restart agent → done.
158 languages — vendored tree-sitter grammars compiled into the binary. Nothing to install, nothing that breaks.
120x fewer tokens — 5 structural queries: ~3,400 tokens vs ~412,000 via file-by-file search. One graph query replaces dozens of grep/read cycles.
43 supported automatic/conditional client surfaces — install configures detected clients and safely activates conditional clients only when their documented platform, marker, or explicit existing config path is present. See Multi-Agent Support for the complete matrix and manual/UI-only boundaries.
Built-in graph visualization — 3D interactive UI at localhost:9749 (optional UI binary variant).
Infrastructure-as-code indexing — Dockerfiles, Kubernetes manifests, and Kustomize overlays indexed as graph nodes with cross-references. Resource nodes for K8s kinds, Module nodes for Kustomize overlays with IMPORTS edges to referenced resources.
15 MCP tools — search, trace, architecture, impact analysis, targeted index-coverage checks, Cypher queries, dead code detection, cross-service HTTP linking, ADR management, and more.

Quick Start

One-line install (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

With graph visualization UI:

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui

Windows (PowerShell):

# 1. Download the installer
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1

# 2. (Optional but recommended) Inspect the script
notepad install.ps1

# 3. Unblock the downloaded file (removes Mark-of-the-Web restriction added by browsers/Invoke-WebRequest)
Unblock-File .\install.ps1

# 4. Run it
.\install.ps1

Note: If you see a script execution policy error, run Set-ExecutionPolicy -Scope Process Bypass first, or invoke with PowerShell -ExecutionPolicy Bypass -File .\install.ps1.

Options: --ui (graph visualization), --skip-config (binary only, no agent setup), --dir=<path> (custom location).

Restart your coding agent. Say "Index this project" — done.

Manual install

Download the archive for your platform from the latest release:
- codebase-memory-mcp-<os>-<arch>.tar.gz (macOS/Linux) or .zip (Windows) — standard
- codebase-memory-mcp-ui-<os>-<arch>.tar.gz / .zip — with graph visualization

Extract and install (each archive includes install.sh or install.ps1):

macOS / Linux:

tar xzf codebase-memory-mcp-*.tar.gz
./install.sh

Windows (PowerShell):

Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath .
Unblock-File .\install.ps1
.\install.ps1

Restart your coding agent.

The install command automatically strips macOS quarantine attributes and ad-hoc signs the binary — no manual xattr/codesign needed.

The install command auto-detects installed coding agents and configures their documented MCP entries plus durable instructions, skills, and lifecycle hooks where supported.

Graph Visualization UI

The UI ships as a separate ui build (it embeds the frontend). The default install on every channel is the lean, headless server; opt into the UI build with:

install.sh: add --ui (see Quick Start)
npm: CBM_VARIANT=ui npm install -g codebase-memory-mcp
PyPI: CBM_VARIANT=ui pip install codebase-memory-mcp
Manual: download the codebase-memory-mcp-ui-<os>-<arch> archive

Then run it:

codebase-memory-mcp --ui=true --port=9749

Open http://localhost:9749 in your browser. The UI runs as a background thread alongside the MCP server — it's available whenever your agent is connected.

Auto-Index

Enable automatic indexing on MCP session start:

codebase-memory-mcp config set auto_index true

When enabled, new projects are indexed automatically on first connection. Previously-indexed projects are registered with the background watcher for ongoing git-based change detection. Configurable file limit: config set auto_index_limit 50000.

Watcher registration is controlled separately by auto_watch (default true). Set config set auto_watch false to keep a session from registering its project with the background watcher — useful when working across many projects and you want each session contained to explicit indexing.

Keeping Up to Date

codebase-memory-mcp update

The MCP server also checks for updates on startup and notifies on the first tool call if a newer release is available.

Uninstall

codebase-memory-mcp uninstall

Removes owned agent config entries, skills, hooks, instructions, and the installed binary. Existing graph indexes are listed and deleted only after confirmation.

Features

Graph & analysis

Architecture overview: get_architecture returns languages, packages, entry points, routes, hotspots, boundaries, layers, and clusters in a single call
Architecture Decision Records: manage_adr persists architectural decisions across sessions
Louvain community detection: Discovers functional modules by clustering call edges
Git diff impact mapping: detect_changes maps uncommitted changes to affected symbols with risk classification
Call graph: Resolves function calls across files and packages (import-aware, type-inferred)
Dead code detection: Finds functions with zero callers, excluding entry points
Cypher-like queries: MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name

Search

Semantic search (semantic_query): vector search across the entire graph, powered by bundled Nomic nomic-embed-code embeddings (40K tokens, 768d int8) compiled into the binary — no API key, no Ollama, no Docker. 11-signal combined scoring (TF-IDF, RRI, API/Type/Decorator signatures, AST profiles, data flow, Halstead-lite, MinHash, module proximity, graph diffusion).
BM25 full-text search via SQLite FTS5 with cbm_camel_split tokenizer (camelCase / snake_case aware)
Structural search (search_graph): regex name patterns, label filters, min/max degree, file scoping
Code search (search_code): graph-augmented grep over indexed files only

Cross-service linking

HTTP route ↔ call-site matching with confidence scoring
gRPC, GraphQL, tRPC service detection with protobuf Route extraction
Channel detection (EMITS / LISTENS_ON) for Socket.IO, EventEmitter, and generic pub-sub patterns across 8 languages with constant resolution

Cross-repo intelligence

CROSS_* edges link nodes across multiple repos indexed under the same store
Multi-galaxy 3D UI layout for cross-repo architecture visualization
Cross-repo architecture summary combining services, routes, and dependencies across the indexed fleet

Edge types (selected)

CALLS, IMPORTS, DEFINES, IMPLEMENTS, INHERITS
HTTP_CALLS, ASYNC_CALLS (cross-service)
EMITS, LISTENS_ON (channels)
DATA_FLOWS with arg-to-param mapping + field access chains
SIMILAR_TO (MinHash + LSH near-clone detection, Jaccard scored)
SEMANTICALLY_RELATED (vocabulary-mismatch, same-language, score ≥ 0.80)

Indexing pipeline

158 vendored tree-sitter grammars compiled into the binary
Generic package / module resolution — bare specifiers like @myorg/pkg, github.com/foo/bar, use my_crate::foo resolved via manifest scanning (package.json, go.mod, Cargo.toml, pyproject.toml, composer.json, pubspec.yaml, pom.xml, build.gradle, mix.exs, *.gemspec)
Infrastructure-as-code indexing — Dockerfiles, Kubernetes manifests, Kustomize overlays as graph nodes
Hybrid LSP semantic type resolution for Python, TypeScript / JavaScript / JSX / TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust, and Perl — a lightweight C implementation of language type-resolution algorithms, structurally inspired by and compatible with major language servers including tsserver / typescript-go, pyright, gopls, Roslyn, Eclipse JDT, and rust-analyzer (parameter binding, return-type inference, generic substitution, JSX component dispatch, JSDoc inference for plain JS files, namespace + trait + late-static-binding resolution for PHP, file-scoped namespaces + records + LINQ method syntax for C#, class-hierarchy + overload + lambda resolution for Java, extension-function + scope-function resolution for Kotlin, trait-method + UFCS resolution for Rust)
RAM-first pipeline: LZ4 compression, in-memory SQLite, single dump at end. Memory released after.

Distribution & operation

Single static binary, zero infrastructure: SQLite-backed, persists to ~/.cache/codebase-memory-mcp/
Auto-sync: Background watcher detects file changes and re-indexes automatically
Route nodes: REST endpoints are first-class graph entities
CLI mode: codebase-memory-mcp cli search_graph '{"project": "my-project", "name_pattern": ".*Handler.*"}'
Available on: npm, PyPI, Homebrew, Scoop, Winget, Chocolatey, AUR, go install

Team-Shared Graph Artifact

Commit a single compressed file to your repo and your teammates skip the reindex.

.codebase-memory/graph.db.zst is a zstd-compressed snapshot of the knowledge graph that lives next to your source. When you index, the artifact is written or refreshed; when a teammate clones the repo and runs codebase-memory-mcp for the first time, the artifact is decompressed and incremental indexing fills in their local diff.

Format: SQLite database, indexes stripped, VACUUM INTO compacted, then zstd 1.5.7 compressed (8–13:1 ratio typical)
Two tiers:
- Best (zstd -9 + index strip + VACUUM INTO) — written on explicit index_repository
- Fast (zstd -3) — written by the watcher for low-latency incremental updates
Bootstrap: when no local DB exists but the artifact is present, index_repository imports the artifact first, then runs incremental indexing — avoiding the full reindex cost
No merge pain: a .gitattributes line with merge=ours is auto-created on first export, so concurrent edits don't produce conflicts on the binary artifact
Optional: never committed unless you want it. Add .codebase-memory/ to .gitignore if you prefer everyone to reindex from scratch.

The result is similar in spirit to graphify's graphify-out/ directory, but as a single compressed file with explicit two-tier export, integrity-checked import, and zero merge friction.

How It Works

codebase-memory-mcp is a structural analysis backend — it builds and queries the knowledge graph. It does not include an LLM. Instead, it relies on your MCP client (Claude Code, or any MCP-compatible agent) to be the intelligence layer.

You: "what calls ProcessOrder?"

Agent calls: trace_path(function_name="ProcessOrder", direction="inbound")

codebase-memory-mcp: executes graph query, returns structured results

Agent: presents the call chain in plain English

Why no built-in LLM? Other code graph tools embed an LLM for natural language → graph query translation. This means extra API keys, extra cost, and another model to configure. With MCP, the agent you're already talking to is the query translator.

Performance

Benchmarked on Apple M3 Pro:

Operation	Time	Notes
Linux kernel full index	3 min	28M LOC, 75K files → 4.81M nodes, 7.72M edges
Linux kernel fast index	1m 12s	1.88M nodes
Django full index	~6s	49K nodes, 196K edges
Cypher query	<1ms	Relationship traversal
Name search (regex)	<10ms	SQL LIKE pre-filtering
Dead code detection	~150ms	Full graph scan with degree filtering
Trace call path (depth=5)	<10ms	BFS traversal

RAM-first pipeline: All indexing runs in memory (LZ4 HC compressed read, in-memory SQLite, single dump at end). Memory is released back to the OS after indexing completes.

Token efficiency: Five structural queries consumed ~3,400 tokens via codebase-memory-mcp versus ~412,000 tokens via file-by-file grep exploration — a 99.2% reduction.

Troubleshooting & Diagnostics

codebase-memory-mcp runs 100% locally and collects no telemetry — your code, queries, environment, and usage never leave your machine. That privacy guarantee also means that when you hit something we can't reproduce on our side (a slow memory climb over hours, a performance regression, a leak that only appears after days of real use), we have no data at all unless you choose to send it. Here is how to capture it yourself.

Capture a diagnostics log

Set CBM_DIAGNOSTICS=1 before the MCP server starts, then reproduce the problem (let it run as long as it takes — a slow leak needs time to show in the trend). The server writes two files to your system temp directory ($TMPDIR or /tmp on macOS/Linux, %TEMP% on Windows):

File	What it is
`cbm-diagnostics-<pid>.ndjson`	The memory trajectory — one JSON line every 5 s with `rss`, `committed` (Windows commit charge), `peak_`, `page_faults`, `fd`, and `queries`. This is the file we need for memory/leak reports* — the trend over time is what pinpoints a leak. It is kept on disk after the server exits (so you can grab it post-mortem) and rotates to `.ndjson.1` past ~8 MB.
`cbm-diagnostics-<pid>.json`	The latest snapshot only — handy for a quick live check. Removed on clean exit.

The startup log prints both paths, e.g.:

level=info msg=diagnostics.start snapshot=/tmp/cbm-diagnostics-12345.json trajectory=/tmp/cbm-diagnostics-12345.ndjson interval=5s

Set the variable in the env block of your agent's MCP server config, or export it before launching the server.

What to share

When you open a memory/performance issue, attach the .ndjson trajectory — it contains no source code or query text, only resource counters. If you'd rather not attach a file, paste it (or an agent's summary of it) into the issue: your assistant can read the NDJSON directly and report whether rss/committed grow monotonically, how fast, and relative to query count — which is exactly what we need to find the cause.

Installation

Pre-built Binaries

Platform	Standard	With Graph UI
macOS (Apple Silicon)	`codebase-memory-mcp-darwin-arm64.tar.gz`	`codebase-memory-mcp-ui-darwin-arm64.tar.gz`
macOS (Intel)	`codebase-memory-mcp-darwin-amd64.tar.gz`	`codebase-memory-mcp-ui-darwin-amd64.tar.gz`
Linux (x86_64)	`codebase-memory-mcp-linux-amd64.tar.gz`	`codebase-memory-mcp-ui-linux-amd64.tar.gz`
Linux (ARM64)	`codebase-memory-mcp-linux-arm64.tar.gz`	`codebase-memory-mcp-ui-linux-arm64.tar.gz`
Windows (x86_64)	`codebase-memory-mcp-windows-amd64.zip`	`codebase-memory-mcp-ui-windows-amd64.zip`

Every release includes checksums.txt with SHA-256 hashes. All binaries are statically linked — no shared library dependencies.

Windows note: SmartScreen may show a warning for unsigned software. Click "More info" → "Run anyway". Verify integrity with checksums.txt.

Setup Scripts

Automated download + install

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup-windows.ps1 | iex

AUR (Arch Linux)

yay -S codebase-memory-mcp-bin

paru -S codebase-memory-mcp-bin

The codebase-memory-mcp-bin package is available at: https://aur.archlinux.org/packages/codebase-memory-mcp-bin

Install via Claude Code

You: "Install this MCP server: https://github.com/DeusData/codebase-memory-mcp"

Build from Source

Prerequisites: C compiler + zlib

Requirement	Check	Install
C compiler (gcc or clang)	`gcc --version` or `clang --version`	macOS: `xcode-select --install`, Linux: `apt install build-essential`
C++ compiler	`g++ --version` or `clang++ --version`	Same as above
zlib	—	macOS: included, Linux: `apt install zlib1g-dev`
Git	`git --version`	Pre-installed on most systems

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
scripts/build.sh                    # standard binary
scripts/build.sh --with-ui          # with graph visualization
# Binary at: build/c/codebase-memory-mcp

Manual MCP Configuration

If you prefer not to use the install command

Add to ~/.claude.json (user scope) or project .mcp.json:

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}

Restart your agent. Verify with /mcp — you should see codebase-memory-mcp with 15 tools.

Multi-Agent Support

install configures 43 client surfaces: 37 detected automatically and 6 conditional or explicit. “Conditional” means the installer writes only when the documented platform or an explicit, already-existing config path proves the target is active. It never flips experimental feature flags, enables plugins, YOLO modes, global permission bypasses, or third-party instruction trust.

Where a client has a documented custom-agent format, the installer creates three exact-owned definitions from one canonical contract:

Scout (Tier 1) — about 3–4 narrow calls for fast positive, provisional discovery; no absence, exhaustive-impact, or dead-code claims.
Verify (Tier 2, default) — task-directed graph evidence, exact source checks, path coverage for every cited file, and scope coverage before negative claims.
Auditor (Tier 3) — bounded scope, current index generation, complete relevant pagination, broader relationship checks, and explicit unresolved limitations.

Every direct tier batches check_index_coverage for its evidence paths and reads flagged ranges or skipped/excluded files directly. A clean coverage result means only “no recorded gap,” never proof of completeness. Clients without safe child MCP access receive the same three tiers as parent-handoff agents; the parent must supply project, generation, pagination state, graph evidence, and coverage results. Updates migrate only byte-identical prior Verify definitions and never overwrite user-modified agents.

Agent	Activation	MCP config	Durable context / augmentation
Claude Code	Detected	`~/.claude.json`	Skill + three exact-tool graph agents; `SessionStart`, `SubagentStart`, non-blocking `PreToolUse` for `Grep`/`Glob`, and post-`Read` coverage
Codex CLI	Detected	`$CODEX_HOME/config.toml`	`AGENTS.md`, skill, three read-only agents; `SessionStart` + `SubagentStart`
Gemini CLI	Detected	`.gemini/settings.json`	`GEMINI.md`, three explicit read/graph-tool subagents; `BeforeTool`, `AfterTool` `read_file` coverage, and `SessionStart`
Zed	Detected	platform `settings.json` (JSONC)	`AGENTS.md` + shared skill
OpenCode	Detected	`$OPENCODE_CONFIG` or resolved global config	`AGENTS.md`, skill, three deny-by-default read-only agents
Antigravity	Detected	`.gemini/config/mcp_config.json`	`.gemini/GEMINI.md`
Aider	Detected	—	`CONVENTIONS.md` via `.aider.conf.yml`
KiloCode	Detected	`.config/kilo/kilo.jsonc`	Rule + three graph-tool subagents with deny-by-default permissions
VS Code	Detected	platform `Code/User/mcp.json`	`~/.copilot/skills`, three read-only agents, `sessionStart` + `subagentStart`
Cursor	Detected	`.cursor/mcp.json`	Skill + three read-only parent-handoff agents; context hooks withheld because session injection races and `readonly` blocks MCP
Windsurf	Detected	`~/.codeium/windsurf/mcp_config.json`	Always-on `global_rules.md`
Augment / Auggie	Detected	`~/.augment/settings.json`	Rule, three read-only handoff subagents, `SessionStart` + post-`view` coverage
OpenClaw	Detected	`$OPENCLAW_CONFIG_PATH` or state `openclaw.json`	Active-workspace `AGENTS.md` + `TOOLS.md`; compaction reinjection
Kiro	Detected	`$KIRO_HOME/settings/mcp.json`	Steering, skill, three JSON agents with isolated Scout/Analysis-profile MCP and explicit graph-tool selectors (`includeMcpJson: false`)
Junie	Detected	`.junie/mcp/mcp.json`	Skill + three graph subagents for EAP-capable builds; Scout and Analysis server aliases hard-limit the tier tool surfaces; no ineffective EAP `SessionStart` hook
Hermes	Detected	`$HERMES_HOME/config.yaml`	Skill + fail-open `pre_llm_call` context augmentation
OpenHands	Detected	`.openhands/mcp.json`	Shared `.agents/skills/codebase-memory/SKILL.md`
Cline	Detected	`~/.cline/mcp.json` + `${CLINE_DATA_DIR:-~/.cline/data}/settings/cline_mcp_settings.json`	Rule + skill; automatic file hooks withheld because they auto-activate and their output is not reliably consumed; child agents cannot use MCP
Warp	Detected, skill only	UI, Warp Drive, or per invocation (manual)	Shared `~/.agents/skills/codebase-memory/SKILL.md`
Qwen Code	Detected	`.qwen/settings.json`	`QWEN.md`, skill, three explicit read/graph-tool agents; `SessionStart`, `SubagentStart`, and post-`ReadFile` coverage
GitHub Copilot CLI	Detected	`$COPILOT_HOME/mcp-config.json`	Instructions, skill, three read-only agents; `sessionStart` + `subagentStart`
Factory Droid	Detected	`.factory/mcp.json`	`AGENTS.md`, skill, three droids with exact per-tier graph-tool lists (without additive whole-server exposure); `SessionStart` + post-`Read` coverage on macOS/Linux, withheld on Windows
Crush	Detected	`.config/crush/crush.json`	Managed context path with explicit parent-to-child handoff
Goose	Detected	`.config/goose/config.yaml`	`.goosehints`
Mistral Vibe	Detected	`$VIBE_HOME/config.toml`	`AGENTS.md`, skill, and three matched agent/prompt pairs with explicit read-only graph-tool allowlists
Qoder CLI	Detected	`~/.qoder/settings.json`	Skill, three directly MCP-attached agents with named-server scoping and exact per-tier graph-tool lists; `SessionStart`, `SubagentStart`, and post-`Read` coverage, including documented PowerShell execution on Windows
Kimi Code CLI	Detected	`$KIMI_CODE_HOME/mcp.json` (default `~/.kimi-code`)	Same-root `AGENTS.md` + skill; fail-open `UserPromptSubmit` hook in `config.toml`
GitLab Duo CLI	Detected	`$GLAB_CONFIG_DIR/duo/mcp.json` or platform fallback	Fail-open user `SessionStart` on macOS/Linux; hook withheld on Windows; no experimental global skill enablement
Rovo Dev CLI	Detected	configured override or `~/.rovodev/mcp.json`	Global `AGENTS.md`, skill + three read-only handoff subagents; no undocumented hook
Amp	Detected	`~/.config/agents/skills/codebase-memory/mcp.json`	Colocated skill + `~/.config/amp/AGENTS.md`; no plugin
Devin CLI / Local	Detected	`~/.config/devin/config.json` (platform app-data path on Windows)	Same-root `AGENTS.md` + skill; macOS/Linux `UserPromptSubmit` + `PostCompaction`, and `SessionStart` only when Claude does not already provide it; hooks withheld on Windows
Tabnine	Detected	`~/.tabnine/mcp_servers.json`	MCP only; no experimental/YOLO setting
Continue / cn	Conditional	Existing `~/.continue/config.yaml` or `$CBM_CONTINUE_CONFIG_PATH`	MCP only
Visual Studio	Conditional, Windows	`~/.mcp.json`	MCP only
TRAE	Conditional	Existing `$CBM_TRAE_CONFIG_PATH`	MCP only
Roo Code	Conditional	Existing `$CBM_ROO_CONFIG_PATH`	MCP only
Amazon Q Developer IDE	Detected	`~/.aws/amazonq/default.json` (preserves an existing `agents/default.json` or legacy `mcp.json`)	MCP only
CodeBuddy Code CLI	Detected	`~/.codebuddy/.mcp.json` (preserves an active deprecated/legacy file)	`CODEBUDDY.md`, skill, three read-only graph agents; beta hooks are not auto-installed
IBM Bob Shell	Detected by `bob`	`~/.bob/mcp_settings.json`	Shared rule; no invented hook or agent
Pochi	Detected	`~/.pochi/config.jsonc` (`mcp`)	`README.pochi.md`, skill, and three `readFile`-only parent-handoff agents
Pi	Detected	—	`~/.pi/agent/AGENTS.md` + skill; MCP/subagents require an explicit reviewed extension
IBM Bob IDE	Conditional	Existing `~/.bob/mcp.json`	Shared rule + IDE skill; no invented hook or agent
Sourcegraph Cody	Explicit opt-in	Existing `$CBM_CODY_CONFIG_PATH`	MCP only

Sessions, compaction, and subagents

Hooks installed by this project are fail-open and context-only. Claude Code's PreToolUse observes Grep/Glob and injects matching graph symbols as additionalContext; PostToolUse on Read adds targeted coverage context when the graph could not fully parse or index that file. It never denies or replaces the requested tool call.

Claude Code, Codex CLI, Qwen Code, GitHub Copilot CLI, and VS Code's Copilot runtime receive paired session/subagent context where the vendor exposes a documented context-output contract. Codex users must review and trust installed hooks through /hooks; changing a hook definition changes its trust hash, so an update can require re-trust. Qoder uses SessionStart, SubagentStart, and post-Read coverage, including its documented PowerShell executor on Windows. Kimi uses UserPromptSubmit, while Hermes uses pre_llm_call; both retain their documented Windows execution paths. Devin installs UserPromptSubmit and PostCompaction on macOS/Linux and adds SessionStart only when Claude's equivalent managed hook is not present. GitLab Duo gets a narrowly scoped macOS/Linux user SessionStart entry on its experimental hook surface. GitLab Duo, Devin, and Factory hooks are withheld on Windows because those vendors do not document a deterministic shell/executor contract there. Gemini CLI, Factory Droid, and Augment also add documented post-read/view coverage context but expose no equivalent documented child-start context.

For runtimes without a stable context-producing lifecycle event, durable files carry the contract across fresh sessions and compaction: verify the graph project and index freshness, query structural facts in the parent, then pass the project, qualified symbols, paths, and call-chain evidence in every delegated task. Claude, Codex, Gemini, Kiro, Qwen, Copilot, CodeBuddy, OpenCode, Kilo, Vibe, Qoder, Junie, and Factory receive Scout, Verify, and Auditor graph profiles. Kiro embeds this MCP server with --tool-profile scout for Scout and --tool-profile analysis for Verify/Auditor. Junie registers equivalent named server aliases because its subagent schema filters by server rather than by individual tool. Both process profiles use positive allowlists: Scout exposes seven fast inspection tools, Analysis exposes eleven, and future or mutating tools remain unavailable until explicitly reviewed. If either Junie alias collides with user configuration, the installer preserves it and installs parent-handoff profiles instead. Qoder combines its documented named-server selection with exact tier-specific MCP tool IDs. Factory uses exact registered MCP tool IDs without its additive mcpServers field, which would expose the whole server. Codex, Kilo, Vibe, and other capable formats likewise enumerate the narrowest supported tool set. Rovo, Cursor, Augment, Pochi, and Cline use parent handoff where direct child MCP is unavailable or unsafe; Pochi is limited to readFile, and Cline child agents cannot use MCP.

Cline's file hooks auto-activate when present, and current Cline does not reliably consume their context output, so automatic adapters are withheld and older owned adapters are cleaned up. CodeBuddy's beta, version-gated hooks are not auto-installed. Junie's EAP SessionStart output is documented as ignored, so no context hook is installed. Junie custom agents remain EAP-dependent. Qoder can resolve higher-priority project or plugin agents before user agents with the same name; reload the client after installation or profile changes. Cursor context hooks are withheld: session context injection has a known race, subagentStart is control-only, and read-only subagents cannot safely receive MCP access. Rovo has no documented session context-output hook, and Bob documents neither a suitable hook nor a custom-agent surface. Those surfaces are not approximated with invented augmentation. Kimi plugins, Amp plugins, and GitLab experimental global skills remain opt-in.

OpenClaw reinjects the Codebase Knowledge Graph (codebase-memory-mcp) AGENTS section after compaction and places the same guidance in TOOLS.md, the bootstrap files inherited by its subagents. Automatic augmentation covers the active/default workspace. Separate agents.list[].workspace directories require making that workspace active for installation or copying the managed block there.

The installed Claude shim is named cbm-code-discovery-gate for backward compatibility; despite the legacy name, it never gates or blocks.

Manual or UI-managed integrations

These are intentionally not counted as automatic installs: Qodo MCP is added through its UI and may be governed by enterprise allowlists; Warp MCP is managed through Warp Drive/UI or per invocation (only the shared skill is automatic); JetBrains AI Assistant / ACP is IDE-managed; GitHub Copilot coding agent, Jules, and CodeRabbit are cloud/repository-managed; Replit exposes a remote/service integration rather than a stable local user-global client; BLACKBOX AI does not document a stable arbitrary user-global MCP/instruction/agent schema; Plandex has no stable global registry safe to mutate; and SWE-agent uses explicit YAML and is no longer a suitable automatic global target.

CLI Mode

Every MCP tool can be invoked from the command line:

codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/repo"}'
codebase-memory-mcp cli list_projects

# Use the "name" returned by list_projects as the project value.
codebase-memory-mcp cli search_graph '{"project": "my-project", "name_pattern": ".*Handler.*", "label": "Function"}'
codebase-memory-mcp cli trace_path '{"project": "my-project", "function_name": "Search", "direction": "both"}'
codebase-memory-mcp cli query_graph '{"project": "my-project", "query": "MATCH (f:Function) RETURN f.name LIMIT 5"}'
codebase-memory-mcp cli --raw search_graph '{"project": "my-project", "label": "Function"}' | jq '.results[].name'

MCP Tools

Indexing

Tool	Description
`index_repository`	Index a repository into the graph. Auto-sync keeps it fresh after that.
`list_projects`	List all indexed projects with node/edge counts.
`delete_project`	Remove a project and all its graph data.
`index_status`	Check indexing status of a project.

Querying

Tool	Description
`search_graph`	Structured search by label, name pattern, file pattern, degree filters. Pagination via limit/offset.
`trace_path`	BFS traversal — who calls a function and what it calls (alias: `trace_call_path`). Depth 1-5.
`detect_changes`	Map git diff to affected symbols + blast radius with risk classification.
`query_graph`	Execute Cypher-like graph queries (read-only).
`get_graph_schema`	Node/edge counts, relationship patterns, property definitions per label. Run this first.
`get_code_snippet`	Read source code for a function by qualified name.
`get_architecture`	Codebase overview: languages, packages, routes, hotspots, clusters, ADR.
`search_code`	Grep-like text search within indexed project files.
`manage_adr`	CRUD for Architecture Decision Records.
`ingest_traces`	Ingest runtime traces to validate HTTP_CALLS edges.

Graph Data Model

Node Labels

Project, Package, Folder, File, Module, Class, Function, Method, Interface, Enum, Type, Route, Resource

Edge Types

CONTAINS_PACKAGE, CONTAINS_FOLDER, CONTAINS_FILE, DEFINES, DEFINES_METHOD, IMPORTS, CALLS, HTTP_CALLS, ASYNC_CALLS, IMPLEMENTS, HANDLES, USAGE, CONFIGURES, WRITES, MEMBER_OF, TESTS, USES_TYPE, FILE_CHANGES_WITH

Qualified Names

get_code_snippet uses qualified names: <project>.<path_parts>.<name>. Use search_graph to discover them first.

Supported Cypher (openCypher read subset)

query_graph is a read-only openCypher subset:

Clauses: MATCH, OPTIONAL MATCH, multiple MATCH, WHERE, WITH (+ WITH … WHERE), RETURN, ORDER BY, SKIP, LIMIT, DISTINCT, UNWIND, UNION / UNION ALL, CASE.
Patterns: labelled nodes, label alternation (n:A|B), relationship types/direction, variable-length paths [*1..3], inline property maps.
WHERE: = <> < <= > >=, AND/OR/XOR/NOT, IN, CONTAINS, STARTS WITH, ENDS WITH, IS [NOT] NULL, regex =~, label test n:Label, and EXISTS { (n)-[:TYPE]->() } (single-hop existence — great for dead-code, e.g. WHERE NOT EXISTS { (f)<-[:CALLS]-() }).
Aggregates: count (+DISTINCT), sum, avg, min, max, collect.
Functions: labels, type, id, keys, properties; toLower/toUpper/toString/toInteger/toFloat/toBoolean; size, length, trim/ltrim/rtrim, reverse; coalesce, substring, replace, left, right.

Anything outside this subset (write/MERGE/CALL clauses, unsupported functions, list/map literals, comprehensions, path functions, parameters) fails with a clear unsupported … error rather than returning empty results.

Ignoring Files

Layered: hardcoded patterns (.git, node_modules, etc.) → .gitignore hierarchy → .cbmignore (project-specific, gitignore syntax). Symlinks are always skipped.

See docs/cbmignore.md for the full .cbmignore how-to: syntax, precedence across the ignore layers, and negation semantics.

Configuration

codebase-memory-mcp config list                          # show all settings
codebase-memory-mcp config set auto_index true           # auto-index on session start
codebase-memory-mcp config set auto_index_limit 50000    # max files for auto-index
codebase-memory-mcp config set auto_watch false          # don't register background git watcher (default: true)
codebase-memory-mcp config reset auto_index              # reset to default

Environment Variables

Variable	Default	Description
`CBM_ALLOWED_ROOT`	(unset)	Restrict `index_repository` to paths within this directory. When set, a `repo_path` that resolves (after symlink / `..` resolution) outside this root is refused; unset imposes no restriction. Useful when the server may be driven by an untrusted caller, e.g. agentic or multi-tenant deployments.
`CBM_CACHE_DIR`	`~/.cache/codebase-memory-mcp`	Override the database storage directory. All project indexes and config are stored here.
`CBM_DIAGNOSTICS`	`false`	Set to `1` or `true` to enable periodic diagnostics output to `/tmp/cbm-diagnostics-<pid>.json`.
`CBM_DOWNLOAD_URL`	(GitHub releases)	Override the download URL for updates. Used for testing or self-hosted deployments.
`CBM_LOG_LEVEL`	`info`	Set the minimum log level. Accepted values (case-insensitive): `debug`, `info`, `warn`, `error`, `none` — or their numeric equivalents `0`–`4` matching the internal enum. Logs go to stderr; stdout is reserved for MCP JSON-RPC.
`CBM_WORKERS`	(detected)	Override the parallel-indexing worker count returned by `cbm_default_worker_count`. Useful inside containers where `sysconf(_SC_NPROCESSORS_ONLN)` reports host CPUs rather than the cgroup's effective quota. Range 1–256; invalid values are ignored with a warning.
`CBM_MEM_BUDGET_MB`	(detected)	Override the in-memory graph budget with an explicit cap in MiB, taking precedence over the `ram_fraction × total_RAM` default. Useful on bare-metal hosts without a cgroup limit, or to pin a budget below the cgroup limit so headroom is left for sibling processes. Must be a positive integer; it is clamped to detected total RAM (logged as `mem.budget.clamped`), and non-numeric or non-positive values are ignored with a warning (`mem.budget.env.invalid`).
`CBM_DUMP_VERIFY_MIN_RATIO`	`0.5`	After indexing, compare persisted SQLite node count to the in-memory dump count. When persisted nodes fall below this fraction of committed nodes (and committed > 50), `index_repository` returns `status:"degraded"` instead of silent `indexed`. Range 0–1; set `0` to disable. Invalid values are ignored with a warning.

# Store indexes in a custom directory
export CBM_CACHE_DIR=~/my-projects/cbm-data

Custom File Extensions

The JSON config files support a single key, extra_extensions, which maps additional file extensions to supported languages. Useful for framework-specific extensions like .blade.php (Laravel) or .mjs (ES modules). (For other tunables, see Environment Variables and the config subcommand above.)

Need the full config-file reference? See docs/CONFIGURATION.md.

Per-project (in your repo root):

// .codebase-memory.json
{"extra_extensions": {".blade.php": "php", ".mjs": "javascript"}}

Global (applies to all projects):

// ~/.config/codebase-memory-mcp/config.json  (or $XDG_CONFIG_HOME/...)
{"extra_extensions": {".twig": "html", ".phtml": "php"}}

Each entry maps an extension (which must start with .) to a language name. Language names are matched case-insensitively. Accepted values (aliases in parentheses) are:

bash (sh), c, c++ (cpp), c# (csharp), clojure, cmake, cobol, common lisp (commonlisp, lisp), css, cuda, dart, dockerfile, elixir, elm, emacs lisp (emacslisp), erlang, f# (fsharp), form, fortran, glsl, go, graphql, groovy, haskell, hcl (terraform), html, ini, java, javascript, json, julia, kotlin, lean, lua, magma, makefile, markdown, matlab, meson, nix, objective-c (objc), ocaml, perl, php, protobuf, python, r, ruby, rust, scala, scss, sql, svelte, swift, toml, tsx, typescript, verilog, vimscript, vue, wolfram, xml, yaml, zig.

Project config overrides global for conflicting extensions. An entry whose language name is unknown, or whose extension does not start with ., is skipped and a warning is logged to stderr (shown at the default info log level). Missing config files are ignored.

Persistence

SQLite databases stored at ~/.cache/codebase-memory-mcp/. Persists across restarts (WAL mode, ACID-safe). To reset: rm -rf ~/.cache/codebase-memory-mcp/.

Troubleshooting

Problem	Fix
`/mcp` doesn't show the server	Check `.mcp.json` path is absolute. Restart agent. Test: `echo '{}' \| /path/to/binary` should output JSON.
`index_repository` fails	Pass absolute path: `index_repository(repo_path="/absolute/path")`
`trace_path` returns 0 results	Use `search_graph(name_pattern=".PartialName.")` first to find the exact name.
Queries return wrong project results	Add `project="name"` parameter. Use `list_projects` to see names.
Binary not found after install	Add to PATH: `export PATH="$HOME/.local/bin:$PATH"`
UI not loading	Ensure you downloaded the `ui` variant and ran `--ui=true`. Check `http://localhost:9749`.

Hybrid LSP

Semantic type resolution beyond tree-sitter.

Tree-sitter alone gives a syntactic AST. That handles naming, structure, and call sites well, but it can't tell you that user.profile.display_name() resolves to Profile.display_name declared three modules away — tree-sitter doesn't track imports, generics, inheritance, or stdlib types.

codebase-memory-mcp ships a lightweight C implementation of language type-resolution algorithms, structurally inspired by and compatible with major language servers (tsserver / typescript-go, pyright, gopls, Roslyn, Eclipse JDT, rust-analyzer), embedded directly into the static binary. No language server process, no per-project setup, no API key. We call this layer Hybrid LSP: it runs alongside tree-sitter on every parse and refines CALLS, USAGE, and RESOLVED_CALLS edges with type information, so the resulting graph mirrors what an IDE "Go to Definition" would resolve.

Languages with full Hybrid LSP:

Language	What it handles
Python (new in v0.7.0)	imports + dotted submodule walks, dataclasses, `Self` return types, generics, `@property`, `match/case` class patterns, SQLAlchemy 2.0 `Mapped[T]`, Pydantic `BaseModel`, `typing.Annotated` / `ClassVar` / `Final` / `InitVar`, async/await, classmethod/staticmethod, narrowing (`isinstance` / `is not None` / walrus), `typing.cast` / `assert_type`, common stdlib (logging, pathlib, json, functools). Target ~95% resolution on idiomatic code.
TypeScript / JavaScript / JSX / TSX	generics, JSX component dispatch, JSDoc inference for plain JS, `.d.ts` declarations, module re-exports, method chaining via return-type propagation, per-file overlay chained to a shared cross-file registry
PHP (new in v0.7.0)	namespaces, traits, late-static-binding, PHPDoc inference, parameter binding, return-type inference
C# (new in v0.7.0)	global usings, file-scoped namespaces, records (incl. C# 12 primary constructors), LINQ method syntax, `async Task<T>` / `ValueTask<T>` unwrap, generic methods, `this` / `base` dispatch, `var` inference, common BCL stdlib
Go (sharpened in v0.7.0)	pre-built per-package cross-file registry, generics, embedded structs, interface satisfaction, package-aware import resolution
C / C++ (sharpened in v0.7.0)	pre-built per-language cross-file registry shared across C and C++; C side handles macros + `typedef` chains + header-vs-source linking; C++ side handles templates, namespaces, `auto` inference, and method resolution via class hierarchy
Java (new in v0.8.0)	imports (single-type, on-demand, static), class hierarchies with `this` / `super` dispatch, generics, annotations, overload matching by arity and parameter types, lambdas / method references bound to functional interfaces, field-type inference, common JDK stdlib
Kotlin (new in v0.8.0)	imports + same-package resolution, classes / objects / companion objects, extension functions, data classes, nullable-type unwrapping, scope functions (`let` / `apply` / `run` / `also` / `with`), infix calls, common stdlib
Rust (new in v0.8.0)	`use` declarations + module paths, `impl` blocks and trait methods, struct fields, generics with trait bounds, operator-trait desugaring, derive-macro method synthesis, UFCS static paths, common std prelude
Perl	packages + `@ISA` / `use parent` / `use base` inheritance with method-resolution-order dispatch, `SUPER::` calls, Exporter (`use Foo qw(...)`) import maps, `bless` / `ref($class)\|\|$class` self-type inference, qualified `Pkg::sub` static calls, curated perlfunc + CPAN OOP stdlib; unresolved receivers emit no edge (zero-edge guarantee)

Two-layer architecture:

Tree-sitter pass — fast, syntactic, runs for every one of the 158 languages. Extracts definitions, calls, imports.
Hybrid LSP pass — type-aware, runs above the tree-sitter pass per-language. Refines call edges using the import graph plus a per-file or pre-built cross-file definition registry. Languages without a Hybrid LSP pass yet fall back to textual resolution, so you always get some answer.

The result is a knowledge graph accurate enough to drive trace_path across packages, inheritance hierarchies, and stdlib calls — without paying for a language server process per project.

Language Support

158 languages, all parsed via vendored tree-sitter grammars compiled into the binary. Benchmarked against 64 real open-source repositories (78 to 49K nodes):

Tier	Score	Languages
Excellent (>= 90%)		Lua, Kotlin, C++, Perl, Objective-C, Groovy, C, Bash, Zig, Swift, CSS, YAML, TOML, HTML, SCSS, HCL, Dockerfile
Good (75-89%)		Python, TypeScript, TSX, Go, Rust, Java, R, Dart, JavaScript, Erlang, Elixir, Scala, Ruby, PHP, C#, SQL
Functional (< 75%)		OCaml, Haskell

Also supported (not yet benchmarked): Ada, Agda, Apex, Assembly (NASM), Astro, AWK, Beancount, BibTeX, Bicep, Bitbake, Blade, Cairo, Cap'n Proto, Clojure, CMake, COBOL, Common Lisp, Crystal, CSV, CUDA, D, Devicetree, Diff, .env, Elm, Emacs Lisp, F#, Fennel, Fish, FORM, Fortran, FunC, GDScript, .gitattributes, .gitignore, Gleam, GLSL, GN, Go module, Go template, GraphQL, Hare, HLSL, Hyprlang, INI, ISPC, Janet, Jinja2, JSDoc, JSON, JSON5, Jsonnet, Julia, Just, Kconfig, KDL, Lean 4, Linker Script, Liquid, LLVM IR, Luau, Magma, Makefile, Markdown, MATLAB, Mermaid, Meson, Move, Nickel, Nim, Nix, Odin, Pascal, Pkl, PO (gettext), Pony, PowerShell, Prisma, .properties, Protobuf, Puppet, PureScript, Racket, Regex, requirements.txt, ReScript, RON, reStructuredText, Scheme, Slang, Smali, Smithy, Solidity, SOQL, SOSL, Squirrel, SSH config, Starlark, Svelte, Sway, SystemVerilog, TableGen, Tcl, Teal, Templ, Thrift, TLA+, Typst, Verilog, VHDL, Vim script, Vue, WGSL, WIT, Wolfram, XML, Zsh.

Architecture

src/
  main.c              Entry point (MCP stdio server + CLI + install/update/config)
  mcp/                MCP server (15 tools, JSON-RPC 2.0, session detection, auto-index)
  cli/                Install/uninstall/update/config (43 client surfaces, hooks, instructions)
  store/              SQLite graph storage (nodes, edges, traversal, search, Louvain)
  pipeline/           Multi-pass indexing (structure → definitions → calls → HTTP links → config → tests)
  cypher/             Cypher query lexer, parser, planner, executor
  discover/           File discovery (.gitignore, .cbmignore, symlink handling)
  watcher/            Background auto-sync (git polling, adaptive intervals)
  traces/             Runtime trace ingestion
  ui/                 Embedded HTTP server + 3D graph visualization
  foundation/         Platform abstractions (threads, filesystem, logging, memory)
internal/cbm/         Vendored tree-sitter grammars (158 languages) + AST extraction engine

Security

Every release binary is verified through a multi-layer pipeline before publication:

VirusTotal — all binaries scanned by 70+ antivirus engines (zero detections required to publish)
SLSA Level 3 — cryptographic build provenance generated by the trusted GitHub Actions build workflow; verify with gh attestation verify <file> --repo DeusData/codebase-memory-mcp --signer-workflow DeusData/codebase-memory-mcp/.github/workflows/_build.yml
Sigstore cosign — keyless signatures on all artifacts; bundles included in every release
SHA-256 checksums — checksums.txt published with every release; verified by both install scripts before extraction
CodeQL SAST — blocks release pipeline if any open alerts remain
Zero runtime dependencies — no transitive supply chain; all libraries vendored at compile time

v0.7.0 VirusTotal scans

Binary	SHA-256	VirusTotal
`linux-amd64`	`8e12bb2d6ead7f20a6d3...`	0/72 ✅
`linux-arm64`	`10f7136bfbf3950c6b2a...`	0/72 ✅
`darwin-arm64`	`7062a7408906344bf4f8...`	0/72 ✅
`darwin-amd64`	`28c6d640e1a0ac7bfcab...`	0/72 ✅
`windows-amd64`	`9c3ddcf78368fd4fa891...`	0/72 ✅

Scan links for every release are also included in the GitHub Release notes automatically.

License

MIT

catchorg/Catch2

A modern, C++-native, test framework for unit-tests, TDD and BDD - using C++14, C++17 and later (C++11 support is in v2.x branch, and C++03 on the Catch1.x branch)

What is Catch2?

Catch2 is mainly a unit testing framework for C++, but it also provides basic micro-benchmarking features, and simple BDD macros.

Catch2's main advantage is that using it is both simple and natural. Test names do not have to be valid identifiers, assertions look like normal C++ boolean expressions, and sections provide a nice and local way to share set-up and tear-down code in tests.

Example unit test

#include <catch2/catch_test_macros.hpp>

#include <cstdint>

uint32_t factorial( uint32_t number ) {
    return number <= 1 ? number : factorial(number-1) * number;
}

TEST_CASE( "Factorials are computed", "[factorial]" ) {
    REQUIRE( factorial( 1) == 1 );
    REQUIRE( factorial( 2) == 2 );
    REQUIRE( factorial( 3) == 6 );
    REQUIRE( factorial(10) == 3'628'800 );
}

Example microbenchmark

#include <catch2/catch_test_macros.hpp>
#include <catch2/benchmark/catch_benchmark.hpp>

#include <cstdint>

uint64_t fibonacci(uint64_t number) {
    return number < 2 ? number : fibonacci(number - 1) + fibonacci(number - 2);
}

TEST_CASE("Benchmark Fibonacci", "[!benchmark]") {
    REQUIRE(fibonacci(5) == 5);

    REQUIRE(fibonacci(20) == 6'765);
    BENCHMARK("fibonacci 20") {
        return fibonacci(20);
    };

    REQUIRE(fibonacci(25) == 75'025);
    BENCHMARK("fibonacci 25") {
        return fibonacci(25);
    };
}

Note that benchmarks are not run by default, so you need to run it explicitly with the [!benchmark] tag.

Catch2 v3 has been released!

You are on the devel branch, where the v3 version is being developed. v3 brings a bunch of significant changes, the big one being that Catch2 is no longer a single-header library. Catch2 now behaves as a normal library, with multiple headers and separately compiled implementation.

The documentation is slowly being updated to take these changes into account, but this work is currently still ongoing.

For migrating from the v2 releases to v3, you should look at our documentation. It provides a simple guidelines on getting started, and collects most common migration problems.

For the previous major version of Catch2 look into the v2.x branch here on GitHub.

How to use it

This documentation comprises these three parts:

Why do we need yet another C++ Test Framework?
Tutorial - getting started
Reference section - all the details

Issues and bugs can be raised on the Issue tracker on GitHub
For discussion or questions please use our Discord
See who else is using Catch2 in Open Source Software or commercially.

asgeirtj/system_prompts_leaks

Extracted system prompts from Anthropic - Claude Fable 5, Opus 4.8, Claude Code, Claude Design. OpenAI - ChatGPT GPT-5.6, Codex GPT-5.6, GPT-5.5. Google - Gemini 3.5 Flash, 3.1 Pro, Antigravity. xAI - Grok, Cursor, Copilot, VS Code, Perplexity, and more. Updated regularly.

As seen in The Washington Post: See the hidden rules behind AI. Then use them to rewrite this article. (May 11, 2026)

System Prompts Leaks

The purpose of this repo is to document the System Prompt instructions for all the AI chatbots out there - Claude, ChatGPT, Gemini etc.

What	Date	Link
Kimi K2.6	July 14, 2026	System prompt
Perplexity Deep Research	July 14, 2026	System prompt
DeepSeek	July 14, 2026	chat.deepseek.com
GPT-5.6	July 10, 2026	ChatGPT (Sol, extra high) · Codex
Claude Sonnet 5	July 1, 2026	System prompt
Claude Design (Opus 4.8 — full prompt + 48 tools + 16 skills + 9 starter sources)	June 26, 2026	System prompt
GitHub Copilot for macOS (app)	June 18, 2026	System prompt
GPT-5.5 Codex (full prompt)	June 18, 2026	System prompt
Claude Fable 5	June 9, 2026	System prompt · Diff vs Opus 4.8
Claude Opus 4.8	June 9, 2026	System prompt · Official
Claude Code Glob & Grep tools	June 9, 2026	Glob · Grep
Claude Code (Opus 4.8)	May 28, 2026	System prompt
Claude Code & Cowork	May 28, 2026	Claude Code · Cowork · Cowork Dispatch
GPT-5.5	May 24, 2026	Thinking · Instant · API · Pro API
Perplexity Computer	May 21, 2026	System prompt
VS Code Copilot Agent	May 21, 2026	System prompt
Docker Gordon AI	May 21, 2026	System prompt
Gemini 3.5 Flash	May 20, 2026	System prompt · AI Studio · Tools
Antigravity CLI	May 20, 2026	System prompt
Zed AI	May 16, 2026	System prompt
Grok Expert	May 11, 2026	System prompt

Anthropic — Claude

Model	Prompt
Claude Fable 5	System prompt
Claude Opus 4.8	System prompt
Claude Sonnet 5	System prompt
Claude Code (Opus 4.8)	System prompt
Claude Opus 4.7	System prompt
Claude Code (Opus 4.6)	System prompt
Claude Opus 4.6	System prompt
Claude Sonnet 4.6	System prompt
Claude.ai	Anthropic Reminders

Integrations, official prompts & older versions


Integrations	Cowork · Cowork Dispatch · Desktop Code · Design · Mobile iOS · In Chrome · For Excel · For Word · In PowerPoint · Default Styles
Claude Code extras	Glob tool · Grep tool · Deferred tools · Docs assistant · Bundled skills
Published (`claude_behavior` at release date, not updated)	Opus 4.8 · Opus 4.7 · Opus 4.6 · Sonnet 4.6 · All versions
Without tools	Opus 4.6 · Sonnet 4.6
Raw prompts	Opus 4.6 · Opus 4.6 (no tools) · Sonnet 4.6 · Sonnet 4.6 (no tools)
Visualize	Visualization
Opus 4.5	System prompt
Sonnet 4.5	System prompt
Sonnet 4	System prompt
Opus 4.1 Thinking	System prompt
Sonnet 3.7	System prompt · With tools · Full w/ tools · Human-readable

OpenAI — ChatGPT

Model	Prompt
GPT-5.6	ChatGPT (Sol, extra high) · Codex
GPT-5.5	Thinking · Instant · API · Pro API · Codex · Friendly · Pragmatic
GPT-5.4	API · Thinking · Codex · Codex Mini
GPT-5.3	Codex · Spark · Codex API · Chat API · Instant
Codex CLI	Per-model prompts · Spark · Plan mode · Personas · Auto-review
Tools	Web search · Deep research · Python · Python code · Canvas · Image gen · Memory · Advanced memory · File search
Policies	Image safety · Automation context

Older models & variants


GPT-5.2	Mini (free) · Thinking · Codex
o4-mini	System prompt · High
o3	System prompt
ChatGPT Atlas	System prompt
GPT-5.1 personalities	Default · Friendly · Professional · Candid · Cynical · Efficient · Nerdy · Quirky
GPT-5	Agent mode · Thinking · Cynic · Listener · Nerdy · Robot · Codex · Codex Mini
GPT-4.5	System prompt
GPT-4.1	Full · Mini
GPT-4o	System prompt · WhatsApp · Advanced voice · Legacy voice
Monday GPT	System prompt
GPT-4o new personality	System prompt
Study and learn	System prompt
Image safety policies	System prompt
API variants	GPT-5 reasoning (high) · o3 high · o3 med · o3 low · o4-mini high · o4-mini med · o4-mini low
Old o4-mini	System prompt
Codex (older)	GPT-5 · GPT-5.1 · GPT-5.1 Codex · GPT-5.1 Mini · GPT-5.1 Max · GPT-5.2 · 5.2 Friendly · 5.2 Pragmatic

Google — Gemini

Model	Prompt
Gemini 3.5 Flash	System prompt · AI Studio · Tools
Gemini 3.1 Pro	System prompt · API
Gemini CLI	System prompt
Antigravity CLI	System prompt
Jules	System prompt

Older models & variants


Gemini 3	Flash · Pro
Gemini Diffusion	System prompt
Google Search AI Mode	System prompt
Gemini YouTube	System prompt
Gemini in Chrome	System prompt
Gemini Workspace	System prompt
Gemini 2.5 Pro	API · Webapp · Guided learning
Gemini 2.5 Flash	Image preview
Gemini 2.0 Flash	Webapp
AI Studio Build	System prompt
Nano / Banana 2	System prompt
NotebookLM	Chat

xAI — Grok

Model	Prompt
Grok Build	System prompt (CLI Agent)
Grok 4.3 Beta	System prompt
Grok 4.2	System prompt
Grok Expert	System prompt

Older versions


Grok 4.1 Beta	System prompt
Grok 4	System prompt · API
Grok 3	System prompt
Grok Account	System prompt
Grok Personas	Personas
Safety Instructions	Post-new

Perplexity

Model	Prompt
Perplexity Computer	System prompt
Deep Research	System prompt
Comet Browser	System prompt
Voice Assistant	System prompt

Microsoft — Copilot

Product	Prompt
GitHub Copilot	System prompt
VS Code Copilot Agent	System prompt
Copilot CLI	System prompt
Copilot for macOS (app)	System prompt
Copilot in Word	System prompt

Cursor

Product	Prompt
Cursor	System prompt

Product	Prompt
Meta AI	Muse Spark · Muse Spark 1.1

Mistral

Product	Prompt
Mistral Medium 3.5 (Vibe)	System prompt
Mistral Code	System prompt

Moonshot — Kimi

Model	Prompt
Kimi K2.6	System prompt

DeepSeek

Product	Prompt
DeepSeek	chat.deepseek.com

Notion

Product	Prompt
Notion AI	System prompt

Qwen

Product	Prompt
Qwen 3.6 Plus	System prompt

Misc

Product	Prompt
Amp Code (Sourcegraph)	System prompt
Docker Gordon AI	System prompt
ElevenLabs Voice Agent	System prompt
OpenCode	System prompt
Reddit Answers	System prompt
Warp 2.0 Agent	System prompt
Zed AI	System prompt

More products


Brave Search	System prompt
Character AI	System prompt
Confer	System prompt
Fellou Browser	System prompt
Gizmo AI	System prompt
Hermes	System prompt
Indus AI	System prompt
Kagi Assistant	System prompt
MiniMax M2.5	System prompt
Proton Lumo AI	System prompt
Raycast AI	System prompt
Sesame AI Maya	System prompt
t3.chat	System prompt
t3 Code	System prompt

Contact

Star History

kunchenguid/no-mistakes

git push no-mistakes

`git push no-mistakes`

Kill all the slop. Raise clean PR.

English · 简体中文

no-mistakes puts a local git proxy in front of your real remote. Push to no-mistakes instead of origin, and it spins up a disposable worktree, runs an AI-driven validation pipeline, forwards the branch to the configured push target only after every check passes, and opens a clean PR automatically.

Non-blocking - the pipeline runs in an isolated worktree without disrupting your work.
Agent-agnostic - claude, codex, rovodev, opencode, pi, copilot, or acp:<target> via acpx, with ordered fallbacks; every gate requires a runnable configured pipeline agent.
Agent-native - /no-mistakes lets your coding agent do a task and gate it, or gate existing committed work: it runs the pipeline, has the pipeline apply safe fixes, and escalates the rest to you.
Human stays in charge - auto-fix or review findings, your call.
Clean PRs by default - push, open PR, watch CI, and auto-fix failures in one shot.

Full documentation: https://kunchenguid.github.io/no-mistakes/

How it works

        your branch
            │  git push no-mistakes
            ▼
   ┌────────────────────────────────────────────────┐
   │  disposable worktree — your work stays put     │
   │  review → test → docs → lint → push → PR → CI  │
   └────────────────────────────────────────────────┘
            │  every check green
            ▼
        clean PR, opened for you

Each step either passes on its own or stops with a finding for you to act on. Safe, mechanical fixes are applied automatically; anything that touches your intent is escalated for you to approve, fix, or skip. Nothing reaches the configured push target until every check is green.

Install

curl -fsSL https://raw.githubusercontent.com/kunchenguid/no-mistakes/main/docs/install.sh | sh

Windows, Go install, and build-from-source instructions are in the installation guide.

Quick Start

$ no-mistakes init
  ✓ Gate initialized

    repo  /Users/you/src/my-repo
    gate  no-mistakes → /Users/you/.no-mistakes/repos/abc123def456.git
  remote  git@github.com:you/my-repo.git
   skill  /no-mistakes installed for agents at user level

  Push through the gate with:
  git push no-mistakes <branch>

$ git checkout my-branch

# do some work in the branch...

$ git push no-mistakes
  * Pipeline started

  Run no-mistakes to review.

$ no-mistakes
# opens the TUI for the active run

For GitHub fork contributions, keep origin pointed at the parent repository and initialize with no-mistakes init --fork-url <your-fork-url>.

From the TUI you act on each finding: auto-fix ones are applied for you (or approve to let them), ask-user ones are a judgement call you approve, fix, or skip. Once every check is green, the gate forwards your branch to the configured push target and opens the PR for you, so there is no manual git push origin and no hand-written PR body. Prefer to let your coding agent drive the same flow headlessly? Use /no-mistakes (see below).

Three ways to trigger the gate

Every change runs through the same pipeline. Pick the entry point that fits how you're working when the change is ready:

git push no-mistakes - the explicit Git path. Push a committed branch to the gate remote instead of origin.
no-mistakes - the TUI. Run it after making changes (no commit needed) and a wizard walks you through creating a branch, committing, and pushing through the gate, then attaches to the run. no-mistakes -y does all of that automatically.
/no-mistakes - the agent skill. Tell the coding agent to do a task and gate it with /no-mistakes <task>, or use bare /no-mistakes to gate existing committed work. It runs the pipeline, has the pipeline apply safe fixes, and stops to ask you about anything that needs a human call.

no-mistakes init installs the /no-mistakes skill for Claude Code and other agents. Under the hood the skill drives no-mistakes axi, a non-interactive TOON interface to the same approval flow.

See the quick start for the full first-run walkthrough.

Development

make build   # Build bin/no-mistakes with version info
make test    # Run go test -race ./... (excludes the e2e suite)
make e2e     # Run the tagged end-to-end agent journey suite
make e2e-record # Re-record e2e fixtures when agent wire formats change
make lint    # Check generated skill drift and run go vet ./...
make skill   # Regenerate committed no-mistakes skill files
make fmt     # Run gofmt -w .
make demo    # Regenerate demo.gif and demo.mp4 (needs vhs and ffmpeg)
make docs    # Build the Astro docs site in docs/dist

See Makefile for the full target list.

make e2e-record overwrites internal/e2e/fixtures/ from the real claude, codex, and opencode CLIs, spends real API quota, and should be reviewed before committing.

Star History

usestrix/strix

Open-source AI penetration testing tool to find and fix your app’s vulnerabilities.

Strix

The open-source AI pentesting tool. Autonomous AI hackers that find and fix your app’s vulnerabilities.

Tip

New! Strix integrates seamlessly with GitHub Actions and CI/CD pipelines. Automatically scan for vulnerabilities on every pull request and block insecure code before it reaches production - Get started with no setup required.

Strix Overview

Strix are autonomous AI penetration testing agents that act just like real hackers - they run your code dynamically, find vulnerabilities, and validate them through actual proofs-of-concept. Built for developers and security teams who need fast, accurate security testing without the overhead of manual pentesting or the false positives of static analysis tools.

Key Capabilities:

Full pentesting toolkit - reconnaissance, exploitation, and validation out of the box
Multi-agent orchestration - teams of AI pentesters that collaborate and scale
Real exploit validation - working PoCs, not false positives like legacy vulnerability scanners
Developer‑first CLI - actionable findings with remediation guidance
Auto‑fix & reporting - generate patches and compliance-ready pentest reports

Use Cases

Application Security Testing - Detect and validate critical vulnerabilities in your applications
Rapid Penetration Testing - Get penetration tests done in hours, not weeks, with compliance reports
Bug Bounty Automation - Automate bug bounty research and generate PoCs for faster reporting
CI/CD Integration - Run tests in CI/CD to block vulnerabilities before reaching production

🚀 Quick Start

Prerequisites:

Docker (running)
An LLM API key from any supported provider (OpenAI, Anthropic, Google, etc.)

Installation & First Scan

# Install Strix
curl -sSL https://strix.ai/install | bash

# Configure your AI provider
export STRIX_LLM="openai/gpt-5.4"
export LLM_API_KEY="your-api-key"

# Run your first security assessment
strix --target ./app-directory

Note

First run automatically pulls the sandbox Docker image. Results are saved to strix_runs/<run-name>

☁️ Strix Platform

Try the Strix full-stack penetration testing platform at app.strix.ai - sign up for free, connect your repos and domains, and launch a pentest in minutes.

Validated findings with PoCs - every vulnerability includes a working proof-of-concept exploit and reproduction steps
One-click autofix - AI-generated security patches as ready-to-merge pull requests
Continuous pentesting - always-on vulnerability scanning that keeps pace with your deployments
DevSecOps integrations - GitHub, GitLab, Bitbucket, Slack, Jira, Linear, and CI/CD pipelines
Continuous learning - AI that builds on past findings, adapts to your codebase, and reduces false positives over time

Start your first pentest →

✨ Features

Agentic Pentesting Tools

Strix agents come equipped with a comprehensive offensive security toolkit - the same tools used by professional penetration testers and ethical hackers:

HTTP Interception Proxy - Full request/response manipulation and analysis with Caido
Browser Exploitation - Automated browser for testing XSS, CSRF, clickjacking, and auth bypass flows
Shell & Command Execution - Interactive terminal for exploit development and post-exploitation
Custom Exploit Runtime - Python sandbox for writing and validating proof-of-concept exploits
Reconnaissance & OSINT - Automated attack surface mapping, subdomain enumeration, and fingerprinting
Static & Dynamic Code Analysis - SAST + DAST capabilities for comprehensive application security testing
Vulnerability Knowledge Base - Structured findings with CVSS scoring and OWASP classification

Comprehensive Vulnerability Scanner

Strix identifies, validates, and exploits a wide range of security vulnerabilities across the OWASP Top 10 and beyond:

Broken Access Control - IDOR, privilege escalation, auth bypass
Injection Attacks - SQL injection, NoSQL injection, OS command injection, SSTI
Server-Side Vulnerabilities - SSRF, XXE, insecure deserialization, RCE
Client-Side Attacks - XSS (stored/reflected/DOM), prototype pollution, CSRF
Business Logic Flaws - Race conditions, payment manipulation, workflow bypass
Authentication & Session - JWT attacks, session fixation, credential stuffing vectors
Infrastructure & Cloud - Misconfigurations, exposed services, cloud security issues
API Security - Broken authentication, mass assignment, rate limiting bypass

Graph of Agents (Multi-Agent Pentesting)

Advanced multi-agent orchestration for comprehensive automated penetration testing:

Distributed Pentesting - Specialized AI agents for recon, exploitation, and post-exploitation
Scalable Security Testing - Parallel execution across multiple targets for fast, comprehensive coverage
Dynamic Coordination - Agents share discoveries, chain vulnerabilities, and collaborate like a red team

Usage Examples

Basic Usage

# Scan a local codebase
strix --target ./app-directory

# Security review of a GitHub repository
strix --target https://github.com/org/repo

# Black-box web application assessment
strix --target https://your-app.com

Advanced Testing Scenarios

# Grey-box authenticated testing
strix --target https://your-app.com --instruction "Perform authenticated testing using credentials: user:pass"

# Multi-target testing (source code + deployed app)
strix -t https://github.com/org/app -t https://your-app.com

# Targets from a file, one target per non-empty, non-comment line
strix --target-list ./targets.txt

# White-box source-aware scan (local repository)
strix --target ./app-directory --scan-mode standard

# Focused testing with custom instructions
strix --target api.your-app.com --instruction "Focus on business logic flaws and IDOR vulnerabilities"

# Provide detailed instructions through file (e.g., rules of engagement, scope, exclusions)
strix --target api.your-app.com --instruction-file ./instruction.md

# Force PR diff-scope against a specific base branch
strix -n --target ./ --scan-mode quick --scope-mode diff --diff-base origin/main

Headless Mode

Run Strix programmatically without interactive UI using the -n/--non-interactive flag - perfect for servers and automated jobs. The CLI prints real-time vulnerability findings and the final report before exiting. Exits with non-zero code when vulnerabilities are found.

strix -n --target https://your-app.com

CI/CD (GitHub Actions)

Strix can be added to your pipeline to run a security test on pull requests with a lightweight GitHub Actions workflow:

name: strix-penetration-test

on:
  pull_request:

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Install Strix
        run: curl -sSL https://strix.ai/install | bash

      - name: Run Strix
        env:
          STRIX_LLM: ${{ secrets.STRIX_LLM }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}

        run: strix -n -t ./ --scan-mode quick

Tip

In CI pull request runs, Strix automatically scopes quick reviews to changed files. If diff-scope cannot resolve, ensure checkout uses full history (fetch-depth: 0) or pass --diff-base explicitly.

Configuration

export STRIX_LLM="openai/gpt-5.4"
export LLM_API_KEY="your-api-key"

# Optional
export LLM_API_BASE="your-api-base-url"  # if using a local model, e.g. Ollama, LMStudio
export PERPLEXITY_API_KEY="your-api-key"  # for search capabilities
export STRIX_REASONING_EFFORT="high"  # control thinking effort (default: high, quick scan: medium)

Note

Strix automatically saves your configuration to ~/.strix/cli-config.json, so you don't have to re-enter it on every run.

Recommended models for best results:

OpenAI GPT-5.4 - openai/gpt-5.4
Anthropic Claude Sonnet 4.6 - anthropic/claude-sonnet-4-6
Google Gemini 3 Pro Preview - vertex_ai/gemini-3-pro-preview

See the LLM Providers documentation for all supported providers including Vertex AI, Bedrock, Azure, and local models.

Enterprise Pentesting

Get the same Strix experience with enterprise-grade controls: SSO (SAML/OIDC), custom compliance-ready penetration testing reports (SOC 2, ISO 27001, PCI DSS), dedicated support & SLA, custom deployment options (VPC/self-hosted), BYOK model support, and tailored AI pentesting agents optimized for your environment. Learn more.

Documentation

Full documentation is available at docs.strix.ai - including detailed guides for usage, CI/CD integrations, skills, and advanced configuration.

Contributing

We welcome contributions of code, docs, and new skills - check out our Contributing Guide to get started or open a pull request/issue.

Join Our Community

Have questions? Found a bug? Want to contribute? Join our Discord!

Support the Project

Love Strix? Give us a ⭐ on GitHub!

Acknowledgements

Strix builds on the incredible work of open-source projects like LiteLLM, Caido, Nuclei, Playwright, and Textual. Huge thanks to their maintainers!

Warning

Only test apps you own or have permission to test. You are responsible for using Strix ethically and legally.

Panniantong/Agent-Reach

Give your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.

👁️ Agent Reach

给你的 AI Agent 一键装上互联网能力

当下最稳的接入方式，替你选好、装好、体检好——接入方式会换代，你不用操心

快速开始 · English · 日本語 · 한국어 · 支持平台 · 设计理念

为什么需要 Agent Reach？

AI Agent 已经能帮你写代码、改文档、管项目——但你让它去网上找点东西，它就抓瞎了：

📺 "帮我看看这个 YouTube 教程讲了什么" → 看不了，拿不到字幕
🐦 "帮我搜一下推特上大家怎么评价这个产品" → 搜不了，Twitter API 要付费
📖 "去 Reddit 上看看有没有人遇到过同样的 bug" → 403 被封，服务器 IP 被拒
📕 "帮我看看小红书上这个品的口碑" → 打不开，必须登录才能看
📺 "B站上有个技术视频，帮我总结一下" → 拿不到，通用下载工具被 B站风控全面拦截
🔍 "帮我在网上搜一下最新的 LLM 框架对比" → 没有好用的搜索，要么付费要么质量差
🌐 "帮我看看这个网页写了啥" → 抓回来一堆 HTML 标签，根本没法读
📦 "这个 GitHub 仓库是干嘛的？Issue 里说了什么？" → 能用，但认证配置很麻烦
📡 "帮我订阅这几个 RSS 源，有更新告诉我" → 要自己装库写代码

这些不难实现，但是需要自己折腾配置

每个平台都有自己的门槛——要付费的 API、要绕过的封锁、要登录的账号、要清洗的数据。你要一个一个去踩坑、装工具、调配置，光是让 Agent 能读个推特就得折腾半天。

Agent Reach 把这件事变成一句话：

帮我安装 Agent Reach：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md

复制给你的 Agent，几分钟后它就能读推特、搜 Reddit、看 YouTube、刷小红书了。

已经装过了？更新也是一句话：

帮我更新 Agent Reach：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md

⭐ Star 这个项目，我们会持续追踪各平台的变化、接入新的渠道。你不用自己盯——平台封了我们修，有新渠道我们加。

✅ 在你用之前，你可能想知道


💰 完全免费	所有工具开源、所有 API 免费。唯一可能花钱的是服务器代理（$1/月），本地电脑不需要
🔒 隐私安全	Cookie 只存在你本地，不上传不外传。代码完全开源，随时可审查
🔄 持续换代	每个平台都是「首选 + 备选」多后端路由。某个接入方式失效了，我们换下一个，你无感（2026-06 实例：yt-dlp 被 B站风控封死 → 已切换 bili-cli，用户零操作）
🤖 兼容所有 Agent	Claude Code、OpenClaw、Cursor、Windsurf……任何能跑命令行的 Agent 都能用
🩺 自带诊断	`agent-reach doctor` 一条命令告诉你哪个通、哪个不通、怎么修

支持的平台

平台	装好即用	配置后解锁	怎么配
🌐 网页	阅读任意网页	—	无需配置
📺 YouTube	字幕提取 + 视频搜索	—	无需配置
📡 RSS	阅读任意 RSS/Atom 源	—	无需配置
🔍 全网搜索	—	全网语义搜索	自动配置（MCP 接入，免费无需 Key）
📦 GitHub	读公开仓库 + 搜索	私有仓库、提 Issue/PR、Fork	告诉 Agent「帮我登录 GitHub」
🐦 Twitter/X	读单条推文	搜索推文、浏览时间线、读长文	告诉 Agent「帮我配 Twitter」
📺 B站	搜索 + 视频详情（bili-cli，无需登录）	字幕（OpenCLI）	告诉 Agent「帮我配 B站」
📖 Reddit	—（没有零配置路径：匿名接口已被封）	搜索 + 读帖子和评论	桌面装 OpenCLI 用浏览器登录态；或 rdt-cli + Cookie
📘 Facebook	—	搜索、主页、Feed、群组列表	桌面装 OpenCLI（复用 Chrome 登录态）
📷 Instagram	—	用户搜索、Profile、用户最近帖子、Explore	桌面装 OpenCLI（复用 Chrome 登录态）
📕 小红书	—	搜索、阅读、评论	桌面装 OpenCLI（刷过小红书即可用）；服务器用 xiaohongshu-mcp 扫码
💼 LinkedIn	Jina Reader 读公开页面	Profile 详情、公司页面、职位搜索	告诉 Agent「帮我配 LinkedIn」
💻 V2EX	热门帖子、节点帖子、帖子详情+回复、用户信息	—	无需配置
📈 雪球	股票行情、搜索股票、热门帖子、热门股票排行	—	告诉 Agent「帮我配雪球」
🎙️ 小宇宙播客	—	播客音频转文字（Whisper 转录，免费 Key）	告诉 Agent「帮我配小宇宙播客」

不知道怎么配？不用查文档。 直接告诉 Agent「帮我配 XXX」，它知道需要什么、会一步一步引导你。

🍪 需要 Cookie/登录态的平台（Twitter、小红书、Reddit、Facebook、Instagram 等），优先让用户在自己的浏览器里登录。OpenCLI 复用 Chrome 登录态；传统 CLI 才需要 Cookie-Editor 导出 Cookie。

🔒 Cookie 只存在你本地，不上传不外传。代码完全开源，随时可审查。 💻 本地电脑不需要代理。代理只有部署在服务器上才需要（~$1/月）。

快速上手

⚠️ OpenClaw 用户请先确认 exec 权限已开启

Agent Reach 依赖 Agent 执行 shell 命令（pip install、mcporter、twitter 等）。如果你的 OpenClaw 使用了默认的 messaging 工具配置，Agent 将无法执行命令。安装前请先开启 exec 权限：
openclaw config set tools.profile "coding"
或在 ~/.openclaw/openclaw.json 中设置 "tools": { "profile": "coding" }。设置后重启 Gateway（openclaw gateway restart）并开启新对话即可。其他平台（Claude Code、Cursor、Windsurf 等）不受此限制。

复制这句话给你的 AI Agent（Claude Code、OpenClaw、Cursor 等）：

帮我安装 Agent Reach：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md

就这一步。Agent 会自己完成剩下的所有事情。

🔄 已安装过？ 更新也是一句话：

帮我更新 Agent Reach：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md

🛡️ 担心安全？ 可以用安全模式——不会自动装系统包，只告诉你需要什么：
帮我安装 Agent Reach（安全模式）：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
安装时使用 --safe 参数

它会做什么？（点击展开）

安装 CLI 工具 — pip install 装好 agent-reach 命令行（自带 yt-dlp、feedparser）
安装系统基建 — 自动检测并安装 Node.js、gh CLI、mcporter
配置搜索引擎 — 通过 MCP 接入 Exa（免费，无需 API Key）
检测环境 — 判断是本地电脑还是服务器，给出对应的配置建议
注册 SKILL.md — 在 Agent 的 skills 目录安装使用指南，以后 Agent 遇到"全网调研"、"搜推特"、"看视频"这类需求，会自动知道该调哪个上游工具
问你要不要更多 — 默认只激活 6 个零配置渠道；小红书、Twitter、Reddit、Facebook、Instagram 这些需要登录态的，Agent 会列菜单问你要哪些，点名才装

安装完之后，agent-reach doctor 一条命令告诉你每个渠道的状态、当前走哪条路。

装好就能用

不需要任何配置，告诉 Agent 就行：

"帮我看看这个链接" → curl https://r.jina.ai/URL 读任意网页
"这个 GitHub 仓库是做什么的" → gh repo view owner/repo
"这个 YouTube 视频讲了什么" → yt-dlp 提取字幕
"B站搜一下 AI 教程" → bili search（无需登录）
"全网搜一下 LLM 框架对比" → Exa 语义搜索
"订阅这个 RSS" → feedparser 解析

不需要记命令。 Agent 读了 SKILL.md 之后自己知道该调什么。需要登录的平台（小红书、Twitter、Reddit、Facebook、Instagram），告诉 Agent「帮我配 XXX」即可解锁。

能力边界：读内容 vs 操作网页

有些任务超出"读"的范围：登录后的网页操作、表单提交、多账号隔离、并行浏览器会话、自动化流程中的登录、验证、风控提示等高摩擦环节的人工接手。这类"动手"场景，可以配合 BrowserAct 这类浏览器自动化工具——30+ 预制平台技能，支持 Claude Code / OpenClaw / Cursor 等主流 Agent。

设计理念

Agent Reach 是一个能力层（capability layer），不是又一个工具。

它比任何具体实现高一层——负责选型、安装、体检、路由，不负责底层读取本身。读取由 Agent 直接调用上游工具完成，没有包装层。

你给一个新 Agent 装环境的时候，总要花时间去找工具、装依赖、调配置——Twitter 用什么读？Reddit 怎么登录？小红书的 CLI 停更了换什么？每次都要重新踩一遍。Agent Reach 做的事情很简单：当下最稳的接入方式，我们替你选好、装好、体检好。接入方式会换代（2026 年 3 月一批单平台 CLI 集体停更，我们换了路由），你不用操心。

🔌 每个平台 = 首选 + 备选的有序后端列表

换接入方式 = 调整列表顺序，不是重写代码。agent-reach doctor 会告诉你每个平台当前在用哪个后端。

channels/
├── web.py          → Jina Reader
├── twitter.py      → twitter-cli ▸ OpenCLI ▸ bird
├── youtube.py      → yt-dlp
├── github.py       → gh CLI
├── bilibili.py     → bili-cli ▸ OpenCLI ▸ 搜索 API（yt-dlp 已被 B站风控封死，退役）
├── reddit.py       → OpenCLI ▸ rdt-cli（无零配置路径，必须登录态）
├── facebook.py     → OpenCLI（桌面浏览器登录态）
├── instagram.py    → OpenCLI（桌面浏览器登录态）
├── xiaohongshu.py  → OpenCLI ▸ xiaohongshu-mcp ▸ xhs-cli
├── linkedin.py     → linkedin-mcp ▸ Jina Reader
├── rss.py          → feedparser
├── exa_search.py   → Exa via mcporter
└── __init__.py     → 渠道注册（doctor 检测用）

每个渠道文件按序真实探测各候选后端（不只是看命令存不存在），第一个完整可用的当选；坏掉的会给出修复处方。实际的读取和搜索由 Agent 直接调用上游工具完成。

当前选型

场景	首选	备选	为什么这么选
读网页	Jina Reader	—	免费，不需要 API Key
读推特	twitter-cli	OpenCLI	实测搜索稳定；OpenCLI 走浏览器登录态兜底
Reddit	OpenCLI（桌面）	rdt-cli	匿名接口已被封、官方 API 审批制——只剩登录态路线
Facebook	OpenCLI（桌面）	—	Graph API/Groups API 权限收紧；浏览器登录态是当前最实用路径
Instagram	OpenCLI（桌面）	官方 Graph API（Business/Creator + 审批）	instaloader 类路径不稳定；OpenCLI 复用真实浏览器会话
YouTube 字幕 + 搜索	yt-dlp	—	154K Star，YouTube 仍是最佳（注意：不再用于 B站）
B站	bili-cli	OpenCLI ▸ 搜索 API	yt-dlp 被 B站风控 412 封死（2026-06 实测），bili-cli 无登录可搜可读
搜全网	Exa via mcporter	—	AI 语义搜索，MCP 接入免 Key
GitHub	gh CLI	—	官方工具，认证后完整 API 能力
读 RSS	feedparser	—	Python 生态标准选择
小红书	OpenCLI（桌面）	xiaohongshu-mcp（服务器）▸ xhs-cli	xhs-cli 作者已转投 OpenCLI（24K Star）；浏览器登录态零摩擦
LinkedIn	linkedin-scraper-mcp	Jina Reader	MCP 服务，浏览器自动化

📌 这些都是「当前选型」，基于真机实测定期复核。某条路失效了我们换下一条——agent-reach doctor 永远告诉你现在走的是哪条。

安全性

Agent Reach 在设计上重视安全：

措施	说明
🔒 凭据本地存储	Cookie、Token 只存在你本机 `~/.agent-reach/config.yaml`，文件权限 600（仅所有者可读写），不上传不外传
🛡️ 安全模式	`agent-reach install --safe` 不会自动修改系统，只列出需要什么，由你决定装不装
👀 完全开源	代码透明，随时可审查。所有依赖工具也是开源项目
🔍 Dry Run	`agent-reach install --dry-run` 预览所有操作，不做任何改动
🧩 可插拔架构	不信任某个组件？换掉对应的 channel 文件即可，不影响其他

🍪 Cookie 安全建议

⚠️ 封号风险提醒： 使用 Cookie 登录的平台（Twitter、小红书等），通过脚本/API 调用存在被平台检测并封号的风险。请务必使用专用小号，不要用你的主账号。

需要 Cookie 或登录态的平台（Twitter、小红书、Reddit、Facebook、Instagram 等）建议使用专用小号，不要用主账号。原因有二：

封号风险 — 平台可能检测到非正常浏览器的 API 调用行为，导致账号被限制或封禁
安全风险 — Cookie 等同于完整登录权限，用小号可以在凭据泄露时限制影响范围

📦 安装方式

方式	命令	适合场景
一键全自动（默认）	`agent-reach install --env=auto`	个人电脑、开发环境
安全模式	`agent-reach install --env=auto --safe`	生产服务器、多人共用机器
仅预览	`agent-reach install --env=auto --dry-run`	先看看会做什么

🗑️ 卸载

agent-reach uninstall

会清除：~/.agent-reach/（含所有 token/cookie）、各 Agent 的 skill 文件、mcporter 中的 MCP 配置。

# 只预览，不实际删除
agent-reach uninstall --dry-run

# 只删 skill 文件，保留 token 配置（重装时用）
agent-reach uninstall --keep-config

卸载 Python 包本身：pip uninstall agent-reach

⭐ 为什么值得 Star

这个项目我自己每天在用，所以我会一直维护它。

有新需求或者大家提了想要的渠道，我会陆续加上
每个渠道我会尽量保证能用、好用、免费
平台改了反爬或者 API 变了，我会想办法解决

为 Web 4.0 基建贡献一份自己的力量。

Star 一下，下次需要的时候能找到。⭐

致谢

OpenCLI · twitter-cli · rdt-cli · xiaohongshu-mcp · xhs-cli · bili-cli · yt-dlp · Jina Reader · Exa · mcporter · feedparser · linkedin-scraper-mcp

联系

📧 Email: pnt01@foxmail.com
🐦 Twitter/X: @Neo_Reidlab

业务合作 / Agent 落地

我正在承接 Agent 相关的定制与落地合作。

如果你在企业生产、运营、市场、投研、数据处理、内容处理或其他业务流程里，有希望用 Agent 自动化的环节，欢迎加我微信交流。

不需要你已经想清楚方案。只要你有真实流程、真实问题或真实需求，我可以一起判断 Agent 能不能解决、怎么做。

加好友请备注：业务 + 你想让 Agent 帮你做什么

Builder 也欢迎备注：Builder + 你在做什么

只是想进交流群，备注：加群

Bug 反馈和功能请求请用 GitHub Issues，更容易跟踪。

License

MIT

友情链接

方舟 Agent Plan 模型订阅套餐 — 集成了包含 Doubao-Seed、Doubao-Seedance、Doubao-Seedream 等在内的字节跳动自研 SOTA 级模型，覆盖文本、代码、图像、视频等多模态任务。最新支持 MiniMax-M3、DeepSeek-V4 系列、GLM-5.2、Doubao-Seed-2.0 系列、Kimi-K2.6 等模型，工具不限。超全模态模型与 Harness 升级一步到位，深度支持 Agent 框架与 AI 编程工具。一次订阅，可以为不同任务切换合适的 AI 引擎。

腾讯云 OpenClaw — 在腾讯云Lighthouse秒级部署OpenClaw全能助手，可通过对话丝滑接入Agent Reach，给你的OpenClaw一键装上互联网能力。

AtomGit 镜像 — Agent Reach 的 AtomGit 同步镜像，便于国内访问与克隆。

Star History

stablyai/orca

Orca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop and mobile.

Orca

_{Español · Português · 中文 · 日本語 · 한국어}

The AI Orchestrator for 100x builders.
Run Codex, ClaudeCode, OpenCode or Pi side-by-side — each in its own worktree, tracked in one place.

Download Orca

Features

Mobile Companion Monitor and steer your agents from your phone — get notified when an agent finishes and send follow-ups from anywhere. iOS App Store · TestFlight · Android APK 0.0.31 · Docs →
Parallel Worktrees Fan one prompt across five agents, each in its own isolated git worktree — compare the results and merge the winner. Docs →
Terminal Splits Ghostty-class terminals with WebGL rendering, infinite splits, and scrollback that survives restarts. Docs →
Design Mode Click any UI element in a real Chromium window to send its HTML, CSS, and a cropped screenshot straight into your agent's prompt. Docs →
GitHub & Linear, Native Browse PRs, issues, and project boards in-app — open a worktree from any task and review without a context switch. Docs →
SSH Worktrees Run agents on a beefy remote box with full file editing, git, and terminals — auto-reconnect and port forwarding included. Docs →
Annotate AI Diffs Drop comments on any diff line and ship them back to the agent — review, edit, and commit without leaving Orca. Docs →
Drag Files to Agents VS Code's editor with autosave everywhere — drag files or images straight into an agent prompt. Docs →
Orca CLI Agents drive Orca too — script every workflow with `orca worktree create`, `snapshot`, `click`, and `fill`. Docs →

Also in the box:

Quick open — Search across worktrees, files, agents, commands, and repo context without leaving your flow.
Account switcher & usage tracking — See Claude and Codex usage and rate-limit resets, and hot-swap accounts without re-logging in.
Rich repo previews — Preview Markdown, images, PDFs, and repo docs in the workspace.
Computer Use — Let agents operate desktop apps and visible UI when a workflow needs real interaction.
Notifications and unread state — Know when an agent finishes or needs attention, then mark threads unread to come back later.
And many, many more — we ship daily, so this list is perpetually behind. The changelog is the real feature list.

Supported Agents

Works with any CLI agent — if it runs in a terminal, it runs in Orca.

Claude Code Codex Grok Cursor GitHub Copilot OpenCode MiMo Code Amp OpenClaude Antigravity Pi oh-my-pi Hermes Agent Devin Goose Auggie Autohand Code Charm Cline Codebuff Command Code Continue Droid Kilocode Kimi Kiro Mistral Vibe Qwen Code Rovo Dev + any CLI agent

Install

Desktop — macOS, Windows, Linux

Download from onOrca.dev
Or grab a build directly: macOS Apple Silicon · macOS Intel · Windows (.exe) · Linux AppImage · All builds
Running orca serve on a headless Linux server? See the headless Linux server guide.

Or via a package manager:

# macOS (Homebrew)
brew install --cask stablyai/orca/orca

# Arch Linux (AUR) — or stably-orca-git to build from source
yay -S stably-orca-bin

Mobile Companion — iOS, Android

Pair with your desktop app to monitor and steer your agents from your phone.

iOS: Download on the App Store or join TestFlight
Android: Download APK 0.0.31

Community & Support

Discord: Join the community on Discord.
Twitter / X: Follow @orca_build for updates and announcements.
WeChat: Scan the QR code to join the community. If the first group is full, use the backup group.
Feedback & Ideas: We ship fast. Missing something? Request a new feature.
Privacy: See the privacy & telemetry docs for what anonymous usage data Orca collects and how to opt out.
Show Support: Star this repo to follow along with our daily ships.

Developing

Want to contribute or run locally? See our CONTRIBUTING.md guide.

Signed Builds

Windows code signing sponored/provided by SignPath.io, certificate by SignPath Foundation.

License

Orca is free and open source under the MIT License.

ogulcancelik/herdr

agent multiplexer that lives in your terminal.

herdr

herdr.dev · install · quick start · docs · sponsors

https://github.com/user-attachments/assets/043ec09f-4bdd-41d5-aee0-8fda6b83e267

agent multiplexer that lives in your terminal.

every agent at a glance — blocked, working, done. real terminal views, not a wrapped interpretation.
detach, agents keep running — reattach from any terminal, or over ssh. sessions survive restarts.
agents can use herdr too — a pure socket api: agents spawn panes, read output, wait on each other. agent skill →
keyboard and mouse, both first-class — tmux-style prefix keys and click, drag, split. pick per moment, not per tool.
plugins — extend panes and workflows. browse the marketplace →
one rust binary, no electron — runs in whatever terminal you already use.

install

curl -fsSL https://herdr.dev/install.sh | sh

or brew install herdr · mise use -g herdr · windows beta: powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex" · binaries

then start it where the work lives:

herdr

run your agents, split panes, walk away. ctrl+b q detaches, herdr reattaches. quick start →

docs

everything lives at herdr.dev/docs: quick start · concepts · supported agents · keyboard · configuration · session state · remote · integrations · plugins · socket api

agent instructions

if you are an ai agent helping with this repository, read AGENTS.md before making changes and read CONTRIBUTING.md before opening issues or PRs.

development

git clone https://github.com/ogulcancelik/herdr
cd herdr
cargo build --release

just test        # unit tests
just check       # formatting, tests, and maintenance checks

license

Herdr is dual-licensed:

Open source: GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
Commercial: commercial licenses are available for organizations that cannot comply with AGPL.

Contact: hey@herdr.dev

Zackriya-Solutions/meetily

Privacy first, AI meeting assistant with 4x faster Parakeet/Whisper live transcription, speaker diarization, and Ollama summarization built on Rust. 100% local processing. no cloud required. Meetily (Meetly Ai - https://meetily.ai) is the #1 Self-hosted, Open-source Ai meeting note taker for macOS & Windows. Understand How to write meeting minutes

Privacy-First AI Meeting Assistant

Open Source • Privacy-First • Enterprise-Ready

Get latest Product updates

Website • LinkedIn • Meetily Discord • Privacy-First AI • Reddit

A privacy-first AI meeting assistant that captures, transcribes, and summarizes meetings entirely on your infrastructure. Built by expert AI engineers passionate about data sovereignty and open source solutions. Perfect for enterprises that need advanced meeting intelligence without compromising on privacy, compliance, or control.

View full Demo Video

Meetily PRO Upgrade Offer - Meetily PRO is available for users who need enhanced accuracy, advanced exports, custom summary workflows, and team-ready features. Use coupon code LAUNCH20 for 20% off until the next Meetily Community Edition release. Speaker diarization is also planned for PRO in mid-June. Explore Meetily PRO →

Table of Contents

Introduction

Meetily is a privacy-first AI meeting assistant that runs entirely on your local machine. It captures your meetings, transcribes them in real-time, and generates summaries, all without sending any data to the cloud. This makes it the perfect solution for professionals and enterprises who need to maintain complete control over their sensitive information.

Why Meetily?

While there are many meeting transcription tools available, this solution stands out by offering:

Privacy First: All processing happens locally on your device.
Cost-Effective: Uses open-source AI models instead of expensive APIs.
Flexible: Works offline and supports multiple meeting platforms.
Customizable: Self-host and modify for your specific needs.

The Privacy Problem

Meeting AI tools create significant privacy and compliance risks across all sectors:

$4.4M average cost per data breach (IBM 2024)
€5.88 billion in GDPR fines issued by 2025
400+ unlawful recording cases filed in California this year

Whether you're a defense consultant, enterprise executive, legal professional, or healthcare provider, your sensitive discussions shouldn't live on servers you don't control. Cloud meeting tools promise convenience but deliver privacy nightmares with unclear data storage practices and potential unauthorized access.

Meetily solves this: Complete data sovereignty on your infrastructure, zero vendor lock-in, and full control over your sensitive conversations.

Features

Local First: All processing is done on your machine. No data ever leaves your computer.
Real-time Transcription: Get a live transcript of your meeting as it happens.
AI-Powered Summaries: Generate summaries of your meetings using powerful language models.
Multi-Platform: Works on macOS, Windows, and Linux.
Open Source: Meetily is open source and free to use.
Flexible AI Provider Support: Choose from Ollama (local), Claude, Groq, OpenRouter, or use your own OpenAI-compatible endpoint.

Installation

🪟 Windows

Download the latest x64-setup.exe from Releases
Run the installer

🍎 macOS

Download meetily_0.4.0_aarch64.dmg from Releases
Open the downloaded .dmg file
Drag Meetily to your Applications folder
Open Meetily from Applications folder

🐧 Linux

Build from source following our detailed guides:

Quick start:

git clone https://github.com/Zackriya-Solutions/meeting-minutes
cd meeting-minutes/frontend
pnpm install
./build-gpu.sh

Key Features in Action

🎯 Local Transcription

Transcribe meetings entirely on your device using Whisper or Parakeet models. No cloud required.

📥 Import & Enhance `Beta`

Import existing audio files to generate transcripts, or enhance to re-transcribe any recorded meeting with a different model or language, all processed locally.

Contributed by Jeremi Joslin, improved by Vishnu P S and Mohammed Safvan

🤖 AI-Powered Summaries

Generate meeting summaries with your choice of AI provider. Ollama (local) is recommended, with support for Claude, Groq, OpenRouter, and OpenAI.

🔒 Privacy-First Design

All data stays on your machine. Transcription models, recordings, and transcripts are stored locally.

🌐 Custom OpenAI Endpoint Support

Use your own OpenAI-compatible endpoint for AI summaries. Perfect for organizations with custom AI infrastructure or preferred providers.

🎙️ Professional Audio Mixing

Capture microphone and system audio simultaneously with intelligent ducking and clipping prevention.

⚡ GPU Acceleration

Built-in support for hardware acceleration across platforms:

macOS: Apple Silicon (Metal) + CoreML
Windows/Linux: NVIDIA (CUDA), AMD/Intel (Vulkan)

Automatically enabled at build time - no configuration needed.

System Architecture

Meetily is a single, self-contained application built with Tauri. It uses a Rust-based backend to handle all the core logic, and a Next.js frontend for the user interface.

For more details, see the Architecture documentation.

For Developers

If you want to contribute to Meetily or build it from source, you'll need to have Rust and Node.js installed. For detailed build instructions, please see the Building from Source guide.

Meetily Pro

Meetily PRO is a professional-grade solution with enhanced accuracy and advanced features for serious users and teams. Built on a different codebase with superior transcription models and enterprise-ready capabilities.

Community Thank-You Offer

Meetily Community Edition will remain free and open source. PRO exists for users and teams who want a more advanced meeting workflow, including higher transcription accuracy, custom summary templates, advanced exports, auto-meeting detection, and self-hosted deployment options.

For the community that helped Meetily grow, we are making the upgrade easier: use coupon code LAUNCH20 for 20% off Meetily PRO until the next Meetily Community Edition release.

Speaker diarization is planned for mid-June, bringing automatic speaker separation to PRO meetings.

Key Advantages Over Community Edition:

Enhanced Accuracy: Superior transcription models for professional-grade accuracy
Custom Summary Templates: Tailor summaries to your specific workflow and needs
Advanced Export Options: PDF, DOCX, and Markdown exports with formatting
Auto-detect and Join Meetings: Automatic meeting detection and joining
Speaker Identification: Distinguish between speakers automatically (Coming Soon)
Chat with Meetings: AI-powered meeting insights and queries (Coming Soon)
Calendar Integration: Seamless integration with your calendar (Coming Soon)
Self-Hosted Deployment: Deploy on your own infrastructure for teams
GDPR Compliance Built-In: Privacy by design architecture with complete audit trails
Priority Support: Dedicated support for PRO users

Who is PRO for?

Professionals who need the highest accuracy for critical meetings
Teams and organizations (2-100 users) requiring self-hosted deployment
Power users who need advanced export formats and custom workflows
Compliance-focused organizations requiring GDPR readiness

Note: Meetily Community Edition remains free & open source forever with local transcription, AI summaries, and core features. PRO is a separate professional solution for users who need enhanced accuracy and advanced capabilities.

For organizations needing 100+ users or managed compliance solutions, explore Meetily Enterprise.

Learn more about pricing and features: https://meetily.ai/pro/

Contributing

We welcome contributions from the community! If you have any questions or suggestions, please open an issue or submit a pull request. Please follow the established project structure and guidelines. For more details, refer to the CONTRIBUTING.md file.

Thanks for all the contributions. Our community is what makes this project possible.

License

MIT License - Feel free to use this project for your own purposes.

Acknowledgments

We borrowed some code from Whisper.cpp.
We borrowed some code from Screenpipe.
We borrowed some code from transcribe-rs.
Thanks to NVIDIA for developing the Parakeet model.
Thanks to istupakov for providing the ONNX conversion of the Parakeet model.

Star History

diegosouzapw/OmniRoute

Never stop coding. Free AI gateway: one endpoint, 231+ providers (50+ free), connect Claude Code, Codex, Cursor, Cline & Copilot to FREE Claude/GPT/Gemini. RTK+Caveman stacked compression saves 15-95% tokens, smart auto-fallback, MCP/A2A, multimodal APIs, Desktop/PWA.

🚀 OmniRoute — The Free AI Gateway

Never stop coding. Connect every AI tool to 250 providers — 90+ free — through one endpoint.

Plug Claude Code, Codex, Cursor, Cline, Copilot & Antigravity into FREE Claude / GPT / Gemini. Auto-fallback.

RTK + Caveman compression saves 15–95% tokens. Never hit limits.

~1.6B documented free tokens/month — up to ~2.1B in your first month with signup credits — aggregated across the free tiers, plus a long tail of permanently-free, no-cap providers, and the compression above stretches every one further. (how we count →)

⭐ Star the repo if OMNIROUTE helped you save money and make your work easier.

💬 Join the community

Questions, provider tips, roadmap & support → Discord · Telegram · WhatsApp 🌍 Global / 🇧🇷 Brasil

🧩 Available

🚀 Quick Start • 🎯 Combos • 🌐 Providers • 🔌 CLI & MCP • 🗜️ Compression • 🌍 Website

💥 The Promise • 🤔 Why • 🏆 What Sets Apart • 🤖 Compatible CLIs • 🖥️ Where It Runs • 🔒 Private • 🎬 In Action • 📚 Explore More • 📧 Support

🌐 In 42+ languages

💰 ~1.6B Free Tokens / Month

Stacking free tiers by hand is painful — dozens of SDKs, dozens of rate limits, and no idea how much you actually have. OmniRoute aggregates the documented free tiers of 40+ provider pools / 500+ models into one honest number and shows it live on the dashboard (/dashboard/free-tiers).

~1.6B free tokens / month (steady) — and up to ~2.1B in your first month with signup credits.
Pool-deduped, honest — we count each shared free pool once, so the headline isn't inflated by rate-limit ceilings the way multi-billion competitor claims are. (Counting every rate limit 24/7 would read ~10B; we don't publish that.)
Plus the un-countable — permanently-free, no-token-cap providers (SiliconFlow, Z.AI GLM-Flash, Kilo, OpenCode Zen…) and a $10 OpenRouter top-up that unlocks +24M/mo, both surfaced separately so they never inflate the headline.
Per-model breakdown, live used / remaining for the current month, and a transparent terms flag per provider.

Preview mockup — a real screenshot lands once the /dashboard/free-tiers page is validated. Full methodology (pool dedupe, credit tiers, provider terms): docs/reference/FREE_TIERS.md.

💥 The Promise

One endpoint. 250 providers. Never stop building — and let OmniRoute pick the cheapest one that works.

🚫 Never hit limits _{Auto-fallback across 250 providers in milliseconds. Quota out? Next provider takes over — zero downtime.}	💸 Save up to 95% tokens _{RTK + Caveman stacked compression cuts 15–95% of eligible tokens (~89% avg on tool-heavy sessions).}	🆓 $0 to start _{90+ providers with a free tier, 11 free forever (Kiro, Qoder, Pollinations, LongCat…). No card needed.}
🔌 Every tool works _{24+ coding agents — Claude Code, Codex, Cursor, Cline, Copilot, Antigravity — through one config.}	🧩 One endpoint _{OpenAI ↔ Claude ↔ Gemini ↔ Responses API translation. Point any tool at /v1 and it just works.}	🛡️ Production-grade _{Circuit breakers, TLS stealth, MCP (94 tools), A2A, memory, guardrails, evals. 21,000+ tests.}

🤔 Why OmniRoute?

Stop juggling 10 dashboards, dead API keys, and surprise bills.

❌ The daily pain	✅ How OmniRoute fixes it
📉 Subscription quota expires unused every month	Maximize subscriptions — track quota, use every token before reset
🛑 Rate limits stop you mid-coding	4-tier auto-fallback — Subscription → API → Cheap → Free, in milliseconds
🔥 Tool outputs (`git diff`, `grep`, logs) burn tokens	RTK + Caveman compression — save 15–95% eligible tokens per request
💸 Expensive APIs ($20–50/mo per provider)	Cost-optimized routing — auto-route to the cheapest viable model
🧰 Each AI tool wants its own setup	One endpoint, every tool, one dashboard
🌍 AI blocked in your country	3-level proxy + TLS fingerprint stealth — use AI from anywhere

┌──────────────────────────────────────────────────────────┐
│        Your IDE / CLI  (Claude Code, Cursor, Cline…)       │
└─────────────────────────┬──────────────────────────────────┘
                          │ http://localhost:20128/v1
                          ▼
┌──────────────────────────────────────────────────────────┐
│                  OmniRoute — Smart Router                  │
│  RTK + Caveman compression · 18 routing strategies         │
│  Circuit breakers · TLS stealth · MCP · A2A · Guardrails   │
└─────────────────────────┬──────────────────────────────────┘
        ┌─────────────┬────┴────────┬─────────────┐
        ▼ Tier 1      ▼ Tier 2      ▼ Tier 3       ▼ Tier 4
   SUBSCRIPTION     API KEY        CHEAP          FREE
   Claude Code,     DeepSeek,      GLM $0.5,      Kiro, Qoder,
   Codex, Copilot   Groq, xAI      MiniMax $0.2   Pollinations
   quota out? ───▶  budget hit? ─▶ budget hit? ─▶ always on

🎯 Combos — The Flagship

A combo is a chain of models OmniRoute routes across automatically. Quota runs out, a provider fails, or costs spike — the combo silently slides to the next model. This is what makes OmniRoute unbreakable. 🛡️

⚡ Zero-config — just use `auto`

No combo to create. Set your model to auto (or a variant) and OmniRoute builds a virtual combo from your connected providers, scored live:

Model ID	What it optimizes for
`auto`	🎯 Balanced default (LKGP — sticks to your last good provider)
`auto/coding`	🧑‍💻 Quality-first weights for code generation
`auto/fast`	⚡ Lowest latency first
`auto/cheap`	💰 Cheapest per token first
`auto/offline`	🔋 Most quota / rate-limit headroom first
`auto/smart`	🔭 Quality-first + 10% exploration to discover better models

🔀 Or build your own — 18 routing strategies

All 18 strategies — mix & match per combo step:

#	Strategy	What it does
1	`priority`	First-target ordered list — drain each before the next 🥇
2	`fill-first`	Fill each target's quota fully before moving on
3	`weighted`	Weighted random by per-target weight
4	`round-robin`	Cycle through targets in order
5	`p2c`	Power-of-two-choices random load balancing
6	`least-used`	Pick the target with the lowest current load
7	`random`	Uniform random pick (deduplicated)
8	`strict-random`	Random without de-duplicating repeats 🎲
9	`cost-optimized`	Minimize $ per request from live catalog pricing 💸
10	`headroom`	Pick the target with the most remaining quota
11	`reset-window`	Prefer the target whose quota window resets soonest
12	`reset-aware`	Rank by quota reset time — short windows first 📊
13	`context-relay`	Hand off context across targets for long conversations 🧠
14	`context-optimized`	Pick the best fit for the current context size
15	`lkgp`	Last-Known-Good Path — sticky to the last successful target
16	`auto`	12-factor live scoring across every connection 🤖
17	`fusion`	Fan out to a panel of models + a judge synthesizes one answer 🧬
18	`pipeline`	Chain steps — each target's output feeds the next one 🔗

_{The Auto-Combo engine scores every candidate on 12 factors (health, quota, cost, latency, success rate, freshness…) — see docs/routing/AUTO-COMBO.md.}

⚖️ Quota-Share — split one subscription across a team ✨ NEW

Running several keys against the same upstream account (one Codex Pro plan, one Kimi key, one GLM Coding seat)? A burst on one key can burn the whole 5-hour / hourly quota and lock everyone else out. Quota-Share distributes a provider's time-based quota fairly across the keys in a pool — and it's work-conserving, so an idle member's slice is lent out instead of wasted.

Knob	What it controls
⚖️ Allocation weight	each key's slice of the pool — e.g. `50 / 30 / 20`
📐 Dimensions	track `%` · requests · tokens · `$`, per 5h / 7d / per-model window
🚦 Policy	`hard` (block over share) · `soft` (deprioritize) · `burst` (use idle headroom)
🧱 Cap	absolute ceiling per key, independent of mode

Pool "team-codex"   ·   1 Codex Pro account   ·   3 keys   ·   5-hour window
  ├─ alice    weight 50  ██████████░░░░░░░░░░   ≤ 50% of the shared 5h quota
  ├─ bob      weight 30  ██████░░░░░░░░░░░░░░   ≤ 30%
  └─ ci-bot   weight 20  ████░░░░░░░░░░░░░░░░   ≤ 20%
Generous mode (<50% pool used) → idle shares are lent out
Strict mode  (≥50% pool used)  → each key held to its fair share

_{Enforced in the hot path before the request leaves OmniRoute, with per-(key, model) caps + session stickiness for prompt-cache integrity (now with a per-combo / global disable toggle). 📖 Quota Sharing Engine}

🧱 Resilience is built in (3 independent layers)

Layer	Scope	What it does
🔌 Circuit breaker	whole provider	Stops hammering a provider that's failing upstream; auto-probes to recover
💤 Connection cooldown	one account / key	Skips a rate-limited key while other keys keep serving
🎯 Model lockout	provider + model	Quarantines just one quota-limited model, not the whole connection

Combo: "always-on"                         Strategy: priority
  1. cc/claude-opus-4-7   ← subscription (use it fully)
  2. cx/gpt-5.5           ← second subscription
  3. glm/glm-5.1          ← cheap backup ($0.5/1M)
  4. kr/claude-sonnet-4.5 ← FREE, unlimited (never fails)
Result: 4 layers of fallback = zero downtime

_{📖 Auto-Combo Engine · Resilience Guide}

🏆 What Sets OmniRoute Apart

Feature	OmniRoute	Other routers
🌐 Providers	250	20–100
🆓 Free providers	90+ (11 free forever)	1–5
🔀 Routing strategies	18 (priority, weighted, cost-optimized, context-relay, fusion…)	1–3
🗜️ Token compression	RTK + Caveman stacked (15–95%)	None / 20–40%
🧰 Built-in MCP server	94 tools, 3 transports, 30 scopes	Rare
🤝 A2A agent protocol	6 skills, JSON-RPC 2.0	None
🧠 Memory (FTS5 + vector)	Yes	Rare
🛡️ Guardrails (PII, injection, vision)	Yes	Rare
☁️ Cloud agents	Codex, Cursor, Devin, Jules	None
🥷 TLS fingerprint stealth	JA3/JA4 via wreq-js	None
🖥️ Multi-platform	Web · Desktop · Termux · PWA	Web only
🌍 i18n	42 locales	0–4

_{📊 Detailed comparison vs LiteLLM, OpenRouter & Portkey → docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md}

✨ What's New

Recent highlights from v3.8.20 → v3.8.47. Full history in CHANGELOG.md.

🗜️ Compression hardening — a default-on inflation guard (discard the stacked result and send the verbatim original whenever compression would grow the prompt), completed Caveman rule packs for German / French / Japanese (dedup + ultra) plus a new Chinese (文言 / wényán) input pack with zh-vs-ja auto-detection, and RTK filters for Gradle & .NET (dotnet) build output. → Compression
💸 Honest flat-rate cost — subscription / coding-plan providers (ChatGPT Web, grok-web, the Minimax / Kimi / GLM / Alibaba Coding plans, Xiaomi MiMo…) now read $0 in cost analytics instead of an inflated per-token estimate, while budget / quota / routing keep estimating unchanged. → API Reference
⚖️ Quota-Share routing — a dedicated combo strategy that spreads load across accounts by available quota: Deficit-Round-Robin scheduling, per-connection max_concurrent with cooldown-wait queueing, multi-window usage buckets (5h / 7d / per-model), per-(key, model) caps, session stickiness for prompt-cache integrity (now with a per-combo / global disable toggle), and proactive saturation from upstream token-usage headers. → Resilience Guide
🤖 One-command CLI/agent setup — a dedicated setup-* command configures each coding tool to route through OmniRoute (Claude Code, Codex, Cline, Continue, Cursor, Roo Code, Kilo Code, Crush, Goose, Qwen Code, Aider, OpenCode); omniroute launch / omniroute launch-codex are zero-config launchers. → CLI Integrations
🛰️ Remote mode — drive a remote OmniRoute from any machine with scoped access tokens (omniroute connect / omniroute contexts / omniroute tokens), plus an omniroute login antigravity helper that runs Google "native/desktop" OAuth on your own machine and pastes a credential blob into a remote/VPS install (where the loopback redirect is unreachable). → Remote Mode
🧭 Smarter auto-routing — OpenRouter-style auto/<category>:<tier> combos (e.g. auto/coding:fast, auto/reasoning:pro), a Fusion strategy (fan out to a panel of models in parallel, then synthesize via a judge), task-aware routing (best-fit connection per task type), per-request X-Route-Model override, live Arena-ELO + models.dev model intelligence, per-step account allowlists, provider-wildcard combo steps, nested combo-ref execution, sticky weighted selection, web_search-aware routing (now with per-model web-search/web-fetch interception rules), native xAI Grok /v1/responses routing, and per-request Auto-Combo controls (X-OmniRoute-Mode mode-preset override + X-OmniRoute-Budget hard USD cost ceiling, scoped to a single request). Embeddings-only and rerank-only models (JinaAI, OpenRouter custom, reranker models…) no longer disappear from the combo builder's model picker. → Auto-Combo
🗜️ Pluggable compression — an async pipeline of 10 composable engines with Compression Studios, an LLMLingua-2 ONNX engine and a heuristic/SLM two-tier Ultra, RTK, delegated Anthropic Context Editing, Output Styles (output-axis steering: terse-prose / less-code / terse-CJK), an adaptive context-budget dial (escalate only as far as needed to fit the context window), per-request x-omniroute-compression control, an opt-in offline eval harness, one-click Headroom proxy lifecycle management from the dashboard (Docker sidecar supported), a synthetic compression playground (Play lanes + A/B Compare with USD-capped fidelity verdicts), an opt-in per-step fidelity gate that rejects a lossy engine before it degrades the prompt, a best-of-N candidate encoder (GCF vs TOON — keep whichever is shorter, with an A/B bytes/token table in the studio), the vendored GCF codec updated to spec v3.2 (nested flattening — deeply-nested payloads go from ~3% to ~32% compression vs JSON), a new omniglyph engine (context-as-image, ~10× fewer tokens on the converted block), CCR ranged/grep/stats retrieval (pull an exact byte/line slice or summary of a stored block instead of re-expanding it), a unified panel with named profiles + an active-profile selector, an opt-in per-engine pipeline circuit-breaker, an opt-in LLM-tier engine (a model pass for higher-ratio semantic compression), a read-lifecycle engine that collapses superseded file reads, usage-observed prefix freeze, a graduated CCR retrieval-feedback ramp, a preserveSystemPrompt mode enum, and a drag-reorder pipeline editor in the studio. → Compression
🕵️ Transparent MITM decrypt (TPROXY) — capture & translate traffic from CLIs that ignore proxy env vars, with a per-SNI certificate authority and a trust-store installer. → MITM/TPROXY
💸 Cost telemetry everywhere — X-OmniRoute-* cost/usage headers on every endpoint (including media), a non-token cost engine, a cache-HIT X-OmniRoute-Cost-Saved header, and per-key USD spend quotas. → API Reference
🧠 Memory you control — opt-in int8 vector quantization (Qdrant + sqlite-vec), opt-in typed memory decay (aged low-value memories fade on a per-type schedule), memory off by default, and a per-request x-omniroute-no-memory header. → Memory
🛡️ Security — a prompt-injection guard across every LLM route (backed by a red-team suite), plus a free DuckDuckGo last-resort web search. → Guardrails
🖼️ New endpoints — /v1/ocr (Mistral OCR) and /v1/audio/translations (Whisper-style audio translation) round out the media API surface. → API Reference
🌍 Deployment & ops — reverse-proxy basePath deployment (OMNIROUTE_BASE_PATH, e.g. serving OmniRoute under /omniroute/), browser-language auto-detect on first visit, per-API-key device/connection tracking (IP+UA fingerprint, masked, in-memory only), root-less MITM cert trust for user-namespaced containers (OMNIROUTE_NO_SUDO), server-side configured-only / available-only filters on the Free Provider Rankings page, and Traditional Chinese (zh-TW) localization for the frontend + CLI. → Environment
🤝 More providers & agents — Cursor Cloud Agent (a 4th cloud agent), CodeBuddy CN (copilot.tencent.com), a Google Flow video-generation provider, new gateways DGrid and Pioneer AI (Fastino Labs), inbound xAI Grok translators plus Grok Build (xAI) with an OAuth import-token flow, GPT-4 / GPT-4o-mini on the GitHub Copilot provider, multi-model Factory Droid, ZenMux Free (session-cookie free tier), Alibaba DashScope text-to-video (wan2.7-t2v), a refreshed 250-provider catalog (OrcaRouter, Wafer AI, OpenAdapter, dit.ai, TokenRouter, …), Vertex AI media generation (speech/transcription/music/video), a first-class Ollama local-provider card, the SenseNova free Token Plan (chat + text-to-image), one-click account import from CLIProxyAPI (~/.cli-proxy-api/), Claude Sonnet 5 wired end-to-end, a new provider wave (Kenari, SumoPod, X5Lab, Charm Hyper, Nube.sh, b.ai, Qiniu, ModelScope, Augment/Auggie CLI, ClinePass, NVIDIA NIM image generation), Codex account import from a raw ChatGPT access token, the Requesty gateway (BYOK, ~200 free req/day), Yuanbao (web) as a cookie-session provider (DeepSeek V3/R1 + Hunyuan), the Zed hosted LLM aggregator (OAuth), Claude 5 Sonnet on the Claude Web provider, Kiro adaptive-thinking reasoning surfaced as reasoning_content, bulk API-key add for Cloudflare Workers AI, and OpenVecta (AI inference gateway). → Providers
⚡ Local performance & infra — a one-click local Redis launcher (omniroute redis up, plus a dashboard Redis panel), one-click Cloudflare Workers and Deno Deploy relay deployers wired into the proxy pool, a relay-backend selector (OMNIROUTE_RELAY_BACKEND=ts|bifrost|auto) so /v1/relay stays the stable surface while choosing the fastest backend internally, Bifrost (Go AI-gateway) and Mux (agent-orchestration daemon) promoted to first-class embedded/supervised services alongside 9Router/CLIProxyAPI, Webshare added as a paid fourth source in the free-proxy provider framework, and shorthand proxy formats + protocol header mode for bulk proxy import. → Embedded Services

🤖 Compatible CLIs & Coding Agents

One config — http://localhost:20128/v1 — and every AI IDE or CLI runs on free & low-cost models.

Claude Code	Codex CLI	Cursor	Copilot	Continue
OpenCode	Kilo Code	Droid	OpenClaw	Kiro	Command

＋ also works with · Cline · Antigravity · Windsurf · AMP · Hermes · Qwen CLI · Roo · Continue · any OpenAI-compatible tool

_{📖 Per-tool setup for all 24+ tools → docs/reference/CLI-TOOLS.md · 🧩 OpenCode plugin → @omniroute/opencode-provider}

🌐 250 AI Providers — 90+ Free

The most complete catalog of any open-source router: 250 providers, 90+ with a free tier, 11 free forever.

🏢 Every major lab — through one endpoint

_OpenAI	_Anthropic	_Gemini	_{xAI Grok}	_DeepSeek	_Mistral
_Qwen	_{Meta Llama}	_Groq	_NVIDIA	_MiniMax	_Cohere
_Perplexity	_HuggingFace	_Together	_Fireworks	_Cloudflare	_Baidu

_{…and 220+ more — every icon resolves live from the dashboard's provider catalog. 📖 Provider Reference}

🆓 Free Forever — $0, no card

AgentRouter _{GPT-5, Claude, Gemini $100 free credits}	Qoder AI _{Kimi-K2, DeepSeek-R1 Unlimited FREE}	Pollinations _{GPT-5, Claude, Llama 4 No key needed}	LongCat _{LongCat-2.0 10M tokens one-time (KYC) 🔑}
Cloudflare AI _{50+ models 10K neurons/day}	NVIDIA NIM _{129 models ~40 RPM free}	Cerebras _{Qwen3 235B 1M tokens/day}

📖 Full machine-readable catalog → docs/reference/PROVIDER_REFERENCE.md

🖥️ Where OmniRoute Runs — Anywhere

Same app, your machine, your rules. From a global npm install to your phone via Termux.

Platform	Install	Highlights
📦 npm (global)	`npm install -g omniroute`	One command, any OS
🐳 Docker	`docker run … diegosouzapw/omniroute`	Multi-arch AMD64 + ARM64
🖥️ Desktop (Electron)	`npm run electron:build`	Native window + system tray — Windows / macOS / Linux
💪 ARM	native `arm64`	Raspberry Pi, ARM servers, Apple Silicon
📱 Android (Termux)	`pkg install nodejs && npx -y omniroute`	Runs on your phone, 24/7, no root
📲 PWA	"Add to Home Screen"	Fullscreen, offline, installable from browser
🧩 OpenCode plugin	`@omniroute/opencode-provider`	Native OpenCode integration
🛠️ From source	`npm install && npm run dev`	Hack on it, contribute

_{📖 Docker Guide · Desktop · Termux · PWA · OpenCode}

🔒 Private & Local-First

Your keys, your machine, your data. OmniRoute is a local proxy — it never phones home.

🏠 Runs 100% on your hardware — npm, Docker, desktop, or your phone. No OmniRoute cloud sits in the request path.
🔐 Credentials encrypted at rest — API keys & OAuth tokens sealed with AES-256-GCM.
🚫 Zero telemetry by default — your prompts go only to the providers you choose, nowhere else.
🛡️ Hardened gateway — API-key scoping, IP filtering, rate limits, prompt-injection guard, loopback-only process routes.
📜 MIT licensed & fully open-source — audit every line, self-host forever.

_{📖 Authorization · Guardrails · Compliance}

🔌 Full CLI + A2A & MCP

OmniRoute isn't just a server — it's a full command-line cockpit with 80+ commands, plus open agent protocols so an AI agent can drive OmniRoute by itself.

⌨️ A real CLI (not just `start`)

omniroute               # serve gateway + dashboard (port 20128)
omniroute chat          # interactive TUI chat client (slash: /model /combo /skill /memory)
omniroute setup         # guided first-run wizard
omniroute doctor        # diagnose providers, ports, native deps

🛰️ Remote mode — run the CLI here, OmniRoute on a VPS

OmniRoute on a server? Drive it from your laptop with the same CLI. Log in once with a scoped access token; every command then targets the remote.

omniroute connect 192.168.0.15            # password → scoped token, saved as a context
omniroute models list                     # ← runs against the REMOTE server
omniroute configure codex                 # ← picks a remote model, writes a local Codex profile
omniroute tokens create --name ci --scope read   # mint narrower tokens for other machines
omniroute contexts use default            # ← switch back to the local server

Tokens are scoped read / write / admin; process-spawning routes stay loopback-only. _{📖 Remote Mode}

providers · oauth · keys · combo · nodes · models · cache · compression · cost · usage · quota · health · resilience · telemetry · logs · audit · mcp · a2a · cloud · memory · skills · eval · tunnel · backup · sync · webhooks · policy · pricing · translator · simulate …

🤝 Connect an agent — and it controls OmniRoute itself

Expose OmniRoute over MCP or A2A and any capable agent gets the keys to the whole gateway — routing, providers, combos, cache, compression, memory — autonomously.

Protocol	Endpoint	Use it for
🧰 MCP (stdio)	`omniroute --mcp`	Plug into Claude Desktop, Cursor, any MCP client
🌊 MCP (HTTP)	`http://localhost:20128/api/mcp/stream`	Remote MCP — 94 tools, 30 scopes, full audit trail
📡 MCP (SSE)	`http://localhost:20128/api/mcp/sse`	Streaming MCP transport
🤝 A2A	`http://localhost:20128/.well-known/agent.json`	Agent-to-agent, JSON-RPC 2.0 + SSE, 6 skills

# Give Claude Code the full OmniRoute toolset over MCP:
claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream

_{📖 MCP Server · A2A Server · Agent Protocols}

🗜️ Save 15–95% Tokens — Automatically

Why use many tokens when few tokens do the trick? Every request passes through OmniRoute's compression pipeline transparently — no client changes. It's now a stack of 10 composable engines that run in order and mix & match per routing combo — building on ideas from RTK, Caveman (⭐ 78K+), LLMLingua-2, and Troglodita (PT-BR).

🧱 The 10-engine stack

Engines run in pipeline order; each is independently toggleable and configurable per combo:

#	Engine	What it does
1	Session-Dedup	Drops content repeated across turns (content-addressed, cross-turn)
2	CCR	Archives large blocks behind retrieve markers, fetched on demand
3	RTK	Smart tool-result filtering, dedup & truncation (command-aware)
4	Headroom	Lossless tabular compaction of homogeneous JSON arrays, flat or nested (~30%), via a vendored GCF codec (spec v3.2)
5	Relevance	Extractive sentence scoring against the last user query
6	Caveman	Rule-based prose compression (~65–75% on output)
7	LLMLingua-2	ML semantic pruning via MobileBERT ONNX — code-safe, async
8	Lite	Whitespace + image-URL trimming (latency-light baseline)
9	Aggressive	Summarization + progressive aging of old turns
10	Ultra	Heuristic token pruning with an optional small-model (SLM) tier

Code blocks, URLs and structured data are always preserved byte-perfect. One-click presets combine the engines:

Mode	Savings	Best for
🪶 Lite	~15%	Always-on safe default
🪨 Standard (Caveman)	~30%	Daily coding
⚡ Aggressive	~50%	Long tool-heavy sessions
🔥 Ultra	~75%	Maximum savings
🧰 RTK	60–90%	Shell/test/build/git output
🔗 Stacked (RTK → Caveman)	78–95%	Mixed prompts + tool logs

Real example — Standard mode:

Before (69 tokens): "The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I would recommend using useMemo to memoize the object."

After (19 tokens): "New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."

Same answer. 72% fewer tokens. Zero accuracy loss. ✅

PT-BR example — Troglodita mode:

Antes (42 tokens): "O problema é que o componente está re-renderizando porque uma nova referência de objeto está sendo criada em cada ciclo de renderização. Eu recomendaria usar useMemo."

Depois (12 tokens): "Re-render: ref nova cada ciclo (objeto inline recriado). Usar useMemo."

Mesma resposta. ~70% menos tokens. Precisão técnica intacta. ✅

📖 How it works — pipeline, architecture & savings math

Client (10,000 tok) ──▶ OmniRoute Compression (10 engines) ──▶ Provider (~1,080 tok, up to 95% saved)

Default stacked combo runs RTK → Caveman. When both act on the same tool/context payload, savings compound:

combined = 1 − (1 − RTK) × (1 − Caveman_input)
average  = 1 − (1 − 0.80) × (1 − 0.46) = 89.2%
range    = 78.4 – 94.6%

Code blocks, URLs, JSON and structured data are always protected by the preservation engine.

🎚️ Beyond the engines — output styles, the adaptive dial & per-request control

The 10 engines above shrink what goes in. Three more layers shape how, when, and what comes out:

🪄 Output Styles (output-axis steering) — inject deterministic, cache-safe response-shaping instructions; combinable, each at lite / full / ultra intensity. Adding a style is a one-line registry entry:
- Terse prose — drop filler / articles / hedging; keep technical substance exact.
- Less code — "lazy senior dev" YAGNI: smallest working change, no unrequested scaffolding.
- Terse CJK (文言) — classical-Chinese ultra-terse style (locale-gated to zh).
🎯 Adaptive context-budget (the dial) — instead of one on/off token threshold, escalate the cheapest, most-lossless engines only as far as needed to fit the model's context window. Policy: reserve-output (default, model-aware) · percentage · absolute. Mode: floor (guarantee fit) · replace-autotrigger (your explicit choice wins) · off (legacy threshold).
🎛️ Where compression is decided (precedence, high → low) — per-request x-omniroute-compression header › routing-combo override › active named profile › adaptive / auto-trigger › panel default › off. The applied plan echoes back in the X-OmniRoute-Compression: <mode>; source=<source> response header.

Auto-trigger by token threshold, flip on the adaptive dial, pin a named profile, set a one-off per request, or assign a pipeline per routing combo — whichever fits the workload. An opt-in offline eval harness (npm run eval:compression) scores fidelity vs. savings on a pinned corpus before you promote a change.

📖 COMPRESSION_GUIDE.md · RTK_COMPRESSION.md · COMPRESSION_ENGINES.md

⚡ Quick Start

1) Install & run

npm install -g omniroute
omniroute

Dashboard at http://localhost:20128 · API at http://localhost:20128/v1.

2) Connect a FREE provider (no signup)

Dashboard → Providers → connect Kiro AI (free Claude, ~50 credits/month per account) or OpenCode Free (no auth) → done.

3) Point your coding tool

Base URL: http://localhost:20128/v1
API Key:  [copy from Dashboard → Endpoints]
Model:    auto            (zero-config smart routing — or any provider/model)

4) Verify it's working

curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"

You should see your connected models listed. 🎉 That's it — start coding, and OmniRoute auto-routes & falls back for you.

If your client cannot send custom headers, OmniRoute also exposes tokenized compatibility aliases:

OpenAI catalog:   http://localhost:20128/vscode/YOUR_KEY/
OpenAI models:    http://localhost:20128/vscode/YOUR_KEY/models
OpenAI chat:      http://localhost:20128/vscode/YOUR_KEY/chat/completions
OpenAI responses: http://localhost:20128/vscode/YOUR_KEY/responses
Ollama chat:      http://localhost:20128/vscode/YOUR_KEY/api/chat
Ollama tags:      http://localhost:20128/vscode/YOUR_KEY/api/tags

Use these only for clients that cannot attach Authorization: Bearer .... Header auth remains the preferred mode.

📦 More install methods — Docker, source, pnpm, Arch

🐳 Docker

docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
  -p 20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest

🛠️ From source

cp .env.example .env && npm install
PORT=20128 npm run dev

📦 pnpm

pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core && omniroute

🐧 Arch Linux (AUR)

yay -S omniroute-bin && systemctl --user enable --now omniroute.service

🔧 Nix (Flake)

# Using Nix flakes
nix develop
npm run dev

# Or using devbox
devbox run npm run dev

📖 Docker Guide — Compose profiles, Caddy HTTPS, Cloudflare tunnels.

🦭 Podman

# 1. Build the image
podman build --target runner-base -t omniroute:base .

# 2. Fix data directory permissions for rootless Podman
mkdir -p data && podman unshare chown 1000:1000 ./data

# 3. Set runtime in .env, then run (see contrib/podman/ for Quadlet)
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d

📖 Podman Guide — Quadlet setup, podman-compose, Quadlet.

⚡ Faster / leaner install (skip the native build)

The native SQLite engine (better-sqlite3) is an optional dependency, so a global install never blocks on compiling from source: it uses a prebuilt binary when one matches your platform/Node, and otherwise falls back transparently to a pure-JS engine (node:sqlite on Node 22+, else the bundled sql.js WASM) — no build tools required.

To skip the post-install native warm-up entirely (CI, headless, or slow machines):

OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute   # CI=1 also skips it

For the fastest installs prefer pnpm (content-addressed store + hard links — see above). For a dashboard-free, headless runtime use the Docker base profile (above) or the Termux guide. The CLI and the web dashboard are served by the same process on one port, so there is no separate CLI-only package today.

🎬 OmniRoute in Action

🇧🇷 Português
_{Guia completo}

🇺🇸 English
_{Complete walkthrough}

🇷🇺 Русский
_{Полное руководство}

🎬 Made a video about OmniRoute? Open an issue or discussion with the link — we'll feature it here.

📚 Explore More

💰 Pricing at a glance & the $0 Free Stack (11 providers)

Tier	Example	Cost
💳 Subscription	Claude Code Pro / Codex / Copilot	$10–200/mo
🔑 API Key (free tiers)	NVIDIA NIM, Cerebras, Groq	FREE
💰 Cheap	GLM-5 $0.5/1M · MiniMax M2.5 $0.3/1M	pennies
🆓 Free Forever	Kiro, Qoder, Qwen, Pollinations, LongCat	$0

The $0 Free Stack — combine into one unbreakable combo:

Provider	Prefix	Free models	Quota
Kiro	`kr/`	Claude Sonnet 4.5, Haiku 4.5, Opus 4.6	50 credits/mo
Qoder	`if/`	kimi-k2-thinking, qwen3-coder-plus, deepseek-r1	♾️ Unlimited
Qwen	`qw/`	qwen3-coder-plus/flash/next	♾️ Unlimited
Pollinations	`pol/`	GPT-5, Claude, Gemini, DeepSeek, Llama 4	No key needed
LongCat	`lc/`	LongCat-2.0	10M one-time (KYC)
Cloudflare AI	`cf/`	50+ models	10K neurons/day
NVIDIA NIM	`nvidia/`	129 models	~40 RPM
Cerebras	`cerebras/`	Qwen3 235B, GPT-OSS 120B	1M tok/day

💡 The dashboard "cost" is a savings tracker, not a bill — OmniRoute never charges you. A "$290 total cost" using free models means $290 saved.

📖 Complete free directory → docs/reference/FREE_TIERS.md — 25+ providers, quotas, base URLs.

🎯 Use Cases — ready-made combo playbooks

$0 forever:

1. kr/claude-sonnet-4.5   (Kiro — ~50 credits/mo per acct)
2. if/kimi-k2-thinking    (Qoder — unlimited)
3. pol/gpt-5              (Pollinations — no key)
4. lc/LongCat-2.0         (10M one-time backup, KYC)
Compression: aggressive (~50%) → double your free quota · Cost: $0/mo

24/7 no interruptions: chain 2 subscriptions → cheap → free for 5 layers of fallback. Blocked region: free providers + global/per-provider proxy → access AI from any country. Max savings: subscription + cheap backup + ultra compression (~75%) → ~$150–300/mo saved for heavy users.

🌍 Bypass geo-blocks — 3-level proxy + stealth

🇷🇺 🇨🇳 🇮🇷 🇨🇺 🇹🇷 In a blocked region? OmniRoute's 3-level proxy (Global / Per-Provider / Per-Connection) proxies API requests, OAuth flows, connection tests, token refresh & model sync.

Protocols: HTTP/HTTPS, SOCKS5, authenticated proxies
🆓 1proxy marketplace — hundreds of free validated proxies, quality scores, auto-rotation
Anti-detection — TLS fingerprint spoofing (wreq-js), CLI fingerprint matching, proxy IP preservation

📖 docs/ops/PROXY_GUIDE.md

✨ Full feature list — 30+ capabilities (memory, evals, observability)

Routing: 18 strategies · task-aware smart routing · thinking budget controls · wildcard routing · system prompt injection. Compatibility: OpenAI ↔ Claude ↔ Gemini ↔ Responses API · auto OAuth refresh (PKCE, 8 providers) · multi-account round-robin · Batch + Files API · live OpenAPI 3.0. Protocols: MCP (94 tools, 3 transports, 30 scopes) · A2A (JSON-RPC 2.0, SSE, 6 skills) · ACP · cloud agents (Codex, Cursor, Devin, Jules). Plugins: custom plugin marketplace (system-configured registry URL with SSRF-guarded fetch) · install / enable / disable · Notion + Obsidian knowledge-base integrations (WebDAV file server, vault search, note CRUD). Embedded services: one-click install & lifecycle management of local sidecar services (CLIProxy, NineRouter). Quality & Ops: built-in Evals (golden-set: exact/contains/regex/custom) · guardrails (PII, injection, vision) · health dashboard · p50/p95/p99 telemetry · webhooks · compliance audit. AI Agent Skills: drop-in markdown manifests — point any agent at a skills/*/SKILL.md manifest. 43 skills available.

📖 MCP Server · A2A Server · Resilience Guide · Features Gallery

📖 Setup, env vars & FAQ

Env var	Default	Purpose
`PORT`	`20128`	API + dashboard port
`REQUIRE_API_KEY`	`false`	Require API key for all requests
`DATA_DIR`	`~/.omniroute`	Database & config storage

Will I be charged by OmniRoute? No — it's free, open-source software on your machine. You only pay paid providers directly. OmniRoute has no billing system. Are FREE providers really unlimited? Mostly — Qoder, Pollinations, LongCat, and Cloudflare are free with no per-account credit cap. Kiro is free too but capped at ~50 credits/month per account. Stack multiple free providers in a combo and auto-fallback keeps you serving for $0. Will compression hurt quality? No — it only compresses the input; code, URLs, JSON are always protected. Does it work where AI is blocked? Yes — 3-level proxy + 1proxy marketplace reach all 250 providers.

📖 User Guide · API Reference · Environment Config

🐛 Troubleshooting

Problem	Quick fix
"Language model did not provide messages"	Provider quota exhausted → use a combo fallback
Rate limiting (429)	Add fallback: `cc/claude → glm/glm-4.7 → if/kimi-k2-thinking`
OAuth token expired	Auto-refreshed; if stuck, delete + re-auth in Providers
`unsupported_country_region_territory`	Configure proxy in Settings → Proxy
Docker SQLite locks	Use `--stop-timeout 40` for clean WAL checkpoint
Node runtime errors	Use Node `>=22.0.0 <23` or `>=24.0.0 <27`

🐛 Reporting a bug? Run npm run system-info and attach system-info.txt. 📖 docs/guides/TROUBLESHOOTING.md

📸 Dashboard screenshots

Page	Screenshot	Page	Screenshot
Providers		Combos
Analytics		Health
Translator		Settings
CLI Tools		Usage Logs

📧 Support & Community

💬 Chat with the community — Discord, Telegram & WhatsApp (🌍 / 🇧🇷) links are at the top of this README.

🌍 Website: omniroute.online
🐙 GitHub: github.com/diegosouzapw/OmniRoute
🐛 Issues: report a bug (attach npm run system-info output)
🤝 Contributing: see CONTRIBUTING.md or pick a good first issue

🛠️ Tech Stack

Runtime: Node.js 22.x or 24.x LTS (24 LTS recommended) — >=22.0.0 <23 || >=24.0.0 <27
Language: TypeScript 6.0 — 100% TypeScript across src/ and open-sse/ (zero any in core modules since v2.0)
Framework: Next.js 16 + React 19 + Tailwind CSS 4
Database: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills
Schemas: Zod (MCP tool I/O validation, API contracts)
Protocols: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)
Streaming: Server-Sent Events (SSE) + WebSocket bridge (/v1/ws)
Auth: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization
Testing: Node.js test runner + Vitest (21,000+ test cases across 2,586 files — unit, integration, E2E, security, ecosystem)
Platforms: Desktop (Electron), Android (Termux), PWA (any browser)
CI/CD: GitHub Actions (auto npm publish + Docker Hub on release)
Website: omniroute.online
Package: npmjs.com/package/omniroute
Docker: hub.docker.com/r/diegosouzapw/omniroute
Resilience: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing

📖 Documentation

📘 Getting Started

Document	Description
User Guide	Providers, combos, CLI integration, deployment
Setup Guide	Full install methods, CLI tool configs, protocol setup, timeout tuning
CLI Tools Guide	Per-tool setup for Claude Code, Codex, Cursor, Cline, OpenClaw, Kilo, Copilot
Remote Mode	Drive a remote OmniRoute (VPS) from your laptop CLI via scoped access tokens
Claude Code Config	Point Claude Code at OmniRoute (local/remote) with `launch` + per-model profiles
Quick Start	3-step install → connect → configure

🔧 Operations & Deployment

Document	Description
Docker Guide	Docker run, Compose profiles, Caddy HTTPS, tunnels, image tags
Podman Guide	Quadlet systemd integration, podman-compose, SELinux
VM Deployment	Complete guide: VM + nginx + Cloudflare setup
Fly.io Deployment	Deploy to Fly.io with persistent storage
Termux Guide	Run OmniRoute on Android via Termux
PWA Guide	Progressive Web App install, caching, architecture
Uninstall Guide	Clean removal for all install methods
Environment Config	Complete `.env` variables and references

🧠 Features & Architecture

Document	Description
Architecture	System architecture, data flow, and internals
Compression Guide	7-option pipeline: off / lite / standard / aggressive / ultra / RTK / stacked
RTK Compression	Command-output compression, filters, trust, verify, raw-output recovery
Compression Engines	Caveman, RTK, stacked pipelines, dashboard/API/MCP surfaces
Compression Rules Format	JSON rule-pack schemas for Caveman and RTK filters
Compression Language Packs	Language detection and Caveman rule-pack authoring
Resilience Guide	Circuit breakers, cooldowns, queue, anti-thundering herd, TLS spoofing
Auto-Combo Engine	12-factor scoring, mode packs, self-healing
Proxy Guide	3-level proxy system, 1proxy marketplace, registry CRUD
Free Tiers	25+ free API providers consolidated directory
Features Gallery	Visual dashboard tour with screenshots
Codebase Documentation	Beginner-friendly codebase walkthrough

🤖 Protocols & APIs

Document	Description
API Reference	All endpoints with examples
OpenAPI Spec	OpenAPI 3.0 specification
MCP Server	95 MCP tools, IDE configs, Python/TS/Go clients
MCP Server Guide	MCP installation, transports, and tool reference
A2A Server	JSON-RPC 2.0 protocol, skills, streaming, task mgmt
A2A Server Guide	A2A agent card, tasks, skills, and streaming

📋 Project & Quality

Document	Description
Contributing	Development setup and guidelines
Changelog	Full per-version release history
Security Policy	Vulnerability reporting and security practices
i18n Guide	40+ language support, translation workflow, RTL
Release Checklist	Pre-release validation steps
Coverage Plan	Test coverage strategy and 21,000+ test suite

⭐ Top Contributors

OmniRoute is shaped by a passionate open-source community. These individuals have made exceptional contributions that directly impact the quality, stability, and reach of the project. Thank you.

oyi77
_{🥇 189 commits • +155K lines}
_{Analytics engine, SQL aggregations,
proxy marketplace, test coverage}

Chris Staley
_{🥈 70 commits • +5.7K lines}
_{SSE stream hardening, Responses API,
Gemini pagination, test regression fixes}

zenobit
_{🥉 62 commits • +24K lines}
_{CI/CD pipeline, i18n for 33 languages,
Void Linux package, platform fixes}

R.D. & Randi
_{🏅 108 commits • +30K lines}
_{Endpoints page, tunnel integrations,
Docker workflows, A2A status, compression UI}

benzntech
_{🏅 22 commits • +7.5K lines}
_{Electron desktop app, auto-updater,
release build workflows, cross-platform CI}

herjarsa
_{🏅 21 commits • +6K lines}
_{Zero-latency combos, vision-bridge auto-routing,
catalog context-length, resilience 429 hints}

🙏 These contributors' features, bug fixes, and infrastructure improvements are a core part of what makes OmniRoute reliable and feature-rich. Every pull request, every test case, and every i18n translation file matters. Open source is built by people like them.

👥 280+ Contributors

How to Contribute

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

Releasing a New Version

# Create a release — npm publish happens automatically
gh release create v3.8.2 --title "v3.8.2" --generate-notes

📊 Stars

🌍 StarMapper

🙏 Acknowledgments

OmniRoute stands on the shoulders of giants. It started as a fork of 9router and a TypeScript port of the Go project CLIProxyAPI — and from there, every subsystem below was inspired by an open-source project that got there first. Each one shaped a concrete piece of OmniRoute. This is our thank-you to all of them. 🙏

⭐ star counts as of June 2026 — go give these projects a star.

🧬 Lineage & gateway

Project	⭐	How it inspired OmniRoute
9router · decolua	19.0k	The original project this fork is built on — extended here with multi-modal APIs and a full TypeScript rewrite.
CLIProxyAPI · router-for-me	38.8k	The Go implementation that inspired this JavaScript / TypeScript port.
LiteLLM · BerriAI	52.1k	The AI gateway whose public pricing dataset feeds our cost-tracking sync and whose provider-normalization model informed our routing.

🗜️ Context & token compression — engines

Project	⭐	How it inspired OmniRoute
Caveman · JuliusBrussee	78.2k	The viral "why use many token when few token do trick" project — its caveman-speak philosophy powers our standard compression mode and 30+ filler/condensation rules.
RTK – Rust Token Killer · rtk-ai	67.3k	High-performance command-output compression — inspired our RTK engine, JSON filter DSL, raw-output recovery and the stacked RTK → Caveman pipeline.
headroom · headroomlabs-ai	54.5k	Reversible context-compression (SmartCrusher) — inspired our `headroom` engine and the `ccr` retrieve-marker pattern.
LLMLingua · Microsoft	6.4k	Prompt-compression research (LLMLingua / LLMLingua-2) — inspired our async, code-safe, fail-open `llmlingua` engine.
llmlingua-2-js · atjsh	28	The JS/ONNX port (MobileBERT / XLM-RoBERTa) used as the worker-thread backend for our LLMLingua engine.
Troglodita · Lenine Júnior	16	PT-BR token compression — powers our pt-BR language pack: pleonasm reduction and filler removal tuned for Brazilian-Portuguese grammar.
ponytail · DietrichGebert	68.8k	The viral "lazy senior dev" YAGNI-coder skill — inspired our less-code Output Style: smallest-working-change steering that cuts generated code (the output-axis sibling to Caveman's terse prose).

🧩 Compact formats, token research & code-aware tooling

Project	⭐	How it inspired OmniRoute
TOON · toon-format	24.7k	Token-Oriented Object Notation — its columnar, header-plus-rows model shaped our tabular compaction stage.
GCF – Graph Compact Format · Blackwell Systems	14	First inspired our tabular compaction stage; now its zero-dependency, lossless generic-profile encoder is vendored directly as the Headroom codec (MIT, SPDX-marked), current with GCF spec v3.2.
token-optimizer-mcp · ooples	421	Brotli/SQLite cache + per-session context-delta — inspired our `session-dedup` engine.
token-savior · Mibayy	1.0k	Bash-output compaction + MCP profiles — inspired our compression bail-out discipline and MCP tool-manifest reduction.
token-saver · ppgranger	110	Content-aware, per-file-type output compression with failure-aware bail-out — validated our per-type dispatch and minimum-gain skip.
token-optimizer · alexgreensh	1.5k	"Find the ghost tokens" — its offload + recoverable-handle pattern informed our CCR offload thinking.
TokenMizer · Shweta-Mishra-ai	2	A session-graph + cross-turn line-dedup blueprint that informed our session-dedup design.
OmniCompress · jessefreitas	2	Rust columnar-JSON + content-addressed retrieve + cross-message dedup — validated our `headroom`/`ccr`/`session-dedup` engine design and the cache-stable "compressed form is position-independent" invariant.
mcp-compressor · Atlassian Labs	89	MCP tool-schema/description compression — informed our MCP tool-manifest cardinality reduction.
RepoMapper · pdavis68	181	Aider-style repo-map ranking — informed our repo-map / retrieval-ranking exploration.
quiet-shell-mcp · mrsimpson	4	Declarative shell-output reduction over MCP — validated our declarative bash-output compaction.
ts-morph · David Sherret	6.1k	TypeScript Compiler API toolkit — inspired our parser-based comment removal that preserves string, template and regex literals.

🧠 Memory & RAG

Project	⭐	How it inspired OmniRoute
Mem0 · mem0ai	59.8k	Universal memory layer — its proxy-as-write/read-boundary model shaped our memory architecture.
Letta (MemGPT) · letta-ai	23.6k	Stateful agents with tiered memory — inspired our Context Control & Recovery (CCR) tiered model.
WFGY · onestardao	1.8k	The ProblemMap taxonomy of 16 recurring RAG/LLM failure modes — the shared vocabulary in our troubleshooting guide.

🛰️ Traffic inspection, MITM & transparent proxy

Project	⭐	How it inspired OmniRoute
llm-interceptor · chouzz	48	MITM interception/analysis of coding-assistant ↔ LLM traffic — our Traffic Inspector ports its SSE merge, conversation normalization, host passthrough and secret masking (MIT).
ProxyBridge · InterceptSuite	5.3k	Transparent per-process proxy routing — inspired our crash-safe MITM teardown, socket idle-timeouts, `/proc` process attribution and TPROXY capture.

📚 Model data, observability & UI

Project	⭐	How it inspired OmniRoute
models.dev · SST / OpenCode	5.6k	Open database of AI model specs, pricing and capabilities — synced natively into our model catalog.
React Flow / xyflow · xyflow	37.4k	The node-based graph library powering our real-time Compression Studio and Combo/Routing Studio.
LangGraph · LangChain	36.1k	LangGraph Studio's live workflow-graph visualization inspired our Studios' real-time cascade view.
Langfuse · Langfuse	30.1k	Its trace → span → generation observability model shaped our Compression Studio waterfall.
Kiali · Kiali	3.6k	Istio service-mesh observability — inspired our circuit-breaker badges and error-edge visuals in the Routing/Combo Studio.
lobe-icons · LobeHub	2.2k	AI/LLM brand logos that render the provider icons across our dashboard.

🛡️ Security

Project	⭐	How it inspired OmniRoute
awesome-secure-defaults · tldrsec	708	A curated list of secure-by-default libraries that guides our security choices (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink).

🧭 Complementary tools

Project	How it composes with OmniRoute
CodeWebChat · robertpiosik	Editor-side companion — VS Code + browser extension that autofills 15+ chatbot web UIs with editor context. Owns the free-web-UI rail alongside OmniRoute's API rail; can point its API mode at OmniRoute.

❤️ Support

OmniRoute is free and open source, built and maintained in the open. If it saves you time or money, consider supporting development:

⭐ Star the repo — it genuinely helps visibility
💖 GitHub Sponsors — fund ongoing maintenance and new providers
🐛 Report bugs and share feedback in Discussions

📄 License

MIT License - see LICENSE for details.

⬆ Back to top · Built with ❤️ for the open-source AI community.

_{OmniRoute v3.8.43 · Node ≥22.0.0 · MIT License · omniroute.online}

gabime/spdlog

Fast C++ logging library.

spdlog

Fast C++ logging library

Install

Header-only version

Copy the include folder to your build tree and use a C++11 compiler.

Compiled version (recommended - much faster compile times)

$ git clone https://github.com/gabime/spdlog.git
$ cd spdlog && mkdir build && cd build
$ cmake .. && cmake --build .

see example CMakeLists.txt on how to use.

Platforms

Linux, FreeBSD, OpenBSD, Solaris, AIX
Windows (msvc 2013+, cygwin)
macOS (clang 3.5+)
Android

Package managers:

Debian: sudo apt install libspdlog-dev
Homebrew: brew install spdlog
MacPorts: sudo port install spdlog
FreeBSD: pkg install spdlog
Fedora: dnf install spdlog
Gentoo: emerge dev-libs/spdlog
Arch Linux: pacman -S spdlog
openSUSE: sudo zypper in spdlog-devel
ALT Linux: apt-get install libspdlog-devel
vcpkg: vcpkg install spdlog
conan: conan install --requires=spdlog/[*]
conda: conda install -c conda-forge spdlog
build2: depends: spdlog ^1.8.2

Features

Very fast (see benchmarks below).
Headers only or compiled
Feature-rich formatting, using the excellent fmt library.
Asynchronous mode (optional)
Custom formatting.
Multi/Single threaded loggers.
Various log targets:
- Rotating log files.
- Daily log files.
- Console logging (colors supported).
- syslog.
- Windows event log.
- Windows debugger (OutputDebugString(..)).
- Log to Qt widgets (example).
- Easily extendable with custom log targets.
Log filtering - log levels can be modified at runtime as well as compile time.
Support for loading log levels from argv or environment var.
Backtrace support - store debug messages in a ring buffer and display them later on demand.

Usage samples

Basic usage

#include "spdlog/spdlog.h"

int main() 
{
    spdlog::info("Welcome to spdlog!");
    spdlog::error("Some error message with arg: {}", 1);
    
    spdlog::warn("Easy padding in numbers like {:08d}", 12);
    spdlog::critical("Support for int: {0:d};  hex: {0:x};  oct: {0:o}; bin: {0:b}", 42);
    spdlog::info("Support for floats {:03.2f}", 1.23456);
    spdlog::info("Positional args are {1} {0}..", "too", "supported");
    spdlog::info("{:<30}", "left aligned");
    
    spdlog::set_level(spdlog::level::debug); // Set *global* log level to debug
    spdlog::debug("This message should be displayed..");    
    
    // change log pattern
    spdlog::set_pattern("[%H:%M:%S %z] [%n] [%^---%L---%$] [thread %t] %v");
    
    // Compile time log levels
    // Note that this does not change the current log level, it will only
    // remove (depending on SPDLOG_ACTIVE_LEVEL) the call on the release code.
    SPDLOG_TRACE("Some trace message with param {}", 42);
    SPDLOG_DEBUG("Some debug message");
}

Create stdout/stderr logger object

#include "spdlog/spdlog.h"
#include "spdlog/sinks/stdout_color_sinks.h"
void stdout_example()
{
    // create a color multi-threaded logger
    auto console = spdlog::stdout_color_mt("console");    
    auto err_logger = spdlog::stderr_color_mt("stderr");    
    spdlog::get("console")->info("loggers can be retrieved from a global registry using the spdlog::get(logger_name)");
}

Basic file logger

#include "spdlog/sinks/basic_file_sink.h"
void basic_logfile_example()
{
    try 
    {
        auto logger = spdlog::basic_logger_mt("basic_logger", "logs/basic-log.txt");
    }
    catch (const spdlog::spdlog_ex &ex)
    {
        std::cout << "Log init failed: " << ex.what() << std::endl;
    }
}

Rotating files

#include "spdlog/sinks/rotating_file_sink.h"
void rotating_example()
{
    // Create a file rotating logger with 5 MB size max and 3 rotated files
    auto max_size = 1048576 * 5;
    auto max_files = 3;
    auto logger = spdlog::rotating_logger_mt("some_logger_name", "logs/rotating.txt", max_size, max_files);
}

Daily files


#include "spdlog/sinks/daily_file_sink.h"
void daily_example()
{
    // Create a daily logger - a new file is created every day at 2:30 am
    auto logger = spdlog::daily_logger_mt("daily_logger", "logs/daily.txt", 2, 30);
}

Backtrace support

// Debug messages can be stored in a ring buffer instead of being logged immediately.
// This is useful to display debug logs only when needed (e.g. when an error happens).
// When needed, call dump_backtrace() to dump them to your log.

spdlog::enable_backtrace(32); // Store the latest 32 messages in a buffer. 
// or my_logger->enable_backtrace(32)..
for(int i = 0; i < 100; i++)
{
  spdlog::debug("Backtrace message {}", i); // not logged yet..
}
// e.g. if some error happened:
spdlog::dump_backtrace(); // log them now! show the last 32 messages
// or my_logger->dump_backtrace(32)..

Periodic flush

// periodically flush all *registered* loggers every 3 seconds:
// warning: only use if all your loggers are thread-safe ("_mt" loggers)
spdlog::flush_every(std::chrono::seconds(3));

Stopwatch

// Stopwatch support for spdlog
#include "spdlog/stopwatch.h"
void stopwatch_example()
{
    spdlog::stopwatch sw;    
    spdlog::debug("Elapsed {}", sw);
    spdlog::debug("Elapsed {:.3}", sw);       
}

Log binary data in hex

// many types of std::container<char> types can be used.
// ranges are supported too.
// format flags:
// {:X} - print in uppercase.
// {:s} - don't separate each byte with space.
// {:p} - don't print the position on each line start.
// {:n} - don't split the output into lines.
// {:a} - show ASCII if :n is not set.

#include "spdlog/fmt/bin_to_hex.h"

void binary_example()
{
    auto console = spdlog::get("console");
    std::array<char, 80> buf;
    console->info("Binary example: {}", spdlog::to_hex(buf));
    console->info("Another binary example:{:n}", spdlog::to_hex(std::begin(buf), std::begin(buf) + 10));
    // more examples:
    // logger->info("uppercase: {:X}", spdlog::to_hex(buf));
    // logger->info("uppercase, no delimiters: {:Xs}", spdlog::to_hex(buf));
    // logger->info("uppercase, no delimiters, no position info: {:Xsp}", spdlog::to_hex(buf));
}

Logger with multi sinks - each with a different format and log level


// create a logger with 2 targets, with different log levels and formats.
// The console will show only warnings or errors, while the file will log all. 
void multi_sink_example()
{
    auto console_sink = std::make_shared<spdlog::sinks::stdout_color_sink_mt>();
    console_sink->set_level(spdlog::level::warn);
    console_sink->set_pattern("[multi_sink_example] [%^%l%$] %v");

    auto file_sink = std::make_shared<spdlog::sinks::basic_file_sink_mt>("logs/multisink.txt", true);
    file_sink->set_level(spdlog::level::trace);

    spdlog::logger logger("multi_sink", {console_sink, file_sink});
    logger.set_level(spdlog::level::debug);
    logger.warn("this should appear in both console and file");
    logger.info("this message should not appear in the console, only in the file");
}

Register several loggers - change global level


// Creation of loggers. Set levels to all registered loggers. 
void set_level_example()
{
    auto logger1 = spdlog::basic_logger_mt("logger1", "logs/logger1.txt");
    auto logger2 = spdlog::basic_logger_mt("logger2", "logs/logger2.txt");

    spdlog::set_default_logger(logger2);
    spdlog::default_logger()->set_level(spdlog::level::trace); // set level for the default logger (logger2) to trace

    spdlog::trace("trace message to the logger2 (specified as default)");

    spdlog::set_level(spdlog::level::off) // (sic!) set level for *all* registered loggers to off (disable)
  
    logger1.warn("warn message will not appear because the level set to off");
    logger2.warn("warn message will not appear because the level set to off");
    spdlog::warn("warn message will not appear because the level set to off");
}

User-defined callbacks about log events


// create a logger with a lambda function callback, the callback will be called
// each time something is logged to the logger
void callback_example()
{
    auto callback_sink = std::make_shared<spdlog::sinks::callback_sink_mt>([](const spdlog::details::log_msg &msg) {
         // for example you can be notified by sending an email to yourself
    });
    callback_sink->set_level(spdlog::level::err);

    auto console_sink = std::make_shared<spdlog::sinks::stdout_color_sink_mt>();
    spdlog::logger logger("custom_callback_logger", {console_sink, callback_sink});

    logger.info("some info log");
    logger.error("critical issue"); // will notify you
}

Asynchronous logging

#include "spdlog/async.h"
#include "spdlog/sinks/basic_file_sink.h"
void async_example()
{
    // default thread pool settings can be modified *before* creating the async logger:
    // spdlog::init_thread_pool(8192, 1); // queue with 8k items and 1 backing thread.
    auto async_file = spdlog::basic_logger_mt<spdlog::async_factory>("async_file_logger", "logs/async_log.txt");
    // alternatively:
    // auto async_file = spdlog::create_async<spdlog::sinks::basic_file_sink_mt>("async_file_logger", "logs/async_log.txt");   
}

Asynchronous logger with multi sinks

#include "spdlog/async.h"
#include "spdlog/sinks/stdout_color_sinks.h"
#include "spdlog/sinks/rotating_file_sink.h"

void multi_sink_example2()
{
    spdlog::init_thread_pool(8192, 1);
    auto stdout_sink = std::make_shared<spdlog::sinks::stdout_color_sink_mt >();
    auto rotating_sink = std::make_shared<spdlog::sinks::rotating_file_sink_mt>("mylog.txt", 1024*1024*10, 3);
    std::vector<spdlog::sink_ptr> sinks {stdout_sink, rotating_sink};
    auto logger = std::make_shared<spdlog::async_logger>("loggername", sinks.begin(), sinks.end(), spdlog::thread_pool(), spdlog::async_overflow_policy::block);
    spdlog::register_logger(logger);
}

User-defined types

template<>
struct fmt::formatter<my_type> : fmt::formatter<std::string>
{
    auto format(my_type my, format_context &ctx) const -> decltype(ctx.out())
    {
        return fmt::format_to(ctx.out(), "[my_type i={}]", my.i);
    }
};

void user_defined_example()
{
    spdlog::info("user defined type: {}", my_type(14));
}

User-defined flags in the log pattern

// Log patterns can contain custom flags.
// the following example will add new flag '%*' - which will be bound to a <my_formatter_flag> instance.
#include "spdlog/pattern_formatter.h"
class my_formatter_flag : public spdlog::custom_flag_formatter
{
public:
    void format(const spdlog::details::log_msg &, const std::tm &, spdlog::memory_buf_t &dest) override
    {
        std::string some_txt = "custom-flag";
        dest.append(some_txt.data(), some_txt.data() + some_txt.size());
    }

    std::unique_ptr<custom_flag_formatter> clone() const override
    {
        return spdlog::details::make_unique<my_formatter_flag>();
    }
};

void custom_flags_example()
{    
    auto formatter = std::make_unique<spdlog::pattern_formatter>();
    formatter->add_flag<my_formatter_flag>('*').set_pattern("[%n] [%*] [%^%l%$] %v");
    spdlog::set_formatter(std::move(formatter));
}

Custom error handler

void err_handler_example()
{
    // can be set globally or per logger(logger->set_error_handler(..))
    spdlog::set_error_handler([](const std::string &msg) { spdlog::get("console")->error("*** LOGGER ERROR ***: {}", msg); });
    spdlog::get("console")->info("some invalid message to trigger an error {}{}{}{}", 3);
}

syslog

#include "spdlog/sinks/syslog_sink.h"
void syslog_example()
{
    std::string ident = "spdlog-example";
    auto syslog_logger = spdlog::syslog_logger_mt("syslog", ident, LOG_PID);
    syslog_logger->warn("This is warning that will end up in syslog.");
}

Android example

#include "spdlog/sinks/android_sink.h"
void android_example()
{
    std::string tag = "spdlog-android";
    auto android_logger = spdlog::android_logger_mt("android", tag);
    android_logger->critical("Use \"adb shell logcat\" to view this message.");
}

Load log levels from the env variable or argv

#include "spdlog/cfg/env.h"
int main (int argc, char *argv[])
{
    spdlog::cfg::load_env_levels();
    // or specify the env variable name:
    // MYAPP_LEVEL=info,mylogger=trace && ./example
    // spdlog::cfg::load_env_levels("MYAPP_LEVEL");
    // or from the command line:
    // ./example SPDLOG_LEVEL=info,mylogger=trace
    // #include "spdlog/cfg/argv.h" // for loading levels from argv
    // spdlog::cfg::load_argv_levels(argc, argv);
}

So then you can:

$ export SPDLOG_LEVEL=info,mylogger=trace
$ ./example

Log file open/close event handlers

// You can get callbacks from spdlog before/after a log file has been opened or closed. 
// This is useful for cleanup procedures or for adding something to the start/end of the log file.
void file_events_example()
{
    // pass the spdlog::file_event_handlers to file sinks for open/close log file notifications
    spdlog::file_event_handlers handlers;
    handlers.before_open = [](spdlog::filename_t filename) { spdlog::info("Before opening {}", filename); };
    handlers.after_open = [](spdlog::filename_t filename, std::FILE *fstream) { fputs("After opening\n", fstream); };
    handlers.before_close = [](spdlog::filename_t filename, std::FILE *fstream) { fputs("Before closing\n", fstream); };
    handlers.after_close = [](spdlog::filename_t filename) { spdlog::info("After closing {}", filename); };
    auto my_logger = spdlog::basic_logger_st("some_logger", "logs/events-sample.txt", true, handlers);        
}

Replace the Default Logger

void replace_default_logger_example()
{
    auto new_logger = spdlog::basic_logger_mt("new_default_logger", "logs/new-default-log.txt", true);
    spdlog::set_default_logger(new_logger);
    spdlog::info("new logger log message");
}

Log to Qt with nice colors

#include "spdlog/spdlog.h"
#include "spdlog/sinks/qt_sinks.h"
MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent)
{
    setMinimumSize(640, 480);
    auto log_widget = new QTextEdit(this);
    setCentralWidget(log_widget);
    int max_lines = 500; // keep the text widget to max 500 lines. remove old lines if needed.
    auto logger = spdlog::qt_color_logger_mt("qt_logger", log_widget, max_lines);
    logger->info("Some info message");
}

Mapped Diagnostic Context

// Mapped Diagnostic Context (MDC) is a map that stores key-value pairs (string values) in thread local storage.
// Each thread maintains its own MDC, which loggers use to append diagnostic information to log outputs.
// Note: it is not supported in asynchronous mode due to its reliance on thread-local storage.
#include "spdlog/mdc.h"
void mdc_example()
{
    spdlog::mdc::put("key1", "value1");
    spdlog::mdc::put("key2", "value2");
    // if not using the default format, use the %& formatter to print mdc data
    // spdlog::set_pattern("[%H:%M:%S %z] [%^%L%$] [%&] %v");
}

Benchmarks

Below are some benchmarks done in Ubuntu 64 bit, Intel i7-4770 CPU @ 3.40GHz

Synchronous mode

[info] **************************************************************
[info] Single thread, 1,000,000 iterations
[info] **************************************************************
[info] basic_st         Elapsed: 0.17 secs        5,777,626/sec
[info] rotating_st      Elapsed: 0.18 secs        5,475,894/sec
[info] daily_st         Elapsed: 0.20 secs        5,062,659/sec
[info] empty_logger     Elapsed: 0.07 secs       14,127,300/sec
[info] **************************************************************
[info] C-string (400 bytes). Single thread, 1,000,000 iterations
[info] **************************************************************
[info] basic_st         Elapsed: 0.41 secs        2,412,483/sec
[info] rotating_st      Elapsed: 0.72 secs        1,389,196/sec
[info] daily_st         Elapsed: 0.42 secs        2,393,298/sec
[info] null_st          Elapsed: 0.04 secs       27,446,957/sec
[info] **************************************************************
[info] 10 threads, competing over the same logger object, 1,000,000 iterations
[info] **************************************************************
[info] basic_mt         Elapsed: 0.60 secs        1,659,613/sec
[info] rotating_mt      Elapsed: 0.62 secs        1,612,493/sec
[info] daily_mt         Elapsed: 0.61 secs        1,638,305/sec
[info] null_mt          Elapsed: 0.16 secs        6,272,758/sec

Asynchronous mode

[info] -------------------------------------------------
[info] Messages     : 1,000,000
[info] Threads      : 10
[info] Queue        : 8,192 slots
[info] Queue memory : 8,192 x 272 = 2,176 KB 
[info] -------------------------------------------------
[info] 
[info] *********************************
[info] Queue Overflow Policy: block
[info] *********************************
[info] Elapsed: 1.70784 secs     585,535/sec
[info] Elapsed: 1.69805 secs     588,910/sec
[info] Elapsed: 1.7026 secs      587,337/sec
[info] 
[info] *********************************
[info] Queue Overflow Policy: overrun
[info] *********************************
[info] Elapsed: 0.372816 secs    2,682,285/sec
[info] Elapsed: 0.379758 secs    2,633,255/sec
[info] Elapsed: 0.373532 secs    2,677,147/sec

Documentation

Documentation can be found in the wiki pages.

Powered by

alibaba/page-agent

JavaScript in-page GUI agent. Control web interfaces with natural language.

Page Agent

The GUI Agent Living in Your Webpage. One script gives any web page its own AI agent.

🌐 English | 中文

🚀 Demo | 📖 Docs | 📢 HN Discussion | 𝕏 Follow on X

✨ Features

🎯 Easy integration
- No need for browser extension / python / headless browser.
- Just in-page javascript. Everything happens in your web page.
📖 Text-based DOM manipulation
- No screenshots. No multi-modal LLMs or special permissions needed.
🧠 Bring your own LLMs
- Works with most mainstream models, including locally deployed ones. See supported models.
🐙 Optional chrome extension for multi-page tasks.
- And an MCP Server (Beta) to control it from outside

💡 Use Cases

SaaS AI Copilot — Ship an AI copilot in your product in lines of code. No backend rewrite.
Smart Form Filling — Turn 20-click workflows into one sentence. Perfect for ERP, CRM, and admin systems.
Accessibility — Make any web app accessible through natural language. Voice commands, screen readers, zero barrier.
Multi-page Agent — Extend your own web agent's reach across browser tabs via the Chrome extension.
MCP - Allow your agent clients to control your browser.

🚀 Quick Start

One-line integration

Fastest way to try PageAgent with our free Demo LLM:

<script
    src="https://cdn.jsdelivr.net/npm/page-agent@1.12.1/dist/iife/page-agent.demo.js"
    crossorigin="anonymous"
></script>

<!-- China CDN mirror if you can't access jsDelivr -->
<!-- https://registry.npmmirror.com/page-agent/1.12.1/files/dist/iife/page-agent.demo.js -->

⚠️ For technical evaluation only. This demo CDN uses our free testing LLM API. By using it, you agree to its terms.

Add ?autoInit=false to load the script without creating the demo agent automatically. You can then instantiate it with new window.PageAgent(...) and your own LLMs.

NPM Installation

npm install page-agent

import { PageAgent } from 'page-agent'

const agent = new PageAgent({
    model: 'qwen3.5-plus',
    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
    apiKey: 'YOUR_API_KEY',
    language: 'en-US',
})

await agent.execute('Click the login button')

For more programmatic usage, see 📖 Documentations.

🤝 Contributing

We welcome contributions from the community! See CONTRIBUTING.md for guidelines and docs/developer-guide.md for local development workflows.

Built something cool with PageAgent? Share it in Show and Tell. 🙌

Please read the maintainer's note on principles and current state.

Contributions generated entirely by bots or AI without substantial human involvement will not be accepted.

⚖️ License

MIT License

👏 Acknowledgments

This project builds upon the excellent work of browser-use.

PageAgent is designed for client-side web enhancement, not server-side automation.

DOM processing components and prompt are derived from browser-use:

Browser Use <https://github.com/browser-use/browser-use>
Copyright (c) 2024 Gregor Zunic
Licensed under the MIT License

We gratefully acknowledge the browser-use project and its contributors for their
excellent work on web automation and DOM interaction patterns that helped make
this project possible.

⭐ Star this repo if you find PageAgent helpful!

GoogleCloudPlatform/knowledge-catalog

Google Cloud Knowledge Catalog Tools and Samples

Knowledge Catalog

Knowledge Catalog (formerly Dataplex), is an AI-powered data catalog and metadata management platform. It provides a dynamic knowledge graph of all your data, structured and unstructured, to provide semantics and business context to AI agents

This repository features tools, agents, and samples that demonstrate Knowledge Catalog features, and building context management, enrichment and retrieval solutions.

Getting Started

Contributing

See the contributing instructions to get started contributed.

License

All solutions within this repository are provided under the Apache 2.0 license. Please see LICENSE for more detailed terms and conditions.

Disclaimer

This repository and its contents are not an official Google product.

interviewstreet/hiring-agent

AI agent to evaluate and score resumes.

Hiring Agent

Resume-to-Score pipeline that extracts structured data from PDFs, enriches with GitHub signals, and outputs a fair, explainable evaluation.

Overview

Hiring Agent parses a resume PDF to Markdown, extracts sectioned JSON using a local or hosted LLM, augments the data with GitHub profile and repository signals, then produces an objective evaluation with category scores, evidence, bonus points, and deductions. You can run fully local with Ollama or use Google Gemini.

Architecture

Flow

pymupdf_rag.py converts PDF pages to Markdown-like text.
pdf.py calls the LLM per section using Jinja templates under prompts/templates.
github.py fetches profile and repos, classifies projects, and asks the LLM to select the top 7.
evaluator.py runs a strict-scored evaluation with fairness constraints.
score.py orchestrates everything end to end and writes CSV when development mode is on.

Key modules

models.py Pydantic schemas and LLM provider interfaces.
llm_utils.py Provider initialization and response cleanup.
transform.py Normalization from loose LLM JSON to JSON Resume style.
prompts/ All Jinja templates for extraction and scoring.

Installation and Setup

Prerequisites

Python 3.11+

The repository pins .python-version to 3.11.13.
One LLM backend (either of them)
- Ollama for local models Install from the official site, then run ollama serve.
- Google Gemini if you have an API key, get it from here.

Quick setup with pip

$ git clone https://github.com/interviewstreet/hiring-agent
$ cd hiring-agent

$ python -m venv .venv
# Linux or macOS
$ source .venv/bin/activate
# Windows
# .venv\Scripts\activate

$ pip install -r requirements.txt

Ollama Models

Pull the model you want to use. For example:

$ ollama pull gemma3:4b

If you want different results, you can pull other models such as:

# For higher system configuration
$ ollama pull gemma3:12b

# For lower system configuration
$ ollama pull gemma3:1b

Configuration

Copy the template and set your environment variables.

$ cp .env.example .env

Environment variables

Variable	Values	Description
`LLM_PROVIDER`	`ollama` or `gemini`	Chooses provider. Defaults to Ollama.
`DEFAULT_MODEL`	for example `gemma3:4b` or `gemini-2.5-pro`	Model name passed to the provider.
`GEMINI_API_KEY`	string	Required when `LLM_PROVIDER=gemini`.
`GITHUB_TOKEN`	optional	Inherits from your shell environment, improves GitHub API rate limits.

Provider mapping lives in prompt.py and models.py. The config.py file has a single flag:

# config.py
DEVELOPMENT_MODE = True  # enables caching and CSV export

You can leave it on during iteration. See the next section for details.

How it works

1) PDF extraction

pymupdf_rag.py and pdf.py read the PDF using PyMuPDF and convert pages to Markdown-like text.
The to_markdown routine handles headings, links, tables, and basic formatting.

2) Section parsing with templates

prompts/templates/*.jinja define strict instructions for each section Basics, Work, Education, Skills, Projects, Awards.
pdf.PDFHandler calls the LLM per section and assembles a JSONResume object (see models.py).

3) GitHub enrichment

github.py extracts a username from the resume profiles, fetches profile and repos, and classifies each project.
It asks the LLM to select exactly 7 unique projects with a minimum author commit threshold, favoring meaningful contributions.

4) Evaluation

evaluator.py uses templates that encode fairness and scoring rules.
Scores include open_source, self_projects, production, and technical_skills, plus bonus and deductions, then an explanation for evidence.

5) Output and CSV export

score.py prints a readable summary to stdout.
When DEVELOPMENT_MODE=True it creates or appends a resume_evaluations.csv with key fields, and caches intermediate JSON under cache/.

CLI usage

End to end scoring

Provide a path to a resume PDF.

$ python score.py /path/to/resume.pdf

What happens:

If development mode is on, the PDF extraction result is cached to cache/resumecache_<basename>.json.
If a GitHub profile is found in the resume, repositories are fetched and cached to cache/githubcache_<basename>.json.
The evaluator prints a report and, in development mode, appends a CSV row to resume_evaluations.csv.

Directory layout

.
├── .env.example
├── .python-version
├── config.py
├── evaluator.py
├── github.py
├── llm_utils.py
├── models.py
├── pdf.py
├── prompt.py
├── prompts/
│   ├── template_manager.py
│   └── templates/
│       ├── awards.jinja
│       ├── basics.jinja
│       ├── education.jinja
│       ├── github_project_selection.jinja
│       ├── projects.jinja
│       ├── resume_evaluation_criteria.jinja
│       ├── resume_evaluation_system_message.jinja
│       ├── skills.jinja
│       ├── system_message.jinja
│       └── work.jinja
├── pymupdf_rag.py
├── requirements.txt
├── score.py
└── transform.py

Provider details

Ollama

Set LLM_PROVIDER=ollama
Set DEFAULT_MODEL to any pulled model, for example gemma3:4b
The provider wrapper in models.OllamaProvider calls ollama.chat

Gemini

Set LLM_PROVIDER=gemini
Set DEFAULT_MODEL to a supported Gemini model, for example gemini-2.0-flash
Provide GEMINI_API_KEY
The wrapper in models.GeminiProvider adapts responses to a unified format

Contributing

Please read the CONTRIBUTING.md for detailed guidelines on filing issues, proposing changes, and submitting pull requests. Key principles include:

Keep prompts declarative and provider-agnostic.
Validate changes with a couple of real resumes under different providers.
Add or adjust unit-free smoke tests that call each stage with minimal inputs.

License

MIT © HackerRank

simplex-chat/simplex-chat

SimpleX - the first messaging network operating without user identifiers of any kind - 100% private by design! iOS, Android and desktop apps 📱!

| 30/03/2023 | EN, FR, CZ, PL |

Invest in SimpleX Chat. Register now.

SimpleX - the first messaging platform that has no user identifiers of any kind - 100% private by design!

Why we are building SimpleX Network

Welcome to SimpleX Chat!

📲 Install the app.
↔️ Connect to the team, join user groups and follow our updates.
🤝 Make a private connection with a friend.
🔤 Help translating SimpleX Chat.
⚡️ Contribute and support us with donations.

Learn more about SimpleX Chat.

Install the app

🖲 Protects your messages and metadata - who you talk to and when.
🔐 Double ratchet end-to-end encryption, with additional encryption layer.
📱 Mobile apps for Android (Google Play, APK) and iOS.
🚀 TestFlight preview for iOS with the new features 1-2 weeks earlier - limited to 10,000 users!
🖥 Available as a terminal (console) app / CLI on Linux, MacOS, Windows.

Connect to the team

You can connect to the team via the app using "chat with the developers button" available when you have no conversations in the profile, "Send questions and ideas" in the app settings or via our SimpleX address. Please connect to:

to ask any questions
to suggest any improvements
to share anything relevant

We are replying the questions manually, so it is not instant – it can take up to 24 hours.

If you are interested in helping us to integrate open-source language models, and in joining our team, please get in touch.

Join user groups

You can find the groups created by users in SimpleX Directory. It is also available as SimpleX bot that allows to add your own groups and communities to the directory. We are not responsible for the content shared in these groups.

Please note: The groups below are created for the users to be able to ask questions, make suggestions and ask questions about SimpleX Chat only.

You can join an English-speaking users group if you want to ask any questions: #SimpleX users group

There is also a group #simplex-devs for developers who build on SimpleX platform:

chat bots and automations
integrations with other apps
social apps and services
etc.

You can join these and other groups by opening these links in the app or by opening them in a desktop browser and scanning the QR code.

Follow our updates

We publish our updates and releases via:

Reddit, Twitter, Lemmy, Mastodon and Nostr.
SimpleX Chat team profile.
blog and RSS feed.
mailing list, very rarely.

Make a private connection

You need to share a link with your friend or scan a QR code from their phone, in person or during a video call, to make a connection and start messaging.

The channel through which you share the link does not have to be secure - it is enough that you can confirm who sent you the message and that your SimpleX connection is established.

After you connect, you can verify connection security code.

User guide (NEW)

Read about the app features and settings in the new User guide.

Contribute

We would love to have you join the development! You can help us with:

develop a chat bot for SimpleX Chat!
writing a tutorial or recipes about hosting servers, chat bots, etc.
developing features - please connect to us via chat so we can help you get started.

Help translating SimpleX Chat

Thanks to our users and Weblate, SimpleX Chat apps, website and documents are translated to many other languages.

Join our translators to help SimpleX grow!

locale	language	contributor	Android and iOS	website	Github docs
🇬🇧 en	English		✓	✓	✓
ar	العربية	jermanuts	-
🇧🇬 bg	Български
🇨🇿 cs	Čeština	zen0bit			✓
🇩🇪 de	Deutsch	mlanp
🇪🇸 es	Español	Mateyhv
🇫🇮 fi	Suomi
🇫🇷 fr	Français	ishi_sama			✓
🇮🇱 he	עִברִית		-
🇭🇺 hu	Magyar		-
🇮🇹 it	Italiano	unbranched
🇯🇵 ja	日本語
🇳🇱 nl	Nederlands	mika-nl
🇵🇱 pl	Polski	BxOxSxS
🇧🇷 pt-BR	Português		-
🇷🇺 ru	Русский
🇹🇭 th	ภาษาไทย	titapa-punpun
🇹🇷 tr	Türkçe
🇺🇦 uk	Українська
🇨🇳 zh-CHS	简体中文	sith-on-mars Float-hu

Languages in progress: Arabic, Japanese, Korean, Portuguese and others. We will be adding more languages as some of the already added are completed – please suggest new languages, review the translation guide and get in touch with us!

Please support us with your donations

Huge thank you to everybody who donated to SimpleX Chat!

We are prioritizing users privacy and security - it would be impossible without your support.

Our pledge to our users is that SimpleX protocols are and will remain open, and in public domain, - so anybody can build the future implementations of the clients and the servers. We are building SimpleX platform based on the same principles as email and web, but much more private and secure.

Your donations help us raise more funds - any amount, even the price of the cup of coffee, would make a big difference for us.

It is possible to donate via:

GitHub (commission-free) or OpenCollective (~10% commission).
BTC: bc1q2gy6f02nn6vvcxs0pnu29tpnpyz0qf66505d4u
XMR: 8A3ZWAXrrQddvnT1fPrtbK86ZAoM4nai3Gjg1LEow3JWcryJtovMnHYZnxTJpCLmAbfWbnPMeTzPmMBjAhyd4xoM89hYq1c
BCH: bitcoincash:qq6c8vfvxqrk6rhdysgvkhqc24sggkfsx5nqvdlqcg
ETH/USDT (Ethereum, Arbitrum One): 0xD7047Fe3Eecb2f2FF78d839dD927Be27Bc12c86a (donate.simplexchat.eth)
ZEC: t1fwjQW5gpFhDqXNhxqDWyF9j9WeKvVS5Jg
ZEC shielded: u16rnvkflumf5uw9frngc2lymvmzgdr2mmc9unyu0l44unwfmdcpfm0axujd2w34ct3ye709azxsqge45705lpvvqu264ltzvfay55ygyq
DOGE: D99pV4n9TrPxBPCkQGx4w4SMSa6QjRBxPf
SOL: 7JCf5m3TiHmYKZVr6jCu1KeZVtb9Y1jRMQDU69p5ARnu
please ask if you want to donate any other coins.

Thank you,

Evgeny

SimpleX Chat founder

Why privacy matters

Everyone should care about privacy and security of their communications - innocuous conversations can put you in danger even if there is nothing to hide.

One of the most shocking stories is the experience of Mohamedou Ould Salahi that he wrote about in his memoir and that is shown in The Mauritanian movie. He was put into Guantanamo camp, without trial, and was tortured there for 15 years after a phone call to his relative in Afghanistan, under suspicion of being involved in 9/11 attacks, even though he lived in Germany for the 10 years prior to the attacks.

It is not enough to use an end-to-end encrypted messenger, we all should use the messengers that protect the privacy of our personal networks - who we are connected with.

SimpleX approach to privacy and security

Complete privacy of your identity, profile, contacts and metadata

Unlike any other existing messaging platform, SimpleX has no identifiers assigned to the users - not even random numbers. This protects the privacy of who are you communicating with, hiding it from SimpleX platform servers and from any observers. Read more.

The best protection against spam and abuse

As you have no identifier on SimpleX platform, you cannot be contacted unless you share a one-time invitation link or an optional temporary user address. Read more.

Complete ownership, control and security of your data

SimpleX stores all user data on client devices, the messages are only held temporarily on SimpleX relay servers until they are received. Read more.

Users own SimpleX network

You can use SimpleX with your own servers and still communicate with people using the servers that are pre-configured in the apps or any other SimpleX servers. Read more.

Frequently asked questions

How SimpleX can deliver messages without any user identifiers? See v2 release announcement explaining how SimpleX works.
Why should I not just use Signal? Signal is a centralized platform that uses phone numbers to identify its users and their contacts. It means that while the content of your messages on Signal is protected with robust end-to-end encryption, there is a large amount of meta-data visible to Signal - who you talk with and when.
How is it different from Matrix, Session, Ricochet, Cwtch, etc., that also don't require user identities? Although these platforms do not require a real identity, they do rely on anonymous user identities to deliver messages – it can be, for example, an identity key or a random number. Using a persistent user identity, even anonymous, creates a risk that user's connection graph becomes known to the observers and/or service providers, and it can lead to de-anonymizing some users. If the same user profile is used to connect to two different people via any messenger other than SimpleX, these two people can confirm if they are connected to the same person - they would use the same user identifier in the messages. With SimpleX there is no meta-data in common between your conversations with different contacts - the quality that no other messaging platform has.

News and updates

Recent and important updates:

Jul 29, 2025 SimpleX Chat v6.4.1: welcome your contacts, review members to protect groups, and more.

Jul 3, 2025 SimpleX network: new experience of connecting with people — available in SimpleX Chat v6.4-beta.4

Mar 8, 2025. SimpleX Chat v6.3: new user experience and safety in public groups

Jan 14, 2025. SimpleX network: large groups and privacy-preserving content moderation

Dec 10, 2024. SimpleX network: preset servers operated by Flux, business chats and more with v6.2 of the apps

Oct 14, 2024. SimpleX network: security review of protocols design by Trail of Bits, v6.1 released with better calls and user experience.

Aug 14, 2024. SimpleX network: the investment from Jack Dorsey and Asymmetric, v6.0 released with the new user experience and private message routing

Jun 4, 2024. SimpleX network: private message routing, v5.8 released with IP address protection and chat themes

Mar 14, 2024. SimpleX Chat v5.6 beta: adding quantum resistance to Signal double ratchet algorithm.

Nov 25, 2023. SimpleX Chat v5.4 released: link mobile and desktop apps via quantum resistant protocol, and much better groups.

Apr 22, 2023. SimpleX Chat: vision and funding, v5.0 released with videos and files up to 1gb.

Mar 1, 2023. SimpleX File Transfer Protocol – send large files efficiently, privately and securely, soon to be integrated into SimpleX Chat apps..

Nov 8, 2022. Security audit by Trail of Bits, the new website and v4.2 released.

All updates

⚡ Quick installation of a terminal app

curl -o- https://raw.githubusercontent.com/simplex-chat/simplex-chat/stable/install.sh | bash

Once the chat client is installed, simply run simplex-chat from your terminal.

Read more about installing and using the terminal app.

SimpleX Platform design

SimpleX is a client-server network with a unique network topology that uses redundant, disposable message relay nodes to asynchronously pass messages via unidirectional (simplex) message queues, providing recipient and sender anonymity.

Unlike P2P networks, all messages are passed through one or several server nodes, that do not even need to have persistence. In fact, the current SMP server implementation uses in-memory message storage, persisting only the queue records. SimpleX provides better metadata protection than P2P designs, as no global participant identifiers are used to deliver messages, and avoids the problems of P2P networks.

Unlike federated networks, the server nodes do not have records of the users, do not communicate with each other and do not store messages after they are delivered to the recipients. There is no way to discover the full list of servers participating in SimpleX network. This design avoids the problem of metadata visibility that all federated networks have and better protects from the network-wide attacks.

Only the client devices have information about users, their contacts and groups.

See SimpleX whitepaper for more information on platform objectives and technical design.

See SimpleX Chat Protocol for the format of messages sent between chat clients over SimpleX Messaging Protocol.

Privacy and security: technical details and limitations

SimpleX Chat is a work in progress – we are releasing improvements as they are ready. You have to decide if the current state is good enough for your usage scenario.

We compiled a glossary of terms used to describe communication systems to help understand some terms below and to help compare advantages and disadvantages of various communication systems.

What is already implemented:

Instead of user profile identifiers used by all other platforms, even the most private ones, SimpleX uses pairwise per-queue identifiers (2 addresses for each unidirectional message queue, with an optional 3rd address for push notifications on iOS, 2 queues in each connection between the users). It makes observing the network graph on the application level more difficult, as for n users there can be up to n * (n-1) message queues.
End-to-end encryption in each message queue using NaCl cryptobox. This is added to allow redundancy in the future (passing each message via several servers), to avoid having the same ciphertext in different queues (that would only be visible to the attacker if TLS is compromised). The encryption keys used for this encryption are not rotated, instead we are planning to rotate the queues. Curve25519 keys are used for key negotiation.
Double ratchet end-to-end encryption in each conversation between two users (or group members). This is the same algorithm that is used in Signal and many other messaging apps; it provides OTR messaging with forward secrecy (each message is encrypted by its own ephemeral key) and break-in recovery (the keys are frequently re-negotiated as part of the message exchange). Two pairs of Curve448 keys are used for the initial key agreement, initiating party passes these keys via the connection link, accepting side - in the header of the confirmation message.
Post-quantum resistant key exchange in double ratchet protocol on every ratchet step. Read more in this post and also see this publication by Apple explaining the need for post-quantum key rotation.
Additional layer of encryption using NaCL cryptobox for the messages delivered from the server to the recipient. This layer avoids having any ciphertext in common between sent and received traffic of the server inside TLS (and there are no identifiers in common as well).
Several levels of content padding to frustrate message size attacks.
All message metadata, including the time when the message was received by the server (rounded to a second) is sent to the recipients inside an encrypted envelope, so even if TLS is compromised it cannot be observed.
Only TLS 1.2/1.3 are allowed for client-server connections, limited to cryptographic algorithms: CHACHA20POLY1305_SHA256, Ed25519/Ed448, Curve25519/Curve448.
To protect against replay attacks SimpleX servers require tlsunique channel binding as session ID in each client command signed with per-queue ephemeral key.
To protect your IP address from unknown messaging relays, and for per-message transport anonymity (compared with Tor/VPN per-connection anonymity), from v6.0 all SimpleX Chat clients use private message routing by default. Read more in this post.
To protect your IP address from unknown file relays, when SOCKS proxy is not enabled SimpleX Chat clients ask for a confirmation before downloading the files from unknown servers.
To protect your IP address from known servers all SimpleX Chat clients support accessing messaging servers via Tor - see v3.1 release announcement for more details.
Local database encryption with passphrase - your contacts, groups and all sent and received messages are stored encrypted. If you used SimpleX Chat before v4.0 you need to enable the encryption via the app settings.
Transport isolation - different TCP connections and Tor circuits are used for traffic of different user profiles, optionally - for different contacts and group member connections.
Manual messaging queue rotations to move conversation to another SMP relay.
Sending end-to-end encrypted files using XFTP protocol.
Local files encryption.
Reproducible server builds.

We plan to add:

Automatic message queue rotation and redundancy. Currently the queues created between two users are used until the queue is manually changed by the user or contact is deleted. We are planning to add automatic queue rotation to make these identifiers temporary and rotate based on some schedule TBC (e.g., every X messages, or every X hours/days).
Message "mixing" - adding latency to message delivery, to protect against traffic correlation by message time.
Reproducible clients builds – this is a complex problem, but we are aiming to have it in 2025 at least partially.
Recipients' XFTP relays to reduce traffic and conceal IP addresses from the relays chosen, and potentially controlled, by another party.

For developers

You can:

create chat bots and services.
run simplex-chat terminal CLI to execute individual chat commands, e.g. to send messages as part of shell script execution.
use SimpleX Chat library to integrate chat functionality into your mobile apps.
create chat bots and services in Haskell - see simple and more advanced chat bot example.

If you are considering developing with SimpleX platform please get in touch for any advice and support.

Please also join #simplex-devs group to ask any questions and share your success stories.

Develop a chat bot

You can create a chat bot or any chat-based service in any language running SimpleX Chat terminal CLI as a local WebSocket server.

See our new bot API reference. Most of it is automatically generated from core library types, so it stays up to date.

Also see TypeScript SimpleX Chat client and JavaScript chat bot example.

Roadmap

✅ Easy to deploy SimpleX server with in-memory message storage, without any dependencies.
✅ Terminal (console) client with groups and files support.
✅ One-click SimpleX server deployment on Linode.
✅ End-to-end encryption using double-ratchet protocol with additional encryption layer.
✅ Mobile apps v1 for Android and iOS.
✅ Private instant notifications for Android using background service.
✅ Haskell chat bot templates.
✅ v2.0 - supporting images and files in mobile apps.
✅ Manual chat history deletion.
✅ End-to-end encrypted WebRTC audio and video calls via the mobile apps.
✅ Privacy preserving instant notifications for iOS using Apple Push Notification service.
✅ Chat database export and import.
✅ Chat groups in mobile apps.
✅ Connecting to messaging servers via Tor.
✅ Dual server addresses to access messaging servers as v3 hidden services.
✅ Chat server and TypeScript client SDK to develop chat interfaces, integrations and chat bots (ready for announcement).
✅ Incognito mode to share a new random name with each contact.
✅ Chat database encryption.
✅ Automatic chat history deletion.
✅ Links to join groups and improve groups stability.
✅ Voice messages (with recipient opt-out per contact).
✅ Basic authentication for SMP servers (to authorize creating new queues).
✅ View deleted messages, full message deletion by sender (with recipient opt-in per contact).
✅ Block screenshots and view in recent apps.
✅ Advanced server configuration.
✅ Disappearing messages (with recipient opt-in per-contact).
✅ "Live" messages.
✅ Contact verification via a separate out-of-band channel.
✅ Multiple user profiles in the same chat database.
✅ Optionally avoid re-using the same TCP session for multiple connections.
✅ Preserve message drafts.
✅ File server to optimize for efficient and private sending of large files.
✅ Improved audio & video calls.
✅ Support older Android OS and 32-bit CPUs.
✅ Hidden chat profiles.
✅ Sending and receiving large files via XFTP protocol.
✅ Video messages.
✅ App access passcode.
✅ Improved Android app UI design.
✅ Optional alternative access password.
✅ Message reactions
✅ Message editing history
✅ Reduced battery and traffic usage in large groups.
✅ Message delivery confirmation (with sender opt-out per contact).
✅ Desktop client.
✅ Encryption of local files stored in the app.
✅ Using mobile profiles from the desktop app.
✅ Private notes.
✅ Improve sending videos (including encryption of locally stored videos).
✅ Post-quantum resistant key exchange in double ratchet protocol.
✅ Message delivery relay for senders (to conceal IP address from the recipients' servers and to reduce the traffic).
✅ Support multiple network operators in the app.
🏗 Large groups, communities and public channels.
🏗 Short links to connect and join groups.
🏗 Improve stability and reduce battery usage.
🏗 Improve experience for the new users.
Privacy & security slider - a simple way to set all settings at once.
SMP queue redundancy and rotation (manual is supported).
Include optional message into connection request sent via contact address.
Improved navigation and search in the conversation (expand and scroll to quoted message, scroll to search results, etc.).
Feeds/broadcasts.
Ephemeral/disappearing/OTR conversations with the existing contacts.
Privately share your location.
Web widgets for custom interactivity in the chats.
Programmable chat automations / rules (automatic replies/forward/deletion/sending, reminders, etc.).
Privacy-preserving identity server for optional DNS-based contact/group addresses to simplify connection and discovery, but not used to deliver messages:
- keep all your contacts and groups even if you lose the domain.
- the server doesn't have information about your contacts and groups.
High capacity multi-node SMP relays.

Disclaimers

SimpleX protocols and security model was reviewed, and had many breaking changes and improvements in v1.0.0.

The implementation security assessment of SimpleX cryptography and networking was done in October 2022 by Trail of Bits – see the announcement.

The cryptographic review of SimpleX protocols was done in July 2024 by Trail of Bits – see the announcement.

SimpleX Chat is still a relatively early stage platform (the mobile apps were released in March 2022), so you may discover some bugs and missing features. We would really appreciate if you let us know anything that needs to be fixed or improved.

The default servers configured in the app are provided on the best effort basis. We are currently not guaranteeing any SLAs, although historically our servers had over 99.9% uptime each.

We have never provided or have been requested access to our servers or any information from our servers by any third parties. If we are ever requested to provide such access or information, we will be following due legal process.

We do not log IP addresses of the users and we do not perform any traffic correlation on our servers. If transport level security is critical you must use Tor or some other similar network to access messaging servers. We will be improving the client applications to reduce the opportunities for traffic correlation.

Please read more in Privacy Policy.

Security contact

Please see our Security Policy on how to report security vulnerabilities to us. We will coordinate the fix and disclosure.

Please do NOT report security vulnerabilities via GitHub issues.

License

This software is licensed under the GNU Affero General Public License version 3 (AGPLv3). See the LICENSE file for details. The SimpleX and SimpleX Chat name, logo, associated branding materials, and application and website graphic assets (illustrations, images, visual designs, etc.) are not covered by this license and are subject to the terms outlined in the TRADEMARK and ASSETS_LICENSE files respectively.

If you want to use any graphic assets in your publications, please ask for permission. Texts can be used as direct quotes, referencing the source.

ocornut/imgui

Dear ImGui: Bloat-free Graphical User interface for C++ with minimal dependencies

Dear ImGui

"Give someone state and they'll have a bug one day, but teach them how to represent state in two separate locations that have to be kept in sync and they'll have bugs for a lifetime." -ryg

_{(This library is available under a free and permissive license, but needs financial support to sustain its continued improvements. In addition to maintenance and stability there are many desirable features yet to be added. If your company is using Dear ImGui, please consider reaching out.)}

Businesses: support continued development and maintenance via invoiced sponsoring/support contracts:
E-mail: contact @ dearimgui dot com
Individuals: support continued development and maintenance here. Also see Funding page.

The Pitch - Usage - How it works - Releases & Changelogs - Demo - Getting Started & Integration
Gallery - Support, FAQ - How to help - Funding & Sponsors - Credits - License
Wiki - Extensions - Language bindings & framework backends - Software using Dear ImGui - User quotes

The Pitch

Dear ImGui is a bloat-free graphical user interface library for C++. It outputs optimized vertex buffers that you can render anytime in your 3D-pipeline-enabled application. It is fast, portable, renderer agnostic, and self-contained (no external dependencies).

Dear ImGui is designed to enable fast iterations and to empower programmers to create content creation tools and visualization / debug tools (as opposed to UI for the average end-user). It favors simplicity and productivity toward this goal and lacks certain features commonly found in more high-level libraries. Among other things, full internationalization (right-to-left text, bidirectional text, text shaping etc.) and accessibility features are not supported.

Dear ImGui is particularly suited to integration in game engines (for tooling), real-time 3D applications, fullscreen applications, embedded applications, or any applications on console platforms where operating system features are non-standard.

Minimize state synchronization.
Minimize UI-related state storage on user side.
Minimize setup and maintenance.
Easy to use to create dynamic UI which are the reflection of a dynamic data set.
Easy to use to create code-driven and data-driven tools.
Easy to use to create ad hoc short-lived tools and long-lived, more elaborate tools.
Easy to hack and improve.
Portable, minimize dependencies, run on target (consoles, phones, etc.).
Efficient runtime and memory consumption.
Battle-tested, used by many major actors in the game industry.

Usage

The core of Dear ImGui is self-contained within a few platform-agnostic files which you can easily compile in your application/engine. They are all the files in the root folder of the repository (imgui*.cpp, imgui*.h). No specific build process is required: you can add all files into your existing project.

Backends for a variety of graphics API and rendering platforms are provided in the backends/ folder, along with example applications in the examples/ folder. You may also create your own backend. Anywhere where you can render textured triangles, you can render Dear ImGui.

C++20 users wishing to use a module may use the stripe2933/imgui-module third-party extension.

See the Getting Started & Integration section of this document for more details.

After Dear ImGui is set up in your application, you can use it from _anywhere_ in your program loop:

ImGui::Text("Hello, world %d", 123);
if (ImGui::Button("Save"))
    MySaveFunction();
ImGui::InputText("string", buf, IM_COUNTOF(buf));
ImGui::SliderFloat("float", &f, 0.0f, 1.0f);

// Create a window called "My First Tool", with a menu bar.
ImGui::Begin("My First Tool", &my_tool_active, ImGuiWindowFlags_MenuBar);
if (ImGui::BeginMenuBar())
{
    if (ImGui::BeginMenu("File"))
    {
        if (ImGui::MenuItem("Open..", "Ctrl+O")) { /* Do stuff */ }
        if (ImGui::MenuItem("Save", "Ctrl+S"))   { /* Do stuff */ }
        if (ImGui::MenuItem("Close", "Ctrl+W"))  { my_tool_active = false; }
        ImGui::EndMenu();
    }
    ImGui::EndMenuBar();
}

// Edit a color stored as 4 floats
ImGui::ColorEdit4("Color", my_color);

// Generate samples and plot them
float samples[100];
for (int n = 0; n < 100; n++)
    samples[n] = sinf(n * 0.2f + ImGui::GetTime() * 1.5f);
ImGui::PlotLines("Samples", samples, 100);

// Display contents in a scrolling region
ImGui::TextColored(ImVec4(1,1,0,1), "Important Stuff");
ImGui::BeginChild("Scrolling");
for (int n = 0; n < 50; n++)
    ImGui::Text("%04d: Some text", n);
ImGui::EndChild();
ImGui::End();

Dear ImGui allows you to create elaborate tools as well as very short-lived ones. On the extreme side of short-livedness: using the Edit&Continue (hot code reload) feature of modern compilers you can add a few widgets to tweak variables while your application is running, and remove the code a minute later! Dear ImGui is not just for tweaking values. You can use it to trace a running algorithm by just emitting text commands. You can use it along with your own reflection data to browse your dataset live. You can use it to expose the internals of a subsystem in your engine, to create a logger, an inspection tool, a profiler, a debugger, an entire game-making editor/framework, etc.

How it works

The IMGUI paradigm through its API tries to minimize superfluous state duplication, state synchronization, and state retention from the user's point of view. It is less error-prone (less code and fewer bugs) than traditional retained-mode interfaces, and lends itself to creating dynamic user interfaces. Check out the Wiki's About the IMGUI paradigm section for more details.

Dear ImGui outputs vertex buffers and command lists that you can easily render in your application. The number of draw calls and state changes required to render them is fairly small. Because Dear ImGui doesn't know or touch graphics state directly, you can call its functions anywhere in your code (e.g. in the middle of a running algorithm, or in the middle of your own rendering process). Refer to the sample applications in the examples/ folder for instructions on how to integrate Dear ImGui with your existing codebase.

A common misunderstanding is to mistake immediate mode GUI for immediate mode rendering, which usually implies hammering your driver/GPU with a bunch of inefficient draw calls and state changes as the GUI functions are called. This is NOT what Dear ImGui does. Dear ImGui outputs vertex buffers and a small list of draw calls batches. It never touches your GPU directly. The draw call batches are decently optimal and you can render them later, in your app or even remotely.

Releases & Changelogs

See Releases page for decorated Changelogs. Reading the changelogs is a good way to keep up to date with the things Dear ImGui has to offer, and maybe will give you ideas of some features that you've been ignoring until now!

Demo

Calling the ImGui::ShowDemoWindow() function will create a demo window showcasing a variety of features and examples. The code is always available for reference in imgui_demo.cpp.

imgui_explorer: Web version of the demo w/ source code browser, courtesy of @pthom.

You should be able to build the examples from sources. If you don't, let us know! If you want to have a quick look at some Dear ImGui features, you can download Windows binaries of the demo app here:

imgui-demo-binaries-20260225.zip (Windows, 1.92.6, built 2026/02/25, master) or older binaries.

Gallery

Examples projects using Dear ImGui: Tracy (profiler), ImHex (hex editor/data analysis), RemedyBG (debugger) and hundreds of others.

For more user-submitted screenshots of projects using Dear ImGui, check out the Gallery Threads!

For a list of third-party widgets and extensions, check out the Useful Extensions/Widgets wiki page.


Custom engine erhe (docking branch)	Custom engine for Wonder Boy: The Dragon's Trap (2017)
Custom engine (untitled)	Tracy Profiler (github)

Getting Started & Integration

See the Getting Started guide for details.

On most platforms and when using C++, you should be able to use a combination of the imgui_impl_xxxx backends without modification (e.g. imgui_impl_win32.cpp + imgui_impl_dx11.cpp). If your engine supports multiple platforms, consider using more imgui_impl_xxxx files instead of rewriting them: this will be less work for you, and you can get Dear ImGui running immediately. You can later decide to rewrite a custom backend using your custom engine functions if you wish so.

Integrating Dear ImGui within your custom engine is a matter of mainly 1) wiring mouse/keyboard/gamepad inputs 2) uploading a texture to your GPU/render engine 3) providing a render function that can create/update textures and render textured triangles. This is exactly what backends are doing.

The examples/ folder is populated with applications setting up a window and using standard backends.
The Getting Started guide has instructions to integrate imgui into an existing application using standard backends. It should in theory take you less than an hour to integrate Dear ImGui into your existing codebase where support libraries are linked. Less if you read carefully.
The Backends guide explains what backends are doing, and has instructions to implement a custom backend. You can also refer to the source code of our ~20 backends to understand how they work.
Generally, make sure to spend time reading the FAQ, comments, and the examples applications!

Officially maintained backends (in repository):

Renderers: DirectX9, DirectX10, DirectX11, DirectX12, Metal 3/4, OpenGL/ES/ES2, SDL_GPU, SDL_Renderer2/3, Vulkan, WebGPU.
Platforms: GLFW, SDL2/SDL3, Win32, Glut, OSX, Android.
Frameworks: Allegro5, Emscripten.

Third-party backends/bindings wiki page:

Languages: C, C# and: Beef, ChaiScript, CovScript, Crystal, D, Go, Haskell, Haxe/hxcpp, Java, JavaScript, Julia, Kotlin, Lobster, Lua, Nim, Odin, Pascal, PureBasic, Python, ReaScript, Ruby, Rust, Swift, Zig...
Frameworks: AGS/Adventure Game Studio, Amethyst, Blender, bsf, Cinder, Cocos2d-x, Defold, Diligent Engine, Ebiten, Flexium, GML/Game Maker Studio, GLEQ, Godot, GTK3, Irrlicht Engine, JUCE, LÖVE+LUA, Mach Engine, Magnum, Marmalade, Monogame, NanoRT, nCine, Nim Game Lib, Nintendo 3DS/Switch/WiiU (homebrew), Ogre, openFrameworks, OSG/OpenSceneGraph, Orx, Photoshop, px_render, Qt/QtDirect3D, raylib, SFML, Sokol, Unity, Unreal Engine 4/5, UWP, vtk, VulkanHpp, VulkanSceneGraph, Win32 GDI, WxWidgets.
Many bindings are auto-generated (by good old cimgui or our newer dear_bindings), you can use their metadata output to generate bindings for other languages.

Useful Extensions/Widgets wiki page:

Automation/testing, Text editors, node editors, timeline editors, plotting, software renderers, remote network access, memory editors, gizmos, etc. Notable and well supported extensions include ImPlot, ImPlot3d and Dear ImGui Test Engine.

Also see Wiki for more links and ideas.

Support, Frequently Asked Questions (FAQ)

See: Frequently Asked Questions (FAQ) where common questions are answered.

See: Getting Started and Wiki for many links, references, articles.

See: Articles about the IMGUI paradigm to read/learn about the Immediate Mode GUI paradigm.

See: Upcoming Changes.

See: Dear ImGui Test Engine + Test Suite for Automation & Testing.

For the purposes of getting search engines to crawl the wiki, here's a link to the Crawlable Wiki (not for humans, here's why).

Getting started? For first-time users having issues compiling/linking/running or issues loading fonts, please use GitHub Discussions. For ANY other questions, bug reports, requests, feedback, please post on GitHub Issues. Please read and fill the New Issue template carefully.

Private support is available for paying business customers (E-mail: contact @ dearimgui dot com).

Which version should I get?

We occasionally tag Releases (with nice releases notes) but it is generally safe and recommended to sync to latest master or docking branch. The library is fairly stable and regressions tend to be fixed fast when reported. Advanced users may want to use the docking branch with Multi-Viewport and Docking features. This branch is kept in sync with master regularly.

Who uses Dear ImGui?

See the Quotes, Funding & Sponsors, and Software using Dear ImGui Wiki pages for an idea of who is using Dear ImGui. Please add your game/software if you can! Also, see the Gallery Threads!

How to help

How can I help?

See GitHub Forum/Issues.
You may help with development and submit pull requests! Please understand that by submitting a PR you are also submitting a request for the maintainer to review your code and then take over its maintenance forever. PR should be crafted both in the interest of the end-users and also to ease the maintainer into understanding and accepting it.
See Help wanted on the Wiki for some more ideas.
Be a Funding Supporter! Have your company financially support this project via invoiced sponsors/maintenance or by buying a license for Dear ImGui Test Engine (please reach out: contact AT dearimgui DOT com).

Credits

Developed by Omar Cornut and every direct or indirect contributors to the GitHub. The early version of this library was developed with the support of Media Molecule and first used internally on the game Tearaway (PS Vita).

Recurring contributors include Rokas Kupstys @rokups (2020-2022): a good portion of work on automation system and regression tests now available in Dear ImGui Test Engine.

Maintenance/support contracts, sponsoring invoices and other B2B transactions are hosted and handled by Disco Hello.

Omar: "I first discovered the IMGUI paradigm at Q-Games where Atman Binstock had dropped his own simple implementation in the codebase, which I spent quite some time improving and thinking about. It turned out that Atman was exposed to the concept directly by working with Casey. When I moved to Media Molecule I rewrote a new library trying to overcome the flaws and limitations of the first one I've worked with. It became this library and since then I have spent an unreasonable amount of time iterating and improving it."

Embeds ProggyClean font by Tristan Grimmer (MIT license).
Embeds ProggyForever fonts by Disco Hello, Tristan Grimmer (MIT license).
Embeds stb_textedit.h, stb_truetype.h, stb_rect_pack.h by Sean Barrett (public domain).

Inspiration, feedback, and testing for early versions: Casey Muratori, Atman Binstock, Mikko Mononen, Emmanuel Briney, Stefan Kamoda, Anton Mikhailov, Matt Willis. Special thanks to Alex Evans, Patrick Doane, Marco Koegler for kindly helping. Also thank you to everyone posting feedback, questions and patches on GitHub.

License

Dear ImGui is licensed under the MIT License, see LICENSE.txt for more information.

wonderwhy-er/DesktopCommanderMCP

This is MCP server for Claude that gives it terminal control, file system search and diff file editing capabilities

Desktop Commander MCP

Search, update, manage files and run terminal commands with AI

Work with code and text, run processes, and automate tasks, going far beyond other AI editors - while using host client subscriptions instead of API token costs.

🖥️ Try the Desktop Commander App (Beta)

Want a better experience? The Desktop Commander App gives you everything the MCP server does, plus:

Use any AI model — Claude, GPT-4.5, Gemini 2.5, or any model you prefer
See file changes live — visual file previews as AI edits your files
Add custom MCPs and context — extend with your own tools, no config files
Coming soon — skills system, dictation, background scheduled tasks, and more

👉 Download the App (macOS & Windows)

The MCP server below still works great with Claude Desktop and other MCP clients — the app is for those who want a dedicated, polished experience.

All of your AI development tools in one place. Desktop Commander puts all dev tools in one chat. Execute long-running terminal commands on your computer and manage processes through Model Context Protocol (MCP). Built on top of MCP Filesystem Server to provide additional search and replace file editing capabilities.

Features

Remote AI Control - Use Desktop Commander from ChatGPT, Claude web, and other AI services via Remote MCP
File Preview UI - Visual file previews in Claude Desktop with rendered markdown, inline images, expandable content, built-in markdown editor, and quick "Open in folder" access
Enhanced terminal commands with interactive process control
Execute code in memory (Python, Node.js, R) without saving files
Instant data analysis - just ask to analyze CSV/JSON/Excel files
Native Excel file support - Read, write, edit, and search Excel files (.xlsx, .xls, .xlsm) without external tools
PDF support - Read PDFs with text extraction, create new PDFs from markdown, modify existing PDFs
DOCX support - Read, create, edit, and search Word documents (.docx) with surgical XML editing and markdown-to-DOCX conversion
Interact with running processes (SSH, databases, development servers)
Execute terminal commands with output streaming
Command timeout and background execution support
Process management (list and kill processes)
Session management for long-running commands
Process output pagination - Read terminal output with offset/length controls to prevent context overflow
Server configuration management:
- Get/set configuration values
- Update multiple settings at once
- Dynamic configuration changes without server restart
Full filesystem operations:
- Read/write files (text, Excel, PDF, DOCX)
- Create/list directories
- Recursive directory listing with configurable depth and context overflow protection for large folders
- Move files/directories
- Search files and content (including Excel content)
- Get file metadata
- Negative offset file reading: Read from end of files using negative offset values (like Unix tail)
Code editing capabilities:
- Surgical text replacements for small changes
- Full file rewrites for major changes
- Multiple file support
- Pattern-based replacements
- vscode-ripgrep based recursive code or text search in folders
Comprehensive audit logging:
- All tool calls are automatically logged
- Log rotation with 10MB size limit
- Detailed timestamps and arguments
Safety guardrails (not a sandbox — see SECURITY.md):
- Symlink traversal prevention on file operations
- Command blocklist for accidental execution
- Docker isolation for complete isolation

How to install

Install in Claude Desktop

Desktop Commander offers multiple installation methods for Claude Desktop.

📋 Update & Uninstall Information: Options 1, 2, 3, 4, and 6 have automatic updates. Option 5 requires manual updates. See below for details.

Option 1: Install through npx ⭐ Auto-Updates (Requires Node.js)

Just run this in terminal:

npx @wonderwhy-er/desktop-commander@latest setup

For debugging mode (allows Node.js inspector connection):

npx @wonderwhy-er/desktop-commander@latest setup --debug

Command line options during setup:

--debug: Enable debugging mode for Node.js inspector
--no-onboarding: Disable onboarding prompts for new users

Restart Claude if running.

✅ Auto-Updates: Yes - automatically updates when you restart Claude
🔄 Manual Update: Run the setup command again
🗑️ Uninstall: Run npx @wonderwhy-er/desktop-commander@latest remove

Option 2: Using bash script installer (macOS) ⭐ Auto-Updates (Installs Node.js if needed)

curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install.sh | bash

This script handles all dependencies and configuration automatically.

✅ Auto-Updates: Yes
🔄 Manual Update: Re-run the bash installer command above
🗑️ Uninstall: Run npx @wonderwhy-er/desktop-commander@latest remove

Option 3: Installing via Smithery ⭐ Auto-Updates (Requires Node.js)

Visit: https://smithery.ai/server/@wonderwhy-er/desktop-commander
Login to Smithery if you haven't already
Select your client (Claude Desktop) on the right side
Install with the provided key that appears after selecting your client
Restart Claude Desktop

✅ Auto-Updates: Yes - automatically updates when you restart Claude
🔄 Manual Update: Visit the Smithery page and reinstall

Option 4: Add to claude_desktop_config manually ⭐ Auto-Updates (Requires Node.js)

Add this entry to your claude_desktop_config.json:

On Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%\Claude\claude_desktop_config.json
On Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": [
        "-y",
        "@wonderwhy-er/desktop-commander@latest"
      ]
    }
  }
}

Restart Claude if running.

Option 5: Checkout locally ❌ Manual Updates (Requires Node.js)

git clone https://github.com/wonderwhy-er/DesktopCommanderMCP.git
cd DesktopCommanderMCP
npm run setup

Restart Claude if running.

The setup command will install dependencies, build the server, and configure Claude's desktop app.

❌ Auto-Updates: No - requires manual git updates
🔄 Manual Update: cd DesktopCommanderMCP && git pull && npm run setup
🗑️ Uninstall: Run npx @wonderwhy-er/desktop-commander@latest remove or remove the cloned directory and MCP server entry from Claude config

Option 6: Docker Installation 🐳 ⭐ Auto-Updates (No Node.js Required)

Perfect for users who want isolation or don't have Node.js installed. Runs in a sandboxed Docker container with a persistent work environment.

Prerequisites: Docker Desktop installed and running, Claude Desktop app installed.

macOS/Linux:

bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh)

Windows PowerShell:

iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'))

The installer will check Docker, pull the image, prompt for folder mounting, and configure Claude Desktop.

Docker persistence: Your tools, configs, work files, and package caches all survive restarts.

Manual Docker Configuration

Basic setup (no file access):

{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/desktop-commander:latest"]
    }
  }
}

With folder mounting:

{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/username/Desktop:/mnt/desktop",
        "-v", "/Users/username/Documents:/mnt/documents",
        "mcp/desktop-commander:latest"
      ]
    }
  }
}

Advanced folder mounting:

{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "dc-system:/usr",
        "-v", "dc-home:/root", 
        "-v", "dc-workspace:/workspace",
        "-v", "dc-packages:/var",
        "-v", "/Users/username/Projects:/mnt/Projects",
        "-v", "/Users/username/Downloads:/mnt/Downloads",
        "mcp/desktop-commander:latest"
      ]
    }
  }
}

Docker Management Commands

macOS/Linux:

# Check status
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --status

# Reset all persistent data
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset

Windows PowerShell:

# Check status
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Status

# Reset all data
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Reset

# Show help
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Help

Troubleshooting: Reset and reinstall from scratch:

bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset && bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh)

✅ Auto-Updates: Yes - latest tag automatically gets newer versions
🔄 Manual Update: docker pull mcp/desktop-commander:latest then restart Claude

Install in Other Clients

Desktop Commander works with any MCP-compatible client. The standard JSON configuration is:

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander@latest"]
    }
  }
}

Add this to your client's MCP configuration file at the locations below:

Cursor

View MCP Server in Directory

Or add manually to ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project folder (project-specific).

See Cursor MCP docs for more info.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json. See Windsurf MCP docs for more info.

VS Code / GitHub Copilot

Add to .vscode/mcp.json in your project or VS Code User Settings (JSON). Make sure MCP is enabled under Chat > MCP. Works in Agent mode.

See VS Code MCP docs for more info.

Cline

Configure through the Cline extension settings in VS Code. Open the Cline sidebar, click the MCP Servers icon, and add the JSON configuration above. See Cline MCP docs for more info.

Roo Code

Add to your Roo Code MCP configuration file. See Roo Code MCP docs for more info.

Claude Code

claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest

Remove --scope user to install for the current project only. See Claude Code MCP docs for more info.

Trae

Use the "Add manually" feature and paste the JSON configuration above. See Trae MCP docs for more info.

Kiro

Navigate to Kiro > MCP Servers, click + Add, and paste the JSON configuration above. See Kiro MCP docs for more info.

Codex (OpenAI)

Codex uses TOML configuration. Run this command to add Desktop Commander:

codex mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest

Or manually add to ~/.codex/config.toml:

[mcp_servers.desktop-commander]
command = "npx"
args = ["-y", "@wonderwhy-er/desktop-commander@latest"]

See Codex MCP docs for more info.

JetBrains (AI Assistant)

In JetBrains IDEs, go to Settings → Tools → AI Assistant → Model Context Protocol (MCP), click + Add, select As JSON, and paste the JSON configuration above. See JetBrains MCP docs for more info.

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander@latest"]
    }
  }
}

See Gemini CLI docs for more info.

Augment Code

Press Cmd/Ctrl+Shift+P, open the Augment panel, and add a new MCP server named desktop-commander with the JSON configuration above. See Augment Code MCP docs for more info.

Qwen Code

Run this command to add Desktop Commander:

qwen mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest

Or add to .qwen/settings.json (project) or ~/.qwen/settings.json (global). See Qwen Code MCP docs for more info.

ChatGPT / Claude Web (Remote MCP)

Use Desktop Commander from ChatGPT, Claude web, and other AI services via Remote MCP — no desktop app required.

👉 Get started at mcp.desktopcommander.app

How it works:

You run a lightweight Remote Device on your computer
It connects securely to the cloud Remote MCP service
Your AI sends commands through the cloud to your device
Commands execute locally, results return to your AI
You stay in control — stop anytime with Ctrl+C

Security

✅ Device only runs when you start it
✅ Commands execute under your user permissions
✅ Secure OAuth authentication and encrypted communication channel

Updating & Uninstalling Desktop Commander

Automatic Updates (Options 1, 2, 3, 4 & 6)

Options 1 (npx), Option 2 (bash installer), 3 (Smithery), 4 (manual config), and 6 (Docker) automatically update to the latest version whenever you restart Claude. No manual intervention needed.

Manual Updates (Option 5)

Option 5 (local checkout): cd DesktopCommanderMCP && git pull && npm run setup

Uninstalling Desktop Commander

🤖 Automatic Uninstallation (Recommended)

The easiest way to completely remove Desktop Commander:

npx @wonderwhy-er/desktop-commander@latest remove

This automatic uninstaller will:

✅ Remove Desktop Commander from Claude's MCP server configuration
✅ Create a backup of your Claude config before making changes
✅ Provide guidance for complete package removal
✅ Restore from backup if anything goes wrong

🔧 Manual Uninstallation

If the automatic uninstaller doesn't work or you prefer manual removal:

Remove from Claude Configuration

Locate your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Edit the config file:

Open the file in a text editor
Find and remove the "desktop-commander" entry from the "mcpServers" section
Save the file

Example - Remove this section:

{
    "desktop-commander": {
      "command": "npx",
      "args": ["@wonderwhy-er/desktop-commander@latest"]
    }
}

Close and restart Claude Desktop to complete the removal.

🆘 Troubleshooting

If automatic uninstallation fails:

Use manual uninstallation as a fallback

If Claude won't start after uninstalling:

Restore the backup config file created by the uninstaller
Or manually fix the JSON syntax in your claude_desktop_config.json

Need help?

Join our Discord community: https://discord.com/invite/kQ27sNnZr7

Getting Started

Once Desktop Commander is installed and Claude Desktop is restarted, you're ready to supercharge your Claude experience!

🚀 New User Onboarding

Desktop Commander includes intelligent onboarding to help you discover what's possible:

For New Users: When you're just getting started (fewer than 10 successful commands), Claude will automatically offer helpful getting-started guidance and practical tutorials after you use Desktop Commander successfully.

Request Help Anytime: You can ask for onboarding assistance at any time by simply saying:

"Help me get started with Desktop Commander"
"Show me Desktop Commander examples"
"What can I do with Desktop Commander?"

Claude will then show you beginner-friendly tutorials and examples, including:

📁 Organizing your Downloads folder automatically
📊 Analyzing CSV/Excel files with Python
⚙️ Setting up GitHub Actions CI/CD
🔍 Exploring and understanding codebases
🤖 Running interactive development environments

Usage

The server provides a comprehensive set of tools organized into several categories:

Available Tools

Category	Tool	Description
Configuration	`get_config`	Get the complete server configuration as JSON (includes blockedCommands, defaultShell, allowedDirectories, fileReadLineLimit, fileWriteLineLimit, telemetryEnabled)
	`set_config_value`	Set a specific configuration value by key. Available settings: • `blockedCommands`: Array of shell commands that cannot be executed • `defaultShell`: Shell to use for commands (e.g., bash, zsh, powershell) • `allowedDirectories`: Array of filesystem paths the server can access for file operations (⚠️ terminal commands can still access files outside these directories) • `fileReadLineLimit`: Maximum lines to read at once (default: 1000) • `fileWriteLineLimit`: Maximum lines to write at once (default: 50) • `telemetryEnabled`: Enable/disable telemetry (boolean)
Terminal	`start_process`	Start programs with smart detection of when they're ready for input
	`interact_with_process`	Send commands to running programs and get responses
	`read_process_output`	Read output from running processes
	`force_terminate`	Force terminate a running terminal session
	`list_sessions`	List all active terminal sessions
	`list_processes`	List all running processes with detailed information
	`kill_process`	Terminate a running process by PID
Filesystem	`read_file`	Read contents from local filesystem, URLs, Excel files (.xlsx, .xls, .xlsm), and PDFs with line/page-based pagination
	`read_multiple_files`	Read multiple files simultaneously
	`write_file`	Write file contents with options for rewrite or append mode. Supports Excel files (JSON 2D array format). For PDFs, use `write_pdf`
	`write_pdf`	Create new PDF files from markdown or modify existing PDFs (insert/delete pages). Supports HTML/CSS styling and SVG graphics
	`create_directory`	Create a new directory or ensure it exists
	`list_directory`	Get detailed recursive listing of files and directories (supports depth parameter, default depth=2)
	`move_file`	Move or rename files and directories
	`start_search`	Start streaming search for files by name or content patterns (searches text files and Excel content)
	`get_more_search_results`	Get paginated results from active search with offset support
	`stop_search`	Stop an active search gracefully
	`list_searches`	List all active search sessions
	`get_file_info`	Retrieve detailed metadata about a file or directory (includes sheet info for Excel files)
Text Editing	`edit_block`	Apply targeted text replacements for text files, or range-based cell updates for Excel files
Analytics	`get_usage_stats`	Get usage statistics for your own insight
	`get_recent_tool_calls`	Get recent tool call history with arguments and outputs for debugging and context recovery
	`give_feedback_to_desktop_commander`	Open feedback form in browser to provide feedback to Desktop Commander Team

Quick Examples

Data Analysis:

"Analyze sales.csv and show top customers" → Claude runs Python code in memory

Remote Access:

"SSH to my server and check disk space" → Claude maintains SSH session

Development:

"Start Node.js and test this API" → Claude runs interactive Node session

Tool Usage Examples

Search/Replace Block Format:

filepath.ext
<<<<<<< SEARCH
content to find
=======
new content
>>>>>>> REPLACE

Example:

src/main.js
<<<<<<< SEARCH
console.log("old message");
=======
console.log("new message");
>>>>>>> REPLACE

Enhanced Edit Block Features

The edit_block tool includes several enhancements for better reliability:

Improved Prompting: Tool descriptions now emphasize making multiple small, focused edits rather than one large change
Fuzzy Search Fallback: When exact matches fail, it performs fuzzy search and provides detailed feedback
Character-level Diffs: Shows exactly what's different using {-removed-}{+added+} format
Multiple Occurrence Support: Can replace multiple instances with expected_replacements parameter
Comprehensive Logging: All fuzzy searches are logged for analysis and debugging

When a search fails, you'll see detailed information about the closest match found, including similarity percentage, execution time, and character differences. All these details are automatically logged for later analysis using the fuzzy search log tools.

Docker Support

🐳 Isolated Environment Usage

Desktop Commander can be run in Docker containers for complete isolation from your host system, providing zero risk to your computer. This is perfect for testing, development, or when you want complete sandboxing.

Installation Instructions

Install Docker for Windows/Mac
- Download and install Docker Desktop from docker.com
Get Desktop Commander Docker Configuration
- Visit: https://hub.docker.com/mcp/server/desktop-commander/manual
- Option A: Use the provided terminal command for automated setup
- Option B: Click "Standalone" to get the config JSON and add it manually to your Claude Desktop config
Mount Your Machine Folders (Coming Soon)
- Instructions on how to mount your local directories into the Docker container will be provided soon
- This will allow you to work with your files while maintaining complete isolation

Benefits of Docker Usage

Complete isolation from your host system
Consistent environment across different machines
Easy cleanup - just remove the container when done
Perfect for testing new features or configurations

URL Support

read_file can now fetch content from both local files and URLs
Example: read_file with isUrl: true parameter to read from web resources
Handles both text and image content from remote sources
Images (local or from URLs) are displayed visually in Claude's interface, not as text
Claude can see and analyze the actual image content
Default 30-second timeout for URL requests

File Preview UI & Markdown Editor

Desktop Commander includes a rich file preview widget in Claude Desktop that renders files visually as AI works with them.

Supported file types

Markdown — rendered preview with a built-in editor
Images — inline display (PNG, JPEG, GIF, WebP, etc.)
Code files — syntax-highlighted source view
HTML — rendered preview with toggle to source view
Directories — interactive tree with expand/collapse and lazy loading
PDF, Excel, DOCX — native content extraction and display

Markdown Editor

When viewing a .md file in Claude Desktop, you can edit it directly inside the preview panel — no need to open a separate app.

How to use:

Ask Claude to read or create a markdown file
Expand the file preview to fullscreen using the ⤢ Expand button
The editor activates automatically in fullscreen mode
Edit your content with a live preview toggle, copy, undo, and save controls
Changes are saved back to disk; collapse to return to inline view

Editor features:

Live edit / preview toggle — switch between raw markdown and rendered output
Auto-save to disk with save status indicator
Undo support to revert unsaved changes
Copy button to grab the full markdown source
Open in editor — launch your default markdown app directly from the panel
Partial-file awareness — loads and merges surrounding lines when the file was only partially read
Text selection context — select text in preview mode and the AI can reference your selection

Directory Browser

When Claude runs list_directory, the result opens as an interactive file tree inside the preview panel — not just raw text output.

Features:

Expandable tree — folders expand and collapse on click; top-level contents shown immediately
Lazy loading — subfolders load on demand to keep the initial view fast
Large directory handling — directories with many items show a ⚠ click to load all button instead of overwhelming the view
Open in Finder/Explorer — each folder has a quick-open button to reveal it in your file manager
Click to preview — clicking any file in the tree opens it in the file preview panel directly
Back navigation — after opening a file from the tree, a ← Back button returns you to the directory view

Other preview features

Expand / collapse — toggle between compact summary row and full panel
Open in folder — reveal the file in Finder/Explorer with one click
Load more lines — incrementally load content above or below a partial read window
Text selection — highlight text in any preview; the AI can see and reference your selection

Fuzzy Search Log Analysis (npm scripts)

The fuzzy search logging system includes convenient npm scripts for analyzing logs outside of the MCP environment:

# View recent fuzzy search logs
npm run logs:view -- --count 20

# Analyze patterns and performance
npm run logs:analyze -- --threshold 0.8

# Export logs to CSV or JSON
npm run logs:export -- --format json --output analysis.json

# Clear all logs (with confirmation)
npm run logs:clear

For detailed documentation on these scripts, see scripts/README.md.

Fuzzy Search Logs

Desktop Commander includes comprehensive logging for fuzzy search operations in the edit_block tool. When an exact match isn't found, the system performs a fuzzy search and logs detailed information for analysis.

What Gets Logged

Every fuzzy search operation logs:

Search and found text: The text you're looking for vs. what was found
Similarity score: How close the match is (0-100%)
Execution time: How long the search took
Character differences: Detailed diff showing exactly what's different
File metadata: Extension, search/found text lengths
Character codes: Specific character codes causing differences

Log Location

Logs are automatically saved to:

macOS/Linux: ~/.claude-server-commander-logs/fuzzy-search.log
Windows: %USERPROFILE%\.claude-server-commander-logs\fuzzy-search.log

What You'll Learn

The fuzzy search logs help you understand:

Why exact matches fail: Common issues like whitespace differences, line endings, or character encoding
Performance patterns: How search complexity affects execution time
File type issues: Which file extensions commonly have matching problems
Character encoding problems: Specific character codes that cause diffs

Audit Logging

Desktop Commander now includes comprehensive logging for all tool calls:

What Gets Logged

Every tool call is logged with timestamp, tool name, and arguments (sanitized for privacy)
Logs are rotated automatically when they reach 10MB in size

Log Location

Logs are saved to:

macOS/Linux: ~/.claude-server-commander/claude_tool_call.log
Windows: %USERPROFILE%\.claude-server-commander\claude_tool_call.log

This audit trail helps with debugging, security monitoring, and understanding how Claude is interacting with your system.

Handling Long-Running Commands

For commands that may take a while:

Configuration Management

⚠️ Important Security Warnings

For comprehensive security information and vulnerability reporting: See SECURITY.md

Known security limitations: Directory restrictions and command blocking can be bypassed through various methods including symlinks, command substitution, and absolute paths or code execution
Always change configuration in a separate chat window from where you're doing your actual work. Claude may sometimes attempt to modify configuration settings (like allowedDirectories) if it encounters filesystem access restrictions.
The allowedDirectories setting currently only restricts filesystem operations, not terminal commands. Terminal commands can still access files outside allowed directories.
For production security: Use the Docker installation which provides complete isolation from your host system.

Configuration Tools

You can manage server configuration using the provided tools:

// Get the entire config
get_config({})

// Set a specific config value
set_config_value({ "key": "defaultShell", "value": "/bin/zsh" })

// Set multiple config values using separate calls
set_config_value({ "key": "defaultShell", "value": "/bin/bash" })
set_config_value({ "key": "allowedDirectories", "value": ["/Users/username/projects"] })

The configuration is saved to config.json in the server's working directory and persists between server restarts.

Understanding fileWriteLineLimit

The fileWriteLineLimit setting controls how many lines can be written in a single write_file operation (default: 50 lines). This limit exists for several important reasons:

Why the limit exists:

AIs are wasteful with tokens: Instead of doing two small edits in a file, AIs may decide to rewrite the whole thing. We're trying to force AIs to do things in smaller changes as it saves time and tokens
Claude UX message limits: There are limits within one message and hitting "Continue" does not really work. What we're trying here is to make AI work in smaller chunks so when you hit that limit, multiple chunks have succeeded and that work is not lost - it just needs to restart from the last chunk

Setting the limit:

// You can set it to thousands if you want
set_config_value({ "key": "fileWriteLineLimit", "value": 1000 })

// Or keep it smaller to force more efficient behavior
set_config_value({ "key": "fileWriteLineLimit", "value": 25 })

Maximum value: You can set it to thousands if you want - there's no technical restriction.

Best practices:

Keep the default (50) to encourage efficient AI behavior and avoid token waste
The system automatically suggests chunking when limits are exceeded
Smaller chunks mean less work lost when Claude hits message limits

Best Practices

Create a dedicated chat for configuration changes: Make all your config changes in one chat, then start a new chat for your actual work.
Be careful with empty allowedDirectories: Setting this to an empty array ([]) grants access to your entire filesystem for file operations.
Use specific paths: Instead of using broad paths like /, specify exact directories you want to access.
Always verify configuration after changes: Use get_config({}) to confirm your changes were applied correctly.

Command Line Options

Desktop Commander supports several command line options for customizing behavior:

Disable Onboarding

By default, Desktop Commander shows helpful onboarding prompts to new users (those with fewer than 10 tool calls). You can disable this behavior:

# Disable onboarding for this session
node dist/index.js --no-onboarding

# Or if using npm scripts
npm run start:no-onboarding

# For npx installations, modify your claude_desktop_config.json:
{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": [
        "-y",
        "@wonderwhy-er/desktop-commander@latest",
        "--no-onboarding"
      ]
    }
  }
}

When onboarding is automatically disabled:

When the MCP client name is set to "desktop-commander"
When using the --no-onboarding flag
After users have used onboarding prompts or made 10+ tool calls

Debug information: The server will log when onboarding is disabled: "Onboarding disabled via --no-onboarding flag"

Using Different Shells

You can specify which shell to use for command execution:

// Using default shell (bash or system default)
execute_command({ "command": "echo $SHELL" })

// Using zsh specifically
execute_command({ "command": "echo $SHELL", "shell": "/bin/zsh" })

// Using bash specifically
execute_command({ "command": "echo $SHELL", "shell": "/bin/bash" })

This allows you to use shell-specific features or maintain consistent environments across commands.

execute_command returns after timeout with initial output
Command continues in background
Use read_output with PID to get new output
Use force_terminate to stop if needed

Debugging

If you need to debug the server, you can install it in debug mode:

# Using npx
npx @wonderwhy-er/desktop-commander@latest setup --debug

# Or if installed locally
npm run setup:debug

This will:

Configure Claude to use a separate "desktop-commander" server
Enable Node.js inspector protocol with --inspect-brk=9229 flag
Pause execution at the start until a debugger connects
Enable additional debugging environment variables

To connect a debugger:

In Chrome, visit chrome://inspect and look for the Node.js instance
In VS Code, use the "Attach to Node Process" debug configuration
Other IDEs/tools may have similar "attach" options for Node.js debugging

Important debugging notes:

The server will pause on startup until a debugger connects (due to the --inspect-brk flag)
If you don't see activity during debugging, ensure you're connected to the correct Node.js process
Multiple Node processes may be running; connect to the one on port 9229
The debug server is identified as "desktop-commander-debug" in Claude's MCP server list

Troubleshooting:

If Claude times out while trying to use the debug server, your debugger might not be properly connected
When properly connected, the process will continue execution after hitting the first breakpoint
You can add additional breakpoints in your IDE once connected

Model Context Protocol Integration

This project extends the MCP Filesystem Server to enable:

Local server support in Claude Desktop
Full system command execution
Process management
File operations
Code editing with search/replace blocks

Created as part of exploring Claude MCPs: https://youtube.com/live/TlbjFDbl5Us

Support Desktop Commander

📢 SUPPORT THIS PROJECT

Desktop Commander MCP is free and open source, but needs your support to thrive!

Our philosophy is simple: we don't want you to pay for it if you're not successful. But if Desktop Commander contributes to your success, please consider contributing to ours.

Ways to support:

🌟 GitHub Sponsors - Recurring support
☕ Buy Me A Coffee - One-time contributions
💖 Patreon - Become a patron and support us monthly
⭐ Star on GitHub - Help others discover the project

❤️ Supporters Hall of Fame

Generous supporters are featured here. Thank you for helping make this project possible!

_{Jon Richards}

_{Matija Stepanic}

Why your support matters

Your support allows us to:

Continue active development and maintenance
Add new features and integrations
Improve compatibility across platforms
Provide better documentation and examples
Build a stronger community around the project

Website

Visit our official website at https://desktopcommander.app/ for the latest information, documentation, and updates.

Media

Learn more about this project through these resources:

Article

Claude with MCPs replaced Cursor & Windsurf. How did that happen? - A detailed exploration of how Claude with Model Context Protocol capabilities is changing developer workflows.

Video

Claude Desktop Commander Video Tutorial - Watch how to set up and use the Commander effectively.

Publication at AnalyticsIndiaMag

This Developer Ditched Windsurf, Cursor Using Claude with MCPs

Community

Join our Discord server to get help, share feedback, and connect with other users.

Testimonials

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgyyBt6_ShdDX_rIOad4AaABAg

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgztdHvDMqTb9jiqnf54AaABAg

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgyQFTmYLJ4VBwIlmql4AaABAg

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=Ugy4-exy166_Ma7TH-h4AaABAg

https://medium.com/@pharmx/you-sir-are-my-hero-62cff5836a3e

If you find this project useful, please consider giving it a ⭐ star on GitHub! This helps others discover the project and encourages further development.

We welcome contributions from the community! Whether you've found a bug, have a feature request, or want to contribute code, here's how you can help:

Found a bug? Open an issue at github.com/wonderwhy-er/DesktopCommanderMCP/issues
Have a feature idea? Submit a feature request in the issues section
Want to contribute code? Fork the repository, create a branch, and submit a pull request
Questions or discussions? Start a discussion in the GitHub Discussions tab

All contributions, big or small, are greatly appreciated!

If you find this tool valuable for your workflow, please consider supporting the project.

Frequently Asked Questions

Here are answers to some common questions. For a more comprehensive FAQ, see our detailed FAQ document.

What is Desktop Commander?

It's an MCP tool that enables Claude Desktop to access your file system and terminal, turning Claude into a versatile assistant for coding, automation, codebase exploration, and more.

How is this different from Cursor/Windsurf?

Unlike IDE-focused tools, Claude Desktop Commander provides a solution-centric approach that works with your entire OS, not just within a coding environment. Claude reads files in full rather than chunking them, can work across multiple projects simultaneously, and executes changes in one go rather than requiring constant review.

Do I need to pay for API credits?

No. This tool works with Claude Desktop's standard Pro subscription ($20/month), not with API calls, so you won't incur additional costs beyond the subscription fee.

Does Desktop Commander automatically update?

Yes, when installed through npx or Smithery, Desktop Commander automatically updates to the latest version when you restart Claude. No manual update process is needed.

What are the most common use cases?

Exploring and understanding complex codebases
Generating diagrams and documentation
Automating tasks across your system
Working with multiple projects simultaneously
Making surgical code changes with precise control

I'm having trouble installing or using the tool. Where can I get help?

Join our Discord server for community support, check the GitHub issues for known problems, or review the full FAQ for troubleshooting tips. You can also visit our website FAQ section for a more user-friendly experience. If you encounter a new issue, please consider opening a GitHub issue with details about your problem.

How do I report security vulnerabilities?

Please create a GitHub Issue with detailed information about any security vulnerabilities you discover. See our Security Policy for complete guidelines on responsible disclosure.

Data Collection & Privacy

Desktop Commander collects limited, pseudonymous telemetry to improve the tool. We do not collect file contents, file paths, or command arguments.

Opt-out: Ask Claude to "disable Desktop Commander telemetry" or set "telemetryEnabled": false in your config.

For complete details, see our Privacy Policy.

Verifications

License

MIT

n0-computer/iroh

IP addresses break, dial keys instead. A library that adds QUIC + NAT Traversal to your apps.

less net work for networks

Docs Site | Rust Docs

What is iroh?

Iroh gives you an API for dialing by public key. You say “connect to that phone”, iroh will find & maintain the fastest connection for you, regardless of where it is.

Hole-punching

The fastest route is a direct connection, so if necessary, iroh tries to hole-punch. Should this fail, it can fall back to an open ecosystem of public relay servers. To ensure these connections are as fast as possible, we continuously measure iroh.

Built on QUIC

Iroh uses noq to establish QUIC connections between endpoints. This way you get authenticated encryption, concurrent streams with stream priorities, a datagram transport and avoid head-of-line-blocking out of the box.

Compose Protocols

Use pre-existing protocols built on iroh instead of writing your own:

iroh-blobs for BLAKE3-based content-addressed blob transfer scaling from kilobytes to terabytes
iroh-gossip for establishing publish-subscribe overlay networks that scale, requiring only resources that your average phone can handle
iroh-docs for an eventually-consistent key-value store of iroh-blobs blobs

Getting Started

Rust Library

It's easiest to use iroh from rust. Install it using cargo add iroh, then on the connecting side:

const ALPN: &[u8] = b"iroh-example/echo/0";

let endpoint = Endpoint::bind().await?;

// Open a connection to the accepting endpoint
let conn = endpoint.connect(addr, ALPN).await?;

// Open a bidirectional QUIC stream
let (mut send, mut recv) = conn.open_bi().await?;

// Send some data to be echoed
send.write_all(b"Hello, world!").await?;
send.finish()?;

// Receive the echo
let response = recv.read_to_end(1000).await?;
assert_eq!(&response, b"Hello, world!");

// As the side receiving the last application data - say goodbye
conn.close(0u32.into(), b"bye!");

// Close the endpoint and all its connections
endpoint.close().await;

And on the accepting side:

let endpoint = Endpoint::bind().await?;

let router = Router::builder(endpoint)
    .accept(ALPN.to_vec(), Arc::new(Echo))
    .spawn()
    .await?;

// The protocol definition:
#[derive(Debug, Clone)]
struct Echo;

impl ProtocolHandler for Echo {
    async fn accept(&self, connection: Connection) -> Result<()> {
        let (mut send, mut recv) = connection.accept_bi().await?;

        // Echo any bytes received back directly.
        let bytes_sent = tokio::io::copy(&mut recv, &mut send).await?;

        send.finish()?;
        connection.closed().await;

        Ok(())
    }
}

The full example code with more comments can be found at echo.rs.

Or use one of the pre-existing protocols, e.g. iroh-blobs or iroh-gossip.

Other Languages

If you want to use iroh from other languages, make sure to check out iroh-ffi, the repository for FFI bindings.

Repository Structure

This repository contains a workspace of crates:

iroh: The core library for hole-punching & communicating with relays.
iroh-relay: The relay client and server implementation. This is the code we run in production for the public relays (and you can, too!).
iroh-base: Common types like EndpointId or RelayUrl.
iroh-dns-server: DNS server implementation powering the DNS/Pkarr address lookup for EndpointIds, running at dns.iroh.link.

License

This project is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

OpenCut-app/OpenCut

The open-source CapCut alternative

OpenCut

A free and open source video editor for web, desktop, and mobile.

Status

OpenCut is being rewritten from the ground up. What's coming:

An Editor API
First-class third party plugins (made possible by a plugin-first architecture)
Desktop, mobile, and browser from one codebase (Rust core)
MCP server (for AI agents)
Headless mode (automation, batch rendering)
A scripting tab directly in the editor

You can still find the previous version at opencut-app/opencut-classic, which is the one to reach for today. opencut.app still runs the classic version. The rewrite will live at new.opencut.app until it's ready to take over.

Development

Install proto if you haven't already:

bash <(curl -fsSL https://moonrepo.dev/install/proto.sh)

From the repo root:

proto use    # installs the tools pinned in .prototools

moon run web:dev       # localhost:5173
moon run api:dev       # localhost:8787
moon run desktop:dev   # see apps/desktop/README.md

Contributing

We're not set up to take outside contributions yet while the architecture is being designed. If you want to follow along, ask questions, or just hang out, join the Discord or open an issue.

License

MIT

	Bloome lets multiple AI agents (Claude, ChatGPT, DeepSeek, and more) collaborate in one conversation for agentic video pipelines. It has zero setup, runs in the cloud, works on web and mobile, and lets you share a configured agent with your whole team. Try Bloome.
	Atlas Cloud is a full-modal AI inference platform that gives developers a single AI API for video generation, image generation, and LLM APIs. Instead of managing multiple vendor integrations, you connect once and get unified access to 300+ curated models across all modalities. Check out Atlas Cloud's new coding plan promotion for more budget-friendly API access.