GitHub Rust Monthly Trending Repositories

1jehuang/jcode

The most RAM efficient harness

jcode

The most RAM efficient harness
The most intelligent harness

Website · Docs · SDK · Benchmarks · Features · Install · Quick Start · Further Reading · Contributing

Installation

# macOS & Linux
curl -fsSL https://jcode.sh/install | bash

# Windows 11 (PowerShell 5.1+)
irm https://jcode.sh/install.ps1 | iex

Need Homebrew, source builds, provider setup, or want an agent to set it up for you? Jump to detailed installation.

Performance & Resource Efficiency

jcode is built to be as performant and resource efficient as possible. Every metric is optimized to the bone, which is important for scaling multi-session workflows. Here we sample a few metrics to show the difference: RAM usage and boot up.

RAM comparison

1 active session

Tool	PSS	Comparison
jcode (local embedding off)	27.8 MB	baseline
jcode	167.1 MB	6.0× more RAM
pi	144.4 MB	5.2× more RAM
Codex CLI	140.0 MB	5.0× more RAM
OpenCode	371.5 MB	13.4× more RAM
GitHub Copilot CLI	333.3 MB	12.0× more RAM
Cursor Agent	214.9 MB	7.7× more RAM
Claude Code	386.6 MB	13.9× more RAM
Antigravity CLI	243.7 MB	8.8× more RAM

10 active sessions

Tool	PSS	Comparison
jcode (local embedding off)	117.0 MB	baseline
jcode	260.8 MB	2.2× more RAM
pi	833.0 MB	7.1× more RAM
Codex CLI	334.8 MB	2.9× more RAM
OpenCode	3237.2 MB	27.7× more RAM
GitHub Copilot CLI	1756.5 MB	15.0× more RAM
Cursor Agent	1632.4 MB	14.0× more RAM
Claude Code	2300.6 MB	19.7× more RAM
Antigravity CLI	1021.2 MB	8.7× more RAM

Time to first frame

Tool	Time to first frame	Range	Comparison
jcode	14.0 ms	10.1–19.3 ms	baseline
Antigravity CLI	383.5 ms	363.1–415.4 ms	27.4× slower
pi	590.7 ms	369.6–934.8 ms	42.2× slower
Codex CLI	882.8 ms	742.3–1640.9 ms	63.1× slower
OpenCode	1035.9 ms	922.5–1104.4 ms	74.0× slower
GitHub Copilot CLI	1518.6 ms	1357.4–1826.8 ms	108.5× slower
Cursor Agent	1949.7 ms	1711.0–2104.8 ms	139.3× slower
Claude Code	3436.9 ms	2032.7–8927.2 ms	245.5× slower

Measured on this Linux machine across 10 interactive PTY launches.

Time to first input

(time until typed probe text appears on the rendered screen; Antigravity uses its internal input-ready log marker because the sign-in screen suppresses probe echo.)

Tool	Time to first input	Range	Comparison
jcode	48.7 ms	30.3–62.7 ms	baseline
Antigravity CLI	383.7 ms	363.4–415.7 ms	7.9× slower
pi	596.4 ms	373.9–955.2 ms	12.2× slower
Codex CLI	905.8 ms	760.1–1675.7 ms	18.6× slower
OpenCode	1047.9 ms	931.1–1116.9 ms	21.5× slower
GitHub Copilot CLI	1583.4 ms	1422.8–1880.0 ms	32.5× slower
Cursor Agent	1978.7 ms	1727.3–2130.0 ms	40.6× slower
Claude Code	3512.8 ms	2137.4–9002.0 ms	72.2× slower

Measured on this Linux machine across 10 interactive PTY launches. Antigravity CLI was unauthenticated for this run; its sign-in screen rendered normally and emitted an internal CLI ready for user input marker, but did not echo the typed probe.

Additional clients / memory scaling

Tool	Extra PSS per added session	Comparison
jcode (local embedding off)	~9.9 MB	baseline
jcode	~10.4 MB	1.1× more RAM
pi	~76.5 MB	7.7× more RAM
Codex CLI	~21.6 MB	2.2× more RAM
OpenCode	~318.4 MB	32.2× more RAM
GitHub Copilot CLI	~158.1 MB	16.0× more RAM
Cursor Agent	~157.5 MB	15.9× more RAM
Claude Code	~212.7 MB	21.5× more RAM
Antigravity CLI	~86.4 MB	8.7× more RAM

versions tested for this corrected memory rerun:

jcode v0.9.1888-dev (be386f2)
pi 0.62.0
codex-cli 0.120.0
opencode 1.0.203
GitHub Copilot CLI 1.0.24 for the 1-session rerun, GitHub Copilot CLI 1.0.27 for the 10-session rerun
Cursor Agent 2026.04.08-a41fba1
Claude Code 2.1.86 (Claude Code)
Antigravity CLI 1.0.0

jcode performance demonstration

Memory (Agent memory)

Jcode embeds each turn/response as a semantic vector. Every turn does queries a graph of memories to efficiently find related memory entries via a cosine similarity check. The embedding hits are fed into the conversation, or optionally uses a memory sideagent which verifies the memories are relevant, and potentially does more work for information retreival before injecting into the conversation. This results in a human like memory system which allows the agent to automatically recall relevant information to the conversation without actively calling memory tools or being a token burner. ot To have memories which are retrieved, they must also be extracted and stored. Every so often (semantic drift, K turns since last extraction, session end, etc), memories are extracted via a memory sideagent, and put into the memory graph.

The harness also provides explicit memory tools to allow the agent to actively search or store the memory without relying on a passive background process. The harness also provides session search for traditional RAG on previous sessions.

Memories are automatically consolidated every so often via the ambient mode. This reorganizes, checks for staleness and conflicts, etc

jcode memory demonstration

UI: Side panels, Diagrams, Info Widgets, rendering, scrolling, alignment

The side panel is a place for auxiliary information. Tell your jcode agent to load a file into the side panel and see it update in real time, or tell your agent to write directly to the side panel, or use it as a diff viewer. The side panel (and chat) is able to render mermaid diagrams inline.

To make this possible, I created a new mermaid rendering library to render diagrams 1800x faster. It has no browser or Typescript dependency. See https://github.com/1jehuang/mermaid-rs-renderer

To show you important information without taking space away from the screen that could be used for responses, I developed info widgets. Info widgets will only ever take up the negative space on the screen to show you information, and will get out of the way if there isn't any.

Jcode can render at over a thousand fps. Your monitor will not have the refresh rate to show you, but this means you will not have silly flicker problems.

The custom scrollback implementation of jcode allows it to do much more than a native scrollback. However, it is a terminal-level limitation that I cannot have smooth, partial line scrolling with a custom scrollback. To fix this, I made my own terminal. Handterm https://github.com/1jehuang/handterm implements a native scroll api, and also happens to be very efficient. This is a work in progress. Scrolling is still well implemented for normal terminals.

Jcode is left-aligned by default. You can switch to centered mode with the Alt+C hotkey, with the /alignment command, or in the config.

To disable emoji globally in TUI and CLI output, set emoji = false under [display] in ~/.jcode/config.toml, or launch with JCODE_NO_EMOJI=1. Jcode replaces emoji with compact ASCII markers while preserving other Unicode text.

Swarm

Spawn two or more agents in the same repo, and they will automatically be managed by the server to allow native collaboration. When agent A edits a file that agent B has read (code shifting under its feet), the server notifies agent B. Agent B can ignore it if it is not relevant, or it can check the diff to make sure that it doesn't conflict. Each agent has messaging abilities, capable of DMing just one agent, broadcasting to all other agents hosted by the server, or just agents working in that repo. This allows you to spawn multiple sessions in the same repo, and have all conflicts automatically resolved.

jcode swarm demonstration

Agents are also able to spawn their own swarms autonomously. They have a swarm tool which allows them to spawn in their own teamates to accomplish tasks in parallel. Doing so turns the main agent into a coordinator and the spawned agents into workers. Groups of agents, their messaging channels, their completion statuses, etc are all automatically managed. This can be done headlessly or headed.

OAuth and Providers

jcode works with subscription-backed OAuth flows and many provider integrations, so you can use the models you already pay for and still fall back to direct API providers when needed.

Supported built-in login flows

Claude (jcode login --provider claude)
OpenAI / ChatGPT / Codex (jcode login --provider openai)
Google Gemini (jcode login --provider gemini)
GitHub Copilot (jcode login --provider copilot)
Azure OpenAI (jcode login --provider azure)
Alibaba Cloud Coding Plan (jcode login --provider alibaba-coding-plan)
Fireworks (jcode login --provider fireworks)
MiniMax (jcode login --provider minimax)
Meta Model API / Muse (jcode login --provider meta-muse)
LM Studio (jcode login --provider lmstudio)
Ollama (jcode login --provider ollama)
Custom OpenAI-compatible endpoint (jcode login --provider openai-compatible)

For custom OpenAI-compatible endpoints, jcode now prompts for the API base and supports local localhost servers without requiring an API key.

Config-file setup for self-hosted endpoints and MCP

If you prefer to configure things by editing files instead of using the login UI, jcode supports both a custom OpenAI-compatible endpoint config and MCP config files.

OpenAI-compatible providers

Many hosted services speak the standard OpenAI /v1/chat/completions API. jcode talks to them through one shared OpenAI-compatible provider, so you can use almost any such endpoint without waiting for a dedicated integration.

There are two ways to set one up:

Built-in named profiles — jcode ships ready-made profiles for several popular OpenAI-compatible services. Log in by id and jcode fills in the base URL and key environment variable for you:
```
jcode login --provider <profile-id>
# for example:
jcode login --provider openrouter
jcode login --provider deepseek
jcode login --provider opencode      # OpenCode Zen
jcode login --provider moonshotai
jcode login --provider meta-muse     # Meta Model API / Muse Spark
```
Built-in OpenAI-compatible profile ids include: openrouter, deepseek, zai, kimi, moonshotai, meta-muse (Meta Model API / Muse Spark), opencode (OpenCode Zen), opencode-go, 302ai, baseten, cortecs, huggingface, nebius, scaleway, stackit, and firmware. Each profile only sets the endpoint and key variable; you still pick the model with /model (or --model). Run jcode login with no provider to see the interactive list.
Any other endpoint — point jcode at an arbitrary OpenAI-compatible API (hosted or local) with jcode login --provider openai-compatible or the scriptable jcode provider add command described below.

Useful environment overrides for these endpoints:

JCODE_STREAM_IDLE_TIMEOUT_SECS — raise the base streaming idle timeout (default 180s) for slow reasoning models that think silently before emitting tokens. High reasoning efforts scale this automatically (high 2x, xhigh 3x, max 4x). Also settable as [provider] stream_idle_timeout_secs in config.toml.
Per-model context_window (alias context_limit) in a [[providers.<name>.models]] entry — set the context window when the endpoint has no usable /v1/models response, so jcode does not fall back to the generic 200k default.
extra_body — inject non-standard top-level fields into every chat/completions request body for backends that require them. See Extra request-body fields below.

For details on self-hosting, local runtimes, and the exact config file shape, see below.

Self-hosted OpenAI-compatible endpoints, including vLLM

For agents and scripts, the preferred path is the one-shot provider profile command. It writes a named profile to ~/.jcode/config.toml, stores secrets in jcode's private app config directory when requested, and prints exact run/validation commands:

# Secret-safe setup for a hosted OpenAI-compatible API.
printf '%s' "$MY_API_KEY" | jcode provider add my-api \
  --base-url https://llm.example.com/v1 \
  --model my-model-id \
  --api-key-stdin \
  --set-default \
  --json

# Smoke test the profile.
jcode --provider-profile my-api auth-test --prompt 'Reply exactly JCODE_PROVIDER_SETUP_OK'

# Use it directly.
jcode --provider-profile my-api run 'hello'

For local servers that do not require auth:

jcode provider add local-vllm \
  --base-url http://localhost:8000/v1 \
  --model Qwen/Qwen3-Coder-30B-A3B-Instruct \
  --no-api-key \
  --set-default

Built-in local profiles are available for the common desktop/local runtimes:

# Ollama: start the local server and install a model first.
ollama pull llama3.2
jcode login --provider ollama
jcode --provider ollama --model llama3.2 run 'hello'

# LM Studio: start the Local Server, load a chat model, then use the exact
# model identifier shown by LM Studio or by curl http://localhost:1234/v1/models.
jcode login --provider lmstudio
jcode --provider lmstudio --model '<model-id>' run 'hello'

Ollama and LM Studio both expose OpenAI-compatible /v1/models and /v1/chat/completions endpoints. jcode uses streaming chat completions, function/tool calling, and OpenAI-style image content for vision-capable local models. If a local server requires a token, enter it during jcode login or create a named profile with --api-key-stdin.

Useful flags:

--api-key-env NAME: reference an existing environment variable instead of storing a key.
--api-key-stdin: read and store a key without putting it in shell history.
--context-window TOKENS: persist the model context window for model selection and routing.
--overwrite: replace an existing profile of the same name.
--model-catalog: use the endpoint's /models response in addition to configured models.

The generated profile can also be edited manually in ~/.jcode/config.toml:

[provider]
default_provider = "my-api"
default_model = "my-model-id"

[providers.my-api]
type = "openai-compatible"
base_url = "https://llm.example.com/v1"
api_key_env = "JCODE_PROVIDER_MY_API_API_KEY"
env_file = "provider-my-api.env"
default_model = "my-model-id"

[[providers.my-api.models]]
id = "my-model-id"
context_window = 128000

Extra request-body fields (`extra_body`)

Some OpenAI-compatible backends require non-standard top-level request fields. For example, NVIDIA NIM DeepSeek-V4 reasoning models (deepseek-ai/deepseek-v4-flash, deepseek-ai/deepseek-v4-pro) only enable thinking when the request includes chat_template_kwargs; without it they reply without reasoning (or, for some deployments, hang). jcode lets you inject arbitrary top-level fields two ways.

Per named profile, via extra_body in config.toml (a TOML table merged verbatim into the JSON body):

[providers.my-nim]
type = "openai-compatible"
base_url = "https://integrate.api.nvidia.com/v1"
api_key_env = "NVIDIA_API_KEY"
default_model = "deepseek-ai/deepseek-v4-flash"

[providers.my-nim.extra_body.chat_template_kwargs]
thinking = true
reasoning_effort = "high"

For built-in profiles (e.g. nvidia-nim) or any endpoint, via the JCODE_OPENAI_EXTRA_BODY environment variable (a JSON object string). It can live in the provider's env file (~/.config/jcode/nvidia-nim.env) next to the API key:
```
JCODE_OPENAI_EXTRA_BODY={"chat_template_kwargs":{"thinking":true,"reasoning_effort":"high"}}
```

Keys from extra_body are merged last and override any jcode-generated body field with the same name (JCODE_OPENAI_EXTRA_BODY wins over the config extra_body on key collisions). Invalid values are logged and ignored rather than failing the request.

The custom OpenAI-compatible provider reads overrides from environment variables or from an env file in jcode's app config directory. On Linux this is usually ~/.config/jcode/, so the default file is usually:

~/.config/jcode/openai-compatible.env

Example for a local or LAN vLLM server:

JCODE_OPENAI_COMPAT_API_BASE=http://192.168.1.50:8000/v1
JCODE_OPENAI_COMPAT_DEFAULT_MODEL=Qwen/Qwen3-Coder-30B-A3B-Instruct
# Optional if your server expects auth
OPENAI_COMPAT_API_KEY=your-token-here

Notes:

jcode login --provider openai-compatible can create or update this for you.
Plain http:// is accepted for localhost and private LAN IPs. Public remote HTTP is still rejected.
HTTPS endpoints work as usual.

MCP config files

MCP config is separate from config.toml.

Primary config files:

~/.jcode/mcp.json for global MCP servers
.jcode/mcp.json for project-local MCP servers

Claude Code compatibility:

~/.claude.json (Claude Code's user config): top-level mcpServers, plus per-project servers under projects.<abs_path>.mcpServers for the current directory
.mcp.json at the repo root (Claude Code's project config)
.claude/mcp.json (legacy fallback)

Claude Code config is read live on every load rather than copied into jcode's global config. Additions, edits, and deletions therefore take effect without leaving a stale snapshot (and inline environment values are not duplicated). For migration from Codex CLI, jcode still performs a one-time import from ~/.codex/config.toml into ~/.jcode/mcp.json when the latter does not exist. That imported file is then jcode-owned; later Codex changes are not synced automatically. Imported environment values are copied too and may contain secrets.

Both the canonical mcpServers key and jcode's historical servers key are accepted. jcode currently supports stdio (command-based) servers only; HTTP/SSE entries ("type": "http"/"sse") are recognized and skipped with a log line.

Example MCP config:

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/mcp-server",
      "args": ["--root", "/workspace"],
      "env": {},
      "shared": true
    }
  }
}

For headless or SSH sessions, OAuth-style providers support jcode login --provider <provider> --no-browser (alias: --headless) so jcode prints the auth URL/QR and falls back to manual code or callback paste instead of trying to launch a local browser.

For more scriptable remote flows, claude, openai, gemini, and antigravity also support a two-step pattern:

# Step 1: print a resumable auth URL
jcode login --provider openai --print-auth-url --json

# Step 2: complete later with the callback URL or auth code
jcode login --provider openai --callback-url 'http://localhost:1455/auth/callback?...'
jcode login --provider gemini --auth-code '...'

Additional scriptable cases:

# Copilot device flow: print URL + user code, then complete later
jcode login --provider copilot --print-auth-url --json
jcode login --provider copilot --complete

# Gmail/Google OAuth after credentials are already configured
jcode login --provider google --print-auth-url --google-access-tier readonly
jcode login --provider google --callback-url 'http://127.0.0.1:8456?...'

Pending scriptable login state is stored under ~/.jcode/pending-login/, automatically expires, and stale entries are cleaned up when new scriptable logins start or resume.

For the built-in OpenAI login flow, jcode opens a local callback on http://localhost:1455/auth/callback by default.

The above image is the first page of provider logins

Supported provider

Native / first-party style providers: claude, openai, copilot, gemini, azure, alibaba-coding-plan
Aggregator / compatibility providers: openrouter, openai-compatible
Additional provider integrations: opencode, opencode-go, zai / kimi, 302ai, baseten, cortecs, deepseek, firmware, huggingface, moonshotai, nebius, scaleway, stackit, groq, mistral, perplexity, togetherai, deepinfra, fireworks, minimax, xai, lmstudio, ollama, chutes, cerebras, cursor, antigravity, google

Jcode also supports easy multi-account switching. Ran out of tokens on your first ChatGPT Pro subscription? /account and quickly switch to your second.

Customizability / Self-Dev

Jcode is inventing a new form of customizability. One that doesn't limit you to what a plugin or extension can do. Tell your jcode agent to enter self dev mode, and it will start modifying its own source code. Jcode is optimized to iterate on itself. There is significant infrastructure around self developement, which allows it to edit, build, and test its own source code, then reload its own binary and continue work in your (potentially many) sessions, fully automatically.

It is reccomended that you use a frontier model for this. The jcode codebase is not a simple one, and weaker models can make subtle, breaking changes. GPT 5.5 or the latest available frontier model works well.

Misc.

The devil is in the details. There are many undocumented optimizations and niceties that jcode implements. Some examples:

Anthropic's Claude cache goes cold after 5 minutes. If you initiate Claude after these 5 minutes, you have a cache miss, potentially costing you lots of tokens. The ui warns you when the cache went cold, and notfies you if there was an unexpected cache miss.

jcode comes with instructions on how to set up Firefox Agent Bridge. Ask you agent to set it up, and then you will have browser automation in jcode as well.

Agent grep is a grep tool I made for the jcode agent. It adds file strucuture information (ie the list of functions, their displacement, etc) to the grep return, so that the agent can infer more of what the file doesn without actually reading the file. It also implements a harness-level integration that adaptively truncates returns based on what the agent has already seen. This saves on context a lot.

Inputs are by default interleaved with the working agent. It sends the input as soon as it safely can without breaking the KV cache. Submit with shift enter instead, and it will send a queue send, and wait for the agent to fully finish its turn before sending.

Resume sessions from different harnesses. Claude code broke on you? Resume the session from jcode and continue where you left off. Session resume is supported for codex, claude code, opencode, and pi.

image of /Resume for codex sessions

Skills are not all loaded on startup. The conversation is embedded as a semantic vector, and will automatically inject a skill if there is an embedding hit similar to memories. The agent has a skill tool for you to manually activate a skill at anytime. You may also activate via slash commands.

iOS Application / Native OpenClaw

A native iOS application version of jcode is coming soon. This will allow you to work with jcode on your personal machine's environment from your phone, via Tailscale. Openclaw like features will be bundled with this iOS application.

Other planned features

Agents dont like to commit in dirty git state with active changes. Git was clearly not built for multi-agent workflows, and git worktrees is not a good solution. Given this, I believe that is an opporunity for a new git like primitive to be born.

Build speed improvements: An incremental debug cargo build with cache enabled takes about 1 minute on my machine. The goal is 5-20 seconds. Refactors and crates seams should be able to make this happen.

Quick Start

# Launch the TUI
jcode

# Run a single command non-interactively
jcode run "say hello"

# Resume a previous session by memorable name
jcode --resume fox

# Run as a persistent background server, then attach more clients
jcode serve
jcode connect

# Send voice input from your configured STT command
jcode dictate

jcode supports interactive TUI use, non-interactive runs, persistent server/client workflows, and hotkey-friendly dictation without requiring a bundled speech-to-text stack.

jcode workflow demonstration

Browser Automation

jcode includes a first-class built-in browser tool for browser control inside agent sessions.

Current built-in backend:

Firefox via Firefox Agent Bridge

Current built-in tool actions include:

status
setup
open
snapshot
get_content
interactables
click
type
fill_form
select
wait
screenshot
eval
scroll
upload
press

Quick setup:

jcode browser status
jcode browser setup

Once setup is complete, the model can use the built-in browser tool directly. The UI also summarizes browser tool calls compactly, for example opening a URL, clicking a selector, or typing into a field without echoing sensitive typed text.

Notes:

the provider/tool architecture is in place for additional backends
Firefox is the wired built-in backend today
Chrome bridge / remote debugging style providers can be added on top of the same browser tool later

Detailed Installation

Setup

If you want another agent to set up jcode for you, give it this prompt:

Set up jcode on this machine for me.

1. Detect the operating system, available package managers, and shell environment, then install jcode using the best matching command below instead of referring me somewhere else:

   - macOS with Homebrew available:
     brew tap 1jehuang/jcode
     brew install jcode

   - macOS or Linux via install script:
     curl -fsSL https://jcode.sh/install | bash

   - Windows PowerShell:
     irm https://jcode.sh/install.ps1 | iex

   - From source if the above paths are not appropriate:
     git clone https://github.com/1jehuang/jcode.git
     cd jcode
     cargo build --release
     scripts/install_release.sh

   - For local self-dev / refactor work on Linux x86_64, prefer:
     scripts/dev_cargo.sh build --release -p jcode --bin jcode
     scripts/dev_cargo.sh --print-setup
     scripts/install_release.sh

2. Verify that `jcode` is on my `PATH`.
3. Launch `jcode` once in a new terminal window/session to confirm it starts successfully.
4. Before attempting any interactive login flow, assess which providers are already available non-interactively and prefer those first. Check existing local credentials, config files, CLI sessions, and environment variables such as:
   - Claude: `~/.jcode/auth.json`, `~/.claude/.credentials.json`, `~/.local/share/opencode/auth.json`, `ANTHROPIC_API_KEY`
   - OpenAI: `~/.jcode/openai-auth.json`, `~/.codex/auth.json`, `OPENAI_API_KEY`
   - Gemini: `~/.jcode/gemini_oauth.json`, `~/.gemini/oauth_creds.json`
   - GitHub Copilot: existing auth under `~/.config/github-copilot/`
   - Azure OpenAI: `~/.config/jcode/azure-openai.env`, `AZURE_OPENAI_*`, or an existing `az login`
   - OpenRouter: `OPENROUTER_API_KEY`
   - Fireworks: `~/.config/jcode/fireworks.env`, `FIREWORKS_API_KEY`
   - MiniMax: `~/.config/jcode/minimax.env`, `MINIMAX_API_KEY`
   - NVIDIA NIM: `~/.config/jcode/nvidia-nim.env`, `NVIDIA_API_KEY`
   - Alibaba Cloud Coding Plan: existing jcode config/env if present
5. Prefer whichever provider is already configured and verify it with `jcode auth-test --all-configured` or a provider-specific auth test when appropriate.
6. Only if no usable provider is already configured, guide me through the minimal manual step needed:
   - Claude: `jcode login --provider claude`
   - GitHub Copilot: `jcode login --provider copilot`
   - OpenAI: `jcode login --provider openai`
   - Gemini: `jcode login --provider gemini`
   - Azure OpenAI: `jcode login --provider azure`
   - Fireworks: `jcode login --provider fireworks`
   - MiniMax: `jcode login --provider minimax`
   - NVIDIA NIM: `jcode login --provider nvidia-nim`
   - Alibaba Cloud Coding Plan: `jcode login --provider alibaba-coding-plan`
   - OpenRouter: help me set `OPENROUTER_API_KEY`
   - Anthropic direct API: help me set `ANTHROPIC_API_KEY`
7. After setup, run a simple smoke test with `jcode run "say hello"` and confirm it works.
8. If I want browser automation, also check `jcode browser status`. If browser automation is not ready, run `jcode browser setup`, verify the built-in `browser` tool works, and explain any remaining manual step.
9. Explain any manual step that still needs me, especially browser OAuth, device login, API key entry, or browser extension approval.

This is intended to be a copy-paste bootstrap prompt for jcode itself or any other coding agent.

Quick Install

# macOS & Linux
curl -fsSL https://jcode.sh/install | bash

On Termux, install the glibc runtime and patchelf first so the installer can patch the downloaded Linux binary to Termux's glibc dynamic linker and create a launcher that avoids Termux's LD_PRELOAD shim:

pkg install glibc patchelf
curl -fsSL https://jcode.sh/install | bash

# Windows 11 x64 or ARM64 (PowerShell 5.1+)
irm https://jcode.sh/install.ps1 | iex

The Windows installer selects the correct architecture and verifies the download against the release's SHA256SUMS. Alacritty and the optional global launch hotkey require explicit consent and are not installed by default. See Windows support, security, Defender, and SmartScreen notes.

If a release does not contain a matching Windows asset, the installer stops instead of unexpectedly starting a long compilation. An explicit source build is available with -BuildFromSource and requires Git, Rust, and Visual Studio 2022 Build Tools with the Desktop development with C++ workload.

macOS via Homebrew

brew tap 1jehuang/jcode
brew install jcode

From Source (all platforms)

git clone https://github.com/1jehuang/jcode.git
cd jcode
cargo build --release

For local self-dev / refactor work on Linux x86_64, prefer:

scripts/dev_cargo.sh build --release -p jcode --bin jcode
scripts/dev_cargo.sh --print-setup

That wrapper automatically uses sccache when available, prefers a fast working local linker setup (clang + lld) instead of assuming every machine's mold configuration is valid, and can print the active linker/cache setup via --print-setup so slow-path builds are easier to diagnose.

Then symlink to your PATH:

scripts/install_release.sh

Uninstall

Removes installed binaries and the launcher but keeps your config, auth, and sessions so a clean reinstall picks up where you left off:

curl -fsSL https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/uninstall.sh | bash -s -- --yes

For a full wipe of everything including config, auth, sessions, logs, and memory (useful for recovering from a broken install):

curl -fsSL https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/uninstall.sh | bash -s -- --purge --yes

Add --dry-run to preview what would be removed without deleting anything.

Platform Support

Platform	Status
Linux x86_64 / aarch64	Fully supported
macOS Apple Silicon & Intel	Supported
Windows x86_64	Supported (native + WSL2)
Termux aarch64 / x86_64	Supported with `pkg install glibc patchelf`

openai/codex

Lightweight coding agent that runs in your terminal

Codex CLI is a coding agent from OpenAI that runs locally on your computer.

If you want Codex in your code editor (VS Code, Cursor, Windsurf), install in your IDE.
If you want the desktop app experience, run codex app or visit the Codex App page.
If you are looking for the cloud-based agent from OpenAI, Codex Web, go to chatgpt.com/codex.

Quickstart

Installing and running Codex CLI

Run the following on Mac or Linux to install Codex CLI:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Run the following on Windows to install Codex CLI:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

The standalone installers download from https://releases.openai.com/codex by default and fall back to GitHub Releases if a metadata or asset download is unavailable. To force GitHub Releases, set CODEX_INSTALLER_USE_RELEASES_OPENAI_COM to false (0 and no are also accepted):

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh

$env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM='false'; irm https://chatgpt.com/codex/install.ps1 | iex

Codex CLI can also be installed via the following package managers:

# Install using npm
npm install -g @openai/codex

# Install using Homebrew
brew install --cask codex

Then simply run codex to get started.

You can also go to the latest GitHub Release and download the appropriate binary for your platform.

Each GitHub Release contains many executables, but in practice, you likely want one of these:

macOS
- Apple Silicon/arm64: codex-aarch64-apple-darwin.tar.gz
- x86_64 (older Mac hardware): codex-x86_64-apple-darwin.tar.gz
Linux
- x86_64: codex-x86_64-unknown-linux-musl.tar.gz
- arm64: codex-aarch64-unknown-linux-musl.tar.gz

Each archive contains a single entry with the platform baked into the name (e.g., codex-x86_64-unknown-linux-musl), so you likely want to rename it to codex after extracting it.

Using Codex with your ChatGPT plan

Run codex and select Sign in with ChatGPT. We recommend signing into your ChatGPT account to use Codex as part of your Plus, Pro, Business, Edu, or Enterprise plan. Learn more about what's included in your ChatGPT plan.

You can also use Codex with an API key, but this requires additional setup.

Docs

This repository is licensed under the Apache-2.0 License.

Pumpkin-MC/Pumpkin

Empowering everyone to host fast and efficient Minecraft servers.

Pumpkin

Pumpkin is a Minecraft server built entirely in Rust, offering a fast, efficient, and customizable experience. It prioritizes performance and player enjoyment while adhering to the core mechanics of the game.

Goals

Performance: Leveraging multi-threading for maximum speed and efficiency.
Compatibility: Supports the latest Java & Bedrock Minecraft server version while adhering to Vanilla game mechanics.
Security: Prioritizes security by preventing known security exploits.
Flexibility: Highly configurable, with the ability to disable unnecessary features.
Extensibility: Provides a foundation for plugin development.

Important

Pumpkin is currently under heavy development.

See what needs to be done before the 1.0.0 Release

Features

How to run

See our Quick Start guide to get Pumpkin running.

Contributions

Contributions are welcome! See CONTRIBUTING.md

Docs

Pumpkin's documentation can be found at https://pumpkinmc.org/

Communication

Consider joining our Discord server to stay up-to-date on events, updates, and connect with other members.

Funding

If you want to fund me and help the project, check out the Donation Page.

cjpais/Handy

A free, open source, and extensible speech-to-text application that works completely offline.

Handy

A free, open source, and extensible speech-to-text application that works completely offline.

Handy is a cross-platform desktop application that provides simple, privacy-focused speech transcription. Press a shortcut, speak, and have your words appear in any text field. This happens on your own computer without sending any information to the cloud.

Why Handy?

Handy was created to fill the gap for a truly open source, extensible speech-to-text tool. As stated on handy.computer:

Free: Accessibility tooling belongs in everyone's hands, not behind a paywall
Open Source: Together we can build further. Extend Handy for yourself and contribute to something bigger
Private: Your voice stays on your computer. Get transcriptions without sending audio to the cloud
Simple: One tool, one job. Transcribe what you say and put it into a text box

Handy isn't trying to be the best speech-to-text app—it's trying to be the most forkable one.

How It Works

Press a configurable keyboard shortcut to start/stop recording (or use push-to-talk mode)
Speak your words while the shortcut is active
Release and Handy processes your speech using Whisper
Get your transcribed text pasted directly into whatever app you're using

The process is entirely local:

Silence is filtered using VAD (Voice Activity Detection) with Silero
Transcription uses your choice of models:
- Whisper models (Small/Medium/Turbo/Large) with GPU acceleration when available
- Parakeet V3 - CPU-optimized model with excellent performance and automatic language detection
Works on Windows, macOS, and Linux

Quick Start

Installation

Download the latest release from the releases page or the website
- macOS: Also available via Homebrew cask: brew install --cask handy
- Windows: Also available via winget: winget install cjpais.Handy
  Note: The Homebrew cask and winget package are not maintained by the Handy developers.
Install the application
Launch Handy and grant necessary system permissions (microphone, accessibility)
Configure your preferred keyboard shortcuts in Settings
Start transcribing!

Development Setup

For detailed build instructions including platform-specific requirements, see BUILD.md.

Integrations

Control Handy from Raycast — start/stop recording, browse transcript history, manage dictionary, switch models and languages.

Source · by @mattiacolombomc

Architecture

Handy is built as a Tauri application combining:

Frontend: React + TypeScript with Tailwind CSS for the settings UI
Backend: Rust for system integration, audio processing, and ML inference
Core Libraries:
- transcribe-cpp: Local speech recognition with Whisper-family models (GGML/GGUF)
- transcribe-rs: CPU-optimized speech recognition with Parakeet models
- cpal: Cross-platform audio I/O
- vad-rs: Voice Activity Detection
- rdev: Global keyboard shortcuts and system events
- rubato: Audio resampling

Debug Mode

Handy includes an advanced debug mode for development and troubleshooting. Access it by pressing:

macOS: Cmd+Shift+D
Windows/Linux: Ctrl+Shift+D

CLI Parameters

Handy supports command-line flags for controlling a running instance and customizing startup behavior. These work on all platforms (macOS, Windows, Linux).

Remote control flags (sent to an already-running instance via the single-instance plugin):

handy --toggle-transcription    # Toggle recording on/off
handy --toggle-post-process     # Toggle recording with post-processing on/off
handy --cancel                  # Cancel the current operation

Startup flags:

handy --start-hidden            # Start without showing the main window
handy --no-tray                 # Start without the system tray icon
handy --debug                   # Enable debug mode with verbose logging
handy --help                    # Show all available flags

Flags can be combined for autostart scenarios:

handy --start-hidden --no-tray

macOS tip: When Handy is installed as an app bundle, invoke the binary directly:
/Applications/Handy.app/Contents/MacOS/Handy --toggle-transcription

Known Issues & Current Limitations

This project is actively being developed and has some known issues. We believe in transparency about the current state:

Major Issues (Help Wanted)

Whisper Model Crashes:

Whisper models crash on certain system configurations (Windows and Linux)
Does not affect all systems - issue is configuration-dependent
- If you experience crashes and are a developer, please help to fix and provide debug logs!

Wayland Support (Linux):

Limited support for Wayland display server
Requires wtype or dotool for text input to work correctly (see Linux Notes below for installation)

Linux Notes

Text Input Tools:

For reliable text input on Linux, install the appropriate tool for your display server:

Display Server	Recommended Tool	Install Command
X11	`xdotool`	`sudo apt install xdotool`
Wayland	`wtype`	`sudo apt install wtype`
Both	`dotool`	`sudo apt install dotool` (requires `input` group)

X11: Install xdotool for both direct typing and clipboard paste shortcuts
Ubuntu 26.04: Has Wayland display server by default. wtype does not works, you need to install ydotool and configure systemd as describe here.
Wayland: Install wtype (preferred) or dotool for text input to work correctly
dotool setup: Requires adding your user to the input group: sudo usermod -aG input $USER (then log out and back in)

Without these tools, Handy falls back to enigo which may have limited compatibility, especially on Wayland.

Other Notes:

Runtime library dependency (libgtk-layer-shell.so.0):

Handy links gtk-layer-shell on Linux. If startup fails with error while loading shared libraries: libgtk-layer-shell.so.0, install the runtime package for your distro:

Distro	Package to install	Example command
Ubuntu/Debian	`libgtk-layer-shell0`	`sudo apt install libgtk-layer-shell0`
Fedora/RHEL	`gtk-layer-shell`	`sudo dnf install gtk-layer-shell`
Arch Linux	`gtk-layer-shell`	`sudo pacman -S gtk-layer-shell`

For building from source on Ubuntu/Debian, you may also need libgtk-layer-shell-dev.

The recording overlay is disabled by default on Linux (Overlay Position: None) because certain compositors treat it as the active window. When the overlay is visible it can steal focus, which prevents Handy from pasting back into the application that triggered transcription. If you enable the overlay anyway, be aware that clipboard-based pasting might fail or end up in the wrong window.
If you are having trouble with the app, running with the environment variable WEBKIT_DISABLE_DMABUF_RENDERER=1 may help
If Handy fails to start reliably on Linux, see Troubleshooting → Linux Startup Crashes or Instability.
Global keyboard shortcuts (Wayland): On Wayland, system-level shortcuts must be configured through your desktop environment or window manager. Use the CLI flags as the command for your custom shortcut.

GNOME:
1. Open Settings > Keyboard > Keyboard Shortcuts > Custom Shortcuts
2. Click the + button to add a new shortcut
3. Set the Name to Toggle Handy Transcription
4. Set the Command to handy --toggle-transcription
5. Click Set Shortcut and press your desired key combination (e.g., Super+O)
KDE Plasma:
1. Open System Settings > Shortcuts > Custom Shortcuts
2. Click Edit > New > Global Shortcut > Command/URL
3. Name it Toggle Handy Transcription
4. In the Trigger tab, set your desired key combination
5. In the Action tab, set the command to handy --toggle-transcription
Sway / i3:

Add to your config file (~/.config/sway/config or ~/.config/i3/config):
```
bindsym $mod+o exec handy --toggle-transcription
```
Hyprland:

Add to your config file (~/.config/hypr/hyprland.conf):
```
bind = $mainMod, O, exec, handy --toggle-transcription
```

You can also trigger Handy externally via Unix signals or the CLI flags, which lets Wayland window managers or other hotkey daemons keep ownership of keybindings:

Action	Trigger
Toggle transcription	`pkill -USR2 -n handy` or `handy --toggle-transcription`
Toggle transcription with post-processing	`handy --toggle-post-process`

Example Sway config:

bindsym $mod+o exec pkill -USR2 -n handy
bindsym $mod+p exec handy --toggle-post-process

pkill here simply delivers the signal—it does not terminate the process.

Behavior change: older releases also accepted SIGUSR1 for toggling transcription with post-processing. WebKitGTK — the webview engine embedded in Handy on Linux — uses SIGUSR1 internally to coordinate JavaScript garbage collection, so listening for it caused phantom recordings and interrupted dictations every few minutes (#1660). Handy no longer listens for SIGUSR1 on Linux; the post-processing toggle is still available via handy --toggle-post-process. Remove any pkill -USR1 bindings: the signal is now delivered straight to WebKit's internal handler and can crash the app.

Overlay & Pasting Issues (Linux):

The recording overlay window can interfere with pasting transcribed text into target applications on Linux (X11)
Solution: Open Settings > Advanced and set "Overlay Position" to "None" to disable the overlay
Enable "Audio Feedback" (also in Advanced) if you still want audible confirmation of recording state
Users who upgrade from older versions or import settings from other platforms may need to manually apply this change

Platform Support

macOS (both Intel and Apple Silicon)
x64 Windows
x64 Linux

System Requirements/Recommendations

The following are recommendations for running Handy on your own machine. If you don't meet the system requirements, the performance of the application may be degraded. We are working on improving the performance across all kinds of computers and hardware.

For Whisper Models:

macOS: M series Mac, Intel Mac
Windows: Intel, AMD, or NVIDIA GPU
Linux: Intel, AMD, or NVIDIA GPU
- Ubuntu 22.04, 24.04

For Parakeet V3 Model:

CPU-only operation - runs on a wide variety of hardware
Minimum: Intel Skylake (6th gen) or equivalent AMD processors
Performance: ~5x real-time speed on mid-range hardware (tested on i5)
Automatic language detection - no manual language selection required

Roadmap & Active Development

We're actively working on several features and improvements. Contributions and feedback are welcome!

In Progress

Debug Logging:

Adding debug logging to a file to help diagnose issues

macOS Keyboard Improvements:

Support for Globe key as transcription trigger
A rewrite of global shortcut handling for MacOS, and potentially other OS's too.

Opt-in Analytics:

Collect anonymous usage data to help improve Handy
Privacy-first approach with clear opt-in

Settings Refactoring:

Cleanup and refactor settings system which is becoming bloated and messy
Implement better abstractions for settings management

Tauri Commands Cleanup:

Abstract and organize Tauri command patterns
Investigate tauri-specta for improved type safety and organization

Verify Release Signatures

Handy release artifacts are signed with Tauri's updater signature format. The public key is stored in src-tauri/tauri.conf.json under plugins.updater.pubkey.

To verify a release manually, set ARTIFACT to the filename you downloaded, save the pubkey value from src-tauri/tauri.conf.json to handy.pub.b64, then decode the public key and matching .sig file from base64 and verify the artifact with minisign:

# Replace with the file you downloaded
ARTIFACT="Handy_0.8.1_amd64.AppImage"

python3 - "$ARTIFACT" <<'PY'
import base64, pathlib, sys

artifact = sys.argv[1]

pub = pathlib.Path("handy.pub.b64").read_text().strip()
pathlib.Path("handy.pub").write_bytes(base64.b64decode(pub))

sig = pathlib.Path(f"{artifact}.sig").read_text().strip()
pathlib.Path(f"{artifact}.minisig").write_bytes(base64.b64decode(sig))
PY

minisign -Vm "$ARTIFACT" \
  -p handy.pub \
  -x "$ARTIFACT.minisig"

On success, minisign prints:

Signature and comment signature verified

Do not use gpg for these .sig files.

Troubleshooting

Manual Model Installation (For Proxy Users or Network Restrictions)

If you're behind a proxy, firewall, or in a restricted network environment where Handy cannot download models automatically, you can manually download and install them. The URLs are publicly accessible from any browser.

Step 1: Find Your App Data Directory

Open Handy settings
Navigate to the About section
Copy the "App Data Directory" path shown there, or use the shortcuts:
- macOS: Cmd+Shift+D to open debug menu
- Windows/Linux: Ctrl+Shift+D to open debug menu

The typical paths are:

macOS: ~/Library/Application Support/com.pais.handy/
Windows: C:\Users\{username}\AppData\Roaming\com.pais.handy\
Linux: ~/.config/com.pais.handy/

Step 2: Create Models Directory

Inside your app data directory, create a models folder if it doesn't already exist:

# macOS/Linux
mkdir -p ~/Library/Application\ Support/com.pais.handy/models

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:APPDATA\com.pais.handy\models"

Step 3: Download Model Files

Download the models you want from below

Whisper Models (single .bin files):

Small (487 MB): https://blob.handy.computer/ggml-small.bin
Medium (492 MB): https://blob.handy.computer/whisper-medium-q4_1.bin
Turbo (1600 MB): https://blob.handy.computer/ggml-large-v3-turbo.bin
Large (1100 MB): https://blob.handy.computer/ggml-large-v3-q5_0.bin

Parakeet Unified EN 0.6B (single .gguf file, recommended):

Q8_0 (731 MB): https://huggingface.co/handy-computer/parakeet-unified-en-0.6b-gguf/resolve/main/parakeet-unified-en-0.6b-Q8_0.gguf

Parakeet Models (compressed archives):

V2 (473 MB): https://blob.handy.computer/parakeet-v2-int8.tar.gz
V3 (478 MB): https://blob.handy.computer/parakeet-v3-int8.tar.gz

Step 4: Install Models

For Whisper Models (.bin files):

Simply place the .bin file directly into the models directory:

{app_data_dir}/models/
├── ggml-small.bin
├── whisper-medium-q4_1.bin
├── ggml-large-v3-turbo.bin
└── ggml-large-v3-q5_0.bin

For GGUF Models (.gguf files):

Place the .gguf file directly into the models directory, exactly like the Whisper .bin files above. Handy also picks up models already present in the shared Hugging Face cache (~/.cache/huggingface/hub), so a copy downloaded by another tool works without being moved.

For Parakeet Models (.tar.gz archives):

Extract the .tar.gz file
Place the extracted directory into the models folder
The directory must be named exactly as follows:
- Parakeet V2: parakeet-tdt-0.6b-v2-int8
- Parakeet V3: parakeet-tdt-0.6b-v3-int8

Final structure should look like:

{app_data_dir}/models/
├── parakeet-tdt-0.6b-v2-int8/     (directory with model files inside)
│   ├── (model files)
│   └── (config files)
└── parakeet-tdt-0.6b-v3-int8/     (directory with model files inside)
    ├── (model files)
    └── (config files)

Important Notes:

For Parakeet models, the extracted directory name must match exactly as shown above
Do not rename the .bin or .gguf files—use the exact filenames from the download URLs
After placing the files, restart Handy to detect the new models

Step 5: Verify Installation

Restart Handy
Open Settings → Models
Your manually installed models should now appear as "Downloaded"
Select the model you want to use and test transcription

Custom Whisper Models

Handy can auto-discover custom Whisper GGML models placed in the models directory. This is useful for users who want to use fine-tuned or community models not included in the default model list.

How to use:

Obtain a Whisper model in GGML .bin format (e.g., from Hugging Face)
Place the .bin file in your models directory (see paths above)
Restart Handy to discover the new model
The model will appear in the "Custom Models" section of the Models settings page

Important:

Community models are user-provided and may not receive troubleshooting assistance
The model must be a valid Whisper GGML format (.bin file)
Model name is derived from the filename (e.g., my-custom-model.bin → "My Custom Model")

Linux Startup Crashes or Instability

If Handy fails to start reliably on Linux — for example, it crashes shortly after launch, never shows its window, or reports a Wayland protocol error — try the steps below in order.

1. Install (or reinstall) gtk-layer-shell

Handy uses gtk-layer-shell for its recording overlay and links against it at runtime. A missing or broken installation is the most common cause of startup failures and can manifest as a crash or a hang well before any window is shown. Make sure the runtime package is installed for your distro:

Distro	Package to install	Example command
Ubuntu/Debian	`libgtk-layer-shell0`	`sudo apt install libgtk-layer-shell0`
Fedora/RHEL	`gtk-layer-shell`	`sudo dnf install gtk-layer-shell`
Arch Linux	`gtk-layer-shell`	`sudo pacman -S gtk-layer-shell`

If it is already installed and you still see startup problems, try reinstalling it (e.g. sudo pacman -S gtk-layer-shell again) in case the library files were corrupted by a partial upgrade.

2. Disable the GTK layer shell overlay (HANDY_NO_GTK_LAYER_SHELL)

If installing the library does not help, you can skip gtk-layer-shell initialization entirely as a workaround. On some compositors (notably KDE Plasma under Wayland) it has been reported to interact poorly with the recording overlay. With this variable set, the overlay falls back to a regular always-on-top window:

HANDY_NO_GTK_LAYER_SHELL=1 handy

3. Disable WebKit DMA-BUF renderer (WEBKIT_DISABLE_DMABUF_RENDERER)

On some GPU/driver combinations the WebKitGTK DMA-BUF renderer can cause the window to fail to render or to crash. Try:

WEBKIT_DISABLE_DMABUF_RENDERER=1 handy

Making a workaround permanent

Once you've found a flag that helps, export it from your shell profile (~/.bashrc, ~/.zshenv, …) or from the desktop autostart entry that launches Handy. If you launch Handy from a .desktop file, you can prefix the Exec= line, e.g.:

Exec=env HANDY_NO_GTK_LAYER_SHELL=1 handy

If a workaround helps you, please open an issue describing your distro, desktop environment, and session type — that information helps us narrow down the underlying bug.

Handy Starts or Stops Recording on Its Own (Linux)

Handy 0.9.4 and earlier listened for SIGUSR1 as a remote-control trigger. WebKitGTK — the webview engine embedded in Handy on Linux — uses that same signal internally to coordinate JavaScript garbage collection, so GC cycles were misread as hotkey presses: recordings started on their own, or real dictations were cut off mid-sentence (typically ~2 minutes in). See #1660.

Update to a newer release, and replace any pkill -USR1 -n handy keybindings with handy --toggle-post-process.

How to Contribute

Check existing issues at github.com/cjpais/Handy/issues
Fork the repository and create a feature branch
Test thoroughly on your target platform
Submit a pull request with clear description of changes
Join the discussion - reach out at contact@handy.computer

The goal is to create both a useful tool and a foundation for others to build upon—a well-patterned, simple codebase that serves the community.

Related Projects

Handy CLI - The original Python command-line version
handy.computer - Project website with demos and documentation

License

MIT License - see LICENSE file for details.

Handy is open-source software, but the Handy name, logo, icon, and brand assets are not open-source. Unofficial forks, rewrites, and redistributions must use their own branding and must not imply endorsement or affiliation.

Acknowledgments

Whisper by OpenAI for the speech recognition model
ggml and transcribe.cpp for amazing cross-platform speech-to-text inference/acceleration
Silero for great lightweight VAD
Tauri team for the excellent Rust-based app framework
Community contributors helping make Handy better

t8y2/dbx

20 MB lightweight cross-platform database client for 70+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具，支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 70+ 数据库，提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。

70+ databases in 20 MB. Desktop, Docker, CLI, built-in AI assistant, and MCP Server.

English | 前往中文版本

Why DBX?

🪶 20 MB, zero runtime bloat

No Java JRE. No Python venv. No bundled Chromium. DBX ships as a single small binary — download, install, connect. DBeaver needs Java; TablePlus is macOS-only. DBX runs everywhere with nothing extra.

🤖 AI that lives in your editor

Highlight a table, describe what you want, get SQL back — no copy-paste between tools. Works with Claude, OpenAI, or local models via Ollama. Built-in safety checks review AI-generated SQL before it runs.

🔌 MCP: your databases, AI-ready

DBX speaks the Model Context Protocol. Claude Code, Cursor, Windsurf, and other AI coding agents can query your databases through connections you already set up. One config, everywhere.

🌐 Desktop + Docker + Web

Native app on macOS, Windows, and Linux. Self-host via Docker for team access. Web version for browser-only environments. Same feature set. Same connections.

Features

70+ Databases, One Tool

MySQL, PostgreSQL, SQLite, Cloudflare D1, Redis, MongoDB, DuckDB, ClickHouse, SQL Server, Oracle, Elasticsearch, Easysearch, Qdrant, Milvus, Weaviate, MariaDB, TiDB, OceanBase, openGauss, GaussDB, KWDB, KingBase, Vastbase, GoldenDB, Doris, SelectDB, StarRocks, Manticore Search, Redshift, DM, TDengine, XuguDB, CockroachDB, Access, HighGo, UXDB, Dolt, and more. Agent-based profiles extend DBX to H2, Snowflake, Trino, PrestoSQL, Hive, DB2, Informix, Neo4j, Cassandra, BigQuery, Kylin, SunDB, JDBCX, and custom JDBC connections. New native and agent-driven drivers also cover Databricks, SAP HANA, Teradata, Vertica, Firebird, Exasol, YashanDB, GBase 8a/8s, Databend, RQLite, Turso, InfluxDB, QuestDB, IoTDB, etcd, ZooKeeper, Nacos, IRIS, and more. Message queue admin is also available for Pulsar, Kafka, and RocketMQ. All in a single ~20 MB app. No bundled Chromium.

Query Editor

CodeMirror 6 with SQL syntax highlighting, metadata-aware autocomplete, Cmd+Enter execution, selected SQL execution, SQL formatting, diagnostics, and 9 editor themes. Persistent query history, saved SQL snippets, tab restore, and SQL file execution keep repeat work close at hand.

AI SQL Assistant

Describe what you want in plain language — get SQL back. DBX can explain queries, optimize SQL, fix errors, and run AI-generated SQL through built-in safety checks. Works with Claude, OpenAI, local models, or any OpenAI-compatible endpoint.

Data Grid

Virtual-scrolled table that handles large result sets. Inline editing, SQL preview before save, WHERE / ORDER BY controls, DataGrip-style filters, LIKE / NOT LIKE context filters, sorting, full-text search, pagination, column resize, auto-fit, row numbers, zebra stripes, and full cell details. Export or copy as CSV, JSON, Markdown, XLSX, or INSERT statements.

Schema Tools

Schema browser — databases, schemas, tables, columns, indexes, foreign keys, triggers, with sidebar search & pin
Object browser — grouped procedures, functions, views, and source editing where supported
Table structure editor — reviewable column and index changes for supported engines
ER diagram — visualize table relationships
Schema diff — compare structures across connections
Explain plan — visual query execution plan
Field lineage — column-level lineage analysis
Database search — find objects across large schemas

Data Operations

Table import — CSV, Excel
Data transfer — migrate between databases
Database export — full database dump
Data compare — compare table data and review synchronization output
SQL file execution — run .sql files directly
File preview — drag & drop Parquet, CSV, JSON to preview instantly (powered by DuckDB)
Connection import — bring connection profiles from DBeaver or Navicat

Specialized Browsers

Redis — key pattern search, batch key operations, command runner, TTL editing, and all data types (String, Hash, List, Set, ZSet, Stream)
MongoDB — document CRUD with pagination, Atlas & replica set URL connection

Safety & Connectivity

SSH tunnel (key & password) · database and AI proxy settings · auto-reconnect on connection loss · confirmation dialogs for destructive operations · encrypted config export/import · color-coded connections · driver store and optional JDBC plugin

Polished UI

Dark mode with native title bar sync · 9 editor themes · English, 简体中文 & Español · layout preferences · built-in auto-update

AI Agent Integration (MCP)

DBX provides a separate Rust-powered MCP server that lets AI coding agents query databases using connections configured in DBX. The MCP server is distributed independently from the desktop application, so installing DBX does not automatically install the MCP executable.

npx @dbx-app/mcp-server

Add to your .mcp.json:

{
  "mcpServers": {
    "dbx": { "command": "npx", "args": ["-y", "@dbx-app/mcp-server"] }
  }
}

Manage the connection allowlist and the Read only, Data read/write, and Full access modes in DBX Settings → MCP. The machine-readable values remain read_only, safe_write, and high_risk_write; client configs do not need permission or connection-scope environment variables.

For upgrade compatibility, an existing DBX_MCP_ALLOW_WRITES=0 (or false) remains a read-only restriction only until a central MCP policy is saved for the first time; it can never enable writes or override a saved policy.

Windows portable builds need DBX_DATA_DIR in the MCP config, pointing to the data directory next to DBX.exe (the folder that contains dbx.db).

For DBX Web or Docker deployments, point the MCP server at the Web backend API. If the Web login page requires a password, set DBX_WEB_PASSWORD to the same password used there:

{
  "mcpServers": {
    "dbx": {
      "command": "npx",
      "args": ["-y", "@dbx-app/mcp-server"],
      "env": {
        "DBX_WEB_URL": "http://localhost:4224",
        "DBX_WEB_PASSWORD": "your-web-login-password"
      }
    }
  }
}

Works with Claude Code, Cursor, Windsurf, and any MCP-compatible agent. Supports listing connections, browsing tables, executing SQL, and opening tables directly in DBX's UI.

Precompiled native binaries are also published for macOS, Linux, and Windows in package releases. They run without Node.js and are suitable for offline or server environments. The npm installation uses the same Rust binary through a small Node.js launcher.

DBX also provides a dedicated CLI package for terminal, script, and Codex workflows:

npm install -g @dbx-app/cli
# or via Homebrew
brew tap t8y2/dbx && brew install dbx-cli
dbx connections list --json
dbx query local "select 1" --json

See the MCP server README and CLI README for details.

Install

Download the latest release from the Releases page.

Homebrew (macOS):

brew install --cask dbx

Scoop (Windows):

scoop bucket add dbx https://github.com/t8y2/scoop-bucket
scoop install dbx

WinGet (Windows):

winget install t8y2.dbx

Flatpak (Linux):

flatpak remote-add --if-not-exists flatpark https://dl.flatpark.org/flatpark.flatpakrepo
flatpak install flatpark com.dbxio.dbx

Updates then arrive through the regular flatpak update. See the DBX page on FlatPark for details.

Self-Hosted (Docker)

DBX provides a web version that can be deployed via Docker. The examples use the latest tag to pull the current release.

docker run -d --pull=always --name dbx -p 4224:4224 -v dbx-data:/app/data t8y2/dbx:latest

This uses the cross-platform dbx-data named volume. Users in China can use the CNB image, docker.cnb.cool/dbxio.com/dbx:latest, for faster pulls.

For Docker Compose, deploy/docker-compose.yml remains the source-build configuration. To deploy a published image, use deploy/docker-compose.release.yml:

docker compose -f deploy/docker-compose.release.yml up -d

services:
  dbx:
    image: t8y2/dbx:latest
    # For faster pulls in China, use the CNB image instead:
    # image: docker.cnb.cool/dbxio.com/dbx:latest
    pull_policy: always
    ports:
      - "4224:4224"
    volumes:
      - dbx-data:/app/data
    restart: unless-stopped

volumes:
  dbx-data:

Open http://localhost:4224 in your browser. Multi-arch images (amd64 / arm64) are available.

To publish DBX under a reverse-proxy context path such as /dbx, set the runtime base path and proxy the same prefix to the container:

environment:
  - DBX_PUBLIC_BASE_PATH=/dbx

When building the frontend yourself with an absolute asset base, set VITE_DBX_BASE_PATH=/dbx/ before pnpm build.

Getting Started

Prerequisites

Node.js >= 18
pnpm
Rust >= 1.88

System Dependencies

macOS:

No additional dependencies required.

Linux (Ubuntu/Debian):

sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libappindicator3-dev librsvg2-dev patchelf libssl-dev

NIXOS/NIX :

See README-NIX.md

Windows:

No additional dependencies required.

Development

make

make installs root dependencies when needed and starts the local Tauri desktop development environment.

Development builds can run alongside an installed DBX instance and share its local data, including connections and history. Avoid changing the same connection or global setting in both windows at once.

Tip

DuckDB compilation takes a while. If you're not working on DuckDB features, skip it to speed up local builds:

# Fast checks (skip DuckDB)
make cargo-check-fast
make cargo-test-fast

# Tauri dev without DuckDB
make dev-fast

The --no-default-features flag only affects local development. Release builds (pnpm tauri build) always include DuckDB.

Web version:

make dev-web       # frontend
make dev-backend   # backend

Documentation site:

make docs

The official DBX documentation site lives in docs/. If you want to improve the website content or documentation pages, edit the files under docs/ and run make docs to preview the site locally.

For clean, reproducible local database instances, use the versioned Docker Compose recipes under deploy/database/:

make db-list
make db-verify DB=mysql@8.4

JDBC agent driver development projects live in agents/:

cd agents
./gradlew test

Build artifacts from agents/drivers/<db-type>/build/libs/ are picked up by local driver install flows when available.

Build

make package

The installer will be in src-tauri/target/release/bundle/.

Tech Stack

Layer	Technology
Framework	Tauri 2
Frontend	Vue 3 + TypeScript
UI	shadcn-vue + Tailwind CSS
Editor	CodeMirror 6
Backend	Rust + sqlx / tiberius / redis-rs / mongodb

Documentation

Official docs — feature guides and tutorials
Database Test Lab — local database recipes for development and verification
Contributing — how to pick up issues and open PRs
Web API reference — HTTP API for Docker/Web deployments
Examples — CLI, MCP, Docker, and API samples

Community

Support DBX

DBX is free and open source, but ongoing maintenance, database compatibility testing, infrastructure, and release work require sustained time and resources.

Sponsors & Partners

	RainYun is a cloud service provider offering cloud servers, physical servers, game hosting, and developer-friendly infrastructure services.	Visit RainYun
	Qiniu Cloud provides DBX with object storage, CDN, and other cloud infrastructure resources.	Visit Qiniu Cloud
	Easysearch is an enterprise-grade distributed search engine compatible with Elasticsearch APIs, combining full-text, vector, geospatial search, real-time analytics, and AI capabilities in one platform.	Visit Easysearch
	Atlas Cloud gives developers one unified API for 400+ AI models across chat, image, video, and audio.	Visit Atlas Cloud

Support DBX — voluntary donations via WeChat or Alipay
Sponsors & Partners — sponsorship, infrastructure, tools, and community collaboration

FAQ

Is DBX free?

Yes. DBX is open source under Apache-2.0. All features are free.

Does DBX phone home?

No. DBX does not collect telemetry. The auto-update feature checks GitHub Releases for new versions — you can disable it in settings.

Can I use DBX without an internet connection?

Yes. The desktop app works fully offline. For air-gapped driver installs, download offline driver packages from the [Offline Drivers page](https://dbxio.com/en/drivers) on an internet-connected machine, transfer them to the offline machine, then import them in DBX from Settings > Driver Manager. AI features need network access to the model endpoint (or a local model via Ollama).

How is DBX different from DBeaver / TablePlus / Beekeeper Studio?

DBX is 20 MB with no runtime dependencies for its native database features (no system Java or Python required). AI is built into the application, while MCP is provided as a separately installed Rust companion package or native binary. It supports 70+ databases across desktop, Docker, and web from a shared Rust core.

What databases are supported?

MySQL, PostgreSQL, SQLite, Cloudflare D1, Redis, MongoDB, DuckDB, ClickHouse, SQL Server, Oracle, Elasticsearch, Easysearch, Qdrant, Milvus, Weaviate, MariaDB, TiDB, OceanBase, openGauss, GaussDB, KWDB, KingBase, Vastbase, GoldenDB, Doris, SelectDB, StarRocks, Manticore Search, Redshift, DM, TDengine, XuguDB, CockroachDB, Access, HighGo, UXDB, and more. Agent-based profiles extend support to H2, Snowflake, Trino, PrestoSQL, Hive, DB2, Informix, Neo4j, Cassandra, BigQuery, Kylin, SunDB, JDBCX, Databricks, SAP HANA, Teradata, Vertica, Firebird, Exasol, YashanDB, GBase 8a/8s, Databend, RQLite, Turso, InfluxDB, QuestDB, IoTDB, etcd, ZooKeeper, Nacos, IRIS, and custom JDBC connections. Message queue admin (Pulsar, Kafka, RocketMQ) is also supported.

How do I report a bug or request a feature?

Open an issue on GitHub Issues.

Contributors

Star History

License

Apache-2.0

dani-garcia/vaultwarden

Unofficial Bitwarden compatible server written in Rust, formerly known as bitwarden_rs

An alternative server implementation of the Bitwarden Client API, written in Rust and compatible with official Bitwarden clients [disclaimer], perfect for self-hosted deployment where running the official resource-heavy service might not be ideal.

Important

When using this server, please report any bugs or suggestions directly to us (see Get in touch), regardless of whatever clients you are using (mobile, desktop, browser...). DO NOT use the official Bitwarden support channels.

Features

A nearly complete implementation of the Bitwarden Client API is provided, including:

Personal Vault
Send
Attachments
Website icons
Personal API Key
Organizations
- Collections, Password Sharing, Member Roles, Groups, Event Logs, Admin Password Reset, Directory Connector, Policies
Multi/Two Factor Authentication
- Authenticator, Email, FIDO2 WebAuthn, YubiKey, Duo
Emergency Access
Vaultwarden Admin Backend
Modified Web Vault client (Bundled within our containers)

Usage

Important

The web-vault requires the use of HTTPS and a secure context for the Web Crypto API.
That means it will only work if you enable HTTPS.
We also suggest to use a reverse proxy.

The recommended way to install and use Vaultwarden is via our container images which are published to ghcr.io, docker.io and quay.io. See which container image to use for an explanation of the provided tags.

There are also community driven packages which can be used, but those might be lagging behind the latest version or might deviate in the way Vaultwarden is configured, as described in our Wiki.

Alternatively, you can also build Vaultwarden yourself.

While Vaultwarden is based upon the Rocket web framework which has built-in support for TLS our recommendation would be that you setup a reverse proxy (see proxy examples).

Tip

For more detailed examples on how to install, use and configure Vaultwarden you can check our Wiki.

Docker/Podman CLI

Pull the container image and mount a volume from the host for persistent storage.
You can replace docker with podman if you prefer to use podman.

docker pull vaultwarden/server:latest
docker run --detach --name vaultwarden \
  --env DOMAIN="https://vw.domain.tld" \
  --volume /vw-data/:/data/ \
  --restart unless-stopped \
  --publish 127.0.0.1:8000:80 \
  vaultwarden/server:latest

This will preserve any persistent data under /vw-data/, you can adapt the path to whatever suits you.

Docker Compose

To use Docker compose you need to create a compose.yaml which will hold the configuration to run the Vaultwarden container.

services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: "https://vw.domain.tld"
    volumes:
      - ./vw-data/:/data/
    ports:
      - 127.0.0.1:8000:80

Get in touch

Have a question, suggestion or need help? Join our community on Matrix, GitHub Discussions or Discourse Forums.

Encountered a bug or crash? Please search our issue tracker and discussions to see if it's already been reported. If not, please start a new discussion or create a new issue. Ensure you're using the latest version of Vaultwarden and there aren't any similar issues open or closed!

Contributors

Thanks for your contribution to the project!

Disclaimer

This project is not associated with Bitwarden or Bitwarden, Inc.

However, one of the active maintainers for Vaultwarden is employed by Bitwarden and is allowed to contribute to the project on their own time. These contributions are independent of Bitwarden and are reviewed by other maintainers.

The maintainers work together to set the direction for the project, focusing on serving the self-hosting community, including individuals, families, and small organizations, while ensuring the project's sustainability.

Please note: We cannot be held liable for any data loss that may occur while using Vaultwarden. This includes passwords, attachments, and other information handled by the application. We highly recommend performing regular backups of your files and database. However, should you experience data loss, we encourage you to contact us immediately.

Bitwarden_RS

This project was known as Bitwarden_RS and has been renamed to separate itself from the official Bitwarden server in the hopes of avoiding confusion and trademark/branding issues.
Please see #1642 - v1.21.0 release and project rename to Vaultwarden for more explanation.

rustfs/rustfs

🚀2.3x faster than MinIO for 4KB object payloads. RustFS is an open-source, S3-compatible high-performance object storage system supporting migration and coexistence with other S3-compatible platforms such as MinIO and Ceph.

RustFS is a high-performance, distributed object storage system built in Rust.

Getting Started · Docs · Bug reports · Discussions

RustFS is a high-performance, distributed object storage system built in Rust—one of the most loved programming languages worldwide. RustFS combines the simplicity of MinIO with the memory safety and raw performance of Rust. It offers broad S3 API compatibility for supported features, is completely open-source, and is optimized for data lakes, AI, and big data workloads.

Unlike other storage systems, RustFS is released under the permissible Apache 2.0 license, avoiding the restrictions of AGPL. With Rust as its foundation, RustFS delivers superior speed and secure distributed features for next-generation object storage.

Feature & Status

High Performance: Built with Rust to ensure maximum speed and resource efficiency.
Distributed Architecture: Scalable and fault-tolerant design suitable for large-scale deployments.
S3 Compatibility: Seamless integration with common S3-compatible applications and tools; current coverage is tracked in the S3 compatibility matrix.
OpenStack Swift API: Native support for Swift protocol with Keystone authentication.
OpenStack Keystone Integration: Native support for OpenStack Keystone authentication with X-Auth-Token headers.
Data Lake Support: Optimized for high-throughput big data and AI workloads.
Open Source: Licensed under Apache 2.0, encouraging unrestricted community contributions and commercial usage.
User-Friendly: Designed with simplicity in mind for easy deployment and management.

Feature	Status	Feature	Status
S3 Core Features	✅ Available	Bitrot Protection	✅ Available
Upload / Download	✅ Available	Single Node Mode	✅ Available
Versioning	✅ Available	Bucket Replication	✅ Available
Logging	✅ Available	Lifecycle Management	🚧 Under Testing
Event Notifications	✅ Available	Distributed Mode	🚧 Under Testing
K8s Helm Charts	✅ Available	RustFS KMS	🚧 Under Testing
Keystone Auth	✅ Available	Multi-Tenancy	✅ Available
Swift API	✅ Available	Swift Metadata Ops	🚧 Partial

RustFS vs MinIO Performance

Stress Test Environment:

Type	Parameter	Remark
CPU	2 Core	Intel Xeon (Sapphire Rapids) Platinum 8475B, 2.7/3.2 GHz
Memory	4GB
Network	15Gbps
Drive	40GB x 4	IOPS 3800 / Drive

https://github.com/user-attachments/assets/2e4979b5-260c-4f2c-ac12-c87fd558072a

RustFS vs Other Object Storage

Feature	RustFS	Other Object Storage
Console Experience	Powerful Console Comprehensive management interface.	Basic / Limited Console Often overly simple or lacking critical features.
Language & Safety	Rust-based Memory safety by design.	Go or C-based Potential for memory GC pauses or leaks.
Data Sovereignty	No Telemetry / Full Compliance Guards against unauthorized cross-border data egress. Compliant with GDPR (EU/UK), CCPA (US), and APPI (Japan).	Potential Risk Possible legal exposure and unwanted data telemetry.
Licensing	Permissive Apache 2.0 Business-friendly, no "poison pill" clauses.	Restrictive AGPL v3 Risk of license traps and intellectual property pollution.
Compatibility	S3-Compatible Core Works with common S3-compatible clients, with coverage tracked in the compatibility matrix.	Variable Compatibility May lack support for local cloud vendors or specific APIs.
Edge & IoT	Strong Edge Support Ideal for secure, innovative edge devices.	Weak Edge Support Often too heavy for edge gateways.
Risk Profile	Enterprise Risk Mitigation Clear IP rights and safe for commercial use.	Legal Risks Intellectual property ambiguity and usage restrictions.

Staying ahead

Star RustFS on GitHub and be instantly notified of new releases.

Quickstart

To get started with RustFS, follow these steps:

1. One-click Installation (Option 1)

curl -O https://rustfs.com/install_rustfs.sh && bash install_rustfs.sh

2. Docker Quick Start (Option 2)

The RustFS container runs as a non-root user rustfs (UID/GID 10001:10001). If you bind-mount host directories with Docker or Compose, every mounted path must be writable by that user, otherwise startup may fail with permission denied errors. This applies to data directories, log directories, and TLS certificate directories when RUSTFS_TLS_PATH is enabled.

# Create data and logs directories
mkdir -p data logs

# Change the owner of these directories
chown -R 10001:10001 data logs

# Using latest version
docker run -d -p 9000:9000 -p 9001:9001 -v $(pwd)/data:/data -v $(pwd)/logs:/logs rustfs/rustfs:latest

# Using specific version
docker run -d -p 9000:9000 -p 9001:9001 -v $(pwd)/data:/data -v $(pwd)/logs:/logs rustfs/rustfs:1.0.0-rc.1

If you use podman instead of docker, you can install the RustFS with the below command

# Create data and logs directories
mkdir -p data logs

# Run the container (podman will automatically set the folders ownership)
podman run -d -p 9000:9000 -p 9001:9001 -v $(pwd)/data:/data:Z,U -v $(pwd)/logs:/logs:Z,U rustfs/rustfs:latest

If you enable TLS with a bind-mounted certificate directory, prepare that mount the same way:

mkdir -p certs
chown -R 10001:10001 certs

You can also use Docker Compose. Using the docker-compose-simple.yml file in the root directory:

docker compose -f docker-compose-simple.yml up -d

Before running Compose with host bind mounts:

Ensure every mounted host path is writable by 10001:10001.
If you enable TLS, ensure the certificate mount for /opt/tls is also readable by 10001:10001.
If matching host ownership is not practical, run the rustfs service with user: "<host-uid>:<host-gid>" instead.
docker-compose-simple.yml includes a volume-permission-helper service for named volumes. docker-compose-simple.yml relies on you to prepare bind-mounted host paths in advance.

Similarly, you can run the command with podman

podman compose -f docker-compose-simple.yml up -d

Webhook notification quick start (Docker):

docker run -d --name rustfs -p 9000:9000 \
  -e RUSTFS_NOTIFY_ENABLE=true \
  -e RUSTFS_NOTIFY_WEBHOOK_ENABLE_PRIMARY=on \
  -e RUSTFS_NOTIFY_WEBHOOK_ENDPOINT_PRIMARY=http://<host-ip>:3020/webhook \
  -e RUSTFS_NOTIFY_WEBHOOK_QUEUE_DIR_PRIMARY=/tmp/rustfs-events \
  -e RUSTFS_OUTBOUND_ALLOW_ORIGINS=http://<host-ip>:3020 \
  rustfs/rustfs:latest

Notes:

RUSTFS_NOTIFY_ENABLE=true enables the global notify module switch.
For ARN arn:rustfs:sqs::primary:webhook, use instance-scoped env vars with _PRIMARY.
If queue dir is omitted, default is /opt/rustfs/events; ensure it is writable by the container runtime user.
RUSTFS_NOTIFY_WEBHOOK_SKIP_TLS_VERIFY_PRIMARY defaults to false; enabling it skips webhook TLS certificate verification, allows MITM attacks, and emits a startup warning. Prefer RUSTFS_NOTIFY_WEBHOOK_CLIENT_CA_PRIMARY for private CAs.
Since 1.0.0-beta.11, webhook endpoints on private or container networks (Docker Compose service names, host.docker.internal, RFC 1918 addresses) are blocked unless their exact scheme://host:port origin is listed in RUSTFS_OUTBOUND_ALLOW_ORIGINS (the origin only, without the path). See Outbound Connection Policy.

NOTE: We recommend reviewing the docker-compose.yml file before running. It defines several services including Grafana, Prometheus, and Jaeger, which are helpful for RustFS observability. If you wish to start Redis or Nginx containers, you can specify the corresponding profiles.

3. Build from Source (Option 3) - Advanced Users

For developers who want to build RustFS Docker images from source with multi-architecture support:

# Build multi-architecture images locally
./docker-buildx.sh --build-arg RELEASE=latest

# Build and push to registry
./docker-buildx.sh --push

# Build specific version
./docker-buildx.sh --release v1.0.0 --push

# Build for custom registry
./docker-buildx.sh --registry your-registry.com --namespace yourname --push

The docker-buildx.sh script supports:

Multi-architecture builds: linux/amd64, linux/arm64
Automatic version detection: Uses git tags or commit hashes
Registry flexibility: Supports Docker Hub, GitHub Container Registry, etc.
Build optimization: Includes caching and parallel builds

You can also use Make targets for convenience:

make docker-buildx                    # Build locally
make docker-buildx-push               # Build and push
make docker-buildx-version VERSION=v1.0.0  # Build specific version
make help-docker                      # Show all Docker-related commands

Heads-up (macOS cross-compilation): macOS keeps the default ulimit -n at 256, so cargo zigbuild or ./build-rustfs.sh --platform ... may fail with ProcessFdQuotaExceeded when targeting Linux. The build script attempts to raise the limit automatically, but if you still see the warning, run ulimit -n 4096 (or higher) in your shell before building.

4. Build with Helm Chart (Option 4) - Cloud Native

Follow the instructions in the Helm Chart README to install RustFS on a Kubernetes cluster.

For scanner pacing, cycle budgets, bitrot cadence, lifecycle transition status, and single-node single-disk idle CPU tuning, see Scanner Runtime Controls. For repeatable scanner-pressure validation, see Scanner Benchmark Runbook. For drive timeout knobs on slow storage — including the walk stall budget that governs ListObjects on large prefixes — see Drive Timeout Tuning.

5. Nix Flake (Option 5)

If you have Nix with flakes enabled:

# Run directly without installing
nix run github:rustfs/rustfs

# Build the binary
nix build github:rustfs/rustfs
./result/bin/rustfs --help

# Or from a local checkout
nix build
nix run

6. X-CMD (Option 6)

If you are an x-cmd user:

# Run directly without installing
x rustfs

# Download the binary and install it to the global environment
x env use rustfs
rustfs --help

Accessing RustFS

Access the Console: Open your web browser and navigate to http://localhost:9001 to access the RustFS console.
- Default credentials: rustfsadmin / rustfsadmin
Create a Bucket: Use the console to create a new bucket for your objects.
Upload Objects: You can upload files directly through the console or use S3-compatible APIs/clients to interact with your RustFS instance.

NOTE: To access the RustFS instance via https, please refer to the TLS Configuration Docs.

OIDC Roles Claim (Microsoft Entra ID)

RustFS supports mapping an OIDC claim containing role values into the existing authorization pipeline. The roles_claim setting is optional: when unset or empty, only the groups claim contributes to authorization (same as older RustFS releases). For Microsoft Entra ID app roles, set roles_claim=roles so both console admin checks and bucket IAM policies can evaluate those roles.

Example environment configuration (opt-in roles claim):

RUSTFS_IDENTITY_OPENID_ENABLE=on
RUSTFS_IDENTITY_OPENID_CONFIG_URL="https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration"
RUSTFS_IDENTITY_OPENID_CLIENT_ID="<client-id>"
RUSTFS_IDENTITY_OPENID_CLIENT_SECRET="<client-secret>"
RUSTFS_IDENTITY_OPENID_SCOPES="openid,profile,email"
RUSTFS_IDENTITY_OPENID_GROUPS_CLAIM="groups"
RUSTFS_IDENTITY_OPENID_ROLES_CLAIM="roles"

Policy condition example (evaluate app roles directly with jwt:roles; when roles_claim is configured, RustFS also merges those values into jwt:groups for backward compatibility with older policies):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["admin:*"],
      "Resource": ["arn:aws:s3:::*"],
      "Condition": {
        "ForAnyValue:StringEquals": {
          "jwt:roles": ["RustFS.ConsoleAdmin"]
        }
      }
    }
  ]
}

Documentation

For detailed documentation, including configuration options, API references, and advanced usage, please visit our Documentation.

Getting Help

If you have any questions or need assistance:

Check the FAQ for common issues and solutions.
Join our GitHub Discussions to ask questions and share your experiences.
Open an issue on our GitHub Issues page for bug reports or feature requests.

Contact

Bugs: GitHub Issues
Business: hello@rustfs.com
Jobs: jobs@rustfs.com
General Discussion: GitHub Discussions
Contributing: CONTRIBUTING.md

Contributors

RustFS is a community-driven project, and we appreciate all contributions. Check out the Contributors page to see the amazing people who have helped make RustFS better.

Star History

License

Apache 2.0

RustFS is a trademark of RustFS, Inc. All other trademarks are the property of their respective owners.

raine/workmux

git worktrees + tmux windows for zero-friction parallel dev

Parallel development in tmux* with git worktrees

📖 Documentation · Install · Quick start · Commands · Changelog

Giga opinionated zero-friction workflow tool for managing git worktrees and tmux windows as isolated development environments. Perfect for running multiple AI agents in parallel without conflict.

Philosophy: Build on tools you already use. tmux/zellij/kitty/etc. for windowing, git for worktrees, your agent for coding - workmux ties them together.

^{_{* Also supports kitty, WezTerm, and Zellij as alternative backends.}}

📖 New to workmux? Read the introduction blog post for a quick overview.

Tip

I'm building aven, a local-first task manager for power users and agents.

Why workmux?

Parallel workflows. Work on multiple features the same time, each with its own AI agent. No stashing, no branch switching, no conflicts.

One window per task. A natural mental model. Each has its own terminal state, editor session, dev server, and AI agent. Context switching is switching tabs.

Automated setup. New worktrees start broken (no .env, no node_modules, no dev server). workmux can copy config files, symlink dependencies, and run install commands on creation.

One-command cleanup. workmux merge handles the full lifecycle: merge the branch, delete the worktree, close the tmux window, remove the local branch.

Terminal workflow. Build on your terminal setup instead of yet another agentic GUI that won't exist next year. If you don't have one yet, tmux might be worth picking up.

New to worktrees? See Why git worktrees?

Features

Create git worktrees with matching tmux windows in a single command (add)
Merge branches and clean up everything (worktree, tmux window, branches) in one command (merge)
Dashboard for monitoring agents, reviewing changes, and sending commands
Sidebar for a persistent, at-a-glance view of all agents across tmux windows
Delegate tasks to worktree agents with the /worktree skill
Display agent status in tmux window names
Automatically set up your preferred tmux pane layout (editor, shell, watchers, etc.)
Run post-creation hooks (install dependencies, setup database, etc.)
Copy or symlink configuration files (.env, node_modules) into new worktrees
Sandbox agents in containers or VMs for enhanced security
Automatic branch name generation from prompts using LLM
Shell completions

Hype

"I've been using (and loving) workmux which brings together tmux, git worktrees, and CLI agents into an opinionated workflow."
— @Coolin96 🔗

"Thank you so much for your work with workmux! It's a tool I've been wanting to exist for a long time."
— @rstacruz 🔗

"It's become my daily driver - the perfect level of abstraction over tmux + git, without getting in the way or obscuring the underlying tooling."
— @cisaacstern 🔗

"I have to mention workmux at every opportunity because it's the perfect glue between worktrees, agents and tmux windows."
— @dedbrizz 🔗

"Since I discovered workmux I'm cooking. Amazing parallel-agent driver if you like tmux and want to keep your config."
— @MatijaSosic 🔗

"Using workmux with a well-configured tmux has been a breath of fresh air"
— @sbeirakh_il 🔗

"I've been using it for about a month now, and it's been nothing but great."
— @gabrielrockson_ 🔗

Installation

Bash YOLO

curl -fsSL https://raw.githubusercontent.com/raine/workmux/main/scripts/install.sh | bash

Homebrew (macOS/Linux)

brew install raine/workmux/workmux

Other methods (Cargo, mise, Nix)

Cargo (requires rustup):

cargo install workmux

mise:

mise use -g cargo:raine/workmux

Nix (flake and home-manager setup):

nix profile install github:raine/workmux

For manual installation, see pre-built binaries.

Quick start

Note

workmux requires a terminal multiplexer. Make sure you have tmux (or WezTerm / Kitty / Zellij) installed and running before you start. See My tmux setup if you need a starting point.

Initialize configuration (optional):
```
workmux init
```
This creates a .workmux.yaml file to customize your workflow (pane layouts, setup commands, file operations, etc.). workmux works out of the box with sensible defaults, so this step is optional.
Create a new worktree and tmux window:
```
workmux add new-feature
```
This will:
- Create a git worktree at <project_root>/../<project_name>__worktrees/new-feature
- Copy config files and symlink dependencies (if configured)
- Run any post_create setup commands
- Create a tmux window named wm-new-feature (the prefix is configurable)
- Set up your configured or the default tmux pane layout
- Automatically switch your tmux client to the new window
Do your thing
Finish and clean up

Local merge: Run workmux merge to merge into the base branch and clean up in one step.

PR workflow: Push and open a PR. After it's merged, run workmux remove to clean up.

Configuration

workmux uses a two-level configuration system:

Global (~/.config/workmux/config.yaml): Personal defaults for all projects
Project (.workmux.yaml): Project-specific overrides

Project settings override global settings. When you run workmux from a subdirectory, it walks upward to find the nearest .workmux.yaml, allowing nested configs for monorepos. See the Monorepos guide for details. For hook lists (post_create, pre_merge, pre_remove) and file operation lists (files.copy, files.symlink), you can use "<global>" to include global values alongside project-specific ones. Other settings like panes are replaced entirely when defined in the project config.

Global configuration example

~/.config/workmux/config.yaml:

nerdfont: true # Enable nerdfont icons (prompted on first run)
merge_strategy: rebase # Make workmux merge do rebase by default
merge_keep: true # Keep worktree, window, and branch after merge by default
agent: claude

panes:
  - command: <agent> # Start the configured agent (e.g., claude)
    focus: true
  - split: horizontal # Second pane with default shell

Project configuration example

.workmux.yaml:

post_create:
  - '<global>'
  - mise use

files:
  symlink:
    - '<global>' # Include global symlinks (node_modules)
    - .pnpm-store # Add project-specific symlink

panes:
  - command: pnpm install
    focus: true
  - command: <agent>
    split: horizontal
  - command: pnpm run dev
    split: vertical

For a real-world example, see workmux's own .workmux.yaml.

Configuration options

Most options have sensible defaults. You only need to configure what you want to customize.

Basic options

Option	Description	Default
`main_branch`	Branch to merge into	Auto-detected
`base_branch`	Default base ref for new worktrees, or `auto` for the effective main branch	Current branch
`worktree_dir`	Directory for worktrees (absolute or relative). Supports `~` and `{project}`.	`<project>__worktrees/`
`window_prefix`	Prefix for tmux window/session names	`wm-`
`mode`	Tmux mode (`window` or `session`)	`window`
`window_placement`	New tmux window placement (`after_current` or `rightmost`)	`after_current`
`agent`	Default agent for `<agent>` placeholder	`claude`
`agents`	Named agent commands (docs, global-only)	`{}`
`merge_strategy`	Default merge strategy (`merge`, `rebase`, `squash`)	`merge`
`merge_keep`	Keep resources after `workmux merge` by default	`false`
`theme`	Dashboard color scheme (custom colors)	`default` (auto dark/light)

Set base_branch: auto to create independent work streams from each repository's effective main branch. Workmux uses configured main_branch, then the local origin/HEAD, main, or master. Detection uses local Git state and does not fetch. Omitting base_branch continues to create branches from the checked-out branch.

Naming options

Option	Description	Default
`worktree_naming`	How to derive names from branches	`full`
`worktree_prefix`	Prefix for worktree directories and windows	none

worktree_naming strategies:

full: Use the full branch name (slashes become dashes)
basename: Use only the part after the last / (e.g., prj-123/feature → feature)

Panes

Define your multiplexer pane layout with the panes array. For multiple windows in session mode, use windows instead (they are mutually exclusive).

panes:
  - command: <agent>
    name: agent
    focus: true
  - command: npm run dev
    name: dev
    split: horizontal
    size: 15

Each pane supports:

Option	Description	Default
`name`	Pane display name (currently applied by the Zellij backend)	—
`command`	Command to run (see agent placeholders)	Shell
`focus`	Whether this pane receives focus	`false`
`zoom`	Zoom pane to fullscreen (implies `focus: true`)	`false`
`split`	Split direction (`horizontal` or `vertical`)	—
`size`	Absolute size in lines/cells	50%
`percentage`	Size as percentage (1-100)	50%

Agent placeholders

<agent>: resolves to the configured agent (from agent config or --agent flag)

Built-in agents (claude, gemini, agy, codex, opencode, kiro-cli, vibe, pi, omp) are auto-detected when used as literal commands and receive prompt injection automatically, without needing the <agent> placeholder or a matching agent config:

panes:
  - command: 'claude --dangerously-skip-permissions'
    focus: true
  - command: 'codex --yolo'
    split: vertical

Each agent receives the prompt (via -p/-P/-e) using the correct format for that agent. Auto-detection matches the executable name regardless of flags or path.

Antigravity CLI support covers command detection, prompt injection, and status tracking via lifecycle hooks installed by workmux setup.

Named layouts

Define reusable pane arrangements in the layouts map and select one at add-time with -l/--layout:

layouts:
  design:
    panes:
      - command: <agent>
        focus: true
      - command: <agent:codex>
        split: vertical
  review:
    panes:
      - command: <agent>

workmux add my-feature -l design

When -l is used, the layout's panes replace the top-level panes for that worktree. All other config (hooks, files, agent, etc.) comes from the top-level as usual. The -l flag cannot be combined with --agent.

File operations

New worktrees are clean checkouts with no gitignored files (.env, node_modules, etc.). Use files to automatically copy or symlink what each worktree needs:

files:
  copy:
    - .env
  symlink:
    - .next/cache # Share build cache across worktrees

Both copy and symlink accept glob patterns.

To re-apply file operations to an existing worktree (e.g., after updating the config), run workmux sync-files from inside the worktree. Use --all to sync all worktrees at once.

Lifecycle hooks

Run commands at specific points in the worktree lifecycle, such as installing dependencies or running database migrations. All hooks run with the worktree directory as the working directory (or the nested config directory for nested configs) and receive environment variables: WM_HANDLE, WM_WORKTREE_PATH, WM_PROJECT_ROOT, WM_CONFIG_DIR.

WM_CONFIG_DIR points to the directory containing the .workmux.yaml that was used, which may differ from WM_WORKTREE_PATH when using nested configs.

Hook	When it runs	Additional env vars
`post_create`	After worktree creation, before tmux window opens	—
`pre_merge`	Before merging (aborts on failure)	`WM_BRANCH_NAME`, `WM_TARGET_BRANCH`
`pre_remove`	Before worktree removal (aborts on failure)	—

Example:

post_create:
  - direnv allow

pre_merge:
  - just check

Agent status icons

Customize the icons shown in tmux window names:

status_icons:
  working: '🤖' # Agent is processing
  waiting: '💬' # Agent needs input (auto-clears on focus)
  done: '✅' # Agent finished (auto-clears on focus)

Agents in "working" status that produce no pane output for 10 seconds are automatically detected as interrupted.

Set status_format: false to disable automatic tmux format modification

Default behavior

Worktrees are created in <project>__worktrees as a sibling directory to your project by default
If no panes configuration is defined, workmux provides opinionated defaults:
- For projects with a CLAUDE.md file: Opens the configured agent (see agent option) in the first pane, defaulting to claude if none is set.
- For all other projects: Opens your default shell.
- Both configurations include a second pane split horizontally
post_create commands are optional and only run if you configure them

Automatic setup with panes

Use the panes configuration to automate environment setup. Unlike post_create hooks which must finish before the tmux window opens, pane commands execute immediately within the new window.

This can be used for:

Installing dependencies: Run npm install or cargo build in a focused pane to monitor progress.
Starting services: Launch dev servers, database containers, or file watchers automatically.
Running agents: Initialize AI agents with specific context.

Since these run in standard tmux panes, you can interact with them (check logs, restart servers) just like a normal terminal session.

Running dependency installation (like pnpm install) in a pane command rather than post_create has a key advantage: you get immediate access to the tmux window while installation runs in the background. With post_create, you'd have to wait for the install to complete before the window even opens. This also means AI agents can start working immediately in their pane while dependencies install in parallel.

panes:
  # Pane 1: Install dependencies, then start dev server
  - command: pnpm install && pnpm run dev

  # Pane 2: AI agent
  - command: <agent>
    split: horizontal
    focus: true

Directory structure

Here's how workmux organizes your worktrees by default:

~/projects/
├── my-project/               <-- Main project directory
│   ├── src/
│   ├── package.json
│   └── .workmux.yaml
│
└── my-project__worktrees/    <-- Worktrees created by workmux
    ├── feature-A/            <-- Isolated workspace for 'feature-A' branch
    │   ├── src/
    │   └── package.json
    │
    └── bugfix-B/             <-- Isolated workspace for 'bugfix-B' branch
        ├── src/
        └── package.json

Each worktree is a separate working directory for a different branch, all sharing the same git repository. This allows you to work on multiple branches simultaneously without conflicts.

You can customize the worktree directory location using the worktree_dir configuration option (see Configuration options). The value supports ~ for the home directory and a {project} placeholder that resolves to the main worktree's directory name. This lets a single global config namespace every repo's worktrees under one root, e.g. worktree_dir: ~/.workmux/{project}.

Shell alias (recommended)

For faster typing, alias workmux to wm:

alias wm='workmux'

Commands

add - Create a new worktree and tmux window
merge - Merge a branch and clean up everything
rebase - Rebase a worktree branch onto its base branch
remove - Remove worktrees without merging
list - List all worktrees with status
open - Open a tmux window for an existing worktree
close - Close a worktree's tmux window (keeps worktree)
resurrect - Restore worktree windows after a crash
path - Get the filesystem path of a worktree
dashboard - Show TUI dashboard of all active agents
sidebar - Toggle a compact agent status sidebar in tmux
reap-agents - Exit tracked agent processes older than a threshold
config edit - Edit the global configuration file
init - Generate configuration file
sandbox - Manage sandbox backends (container/Lima)
claude prune - Clean up stale Claude Code entries
completions - Generate shell completions
docs - Show detailed documentation

`workmux add <branch-name>`

Creates a new git worktree with a matching tmux window and switches you to it immediately. If the branch doesn't exist, it will be created automatically.

<branch-name>: Name of the branch to create or switch to, a remote branch reference (e.g., origin/feature-branch), or a GitHub fork reference (e.g., user:branch). Remote and fork references are automatically fetched and create a local branch with the derived name. Fork references derive the local branch as user-branch (e.g., someuser:feature creates local branch someuser-feature). Optional when using --pr.

Options

--base <branch|commit|tag>: Specify a base branch, commit, or tag to branch from when creating a new branch. Overrides base_branch config. The config value auto uses the effective main branch. Without either setting, workmux uses the currently checked out branch.
--pr <number|url>: Checkout a GitHub pull request by its number or full URL into a new worktree.
- Requires the gh command-line tool to be installed and authenticated.
- URLs use the form https://github.com/<owner>/<repository>/pull/<number>.
- The local branch name defaults to the PR's head branch name, but can be overridden (e.g., workmux add custom-name --pr 123).
- If that local branch already exists and has no worktree, it is reused.
-A, --auto-name: Generate branch name from prompt using LLM. See Automatic branch name generation.
--name <name>: Override the worktree directory and tmux window name. By default, these are derived from the branch name (slugified). Cannot be used with multi-worktree generation (--count, --foreach, or multiple --agent).
-b, --background: Create the tmux window in the background without switching to it. Useful with --prompt-editor.
-w, --with-changes: Move uncommitted changes from the current worktree to the new worktree, then reset the original worktree to a clean state. Useful when you've started working on main and want to move your branches to a new worktree.
--patch: Interactively select which changes to move (requires --with-changes). Opens an interactive prompt for selecting hunks to stash.
-u, --include-untracked: Also move untracked files (requires --with-changes). By default, only staged and modified tracked files are moved.
-p, --prompt <text>: Provide an inline prompt that will be automatically passed to AI agent panes.
-P, --prompt-file <path>: Provide a path to a file whose contents will be used as the prompt.
-e, --prompt-editor: Open your $EDITOR (or $VISUAL) to write the prompt interactively.
--prompt-file-only: Write the prompt file to the worktree without injecting it into agent commands. No agent pane is required. Useful when your editor has an embedded agent that reads .workmux/PROMPT-*.md directly.
-l, --layout <name>: Use a named pane layout from config instead of the default panes. Cannot be combined with --agent.
-a, --agent <name>: The agent(s) to use for the worktree(s). Can be specified multiple times to generate a worktree for each agent. Overrides the agent from your config file.
-W, --wait: Block until the created tmux window is closed. Useful for scripting when you want to wait for an agent to complete its work. The agent can signal completion by running workmux remove --keep-branch.
-o, --open-if-exists: If a worktree for the branch already exists, open it instead of failing. Similar to tmux new-session -A. Useful when you don't know or care whether the worktree already exists.
-s, --session: Create a tmux session instead of a window. See Session mode for details.
--dry-run: Print the resolved worktree path, branch, base, multiplexer target, file operations, and post-create hooks without creating or modifying anything.
--config <path>: Use an alternate config file for this invocation. Still merges with global config.
--fork: Fork the last conversation from the current worktree into the new one. The agent resumes with the forked conversation context. Use --fork=<session-id> to fork a specific session (prefix matching supported). Currently supports Claude Code.

Skip options

These options allow you to skip expensive setup steps when they're not needed (e.g., for documentation-only changes):

-H, --no-hooks: Skip running post_create commands
-F, --no-file-ops: Skip file copy/symlink operations (e.g., skip linking node_modules)
-C, --no-pane-cmds: Skip executing pane commands (panes open with plain shells instead)

What happens

Determines the handle for the worktree by slugifying the branch name (e.g., feature/auth becomes feature-auth). This can be overridden with the --name flag.
Creates a git worktree at <worktree_dir>/<handle> (the worktree_dir is configurable and defaults to a sibling directory of your project)
Runs any configured file operations (copy/symlink)
Executes post_create commands if defined (runs before the tmux window opens, so keep them fast)
Creates a new tmux window named <window_prefix><handle> (e.g., wm-feature-auth with window_prefix: wm-)
Sets up your configured tmux pane layout
Automatically switches your tmux client to the new window

In tmux window mode without --parent-session, $TMUX_PANE identifies the calling pane and its parent session. When $TMUX_PANE is absent or stale, workmux uses live pane working directories when their closest matches identify one session. A tmux server with one session is the final fallback. Remaining ambiguity requires --parent-session <name>. The working directory selects the Git repository and only provides conservative evidence for tmux placement.

Examples

Basic usage

# Create a new branch and worktree
workmux add user-auth

# Use an existing branch
workmux add existing-work

# Create a new branch from a specific base
workmux add hotfix --base production

# Create a worktree from a remote branch (creates local branch "user-auth-pr")
workmux add origin/user-auth-pr

# Remote branches with slashes work too (creates local branch "feature/foo")
workmux add origin/feature/foo

# Preview the resolved plan without creating anything
workmux add feature/parallel-task --dry-run

# Create a worktree in the background without switching to it
workmux add feature/parallel-task --background

# Use a custom name for the worktree directory and tmux window
workmux add feature/long-descriptive-branch-name --name short

# Open existing worktree if it exists, create if it doesn't (idempotent)
workmux add my-feature -o

Checking out pull requests and fork branches

# Checkout PR #123. The local branch will be named after the PR's branch.
workmux add --pr 123

# Checkout a pull request from its full GitHub URL with a custom local branch
workmux add --pr https://github.com/raine/workmux/pull/456 fix/api-bug

# Checkout a fork branch using GitHub's owner:branch format (copy from GitHub UI)
# Creates local branch "someuser-feature-branch" tracking the fork
workmux add someuser:feature-branch

Moving changes to a new worktree

# Move uncommitted changes to a new worktree (including untracked files)
workmux add feature/new-thing --with-changes -u

# Move only staged/modified files (not untracked files)
workmux add fix/bug --with-changes

# Interactively select which changes to move
workmux add feature/partial --with-changes --patch

AI agent prompts

# Create a worktree with an inline prompt for AI agents
workmux add feature/ai --prompt "Implement user authentication with OAuth"

# Override the default agent for a specific worktree
workmux add feature/testing -a gemini

# Create a worktree with a prompt from a file
workmux add feature/refactor --prompt-file task-description.md

# Open your editor to write a prompt interactively
workmux add feature/new-api --prompt-editor

# Write prompt file only (for editors with embedded agents like neovim)
workmux add feature/task -P task.md --prompt-file-only

Skipping setup steps

# Skip expensive setup for documentation-only changes
workmux add docs-update --no-hooks --no-file-ops --no-pane-cmds

# Skip just the file operations (e.g., you don't need node_modules)
workmux add quick-fix --no-file-ops

Scripting with --wait

# Block until the agent completes and closes the window
workmux add feature/api --wait -p "Implement the REST API, then run: workmux remove --keep-branch"

# Use in a script to run sequential agent tasks
for task in task1.md task2.md task3.md; do
  workmux add "task-$(basename $task .md)" --wait -P "$task"
done

AI agent integration

When you provide a prompt via --prompt, --prompt-file, or --prompt-editor, workmux automatically injects the prompt into panes running the configured agent command (e.g., claude, codex, opencode, gemini, agy, kiro-cli, vibe, pi, omp, or whatever you've set via the agent config or --agent flag) without requiring any .workmux.yaml changes:

Panes with a command matching the configured agent are automatically started with the given prompt.
You can keep your .workmux.yaml pane configuration simple (e.g., panes: [{ command: "<agent>" }]) and let workmux handle prompt injection at runtime.

This means you can launch AI agents with task-specific prompts without modifying your project configuration for each task.

If your editor has an embedded agent (e.g., neovim with an agent plugin), use --prompt-file-only to write the prompt to .workmux/PROMPT-<branch>.md without requiring an agent pane. Your editor can then detect and consume the file on startup. This can also be set permanently in config with prompt_file_only: true.

Automatic branch name generation

The --auto-name (-A) flag generates a branch name from your prompt using an LLM. The tool used depends on your configuration:

auto_name.command is set: uses that command as-is
config.agent is a known agent (claude, gemini, agy, codex, opencode, kiro-cli, vibe, pi, omp): uses the agent's CLI with a fast/cheap model
Neither: falls back to the llm CLI tool

Usage

# Opens editor for prompt, generates branch name
workmux add -A

# With inline prompt
workmux add -A -p "Add OAuth authentication"

# With prompt file
workmux add -A -P task-spec.md

Requirements

When agent is configured (e.g., agent: claude), workmux automatically uses that agent's CLI for branch naming. No additional setup is required beyond having the agent installed.

If no agent is configured and no auto_name.command is set, workmux uses the llm CLI tool:

pipx install llm

Configure a model (e.g., OpenAI):

llm keys set openai
# Or use a local model
llm install llm-ollama

If you set auto_name.command, llm is not required.

Agent profile defaults

When an agent is configured, these commands are used automatically:

Agent	Auto-name command
`claude`	`claude --model haiku -p`
`gemini`	`gemini -m gemini-2.5-flash-lite -p`
`codex`	`codex exec --config model_reasoning_effort="low" -m gpt-5.1-codex-mini`
`opencode`	`opencode run`
`kiro-cli`	`kiro-cli chat --no-interactive`
`pi`	`pi -p`
`omp`	`omp -p`

To override back to llm when an agent is configured, set auto_name.command: "llm".

Configuration

Optionally configure auto-name behavior in .workmux.yaml:

auto_name:
  model: 'gemini-2.5-flash-lite'
  background: true # Always run in background when using --auto-name
  system_prompt: |
    Generate a concise git branch name based on the task description.

    Rules:
    - Use kebab-case (lowercase with hyphens)
    - Keep it short: 1-3 words, max 4 if necessary
    - Focus on the core task/feature, not implementation details
    - No prefixes like feat/, fix/, chore/

    Examples of good branch names:
    - "Add dark mode toggle" → dark-mode
    - "Fix the search results not showing" → fix-search
    - "Refactor the authentication module" → auth-refactor
    - "Add CSV export to reports" → export-csv
    - "Shell completion is broken" → shell-completion

    Output ONLY the branch name, nothing else.

To use a specific tool, set auto_name.command. The command string is split into program and arguments, and the composed prompt is piped via stdin. Valid Git branch names are preserved, including slash-separated prefixes such as fix/issue-123.

auto_name:
  command: 'claude -p'

# Force llm even when an agent is configured
auto_name:
  command: 'llm'

Option	Description	Default
`command`	Command for branch name generation (overrides agent profile)	Agent profile or `llm` CLI
`model`	LLM model to use with the `llm` CLI (ignored when `command` set)	`llm`'s default
`background`	Always run in background when using `--auto-name`	`false`
`system_prompt`	Custom system prompt for branch name generation	Built-in prompt

Recommended models for fast, cheap branch name generation (with llm):

gemini-2.5-flash-lite (recommended)
gpt-5-nano

Parallel workflows & multi-worktree generation

workmux can generate multiple worktrees from a single add command, which is ideal for running parallel experiments or delegating tasks to multiple AI agents. This is controlled by four mutually exclusive modes:

(-a, --agent): Create a worktree for each specified agent.
(-n, --count): Create a specific number of worktrees.
(--foreach): Create worktrees based on a matrix of variables.
stdin: Pipe input lines to create worktrees with templated prompts.

When using any of these modes, branch names are generated from a template, and prompts are templated with variables. Single-worktree prompts are passed through literally, so common syntax like GitHub Actions ${{ ... }} does not need to be escaped.

Multi-worktree options

-a, --agent <name>: When used multiple times, creates one worktree for each agent.
-n, --count <number>: Creates <number> worktree instances. Can be combined with a single --agent flag to apply that agent to all instances.
--foreach <matrix>: Creates worktrees from a variable matrix string. The format is "var1:valA,valB;var2:valX,valY". All value lists must have the same length. Values are paired by index position (zip, not Cartesian product): the first value of each variable goes together, the second with the second, etc.
--branch-template <template>: A MiniJinja (Jinja2-compatible) template for generating branch names.
- Available variables: {{ base_name }}, {{ agent }}, {{ num }}, {{ index }}, {{ input }} (stdin), and any variables from --foreach.
- Default: {{ base_name }}{% if agent %}-{{ agent | slugify }}{% endif %}{% for key, value in foreach_vars %}-{{ value | slugify }}{% endfor %}{% if num %}-{{ num }}{% endif %}
--max-concurrent <number>: Limits how many worktrees run simultaneously. When set, workmux creates up to <number> worktrees, then waits for any window to close before starting the next. Requires agents to close windows when done (e.g., via prompt instruction to run workmux remove --keep-branch).

Prompt templating

When generating multiple worktrees, any prompt provided via -p, -P, or -e is treated as a MiniJinja template. You can use variables from your generation mode to create unique prompts for each agent or instance. For ordinary single-worktree add commands, prompt text is not templated.

Variable matrices in prompt files

Instead of passing --foreach on the command line, you can specify the variable matrix directly in your prompt file using YAML frontmatter. This is more convenient for complex matrices and keeps the variables close to the prompt that uses them.

Format:

Create a prompt file with YAML frontmatter at the top, separated by ---:

Example 1: mobile-task.md

---
foreach:
  platform: [iOS, Android]
  lang: [swift, kotlin]
---

Build a {{ platform }} app using {{ lang }}. Implement user authentication and
data persistence.

workmux add mobile-app --prompt-file mobile-task.md
# Generates worktrees: mobile-app-ios-swift, mobile-app-android-kotlin

Example 2: agent-task.md (using agent as a foreach variable)

---
foreach:
  agent: [claude, gemini]
---

Implement the dashboard refactor using your preferred approach.

workmux add refactor --prompt-file agent-task.md
# Generates worktrees: refactor-claude, refactor-gemini

Behavior:

Variables from the frontmatter are available in both the prompt template and the branch name template
All value lists must have the same length, and values are paired by index position (same zip behavior as --foreach)
CLI --foreach overrides frontmatter with a warning if both are present
Works with both --prompt-file and --prompt-editor

Stdin input

You can pipe input lines to workmux add to create multiple worktrees. Each line becomes available as the {{ input }} template variable in your prompt. This is useful for batch-processing tasks from external sources.

Plain text: Each line becomes {{ input }}

echo -e "api\nauth\ndatabase" | workmux add refactor -P task.md
# {{ input }} = "api", "auth", "database"

JSON lines: Each key becomes a template variable

gh repo list --json url,name --jq -c '.[]' | workmux add analyze \
  --branch-template '{{ base_name }}-{{ name }}' \
  -P prompt.md
# Line: {"url":"https://github.com/raine/workmux","name":"workmux"}
# Variables: {{ url }}, {{ name }}, {{ input }} (raw JSON line)

This lets you structure data upstream with jq and use meaningful branch names while keeping the full URL available in your prompt.

Behavior:

Empty lines and whitespace-only lines are filtered out
Stdin input cannot be combined with --foreach (mutually exclusive)
JSON objects (lines starting with {) are parsed and each key becomes a variable
{{ input }} always contains the raw line
If JSON contains an input key, it overwrites the raw line value

Examples

# Create one worktree for claude and one for gemini with a focused prompt
workmux add my-feature -a claude -a gemini -p "Implement the new search API integration"
# Generates worktrees: my-feature-claude, my-feature-gemini

# Create 2 instances of the default agent
workmux add my-feature -n 2 -p "Implement task #{{ num }} in TASKS.md"
# Generates worktrees: my-feature-1, my-feature-2

# Create worktrees from a variable matrix
workmux add my-feature --foreach "platform:iOS,Android" -p "Build for {{ platform }}"
# Generates worktrees: my-feature-ios, my-feature-android

# Create agent-specific worktrees via --foreach
workmux add my-feature --foreach "agent:claude,gemini" -p "Implement the dashboard refactor"
# Generates worktrees: my-feature-claude, my-feature-gemini

# Use frontmatter in a prompt file for cleaner syntax
# task.md contains:
# ---
# foreach:
#   env: [staging, production]
#   task: [smoke-tests, integration-tests]
# ---
# Run {{ task }} against the {{ env }} environment
workmux add testing --prompt-file task.md
# Generates worktrees: testing-staging-smoke-tests, testing-production-integration-tests

# Pipe input from stdin to create worktrees
# review.md contains: Review the {{ input }} module for security issues.
echo -e "auth\npayments\napi" | workmux add review -A -P review.md
# Generates worktrees with LLM-generated branch names for each module

Recipe: Batch processing with worker pools

Combine stdin input, prompt templating, and concurrency limits to create a worker pool that processes items from an external command.

Example: Generate test scaffolding for untested files

# generate-tests.md contains:
# Read the file at {{ input }} and generate a test suite covering
# the exported functions. Focus on happy path and edge cases.
# When done, run: workmux remove --keep-branch

find src/utils -name "*.ts" ! -name "*.test.ts" | \
  workmux add add-tests \
    --branch-template '{{ base_name }}-{{ index }}' \
    --prompt-file generate-tests.md \
    --max-concurrent 3 \
    --background

find ... lists files without tests (one per line) piped to stdin
--branch-template uses {{ index }} for unique branch names
--prompt-file uses {{ input }} to pass each file path to the agent
--max-concurrent 3 limits parallel agents to avoid rate limits
--background runs without switching focus

`workmux merge [branch-name]`

Merges a branch into a target branch (main by default) and automatically cleans up all associated resources (worktree, tmux window, and local branch).

Tip

merge vs remove: Use merge when you want to merge directly without a pull request. If your workflow uses pull requests, use remove to clean up after your PR is merged on the remote.

[branch-name]: Optional name of the branch to merge. If omitted, automatically detects the current branch from the worktree you're in.

Options

--into <branch>: Merge into the specified branch instead of the main branch. Useful for stacked PRs, git-flow workflows, or merging subtasks into a parent feature branch. If the target branch has its own worktree, the merge happens there; otherwise, the main worktree is used.
--ignore-uncommitted: Commit any staged changes before merging without opening an editor
--keep, -k: Keep the worktree, window, and branch after merging (skip cleanup). Useful when you want to verify the merge before cleaning up.
--cleanup: Clean up after merging, overriding merge_keep: true.
--notification: Show a system notification on successful merge. Useful when delegating merge to an AI agent and you want to be notified when it completes.

Merge strategies

By default, workmux merge performs a standard merge commit (configurable via merge_strategy). You can override the configured behavior with these mutually exclusive flags:

--rebase: Rebase the feature branch onto the target before merging (creates a linear history via fast-forward merge). If conflicts occur, you'll need to resolve them manually in the worktree and run git rebase --continue.
--squash: Squash all commits from the feature branch into a single commit on the target. You'll be prompted to provide a commit message in your editor.

If you don't want to have merge commits in your main branch, use the rebase merge strategy, which does --rebase by default.

# ~/.config/workmux/config.yaml
merge_strategy: rebase

To keep the worktree, window, and branch after every merge unless overridden, set:

merge_keep: true

Use workmux merge --cleanup to clean up for a single merge when this default is enabled.

What happens

Determines which branch to merge (specified branch or current branch if omitted)
Determines the target branch (--into or main branch from config)
Checks for uncommitted changes (errors if found, unless --ignore-uncommitted is used)
Commits staged changes if present (unless --ignore-uncommitted is used)
Merges your branch into the target using the selected strategy (default: merge commit)
Deletes the tmux window unless keep behavior is enabled via --keep or merge_keep: true
Removes the worktree unless keep behavior is enabled via --keep or merge_keep: true
Deletes the local branch unless keep behavior is enabled via --keep or merge_keep: true

Typical workflow

When you're done working in a worktree, simply run workmux merge from within that worktree's tmux window. The command will automatically detect which branch you're on, merge it into main, and close the current window as part of cleanup.

Examples

# Merge branch into main (default: merge commit)
workmux merge user-auth

# Merge the current worktree you're in
# (run this from within the worktree's tmux window)
workmux merge

# Rebase onto main before merging for a linear history
workmux merge user-auth --rebase

# Squash all commits into a single commit
workmux merge user-auth --squash

# Merge but keep the worktree/window/branch to verify before cleanup
workmux merge user-auth --keep
# ... verify the merge in main ...
workmux remove user-auth  # clean up later when ready

# Merge into a different branch (stacked PRs)
workmux merge feature/subtask --into feature/parent

`workmux rebase [name]`

Rebases a worktree branch onto its saved base branch. If the branch does not have a saved local base branch, workmux rebases onto the configured main branch.

[name]: Optional worktree name or branch. If omitted, workmux detects the current worktree from the current directory.

What happens

Determines which worktree branch to rebase
Reads the saved base branch recorded when the worktree was created
Falls back to the configured main branch when the saved base is not a local branch
Runs git rebase <base> inside the worktree
Leaves the worktree, window, and branch in place

Examples

workmux rebase user-auth
workmux rebase

`workmux remove [name]...` (alias: `rm`)

Removes worktrees, tmux windows, and branches without merging (unless you keep the branches). Useful for abandoning work or cleaning up experimental branches. Supports removing multiple worktrees in a single command.

[name]...: One or more worktree names (the directory names). Defaults to current directory name if omitted.

Options

--all: Remove all worktrees at once (except the main worktree). Prompts for confirmation unless --force is used. Safely skips worktrees with uncommitted changes or unmerged commits.
--gone: Remove worktrees whose upstream remote branch has been deleted (e.g., after a PR is merged on GitHub). Automatically runs git fetch --prune first.
--force, -f: Skip confirmation prompt and ignore uncommitted changes
--keep-branch, -k: Remove only the worktree and tmux window while keeping the local branch

Examples

# Remove the current worktree (run from within the worktree)
workmux remove

# Remove a specific worktree with confirmation if unmerged
workmux remove experiment

# Remove multiple worktrees at once
workmux rm feature-a feature-b feature-c

# Remove multiple worktrees with force (no confirmation)
workmux rm -f old-work stale-branch

# Use the alias
workmux rm old-work

# Remove worktree/window but keep the branch
workmux remove --keep-branch experiment

# Force remove without prompts
workmux rm -f experiment

# Remove worktrees whose remote branches were deleted (e.g., after PR merge)
workmux rm --gone

# Force remove all gone worktrees (no confirmation)
workmux rm --gone -f

# Remove all worktrees at once
workmux rm --all

`workmux rename [old-name] <new-name>`

Renames a worktree's directory, its tmux window or session, and the per-worktree workmux metadata. Optionally also renames the underlying git branch.

[old-name]: Optional current worktree name. Defaults to the current worktree when run from inside one.
<new-name>: The new handle (directory name and tmux window/session base name).

Options

--branch, -b: Also rename the underlying git branch to match <new-name>. Fails if the worktree is on a detached HEAD.

Examples

# Rename a worktree from inside it
workmux rename feature-new

# Rename a specific worktree by name
workmux rename feature-old feature-new

# Also rename the branch to match
workmux rename feature-old feature-new --branch

Rename is non-destructive: uncommitted changes and untracked files are preserved. The main worktree cannot be renamed. Collisions (existing target path, existing tmux target, or existing branch) are rejected before any changes are made.

`workmux list` (alias: `ls`)

Lists all git worktrees with their agent status, multiplexer window status, and merge status. Supports filtering by worktree handle or branch name.

Arguments

[worktree-or-branch...]: Filter by worktree handle (directory name) or branch name. Accepts multiple values. When omitted, shows all worktrees.

Options

--pr: Show GitHub PR status for each worktree. Requires the gh CLI to be installed and authenticated. Note that it shows pull requests' statuses with Nerd Font icons, which requires Nerd Font compatible font installed.
--json: Output as JSON. Produces a JSON array of objects with fields: handle, branch, path, is_main, mode, has_uncommitted_changes, is_open, created_at.

Examples

# List all worktrees
workmux list

# List with PR status
workmux list --pr

# Output as JSON for scripting
workmux list --json

# Filter to specific worktrees
workmux list my-feature
workmux list feature-auth feature-api

Example output

BRANCH      AGE  AGENT  MUX  UNMERGED  PATH
main        -    -      -    -         ~/project
user-auth   2h   🤖     ✓    -         ~/project__worktrees/user-auth
bug-fix     3d   ✅     ✓    ●         ~/project__worktrees/bug-fix
api-work    1w   -      ✓    -         ~/project__worktrees/api-work

Key

AGE shows how old the worktree is (e.g., 2h, 3d, 1w, 2mo)
AGENT shows the current agent status (see status tracking):
- 🤖 = working, 💬 = waiting for input, ✅ = finished
- Multiple agents per worktree show a count (e.g., 2🤖 1✅)
✓ in MUX column = multiplexer window exists for this worktree
● in UNMERGED column = branch has commits not merged into main
- = not applicable

`workmux status [worktree...]`

Queries tracked agents in the current repository or in explicitly requested worktrees. Use project:handle to target a worktree in another project.

--json: Emit an observation object containing the selected multiplexer context, repository and target scope, state-file counts, the reconciled agent count before scope filtering, and the scoped agents array.
--git: Include staged, unstaged, and unmerged commit information.

Automation must check the command exit status before interpreting an empty agents array. See the status command reference for the JSON contract and fail-closed rules.

`workmux config edit`

Opens the global configuration file (~/.config/workmux/config.yaml) in your preferred editor. Uses $VISUAL, $EDITOR, or falls back to vi. Creates the file with commented-out defaults if it doesn't exist yet.

`workmux config path`

Prints the path to the global configuration file. Useful for scripting.

`workmux config reference`

Prints the default configuration file with all options documented. Useful for discovering available options or piping to an AI agent for context.

`workmux init`

Generates .workmux.yaml with example configuration and "<global>" placeholder usage.

`workmux open [name...]`

Opens or switches to a tmux window for a pre-existing git worktree. If the window already exists, switches to it. If not, creates a new window with the configured pane layout and environment. Accepts multiple names to open several worktrees at once.

[name...]: One or more worktree names (the directory name, which is also the tmux window name without the prefix). Optional with --new when run from inside a worktree.

Options

-n, --new: Force opening in a new window even if one already exists. Creates a duplicate window with a suffix (e.g., -2, -3). Useful for having multiple terminal views into the same worktree. In tmux, the duplicate appears immediately to the right of the window identified by $TMUX_PANE.
-s, --session: Open in session mode, overriding the stored mode. Persists the mode change for subsequent opens. Cannot be combined with --new. Only supported with tmux.
--config <path>: Use an alternate config file for this invocation. Still merges with global config.
--run-hooks: Re-runs the post_create commands (these block window creation).
--force-files: Re-applies file copy/symlink operations. Useful for restoring a deleted .env file.
-p, --prompt <text>: Provide an inline prompt for AI agent panes.
-P, --prompt-file <path>: Provide a path to a file containing the prompt.
-c, --continue: Resume the agent's most recent conversation in this worktree. Injects the appropriate flag for the configured agent (e.g., --continue for Claude, --resume for Gemini).
-e, --prompt-editor: Open your editor to write the prompt interactively.
--prompt-file-only: Write the prompt file without injecting it into agent commands.

What happens

Verifies that a worktree with <name> exists.
If a tmux window exists and --new is not set, switches to it.
Otherwise, creates a new tmux window (with suffix if duplicating). In tmux, duplicate windows appear immediately to the right of the window where the command runs.
(If specified) Runs file operations and post_create hooks.
Sets up your configured tmux pane layout.
Automatically switches your tmux client to the new window.

Examples

# Open or switch to a window for an existing worktree
workmux open user-auth

# Force open a second window for the same worktree (creates user-auth-2)
workmux open user-auth --new

# Open a new window for the current worktree (run from within the worktree)
workmux open --new

# Open in session mode (converts from window mode if needed)
workmux open user-auth --session

# Resume the agent's last conversation
workmux open user-auth --continue

# Resume and send a follow-up prompt
workmux open user-auth --continue -p "Continue implementing the login flow"

# Open and re-run dependency installation
workmux open user-auth --run-hooks

# Open and restore configuration files
workmux open user-auth --force-files

# Open multiple worktrees at once
workmux open user-auth api-refactor bugfix-login

`workmux close [name]`

Closes the tmux window for a worktree without removing the worktree or branch. This is useful when you want to temporarily close a window to reduce clutter or free resources, but plan to return to the work later.

[name]: Optional worktree name (the directory name). Defaults to current directory if omitted.

Examples

# Close the window for a specific worktree
workmux close user-auth

# Close the current worktree's window (run from within the worktree)
workmux close

To reopen the window later, use workmux open.

Tip: You can also use tmux's native kill-window command (default: prefix + &) to close a worktree's window with the same effect.

`workmux resurrect`

Restores worktree windows after a tmux or computer crash. Uses persisted agent state files to detect which worktrees had active agents before the crash, then reopens them with --continue to resume agent conversations.

Options

--dry-run: Show what would be restored without doing it.

Examples

# See what would be restored after a crash
workmux resurrect --dry-run

# Restore all worktrees that had agents running
workmux resurrect

How it works

Reads agent state files from ~/.local/state/workmux/agents/
Matches each state file's working directory to a git worktree in the current repo
Skips worktrees that are already open or no longer exist
Opens each matched worktree with --continue to resume the agent

`workmux sync-files`

Re-applies file operations (copy and symlink from files config) to existing worktrees. Useful when you add new entries to the files config or a symlink was accidentally deleted.

Options

--all: Sync all worktrees instead of just the current one.

Examples

# Sync files to the current worktree
workmux sync-files

# Sync files to all worktrees
workmux sync-files --all

`workmux path <name>`

Prints the filesystem path of an existing worktree. Useful for scripting or quickly navigating to a worktree directory.

<name>: Worktree name (the directory name).

Examples

# Get the path of a worktree
workmux path user-auth
# Output: /Users/you/project__worktrees/user-auth

# Use in scripts or with cd
cd "$(workmux path user-auth)"

# Copy a file to a worktree
cp config.json "$(workmux path feature-branch)/"

`workmux dashboard`

Opens a TUI dashboard showing all active AI agents across all tmux sessions. Useful for monitoring multiple parallel agents and quickly jumping between them.

Options

-d, --diff: Open the diff view directly for the current worktree. Useful when you want to quickly review uncommitted changes without navigating through the agent list.
-P, --preview-size <10-90>: Set preview pane size as percentage (larger = more preview, less table). Default: 60.
-s, --session: Filter to only show agents in the current session. Useful for session-per-project workflows where each session maps to a different repository.
-t, --tab <agents|worktrees>: Open directly on the specified tab.

Important

This feature requires agent status tracking to be configured. Without it, no agents will appear in the dashboard.

Keybindings

Key	Action
`1`-`9`	Quick jump to agent (closes dashboard)
`Tab`	Toggle between current and last agent
`d`	View diff (opens WIP view)
`o`	Open PR in browser
`p`	Peek at agent (dashboard stays open)
`s`	Cycle sort mode
`/`	Filter agents by name
`F`	Toggle session filter
`f`	Toggle stale filter (show/hide stale)
`i`	Enter input mode (type to agent)
`Ctrl+u`	Scroll preview up
`Ctrl+d`	Scroll preview down
`+`/`-`	Resize preview pane
`Enter`	Go to selected agent (closes dashboard)
`j`/`k`	Navigate up/down
`:`	Open command palette
`q`/`Esc`	Quit

Mouse controls

The dashboard captures mouse input while it is open. Click the Agents and Worktrees tabs to switch views, click a table row to select it, and double-click a row to jump to its agent or worktree. Right-click a row to open its action menu, then click an action or use j/k and Enter. Click a footer command to run it. Use the mouse wheel over a table to change the selection without wrapping, or over the live preview to scroll its output.

In diff view, use the wheel to scroll and click a file in the sidebar to jump to its diff. Visible diff and patch footer commands are clickable. Mouse capture is released when the dashboard exits.

Live preview

The bottom half shows a live preview of the selected agent's terminal output. The preview auto-scrolls to show the latest output, but you can scroll through history with Ctrl+u/Ctrl+d. Press i to enter input mode and type directly to the agent without leaving the dashboard.

Columns

#: Quick jump key (1-9)
Project: Project name (from __worktrees path or directory name)
Agent: Worktree/window name
Git: Diff stats showing branch changes (dim) and uncommitted changes (bright). Shows a rebase icon when a rebase is in progress.
Status: Agent status icon (🤖 working, 💬 waiting, ✅ done, or "stale")
Time: Time since last status change
Title: Claude Code session title (auto-generated summary)

Sort modes

Press s to cycle through sort modes:

Priority (default): Waiting > Done > Working > Stale
Project: Group by project name, then by priority within each project
Recency: Most recently updated first
Natural: Original tmux order (by pane creation)

Your sort preference persists in the tmux session.

Session filter

Press F to toggle the session filter. When active, only agents in the current session are shown. This is useful for session-per-project workflows where each session maps to a repository. You can also start the dashboard with --session to default to session filtering. The preference persists across sessions.

Name filter

Press / to activate the name filter. Type to filter the agent list by project or worktree name (case-insensitive). Press Enter to accept the filter and return to normal navigation, or Esc to clear the filter. When a filter is active, it is shown in the footer bar.

Stale filter

Press f to toggle between showing all agents or hiding stale ones. The filter state persists across dashboard sessions within the same tmux server.

Diff view

Press d to view the diff for the selected agent. The diff view has two modes:

WIP - Shows uncommitted changes (git diff HEAD)
review - Shows all changes on the branch vs main (git diff main...HEAD)

Press Tab to toggle between modes. The footer displays which mode is active along with diff statistics showing lines added (+) and removed (-).

Key	Action
`Tab`	Toggle WIP / review
`a`	Enter patch mode (WIP only)
`j`/`k`	Scroll down/up
`Ctrl+d`	Page down
`Ctrl+u`	Page up
`c`	Send commit command to agent
`m`	Trigger merge and exit dashboard
`:`	Open command palette
`q`/`Esc`	Close diff view

Patch mode

Patch mode (a from WIP diff) allows staging individual hunks like git add -p. This is useful for selectively staging parts of an agent's work.

When delta is installed, hunks are rendered with syntax highlighting for better readability.

Key	Action
`y`	Stage current hunk
`n`	Skip current hunk
`u`	Undo last staged hunk
`s`	Split hunk (if splittable)
`o`	Comment on hunk (sends to agent)
`j`/`k`	Navigate to next/previous hunk
`:`	Open command palette
`q`/`Esc`	Exit patch mode

Press y to stage the current hunk and advance to the next. Press n to skip without staging. The counter in the header shows your progress (e.g., [3/10]).

Press s to split the current hunk into smaller pieces when there are context lines between separate changes. Press u to undo the last staged hunk.

Press o to comment on the current hunk. This sends a message to the agent including the file path, line number, the diff hunk as context, and your comment. Useful for giving feedback like "This function should handle the error case".

Example tmux binding

Add to your ~/.tmux.conf for quick access:

bind C-s display-popup -h 30 -w 100 -E "workmux dashboard"

# Open directly on Worktrees tab
bind C-w display-popup -h 30 -w 100 -E "workmux dashboard --tab worktrees"

Then press prefix + Ctrl-s to open the dashboard as a tmux popup.

`workmux sidebar`

Toggles a live agent status sidebar on the left or top edge of all tmux windows. By default, each sidebar pane shows active agents across all tmux sessions with live status updates, providing an always-visible overview without taking over the full screen like the dashboard. Use workmux sidebar filter session to show only agents in the current tmux session.

workmux sidebar                 # Toggle sidebar on/off (all sessions)
workmux sidebar --session       # Toggle current session only, or opt out of global mode
workmux sidebar --position top  # Override configured placement for this toggle

The sidebar displays:

Status icon (working/waiting/done with spinner animation)
Project and worktree name (e.g. myproject/fix-bug)
Elapsed time since last status change

Key	Action
`j`/`k`	Navigate up/down
`Enter`	Jump to agent
`g`/`G`	Jump to first/last
`v`	Toggle layout mode
`f`	Toggle session filter
`q`	Open quit confirmation

With tmux mouse mode enabled (set -g mouse on), click an agent row or top-bar chip to jump to its pane, or scroll to navigate the list.

When the global sidebar is active, workmux sidebar --session hides it in the current tmux session only. Run the same command again to show it in that session again while keeping the global sidebar active elsewhere.

Configure placement, width, and layout in .workmux.yaml:

sidebar:
  position: left # "left" (default) or "top"
  width: 40 # left width in columns, or "15%" for percentage
  layout: tiles # left only: "compact" or "tiles" (default)

The left sidebar defaults to 10% of terminal width, clamped between 25 and 50 columns. Widths above 80 columns use the default width so tmux pane expansion recovers automatically.

Use workmux sidebar --position top or --position left to override the configured placement when enabling the sidebar.

Example tmux binding

bind C-t run-shell "workmux sidebar"

Then press prefix + Ctrl-t to toggle the sidebar.

Note: The sidebar is currently tmux-only. When enabled, a sidebar pane is created in every existing window, and new windows automatically get one via a tmux hook.

`workmux reap-agents`

Shows tracked agent processes whose last state update is older than a threshold. By default this is a dry run, though it still reconciles workmux state while checking live panes.

workmux reap-agents
workmux reap-agents --hours 48
workmux reap-agents --hours 24 --force

Use --force to interrupt matching agents and remove their workmux agent state after they exit.

`workmux sandbox`

Commands for managing sandbox functionality. See the sandbox guide for full documentation.

Command	Description
`sandbox pull`	Pull the latest container image from the registry
`sandbox build`	Build the container image locally
`sandbox shell`	Start an interactive shell inside a sandbox
`sandbox agent`	Run the configured agent in a sandbox with RPC support
`sandbox stop`	Stop running Lima VMs
`sandbox prune`	Delete unused Lima VMs to reclaim disk space
`sandbox install-dev`	Cross-compile and install workmux into sandboxes (dev)

`workmux claude prune`

Removes stale entries from Claude config (~/.claude.json) that point to deleted worktree directories. When you run Claude Code in worktrees, it stores per-worktree settings in that file. Over time, as worktrees are merged or deleted, it can accumulate entries for paths that no longer exist.

What happens

Scans ~/.claude.json for entries pointing to non-existent directories
Creates a backup at ~/.claude.json.bak before making changes
Removes all stale entries
Reports the number of entries cleaned up

Safety

Only removes entries for absolute paths that don't exist
Creates a backup before modifying the file
Preserves all valid entries and relative paths

Examples

# Clean up stale Claude Code entries
workmux claude prune

Example output

  - Removing: /Users/user/project__worktrees/old-feature

✓ Created backup at ~/.claude.json.bak
✓ Removed 3 stale entries from ~/.claude.json

`workmux completions <shell>`

Generates shell completion script for the specified shell. Completions provide tab-completion for commands and dynamic branch name suggestions.

<shell>: Shell type: bash, zsh, or fish.

Examples

# Generate completions for zsh
workmux completions zsh

See the Shell Completions section for installation instructions.

`workmux docs`

Displays this README with terminal formatting. Useful for quick reference without leaving the terminal.

When run interactively, renders markdown with colors and uses a pager (less). When piped (e.g., to an LLM), outputs raw markdown for clean context.

Using with AI agents

You can ask an agent to read the docs and configure workmux for you:

> run `workmux docs` and configure workmux so that on the left pane
  there is claude as agent, and on the right side neovim and empty
  shell on top of each other

⏺ Bash(workmux docs)
  ⎿  <p align="center">
       <picture>
     … +923 lines

⏺ Write(.workmux.yaml)
  ⎿  Wrote 9 lines to .workmux.yaml

⏺ Created .workmux.yaml with the layout:
  - Left: claude agent (focused)
  - Right top: neovim
  - Right bottom: empty shell

Agent status tracking

Workmux can display the status of the agent in your tmux window list, giving you at-a-glance visibility into what the agent in each window doing.

Key

🤖 = agent is working
💬 = agent is waiting for user input
✅ = agent finished (auto-clears on window focus)

Agent	Status
Claude Code	✅ Supported
OpenCode	✅ Supported
Codex	✅ Supported
Copilot CLI	✅ Supported*
Pi	✅ Supported*
Oh My Pi	✅ Supported
Gemini CLI	✅ Supported
Antigravity CLI (`agy`)	✅ Supported*
Kiro	Tracking issue
Mistral Vibe	Tracking issue

Notes:

Copilot CLI: No 💬 waiting state
Pi: No 💬 waiting state
Antigravity CLI (agy): No 💬 waiting state
Kiro: Hooks support is messy: requires a custom agent since the default can't be edited

Setup

Run workmux setup to automatically detect Claude Code, Antigravity CLI, Copilot CLI, OpenCode, Pi, Oh My Pi, and other supported agent CLIs, install status tracking hooks, and install skills:

workmux setup

You can also run specific parts: workmux setup --hooks or workmux setup --skills. For Claude Code, CLAUDE_CONFIG_DIR is respected for both hook and skill installation.

Workmux will also prompt you on first run if it detects an agent without status tracking or skills configured.

Workmux automatically modifies your tmux window-status-format to display the status icons. This happens once per session and only affects the current tmux session (not your global config).

Manual setup

If you prefer manual setup:

Claude Code: install the workmux status plugin:

claude plugin marketplace add raine/workmux
claude plugin install workmux-status

Or manually add the hooks to ~/.claude/settings.json. See .claude-plugin/plugin.json for the hook configuration.

Copilot CLI: copy the hooks to your repository:

mkdir -p .github/hooks/workmux-status
curl -o .github/hooks/workmux-status/hooks.json \
  https://raw.githubusercontent.com/raine/workmux/main/.github/hooks/workmux-status/hooks.json

Note: Copilot hooks are per-repository. The waiting state is not supported due to limitations in the Copilot CLI hooks implementation.

Antigravity CLI (agy): workmux setup installs lifecycle hooks in ~/.gemini/config/hooks.json. PreInvocation marks the pane working, and the terminal Stop event marks it done.

OpenCode: download the workmux status plugin:

mkdir -p ~/.config/opencode/plugins
curl -o ~/.config/opencode/package.json \
  https://raw.githubusercontent.com/raine/workmux/main/resources/opencode/package.json
curl -o ~/.config/opencode/plugins/workmux-status.ts \
  https://raw.githubusercontent.com/raine/workmux/main/resources/opencode/plugins/workmux-status.ts

Restart OpenCode for the plugin to take effect.

Oh My Pi: copy the workmux status extension to your global OMP extensions directory:

mkdir -p ~/.omp/agent/extensions
curl -o ~/.omp/agent/extensions/workmux-status.ts \
  https://raw.githubusercontent.com/raine/workmux/main/.omp/extensions/workmux-status.ts

Restart omp for the extension to take effect.

Customization

You can customize the icons in your config:

# ~/.config/workmux/config.yaml
status_icons:
  working: '🔄'
  waiting: '⏸️'
  done: '✔️'

If you prefer to manage the tmux format yourself, disable auto-modification and add the status variable to your ~/.tmux.conf:

# ~/.config/workmux/config.yaml
status_format: false

# ~/.tmux.conf
set -g window-status-format '#I:#W#{?@workmux_status, #{@workmux_status},}#{?window_flags,#{window_flags}, }'
set -g window-status-current-format '#I:#W#{?@workmux_status, #{@workmux_status},}#{?window_flags,#{window_flags}, }'

Jump to completed or waiting agents

Use workmux last-done to quickly switch to the agent that most recently finished its task or is waiting for user input. Repeated invocations cycle through all completed and waiting agents in reverse chronological order.

Add a tmux keybinding for quick access:

# ~/.tmux.conf
bind-key L run-shell "workmux last-done"

Then press prefix + L to jump to the last completed or waiting agent, press again to cycle to the next oldest, and so on.

Toggle between agents

Use workmux last-agent to toggle between your current agent and the last one you visited. This works like vim's Ctrl+^ or tmux's last-window - it remembers which agent you came from and switches back to it. Pressing it again returns you to where you were.

This is available both as a CLI command and as the Tab key in the dashboard.

Add a tmux keybinding for quick access:

# ~/.tmux.conf
bind Tab run-shell "workmux last-agent"

Then press prefix + Tab to toggle between your two most recent agents.

Sandbox

workmux can run agents inside containers (Docker/Podman/Apple Container) or Lima VMs, isolating them from your host. Agents are restricted to the project worktree; sensitive files like SSH keys, AWS credentials, and other secrets are not accessible. This lets you run agents with --dangerously-skip-permissions without worrying about what they might touch on your host.

Sandboxing is transparent: status indicators, the dashboard, spawning new agents, and merging all continue to work normally across the sandbox boundary.

Backends

	Container (Docker/Podman/Apple Container)	Lima VM
Isolation	Process/VM-level	Machine-level (virtual machine)
Persistence	Ephemeral (new container per session)	Persistent (stateful VMs)
Toolchain	Custom Dockerfile or host command proxying	Built-in Nix & Devbox support
Network	Optional restrictions (domain allowlist)	Unrestricted

Container is a good default: simple to set up and ephemeral, so no state accumulates between sessions. Choose Lima if you want persistent VMs with built-in Nix/Devbox toolchain support.

Quick start

# ~/.config/workmux/config.yaml or .workmux.yaml
sandbox:
  enabled: true
  # backend: lima  # uncomment for Lima VMs (default: container)

The pre-built container image is pulled automatically on first run. For Lima, the VM is created and provisioned on first use.

Shared features

Both backends support:

Host command proxying: Run specific commands (build tools, linters) on the host from inside the sandbox via host_commands config
Extra mounts: Mount additional host directories into the sandbox (read-only by default)
Git identity: Your user.name and user.email are automatically injected so git commits work without exposing your full ~/.gitconfig
Credential sharing: Agent credentials are shared between host and sandbox
Network restrictions (container only): Block outbound connections except to approved domains

See the sandbox guide for full setup, configuration, and security details.

Session mode

By default, workmux creates tmux windows within your current session. With session mode, each worktree gets its own tmux session instead. This allows each worktree to have multiple windows.

Enabling session mode

Add to your config:

# ~/.config/workmux/config.yaml or .workmux.yaml
mode: session

Or use the --session flag:

workmux add feature-branch --session

How it works

Persistence: The mode is stored per-worktree. If you create a worktree with --session, subsequent open/close/remove commands automatically use session mode for that worktree.
Navigation: After merge or remove, workmux switches you back to the previous session.

Multiple windows per session

Use the windows config to launch multiple windows in each session. Each window can have its own pane layout. This is mutually exclusive with the top-level panes config.

mode: session
windows:
  - name: editor
    panes:
      - command: <agent>
        focus: true
      - split: horizontal
        size: 20
  - name: tests
    panes:
      - command: just test --watch
  - panes:
      - command: tail -f app.log

Each window supports:

Option	Description	Default
`name`	Window name (if omitted, tmux auto-names from command)	Auto
`panes`	Pane layout (same syntax as top-level `panes`)	Single shell

focus: true works across windows: the last pane with focus set determines which window is selected when the session opens.

Limitations

tmux only: Session mode is currently only supported for the tmux backend.
No duplicates: Unlike window mode which supports opening multiple windows for the same worktree (-2, -3 suffixes), session mode creates one session per worktree.

Workflow example

Here's a complete workflow:

# Start a new feature
workmux add user-auth

# Work on your feature...
# (tmux automatically sets up your configured panes and environment)

# When ready, merge and clean up
workmux merge user-auth

# Start another feature
workmux add api-endpoint

# List all active worktrees
workmux list

Before and after

workmux turns a multi-step manual workflow into simple commands, making parallel development workflows practical.

Without workmux

# 1. Manually create the worktree and environment
git worktree add ../worktrees/user-auth -b user-auth
cd ../worktrees/user-auth
cp ../../project/.env.example .env
ln -s ../../project/node_modules .
npm install
# ... and other setup steps

# 2. Manually create and configure the tmux window
tmux new-window -n user-auth
tmux split-window -h 'npm run dev'
tmux send-keys -t 0 'claude' C-m
# ... repeat for every pane in your desired layout

# 3. When done, manually merge and clean everything up
cd ../../project
git switch main && git pull
git merge --no-ff user-auth
tmux kill-window -t user-auth
git worktree remove ../worktrees/user-auth
git branch -d user-auth

With workmux

# Create the environment
workmux add user-auth

# ... work on the feature ...

# Merge and clean up
workmux merge

The parallel AI workflow

Run multiple AI agents simultaneously, each in its own worktree.

# Spin up two agents working on different tasks
workmux add refactor-user-model -p "Refactor the User model to use composition"
workmux add add-search-endpoint -p "Add a /search endpoint with pagination"

# Each agent works in isolation. Check progress via tmux windows or the dashboard
workmux dashboard

# Merge completed work back to main
workmux merge refactor-user-model
workmux merge add-search-endpoint

Tip

Use -A (--auto-name) to generate branch names automatically from your prompt, so you don't have to think of one. See Automatic branch name generation.

Why git worktrees?

Git worktrees let you have multiple branches checked out at once in the same repository, each in a separate directory. This provides two main advantages over a standard single-directory setup:

Painless context switching: Switch between tasks just by changing directories (cd ../other-branch). There's no need to git stash or make temporary commits. Your work-in-progress, editor state, and command history remain isolated and intact for each branch.
True parallel development: Work on multiple branches simultaneously without interference. You can run builds, install dependencies (npm install), or run tests in one worktree while actively coding in another. This isolation is perfect for running multiple AI agents in parallel on different tasks.

In a standard Git setup, switching branches disrupts your flow by requiring a clean working tree. Worktrees remove this friction. workmux automates the entire process and pairs each worktree with a dedicated tmux window, creating fully isolated development environments. See Before and after for how workmux streamlines this workflow.

Git worktree caveats

While powerful, git worktrees have nuances that are important to understand. workmux is designed to automate solutions to these, but awareness of the underlying mechanics helps.

Gitignored files require configuration

When git worktree add creates a new working directory, it's a clean checkout. Files listed in your .gitignore (e.g., .env files, node_modules, IDE configuration) will not exist in the new worktree by default. Your application will be broken in the new worktree until you manually create or link these necessary files.

This is a primary feature of workmux. Use the files section in your .workmux.yaml to automatically copy or symlink these files on creation:

# .workmux.yaml
files:
  copy:
    - .env # Copy environment variables
  symlink:
    - .next/cache # Share Next.js build cache

Note: Symlinking node_modules can be efficient but only works if all worktrees share identical dependencies. If different branches have different dependency versions, each worktree needs its own installation. For dependency installation, consider using a pane command instead of post_create hooks - this runs the install in the background without blocking the worktree and window creation:

panes:
  - command: npm install
    focus: true
  - split: horizontal

Conflicts

Worktrees isolate your filesystem, but they do not prevent merge conflicts. If you modify the area of code on two different branches (in two different worktrees), you will still have a conflict when you merge one into the other.

The best practice is to work on logically separate features in parallel worktrees. When conflicts are unavoidable, use standard git tools to resolve them. You can also leverage an AI agent within the worktree to assist with the conflict resolution.

Package manager considerations (pnpm, yarn)

Modern package managers like pnpm use a global store with symlinks to node_modules. Each worktree typically needs its own pnpm install to set up the correct dependency versions for that branch.

If your worktrees always have identical dependencies (e.g., working on multiple features from the same base), you could potentially symlink node_modules between worktrees. However, this breaks as soon as branches diverge in their dependencies, so it's generally safer to run a fresh install in each worktree.

Note: In large monorepos, cleaning up node_modules during worktree removal can take significant time. workmux has a special cleanup mechanism that moves node_modules to a temporary location and deletes it in the background, making the remove command return almost instantly.

Rust projects

Unlike node_modules, Rust's target/ directory should not be symlinked between worktrees. Cargo locks the target directory during builds, so sharing it would block parallel builds and defeat the purpose of worktrees.

Instead, use sccache to share compiled dependencies across worktrees:

brew install sccache

Add to ~/.cargo/config.toml:

[build]
rustc-wrapper = "sccache"

This caches compiled dependencies globally, so new worktrees benefit from cached artifacts without any lock contention.

Port conflicts in monorepos

When running multiple services (API, web app, database) in a monorepo, each worktree needs unique ports to avoid conflicts. For example, if your .env has hardcoded ports like API_PORT=3001 and VITE_PORT=3000, running two worktrees simultaneously would fail because both would try to bind to the same ports. Simply copying .env files won't work since all worktrees would use the same ports.

Solution: Use a post_create hook to generate a .env.local file with unique ports. Many frameworks (Vite, Next.js, CRA) automatically load .env.local and merge it with .env, with .env.local taking precedence. For plain Node.js, use multiple --env-file flags where later files override earlier ones.

Create a script at scripts/worktree-env:

#!/usr/bin/env bash
set -euo pipefail

port_in_use() {
  lsof -nP -iTCP:"$1" -sTCP:LISTEN &>/dev/null
}

find_port() {
  local port=$1
  while port_in_use "$port"; do
    ((port++))
  done
  echo "$port"
}

# Hash the handle to get a deterministic port offset (0-99)
hash=$(echo -n "$WM_HANDLE" | md5 | cut -c1-4)
offset=$((16#$hash % 100))

# Find available ports starting from the hash-based offset
api_port=$(find_port $((3001 + offset * 10)))
vite_port=$(find_port $((3000 + offset * 10)))

# Generate .env.local with port overrides
cat >.env.local <<EOF
API_PORT=$api_port
VITE_PORT=$vite_port
VITE_PUBLIC_API_URL=http://localhost:$api_port
EOF

echo "Created .env.local with ports: API=$api_port, VITE=$vite_port"

Configure workmux to copy .env and generate .env.local:

# .workmux.yaml
files:
  copy:
    - .env # Copy secrets (DATABASE_URL, API keys, etc.)

post_create:
  - ./scripts/worktree-env # Generate .env.local with unique ports

For plain Node.js (without framework support), load both files with later overriding earlier:

{
  "scripts": {
    "api": "node --env-file=.env --env-file=.env.local api/server.js",
    "web": "node --env-file=.env --env-file=.env.local web/server.js"
  }
}

Each worktree now gets unique ports derived from its name, allowing multiple instances to run simultaneously without conflicts. The .env file stays untouched, and .env.local is gitignored.

See the Monorepos guide for alternative approaches using direnv.

Symlinks and `.gitignore` trailing slashes

If your .gitignore uses a trailing slash to ignore directories (e.g., tests/venv/), symlinks to that path in the created worktree will not be ignored and will show up in git status. This is because venv/ only matches directories, not files (symlinks).

To ignore both directories and symlinks, remove the trailing slash:

- tests/venv/
+ tests/venv

Tips

Nerdfont icons

On first run, workmux prompts you to check if a git branch icon displays correctly. If you have a Nerd Font installed, answer yes to enable nerdfont icons throughout the interface, including the tmux window prefix.

To change the setting later, edit ~/.config/workmux/config.yaml:

nerdfont: true # or false for unicode fallbacks

Using direnv

If your project uses direnv for environment management, you can configure workmux to automatically set it up in new worktrees:

# .workmux.yaml
post_create:
  - direnv allow

files:
  symlink:
    - .envrc

Claude Code permissions

By default, Claude Code prompts for permission before running commands. There are several ways to handle this in worktrees:

Share permissions across worktrees

To keep permission prompts but share granted permissions across worktrees:

files:
  symlink:
    - .claude/settings.local.json

Add this to your global config (~/.config/workmux/config.yaml) or project's .workmux.yaml. Since this file contains user-specific permissions, also add it to .gitignore:

.claude/settings.local.json

Named agent profiles

Define named agents in your global config when an agent needs a wrapper command, extra arguments, or environment variables. Simple string aliases still work:

# ~/.config/workmux/config.yaml
agents:
  cc-work: "claude"
  cc-personal: "env CLAUDE_CONFIG_DIR=~/.claude-personal claude"
  cc-bedrock: "env -u CLAUDE_CODE_USE_BEDROCK -u AWS_REGION AWS_PROFILE=prod claude"
  cc-yolo: "claude --dangerously-skip-permissions"
  cod: "codex --yolo"

Structured profiles make the same kind of config easier to maintain because arguments and environment are not written as one long shell string:

# ~/.config/workmux/config.yaml
agents:
  cc-personal:
    type: claude
    command: claude
    env:
      CLAUDE_CONFIG_DIR: ~/.claude-personal
      ANTHROPIC_AUTH_TOKEN:
        from_env: ANTHROPIC_AUTH_TOKEN
  cod-mini:
    type: codex
    command: codex
    args:
      - exec
      - -m
      - gpt-5.1-codex-mini

To skip prompts entirely, define a named agent with the Claude skip-permissions flag:

# ~/.config/workmux/config.yaml
agents:
  cc-yolo:
    type: claude
    command: claude
    args:
      - --dangerously-skip-permissions

Reference a named profile per project with agent: cc-yolo, pass it with -a cc-yolo, or use it directly in a pane with <agent:cc-yolo>. Structured profiles support command, args, env, and type fields.

Delegating tasks with `/worktree`

The /worktree skill lets you delegate tasks to parallel worktree agents directly from your conversation. A main agent on the main branch can act as a coordinator: planning work and spinning up worktree agents for each task.

📝 See this blog post for a detailed walkthrough of the workflow.

Usage

> /worktree Implement user authentication
> /worktree Fix the race condition in handler.go
> /worktree Add dark mode, Implement caching  # multiple tasks

See the Skills guide for more skills including /merge, /rebase, /coordinator, and /open-pr.

Shell completions

To enable tab completions for commands and branch names, add the following to your shell's configuration file.

For bash, add to your .bashrc:

eval "$(workmux completions bash)"

For zsh, add to your .zshrc:

eval "$(workmux completions zsh)"

For fish, add to your config.fish:

workmux completions fish | source

Requirements

Rust (for building)
Git 2.5+ (for worktree support)
tmux (or an alternative backend)

Alternative backends

While tmux is the primary and recommended backend, workmux also supports alternative terminal multiplexers:

WezTerm (experimental) - For users who prefer WezTerm's features. Thanks to @JeremyBYU for contributing this backend.
kitty (experimental) - For users who prefer kitty terminal. Requires allow_remote_control and listen_on configuration.
Zellij (experimental) - For users who prefer Zellij. Detected automatically via $ZELLIJ.

workmux auto-detects the backend from environment variables ($TMUX, $WEZTERM_PANE, $KITTY_WINDOW_ID, or $ZELLIJ). Session-specific variables are checked first, so running tmux inside kitty correctly selects the tmux backend. Set $WORKMUX_BACKEND to override detection.

Inspiration and related tools

workmux is inspired by wtp, an excellent git worktree management tool. While wtp streamlines worktree creation and setup, workmux takes this further by tightly coupling worktrees with tmux window management.

For managing multiple AI agents in parallel, tools like claude-squad and vibe-kanban offer dedicated interfaces, like a TUI or kanban board. In contrast, workmux adheres to its philosophy that tmux is the interface, providing a native tmux experience for managing parallel workflows without requiring a separate interface to learn.

Contributing

Bug reports and feature suggestions are always welcome via issues or discussions. Large and/or complex PRs, especially without prior discussion, may not get merged. Thanks for contributing!

See CONTRIBUTING.md for development setup.

Related projects

tmux-tools — Collection of tmux utilities including file picker, smart sessions, and more
tmux-file-picker — Pop up fzf in tmux to quickly insert file paths, perfect for AI coding assistants
tmux-bro — Smart tmux session manager that sets up project-specific sessions automatically
git-surgeon — Non-interactive hunk-level git staging for AI agents
claude-history — Search and view Claude Code conversation history with fzf
consult-llm — Consult other AI models from your agent workflow
tmux-agent-usage — Display AI agent rate limit usage in your tmux status bar

jdx/mise

dev tools, env vars, task runner

mise-en-place

Dev tools, env vars, and tasks in one CLI

Getting Started • Documentation • Dev Tools • Environments • Tasks

Sponsored by entire.io and 37signals.
View all sponsors.

Tip

My latest project, aube just hit stable! It's the fastest Node.js package manager with strong security defaults and is compatible with npm/pnpm/yarn lockfiles!

What is it?

mise prepares your development environment before each command runs. It keeps project tools, environment variables, and tasks in one mise.toml file so new shells, checkouts, and CI jobs all start from the same setup.

Install and switch between dev tools like node, python, cmake, terraform, and hundreds more.
Load environment variables per project directory, including values from .env files and other sources.
Define and run tasks for building, testing, linting, and deploying projects.

Demo

The following demo shows how to install and use mise to manage multiple versions of node on the same system. Note that calling which node gives us a real path to node, not a shim.

It also shows that you can use mise to install and many other tools such as jq, terraform, or go.

See demo transcript.

Quickstart

Install mise

See Getting started for more options.

$ curl https://mise.run | sh
$ ~/.local/bin/mise --version
              _                                        __
   ____ ___  (_)_______        ___  ____        ____  / /___ _________
  / __ `__ \/ / ___/ _ \______/ _ \/ __ \______/ __ \/ / __ `/ ___/ _ \
 / / / / / / (__  )  __/_____/  __/ / / /_____/ /_/ / / /_/ / /__/  __/
/_/ /_/ /_/_/____/\___/      \___/_/ /_/     / .___/_/\__,_/\___/\___/
                                            /_/                 by @jdx
2026.8.3 macos-arm64 (2026-08-07)

Hook mise into your shell (pick the right one for your shell):

# note this assumes mise is located at ~/.local/bin/mise
# which is what https://mise.run does by default
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc
echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc
echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish
echo '~/.local/bin/mise activate pwsh | Out-String | Invoke-Expression' >> ~/.config/powershell/Microsoft.PowerShell_profile.ps1

Execute commands with specific tools

$ mise exec node@26 -- node -v
mise node@26.x.x ✓ installed
v26.x.x

Install tools

$ mise use --global node@26 go@1
$ node -v
v26.x.x
$ go version
go version go1.x.x macos/arm64

See dev tools for more examples.

Manage environment variables

# mise.toml
[env]
SOME_VAR = "foo"

$ mise set SOME_VAR=bar
$ echo $SOME_VAR
bar

Note that mise can also load .env files.

Run tasks

# mise.toml
[tasks.build]
description = "build the project"
run = "echo building..."

$ mise run build
building...

See tasks for more information.

Example mise project

Here is a combined example to give you an idea of how you can use mise to manage your a project's tools, environment, and tasks.

# mise.toml
[tools]
terraform = "1"
aws-cli = "2"

[env]
TF_WORKSPACE = "development"
AWS_REGION = "us-west-2"
AWS_PROFILE = "dev"

[tasks.plan]
description = "Run terraform plan with configured workspace"
run = """
terraform init
terraform workspace select $TF_WORKSPACE
terraform plan
"""

[tasks.validate]
description = "Validate AWS credentials and terraform config"
run = """
aws sts get-caller-identity
terraform validate
"""

[tasks.deploy]
description = "Deploy infrastructure after validation"
depends = ["validate", "plan"]
run = "terraform apply -auto-approve"

Run it with:

mise install # install tools specified in mise.toml
mise run deploy

Find more examples in the mise cookbook.

Full Documentation

See mise.jdx.dev

GitHub Issues & Discussions

Due to the volume of issue submissions mise received, using GitHub Issues became unsustainable for the project. Instead, mise uses GitHub Discussions which provide a more community-centric platform for communication and require less management on the part of the maintainers.

Please note the following discussion categories, which match how issues are often used:

Announcements
Ideas: for feature requests, etc.
Troubleshooting & Bug Reports

Special Thanks

Thanks to Namespace for providing CI services for mise.

Contributors

rustdesk/rustdesk

An open-source remote desktop application designed for self-hosting, as an alternative to TeamViewer.

Caution

Misuse Disclaimer:
The developers of RustDesk do not condone or support any unethical or illegal use of this software. Misuse, such as unauthorized access, control or invasion of privacy, is strictly against our guidelines. The authors are not responsible for any misuse of the application.

Chat with us: Discord | Twitter | Reddit | YouTube

Yet another remote desktop solution, written in Rust. Works out of the box with no configuration required. You have full control of your data, with no concerns about security. You can use our rendezvous/relay server, set up your own, or write your own rendezvous/relay server.

RustDesk welcomes contribution from everyone. See CONTRIBUTING.md for help getting started.

FAQ

BINARY DOWNLOAD

NIGHTLY BUILD

Dependencies

Desktop versions use Flutter or Sciter (deprecated) for GUI. This tutorial is for Sciter only, since it is easier and more friendly to start. Check out our CI for building the Flutter version.

Please download Sciter dynamic library yourself.

Windows | Linux | macOS

Raw Steps to build

Prepare your Rust development env and C++ build env
Install vcpkg, and set VCPKG_ROOT env variable correctly
- Windows: vcpkg install libvpx:x64-windows-static libyuv:x64-windows-static opus:x64-windows-static aom:x64-windows-static
- Linux/macOS: vcpkg install libvpx libyuv opus aom
run cargo run

Build

How to Build on Linux

Ubuntu 18 (Debian 10)

sudo apt install -y zip g++ gcc git curl wget nasm yasm libgtk-3-dev clang libxcb-randr0-dev libxdo-dev \
        libxfixes-dev libxcb-shape0-dev libxcb-xfixes0-dev libasound2-dev libpulse-dev cmake make \
        libclang-dev ninja-build libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libpam0g-dev

openSUSE Tumbleweed

sudo zypper install gcc-c++ git curl wget nasm yasm gcc gtk3-devel clang libxcb-devel libXfixes-devel cmake alsa-lib-devel gstreamer-devel gstreamer-plugins-base-devel xdotool-devel pam-devel

Fedora 28 (CentOS 8)

sudo yum -y install gcc-c++ git curl wget nasm yasm gcc gtk3-devel clang libxcb-devel libxdo-devel libXfixes-devel pulseaudio-libs-devel cmake alsa-lib-devel gstreamer1-devel gstreamer1-plugins-base-devel pam-devel

Arch (Manjaro)

sudo pacman -Syu --needed unzip git cmake gcc curl wget yasm nasm zip make pkg-config clang gtk3 xdotool libxcb libxfixes alsa-lib pipewire

Install vcpkg

git clone https://github.com/microsoft/vcpkg
cd vcpkg
git checkout 2023.04.15
cd ..
vcpkg/bootstrap-vcpkg.sh
export VCPKG_ROOT=$HOME/vcpkg
vcpkg/vcpkg install libvpx libyuv opus aom

Fix libvpx (For Fedora)

cd vcpkg/buildtrees/libvpx/src
cd *
./configure
sed -i 's/CFLAGS+=-I/CFLAGS+=-fPIC -I/g' Makefile
sed -i 's/CXXFLAGS+=-I/CXXFLAGS+=-fPIC -I/g' Makefile
make
cp libvpx.a $HOME/vcpkg/installed/x64-linux/lib/
cd

Build

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
git clone --recurse-submodules https://github.com/rustdesk/rustdesk
cd rustdesk
mkdir -p target/debug
wget https://raw.githubusercontent.com/c-smile/sciter-sdk/master/bin.lnx/x64/libsciter-gtk.so
mv libsciter-gtk.so target/debug
VCPKG_ROOT=$HOME/vcpkg cargo run

How to build with Docker

Begin by cloning the repository and building the Docker container:

git clone https://github.com/rustdesk/rustdesk
cd rustdesk
git submodule update --init --recursive
docker build -t "rustdesk-builder" .

Then, each time you need to build the application, run the following command:

docker run --rm -it -v $PWD:/home/user/rustdesk -v rustdesk-git-cache:/home/user/.cargo/git -v rustdesk-registry-cache:/home/user/.cargo/registry -e PUID="$(id -u)" -e PGID="$(id -g)" rustdesk-builder

Note that the first build may take longer before dependencies are cached, subsequent builds will be faster. Additionally, if you need to specify different arguments to the build command, you may do so at the end of the command in the <OPTIONAL-ARGS> position. For instance, if you wanted to build an optimized release version, you would run the command above followed by --release. The resulting executable will be available in the target folder on your system, and can be run with:

target/debug/rustdesk

Or, if you're running a release executable:

target/release/rustdesk

Please ensure that you run these commands from the root of the RustDesk repository, or the application may not find the required resources. Also note that other cargo subcommands such as install or run are not currently supported via this method as they would install or run the program inside the container instead of the host.

File Structure

libs/hbb_common: video codec, config, tcp/udp wrapper, protobuf, fs functions for file transfer, and some other utility functions
libs/scrap: screen capture
libs/enigo: platform specific keyboard/mouse control
libs/clipboard: file copy and paste implementation for Windows, Linux, macOS.
src/ui: obsolete Sciter UI (deprecated)
src/server: audio/clipboard/input/video services, and network connections
src/client.rs: start a peer connection
src/rendezvous_mediator.rs: Communicate with rustdesk-server, wait for remote direct (TCP hole punching) or relayed connection
src/platform: platform specific code
flutter: Flutter code for desktop and mobile
flutter/web/js: JavaScript for Flutter web client

Screenshots

DioxusLabs/dioxus

Fullstack app framework for web, desktop, and mobile.

Website | Examples | Tutorial | 中文 | PT-BR | 日本語 | Türkçe | 한국어

Build for web, desktop, and mobile, and more with a single codebase. Zero-config setup, integrated hot-reloading, and signals-based state management. Add backend functionality with Server Functions and bundle with our CLI.

fn app() -> Element {
    let mut count = use_signal(|| 0);

    rsx! {
        h1 { "High-Five counter: {count}" }
        button { onclick: move |_| count += 1, "Up high!" }
        button { onclick: move |_| count -= 1, "Down low!" }
    }
}

⭐️ Unique features:

Cross-platform apps in three lines of code (web, desktop, mobile, server, and more)
Ergonomic state management combines the best of React, Solid, and Svelte
Built-in featureful, type-safe, fullstack web framework
Integrated bundler for deploying to the web, macOS, Linux, and Windows
Subsecond Rust hot-patching and asset hot-reloading
And more! Take a tour of Dioxus.

Instant hot-reloading

With one command, dx serve and your app is running. Edit your markup, styles, and see changes in milliseconds. Use our experimental dx serve --hotpatch to update Rust code in real time.

Build Beautiful Apps

Dioxus apps are styled with HTML and CSS. Use the built-in TailwindCSS support or load your favorite CSS library. Easily call into native code (objective-c, JNI, Web-Sys) for a perfect native touch.

Truly fullstack applications

Dioxus deeply integrates with axum to provide powerful fullstack capabilities for both clients and servers. Pick from a wide array of built-in batteries like WebSockets, SSE, Streaming, File Upload/Download, Server-Side-Rendering, Forms, Middleware, and Hot-Reload, or go fully custom and integrate your existing axum backend.

Experimental Native Renderer

Render using web-sys, webview, server-side-rendering, liveview, or even with our experimental WGPU-based renderer. Embed Dioxus in Bevy, WGPU, or even run on embedded Linux!

First-party primitive components

Get started quickly with a complete set of primitives modeled after shadcn/ui and Radix-Primitives.

First-class Android and iOS support

Dioxus is the fastest way to build native mobile apps with Rust. Simply run dx serve --platform android and your app is running in an emulator or on device in seconds. Call directly into JNI and Native APIs.

Bundle for web, desktop, and mobile

Simply run dx bundle and your app will be built and bundled with maximization optimizations. On the web, take advantage of .avif generation, .wasm compression, minification, and more. Build WebApps weighing less than 50kb and desktop/mobile apps less than 5mb.

Fantastic documentation

We've put a ton of effort into building clean, readable, and comprehensive documentation. All html elements and listeners are documented with MDN docs, and our Docs runs continuous integration with Dioxus itself to ensure that the docs are always up to date. Check out the Dioxus website for guides, references, recipes, and more. Fun fact: we use the Dioxus website as a testbed for new Dioxus features - check it out!

Community

Dioxus is a community-driven project, with a very active Discord and GitHub community. We're always looking for help, and we're happy to answer questions and help you get started. Our SDK is community-run and we even have a GitHub organization for the best Dioxus crates that receive free upgrades and support.

Full-time core team

Dioxus has grown from a side project to a small team of fulltime engineers. Thanks to the generous support of FutureWei, Satellite.im, the GitHub Accelerator program, we're able to work on Dioxus full-time. Our long term goal is for Dioxus to become self-sustaining by providing paid high-quality enterprise tools. If your company is interested in adopting Dioxus and would like to work with us, please reach out!

Supported Platforms

Web	Render directly to the DOM using WebAssembly Pre-render with SSR and rehydrate on the client Simple "hello world" at about 50kb, comparable to React Built-in dev server and hot reloading for quick iteration
Desktop	Render using Webview or - experimentally - with WGPU or Freya (Skia) Zero-config setup. Simply `cargo run` or `dx serve` to build your app Full support for native system access without IPC Supports macOS, Linux, and Windows. Portable <3mb binaries
Mobile	Render using Webview or - experimentally - with WGPU or Skia Build .ipa and .apk files for iOS and Android Call directly into Java and Objective-C with minimal overhead From "hello world" to running on device in seconds
Server-side Rendering	Suspense, hydration, and server-side rendering Quickly drop in backend functionality with server functions Extractors, middleware, and routing integrations Static-site generation and incremental regeneration

Running the examples

The examples in the main branch of this repository target the git version of dioxus and the CLI. If you are looking for examples that work with the latest stable release of dioxus, check out the 0.6 branch.

The examples in the top level of this repository can be run with:

cargo run --example <example>

However, we encourage you to download the dioxus-cli to test out features like hot-reloading. To install the most recent binary CLI, you can use cargo binstall.

curl -fsSL https://dioxuslabs.com/install.sh | bash

If this CLI is out-of-date, you can install it directly from git or cargo-binstall

cargo install --git https://github.com/DioxusLabs/dioxus dioxus-cli --locked

With the CLI, you can also run examples with the web platform. You will need to disable the default desktop feature and enable the web feature with this command:

dx serve --example <example> --platform web -- --no-default-features

Contributing

Check out the website section on contributing.
Report issues on our issue tracker.
Join the discord and ask questions!

License

This project is licensed under either the MIT license or the Apache-2 License.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you, shall be licensed as MIT or Apache-2, without any additional terms or conditions.

astral-sh/uv

An extremely fast Python package and project manager, written in Rust.

uv

An extremely fast Python package and project manager, written in Rust.

Installing Trio's dependencies with a warm cache.

Highlights

A single tool to replace pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more.
10-100x faster than pip.
Provides comprehensive project management, with a universal lockfile.
Runs scripts, with support for inline dependency metadata.
Installs and manages Python versions.
Runs and installs tools published as Python packages.
Includes a pip-compatible interface for a performance boost with a familiar CLI.
Supports Cargo-style workspaces for scalable projects.
Disk-space efficient, with a global cache for dependency deduplication.
Installable without Rust or Python via curl or pip.
Supports macOS, Linux, and Windows.

uv is backed by Astral, the creators of Ruff and ty.

Installation

Install uv with our standalone installers:

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Or, from PyPI:

# With pip.
pip install uv

# Or pipx.
pipx install uv

If installed via the standalone installer, uv can update itself to the latest version:

uv self update

See the installation documentation for details and alternative installation methods.

Documentation

uv's documentation is available at docs.astral.sh/uv.

Additionally, the command line reference documentation can be viewed with uv help.

Features

Projects

uv manages project dependencies and environments, with support for lockfiles, workspaces, and more, similar to rye or poetry:

$ uv init example
Initialized project `example` at `/home/user/example`

$ cd example

$ uv add ruff
Creating virtual environment at: .venv
Resolved 2 packages in 170ms
   Built example @ file:///home/user/example
Prepared 2 packages in 627ms
Installed 2 packages in 1ms
 + example==0.1.0 (from file:///home/user/example)
 + ruff==0.5.0

$ uv run ruff check
All checks passed!

$ uv lock
Resolved 2 packages in 0.33ms

$ uv sync
Resolved 2 packages in 0.70ms
Checked 1 package in 0.02ms

See the project documentation to get started.

uv also supports building and publishing projects, even if they're not managed with uv. See the publish guide to learn more.

Scripts

uv manages dependencies and environments for single-file scripts.

Create a new script and add inline metadata declaring its dependencies:

$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py

$ uv add --script example.py requests
Updated `example.py`

Then, run the script in an isolated virtual environment:

$ uv run example.py
Reading inline script metadata from: example.py
Installed 5 packages in 12ms
<Response [200]>

See the scripts documentation to get started.

Tools

uv executes and installs command-line tools provided by Python packages, similar to pipx.

Run a tool in an ephemeral environment using uvx (an alias for uv tool run):

$ uvx pycowsay 'hello world!'
Resolved 1 package in 167ms
Installed 1 package in 9ms
 + pycowsay==0.0.0.2
  """

  ------------
< hello world! >
  ------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

Install a tool with uv tool install:

$ uv tool install ruff
Resolved 1 package in 6ms
Installed 1 package in 2ms
 + ruff==0.5.0
Installed 1 executable: ruff

$ ruff --version
ruff 0.5.0

See the tools documentation to get started.

Python versions

uv installs Python and allows quickly switching between versions.

Install multiple Python versions:

$ uv python install 3.12 3.13 3.14
Installed 3 versions in 972ms
 + cpython-3.12.12-macos-aarch64-none (python3.12)
 + cpython-3.13.9-macos-aarch64-none (python3.13)
 + cpython-3.14.0-macos-aarch64-none (python3.14)

Download Python versions as needed:

$ uv venv --python 3.12.0
Using Python 3.12.0
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

$ uv run --python pypy@3.8 -- python --version
Python 3.8.16 (a9dbdca6fc3286b0addd2240f11d97d8e8de187a, Dec 29 2022, 11:45:30)
[PyPy 7.3.11 with GCC Apple LLVM 13.1.6 (clang-1316.0.21.2.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>>

Use a specific Python version in the current directory:

$ uv python pin 3.11
Pinned `.python-version` to `3.11`

See the Python installation documentation to get started.

The pip interface

uv provides a drop-in replacement for common pip, pip-tools, and virtualenv commands.

uv extends their interfaces with advanced features, such as dependency version overrides, platform-independent resolutions, reproducible resolutions, alternative resolution strategies, and more.

Migrate to uv without changing your existing workflows — and experience a 10-100x speedup — with the uv pip interface.

Compile requirements into a platform-independent requirements file:

$ uv pip compile requirements.in \
   --universal \
   --output-file requirements.txt
Resolved 43 packages in 12ms

Create a virtual environment:

$ uv venv
Using Python 3.12.3
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

Install the locked requirements:

$ uv pip sync requirements.txt
Resolved 43 packages in 11ms
Installed 43 packages in 208ms
 + babel==2.15.0
 + black==24.4.2
 + certifi==2024.7.4
 ...

See the pip interface documentation to get started.

Contributing

We are passionate about supporting contributors of all levels of experience and would love to see you get involved in the project. See the contributing guide to get started.

FAQ

How do you pronounce uv?

It's pronounced as "you - vee" (/juː viː/)

How should I stylize uv?

Just "uv", please. See the style guide for details.

What platforms does uv support?

See uv's platform support document.

Is uv ready for production?

Yes, uv is stable and widely used in production. See uv's versioning policy document for details.

Acknowledgements

uv's dependency resolver uses PubGrub under the hood. We're grateful to the PubGrub maintainers, especially Jacob Finkelman, for their support.

uv's Git implementation is based on Cargo.

Some of uv's optimizations are inspired by the great work we've seen in pnpm, Orogene, and Bun. We've also learned a lot from Nathaniel J. Smith's Posy and adapted its trampoline for Windows support.

License

uv 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.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in uv by you, as defined in the Apache-2.0 license, shall be dually licensed as above, without any additional terms or conditions.

apache/datafusion

Apache DataFusion SQL Query Engine

Apache DataFusion

Website | API Docs | Chat

DataFusion is an extensible query engine written in Rust that uses Apache Arrow as its in-memory format.

This crate provides libraries and binaries for developers building fast and feature-rich database and analytic systems, customized for particular workloads. See use cases for examples. The following related subprojects target end users:

DataFusion Python offers a Python interface for SQL and DataFrame queries.
DataFusion Java offers a Java interface for SQL and DataFrame queries.
DataFusion Comet is an accelerator for Apache Spark based on DataFusion.
DataFusion Ballista is a distributed query execution engine that scales DataFusion across a cluster of nodes.

"Out of the box," DataFusion offers SQL and DataFrame APIs, excellent performance, built-in support for CSV, Parquet, JSON, and Avro, extensive customization, and a great community.

DataFusion features a full query planner, a columnar, streaming, multi-threaded, vectorized execution engine, and partitioned data sources. You can customize DataFusion at almost all points including additional data sources, query languages, functions, custom operators and more. See the Architecture section for more details.

Here are links to important resources:

What can you do with this crate?

DataFusion is great for building projects such as domain-specific query engines, new database platforms and data pipelines, query languages and more. It lets you start quickly from a fully working engine, and then customize those features specific to your needs. See the list of known users.

Contributing to DataFusion

Please see the contributor guide and communication pages for more information.

We discuss our roadmap via GitHub issues and invite you to join the conversation. The current discussion is the DataFusion 2026 Q3-Q4 Roadmap Discussion.

Crate features

This crate has several features which can be specified in your Cargo.toml.

Default features:

nested_expressions: functions for working with nested types such as array_to_string
compression: reading files compressed with xz2, bzip2, flate2, and zstd
crypto_expressions: cryptographic functions such as md5 and sha256
datetime_expressions: date and time functions such as to_timestamp
encoding_expressions: encode and decode functions
parquet: support for reading the Apache Parquet format
sql: support for SQL parsing and planning
regex_expressions: regular expression functions, such as regexp_match
unicode_expressions: include Unicode-aware functions such as character_length
unparser: enables support to reverse LogicalPlans back into SQL
recursive_protection: uses recursive for stack overflow protection.

Optional features:

avro: support for reading the Apache Avro format
backtrace: include backtrace information in error messages
parquet_encryption: support for using Parquet Modular Encryption
serde: enable arrow-schema's serde feature

DataFusion API Evolution and Deprecation Guidelines

Public methods in Apache DataFusion evolve over time: while we try to maintain a stable API, we also improve the API over time. As a result, we typically deprecate methods before removing them, according to the deprecation guidelines.

Dependencies and `Cargo.lock`

Following the guidance on committing Cargo.lock files, this project commits its Cargo.lock file.

CI uses the committed Cargo.lock file, and dependencies are updated regularly using Dependabot PRs.

modelcontextprotocol/rust-sdk

The official Rust SDK for the Model Context Protocol

RMCP

An official Rust Model Context Protocol SDK implementation with tokio async runtime.

Migrating to 3.x? See the migration guide for breaking changes and upgrade instructions.

This repository contains the following crates:

rmcp: The core crate providing the RMCP protocol implementation - see rmcp
rmcp-macros: A procedural macro crate for generating RMCP tool implementations - see rmcp-macros

This SDK implements the stable MCP 2026-07-28 specification while remaining fully compatible with the 2025-11-25 release and earlier versions. Features introduced in 2026-07-28 — server discovery & negotiation, transport-neutral subscriptions, long-running tasks, response caching, multi-round-trip requests, and standard HTTP routing headers — are documented below. For the full MCP specification, see modelcontextprotocol.io.

Usage

Import the crate

Add the latest published version with cargo:

cargo add rmcp --features server

Or use the dev channel:

cargo add rmcp --features server --git https://github.com/modelcontextprotocol/rust-sdk --branch main

Third Dependencies

Basic dependencies:

tokio
serde Json Schema generation (version 2020-12):
schemars

Build a Client

Start a client

use rmcp::{ServiceExt, transport::{TokioChildProcess, ConfigureCommandExt}};
use tokio::process::Command;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ().serve(TokioChildProcess::new(Command::new("npx").configure(|cmd| {
        cmd.arg("-y").arg("@modelcontextprotocol/server-everything");
    }))?).await?;
    Ok(())
}

Client lifecycle modes

serve() uses the legacy MCP lifecycle: the client sends initialize, receives the negotiated server information, and then sends notifications/initialized. Use ClientServiceExt::serve_with_lifecycle to select another lifecycle explicitly:

use rmcp::{ClientInfo, ClientLifecycleMode, ClientServiceExt, ProtocolVersion};

// Start directly with server/discover and include client metadata on every request.
let client = ClientInfo::default()
    .serve_with_lifecycle(
        transport,
        ClientLifecycleMode::Discover {
            preferred_versions: vec![ProtocolVersion::V_2026_07_28],
        },
    )
    .await?;

// Or probe the discover lifecycle and fall back when a legacy server reports
// that server/discover is not implemented.
let client = ClientInfo::default()
    .serve_with_lifecycle(
        transport,
        ClientLifecycleMode::Auto {
            preferred_versions: vec![ProtocolVersion::V_2026_07_28],
            legacy_version: Some(ProtocolVersion::V_2025_11_25),
        },
    )
    .await?;

ClientLifecycleMode::Initialize is equivalent to the existing serve() behavior. Discover startup does not send notifications/initialized; discovery completes startup, and each subsequent request carries its protocol version, client information, and capabilities in _meta.

Build a Server

Build a transport

use tokio::io::{stdin, stdout};
let transport = (stdin(), stdout());

Build a service

You can easily build a service by using ServerHandler or ClientHandler.

let service = common::counter::Counter::new();

Start the server

// this call will finish the initialization process
let server = service.serve(transport).await?;

Interact with the server

Once the server is initialized, you can send requests or notifications:

// request
let roots = server.list_roots().await?;

// or send notification
server.notify_cancelled(...).await?;

Waiting for service shutdown

let quit_reason = server.waiting().await?;
// or cancel it
let quit_reason = server.cancel().await?;

Tools

Tools let servers expose callable functions to clients. Each tool has a name, description, and a JSON Schema for its parameters. Clients discover tools via list_tools and invoke them via call_tool.

MCP Spec: Tools

Server-side

The #[tool], #[tool_router], and #[tool_handler] macros handle all the wiring. For a tools-only server you can use #[tool_router(server_handler)] to skip the separate ServerHandler impl:

use rmcp::{handler::server::wrapper::Parameters, schemars, tool, tool_router, ServiceExt, transport::stdio};

#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
struct AddParams {
    a: i32,
    b: i32,
}

#[derive(Clone)]
struct Calculator;

#[tool_router(server_handler)]
impl Calculator {
    #[tool(description = "Add two numbers")]
    fn add(&self, Parameters(AddParams { a, b }): Parameters<AddParams>) -> String {
        (a + b).to_string()
    }
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let service = Calculator.serve(stdio()).await?;
    service.waiting().await?;
    Ok(())
}

The generated tool inputSchema and outputSchema are derived from the fields of T. The type name and documentation on T are ignored; only field names, field types, and field documentation are used.

2026-07-28 (SEP-2106): outputSchema may now be any JSON Schema type (not just object), and a tool result's structuredContent may be any JSON value (string, array, number, …) rather than only an object. Existing object-typed tools are unaffected.

When you need custom server metadata or multiple capabilities (tools + prompts), use explicit #[tool_handler]:

use rmcp::{handler::server::wrapper::Parameters, schemars, tool, tool_router, tool_handler, ServerHandler, ServiceExt};

#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
struct AddParams {
    a: i32,
    b: i32,
}

#[derive(Clone)]
struct Calculator;

#[tool_router]
impl Calculator {
    #[tool(description = "Add two numbers")]
    fn add(&self, Parameters(AddParams { a, b }): Parameters<AddParams>) -> String {
        (a + b).to_string()
    }
}

#[tool_handler(name = "calculator", version = "1.0.0", instructions = "A simple calculator")]
impl ServerHandler for Calculator {}

See crates/rmcp-macros for full macro documentation.

Tool result content types

Beyond a plain String, tools can return images, audio, embedded resources, and mixed content. Build a CallToolResult from a Vec<ContentBlock>:

use rmcp::model::{CallToolResult, ContentBlock, ResourceContents};

#[tool(description = "Render a chart")]
async fn chart(&self) -> Result<CallToolResult, McpError> {
    let png_base64 = render_png(); // base64-encoded image bytes
    let wav_base64 = render_wav(); // base64-encoded audio bytes

    Ok(CallToolResult::success(vec![
        // Text
        ContentBlock::text("Here is your chart:"),
        // Image — base64 data + MIME type
        ContentBlock::image(png_base64, "image/png"),
        // Audio — base64 data + MIME type
        ContentBlock::audio(wav_base64, "audio/wav"),
        // Embedded resource — inline text (or ResourceContents::blob for binary)
        ContentBlock::resource(ResourceContents::text(
            "chart source data",
            "chart://last/data.csv",
        )),
    ]))
}
# fn render_png() -> String { String::new() }
# fn render_wav() -> String { String::new() }

Image and audio data are base64 strings with a MIME type. For embedded resources, ResourceContents::text(..) inlines text and ResourceContents::blob(base64, uri) inlines binary.

Error handling

Two failure modes, chosen by whose problem it is:

Tool-level error — Ok(CallToolResult::error(vec![...])). The tool ran but failed in a way the caller should see (no rows matched, upstream 500). The client renders your content, so the message reaches the user. Use this for almost every "the tool ran and didn't work" case.
Protocol error — Err(McpError) with a JSON-RPC code (e.g. McpError::invalid_params(..)). Use this when the server can't route or process the request at all; clients render these opaquely, so the caller does not see your message.

use rmcp::model::{CallToolResult, ContentBlock};
use rmcp::ErrorData as McpError;

#[tool(description = "Look up a record")]
async fn lookup(&self, Parameters(args): Parameters<LookupArgs>) -> Result<CallToolResult, McpError> {
    // Malformed request — the server can't run anything → protocol error.
    if args.query.is_empty() {
        return Err(McpError::invalid_params("query must be non-empty", None));
    }

    // Tool ran, no result → tool-level error the user should see.
    let rows = self.run_query(&args.query).await;
    if rows.is_empty() {
        return Ok(CallToolResult::error(vec![ContentBlock::text(
            format!("no rows matched '{}'", args.query),
        )]));
    }

    Ok(CallToolResult::success(vec![ContentBlock::text(format_rows(&rows))]))
}

Client-side

use rmcp::model::CallToolRequestParams;

// List all tools
let tools = client.list_all_tools().await?;

// Call a tool by name
let result = client.call_tool(CallToolRequestParams::new("add")).await?;

Example: examples/servers/src/common/calculator.rs (server), examples/servers/src/calculator_stdio.rs (stdio runner)

Resources

Resources let servers expose data (files, database records, API responses) that clients can read. Each resource is identified by a URI and returns content as text or binary (base64-encoded) data. Resource templates allow servers to declare URI patterns with dynamic parameters.

MCP Spec: Resources

Server-side

Implement list_resources(), read_resource(), and optionally list_resource_templates() on the ServerHandler trait. Enable the resources capability in get_info().

use rmcp::{
    ErrorData as McpError, RoleServer, ServerHandler, ServiceExt,
    model::*,
    service::RequestContext,
    transport::stdio,
};
use serde_json::json;

#[derive(Clone)]
struct MyServer;

impl ServerHandler for MyServer {
    fn get_info(&self) -> ServerInfo {
        ServerInfo::new(
            ServerCapabilities::builder()
                .enable_resources()
                .build(),
        )
    }

    async fn list_resources(
        &self,
        _request: Option<PaginatedRequestParams>,
        _context: RequestContext<RoleServer>,
    ) -> Result<ListResourcesResult, McpError> {
        Ok(ListResourcesResult {
            resources: vec![
                Resource::new("file:///config.json", "config"),
                Resource::new("memo://insights", "insights"),
            ],
            next_cursor: None,
            meta: None,
        })
    }

    async fn read_resource(
        &self,
        request: ReadResourceRequestParams,
        _context: RequestContext<RoleServer>,
    ) -> Result<ReadResourceResult, McpError> {
        match request.uri.as_str() {
            "file:///config.json" => Ok(ReadResourceResult::new(vec![
                ResourceContents::text(r#"{"key": "value"}"#, &request.uri),
            ])),
            "memo://insights" => Ok(ReadResourceResult::new(vec![
                ResourceContents::text("Analysis results...", &request.uri),
            ])),
            // Binary resource — base64-encode the bytes and return a blob.
            "file:///logo.png" => {
                use base64::{Engine, prelude::BASE64_STANDARD};
                let bytes = std::fs::read("logo.png").unwrap_or_default();
                let blob = BASE64_STANDARD.encode(bytes);
                Ok(ReadResourceResult::new(vec![
                    ResourceContents::blob(blob, &request.uri)
                        .with_mime_type("image/png"),
                ]))
            }
            // Template-expanded URI — the client fills in `{user_id}` from the
            // `users://{user_id}/profile` template declared in
            // `list_resource_templates`, and the server reads the concrete URI.
            uri if uri.starts_with("users://") && uri.ends_with("/profile") => {
                let user_id = uri
                    .trim_start_matches("users://")
                    .trim_end_matches("/profile");
                Ok(ReadResourceResult::new(vec![ResourceContents::text(
                    format!(r#"{{"id": "{user_id}", "name": "User {user_id}"}}"#),
                    uri,
                )]))
            }
            _ => Err(McpError::resource_not_found(
                "resource_not_found",
                Some(json!({ "uri": request.uri })),
            )),
        }
    }

    async fn list_resource_templates(
        &self,
        _request: Option<PaginatedRequestParams>,
        _context: RequestContext<RoleServer>,
    ) -> Result<ListResourceTemplatesResult, McpError> {
        // Declare a URI template with a `{user_id}` parameter. Clients expand it
        // (e.g. `users://42/profile`) and pass the concrete URI to `read_resource`.
        Ok(ListResourceTemplatesResult {
            resource_templates: vec![
                ResourceTemplate::new("users://{user_id}/profile", "user-profile"),
            ],
            next_cursor: None,
            meta: None,
        })
    }
}

Client-side

use rmcp::model::{ReadResourceRequestParams};

// List all resources (handles pagination automatically)
let resources = client.list_all_resources().await?;

// Read a specific resource by URI
let result = client.read_resource(
    ReadResourceRequestParams::new("file:///config.json"),
).await?;

// List resource templates, then read a resource through one by expanding its
// parameters into a concrete URI (`users://{user_id}/profile` → `users://42/profile`).
let templates = client.list_all_resource_templates().await?;
let profile = client.read_resource(
    ReadResourceRequestParams::new("users://42/profile"),
).await?;

Notifications

Servers can notify clients when the resource list changes or when a specific resource is updated:

// Notify that the resource list has changed (clients should re-fetch)
context.peer.notify_resource_list_changed().await?;

// Notify that a specific resource was updated
context.peer.notify_resource_updated(
    ResourceUpdatedNotificationParam::new("file:///config.json"),
).await?;

Clients handle these via ClientHandler:

impl ClientHandler for MyClient {
    async fn on_resource_list_changed(
        &self,
        _context: NotificationContext<RoleClient>,
    ) {
        // Re-fetch the resource list
    }

    async fn on_resource_updated(
        &self,
        params: ResourceUpdatedNotificationParam,
        _context: NotificationContext<RoleClient>,
    ) {
        // Re-read the updated resource at params.uri
    }
}

Example: examples/servers/src/common/counter.rs (server), examples/clients/src/everything_stdio.rs (client)

Prompts

Prompts are reusable message templates that servers expose to clients. They accept typed arguments and return conversation messages. The #[prompt] macro handles argument validation and routing automatically.

MCP Spec: Prompts

Server-side

Use the #[prompt_router], #[prompt], and #[prompt_handler] macros to define prompts declaratively. Arguments are defined as structs deriving JsonSchema.

use rmcp::{
    ErrorData as McpError, RoleServer, ServerHandler, ServiceExt,
    handler::server::{router::prompt::PromptRouter, wrapper::Parameters},
    model::*,
    prompt, prompt_handler, prompt_router,
    schemars::JsonSchema,
    service::RequestContext,
    transport::stdio,
};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, JsonSchema)]
pub struct CodeReviewArgs {
    #[schemars(description = "Programming language of the code")]
    pub language: String,
    #[schemars(description = "Focus areas for the review")]
    pub focus_areas: Option<Vec<String>>,
}

#[derive(Clone)]
pub struct MyServer {
    prompt_router: PromptRouter<Self>,
}

#[prompt_router]
impl MyServer {
    fn new() -> Self {
        Self { prompt_router: Self::prompt_router() }
    }

    /// Simple prompt without parameters
    #[prompt(name = "greeting", description = "A simple greeting")]
    async fn greeting(&self) -> Vec<PromptMessage> {
        vec![PromptMessage::new_text(
            Role::User,
            "Hello! How can you help me today?",
        )]
    }

    /// Prompt with typed arguments
    #[prompt(name = "code_review", description = "Review code in a given language")]
    async fn code_review(
        &self,
        Parameters(args): Parameters<CodeReviewArgs>,
    ) -> Result<GetPromptResult, McpError> {
        let focus = args.focus_areas
            .unwrap_or_else(|| vec!["correctness".into()]);

        Ok(GetPromptResult::new(vec![
            PromptMessage::new_text(
                Role::User,
                format!("Review my {} code. Focus on: {}", args.language, focus.join(", ")),
            ),
        ])
        .with_description(format!("Code review for {}", args.language)))
    }
}

#[prompt_handler]
impl ServerHandler for MyServer {
    fn get_info(&self) -> ServerInfo {
        ServerInfo::new(ServerCapabilities::builder().enable_prompts().build())
    }
}

Prompt functions support several return types:

Vec<PromptMessage> -- simple message list
GetPromptResult -- messages with an optional description
Result<T, McpError> -- either of the above, with error handling

Image and embedded-resource content

A PromptMessage can also carry an image or embedded resource. Use the dedicated constructors (image/audio require the base64 feature):

use rmcp::model::{PromptMessage, Role};

// Image content — raw bytes are base64-encoded for you.
let screenshot: &[u8] = load_png();
let msg = PromptMessage::new_image(Role::User, screenshot, "image/png", None, None);

// Embedded resource — inline a text resource by URI. Pass `Some(text)` for a
// text resource, or `None` for a blob resource.
let msg = PromptMessage::new_resource(
    Role::User,
    "file:///spec.md".to_string(),
    Some("text/markdown".to_string()),
    Some("# Specification\n...".to_string()),
    None, None, None,
);
# fn load_png() -> &'static [u8] { &[] }

Client-side

use rmcp::model::GetPromptRequestParams;

// List all prompts
let prompts = client.list_all_prompts().await?;

// Get a prompt with arguments
let result = client.get_prompt(GetPromptRequestParams {
    meta: None,
    name: "code_review".into(),
    arguments: Some(rmcp::object!({
        "language": "Rust",
        "focus_areas": ["performance", "safety"]
    })),
}).await?;

Notifications

// Server: notify that available prompts have changed
context.peer.notify_prompt_list_changed().await?;

Example: examples/servers/src/prompt_stdio.rs (server), examples/clients/src/everything_stdio.rs (client)

Sampling

Deprecated (SEP-2577): Sampling is deprecated and will be removed in a future release. It remains fully functional for now. See SEP-2577.

Sampling flips the usual direction: the server asks the client to run an LLM completion. The server sends a create_message request, the client processes it through its LLM, and returns the result.

MCP Spec: Sampling

Server-side (requesting sampling)

Access the client's sampling capability through context.peer.create_message():

use rmcp::model::*;

// Inside a ServerHandler method (e.g., call_tool):
let response = context.peer.create_message(
    CreateMessageRequestParams::new(
        vec![SamplingMessage::user_text("Explain this error: connection refused")],
        150,
    )
    .with_model_preferences(
        ModelPreferences::new()
            .with_hints(vec![ModelHint::new("claude")])
            .with_cost_priority(0.3)
            .with_speed_priority(0.8)
            .with_intelligence_priority(0.7),
    )
    .with_system_prompt("You are a helpful assistant.")
    .with_include_context(ContextInclusion::None)
    .with_temperature(0.7),
).await?;

// Extract the response text
let text = response.message.content
    .first()
    .and_then(|c| c.as_text())
    .map(|t| &t.text);

Client-side (handling sampling)

On the client side, implement ClientHandler::create_message(). This is where you'd call your actual LLM:

use rmcp::{ClientHandler, model::*, service::{RequestContext, RoleClient}};

#[derive(Clone, Default)]
struct MyClient;

impl ClientHandler for MyClient {
    async fn create_message(
        &self,
        params: CreateMessageRequestParams,
        _context: RequestContext<RoleClient>,
    ) -> Result<CreateMessageResult, ErrorData> {
        // Forward to your LLM, or return a mock response:
        let response_text = call_your_llm(&params.messages).await;

        Ok(CreateMessageResult::new(
            SamplingMessage::assistant_text(response_text),
            "my-model".into(),
        )
        .with_stop_reason(CreateMessageResult::STOP_REASON_END_TURN))
    }
}

Example: examples/servers/src/sampling_stdio.rs (server), examples/clients/src/sampling_stdio.rs (client)

Elicitation

Elicitation lets a server pause mid-operation to ask the user for input, in one of two modes: form mode (structured fields with a JSON Schema) or URL mode (send the user to a web page and wait for completion).

MCP Spec: Elicitation

Server-side (form mode)

Define a struct deriving JsonSchema, mark it elicit_safe!, and call elicit::<T>() on the peer. Schema validation, defaults, and enum choices all come from the type.

use rmcp::{elicit_safe, model::*, service::{RequestContext, RoleServer}};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, JsonSchema)]
#[schemars(description = "User information")]
pub struct UserInfo {
    #[schemars(description = "User's name")]
    pub name: String,
    // Optional field; omitted if the user doesn't provide it.
    #[serde(default)]
    #[schemars(description = "Preferred greeting")]
    pub greeting: Option<String>,
}

// Whitelist the type for elicitation (schema-validated on both ends).
elicit_safe!(UserInfo);

#[tool(description = "Greet the user")]
async fn greet(&self, ctx: RequestContext<RoleServer>) -> Result<CallToolResult, McpError> {
    // Returns Ok(Some(UserInfo)) if the user accepts.
    // Decline and cancel are returned as ElicitationError variants.
    match ctx.peer.elicit::<UserInfo>("Please provide your name").await {
        Ok(Some(info)) => Ok(CallToolResult::success(vec![ContentBlock::text(
            format!("Hello, {}!", info.name),
        )])),
        Ok(None) => Ok(CallToolResult::success(vec![ContentBlock::text(
            "No name provided.",
        )])),
        Err(e) => Ok(CallToolResult::error(vec![ContentBlock::text(
            format!("Elicitation failed: {e}"),
        )])),
    }
}

Enum values

Enum fields become a choice list. schemars needs two hints to inline and type the enum correctly:

#[derive(Debug, Serialize, Deserialize, JsonSchema, Default)]
#[schemars(inline)]                     // inline the enum into the parent schema
#[schemars(extend("type" = "string"))]  // schemars omits `type` for enums; add it
enum Priority {
    #[schemars(title = "Low priority")]
    #[default]
    Low,
    #[schemars(title = "High priority")]
    High,
}

See examples/servers/src/elicitation_enum_inference.rs for single-select, multi-select, titled, and defaulted enum forms.

Server-side (URL mode)

For flows a form can't capture (OAuth consent, a payment page), send the user to a URL. elicit_url returns the user's ElicitationAction rather than typed data:

use rmcp::model::ElicitationAction;
use url::Url;

let action = ctx.peer.elicit_url(
    "Please complete setup in your browser",
    Url::parse("https://example.com/setup").unwrap(),
    "setup-123", // a unique elicitation id
).await?;

match action {
    ElicitationAction::Accept  => { /* user consented */ }
    ElicitationAction::Decline => { /* user declined */ }
    ElicitationAction::Cancel  => { /* user aborted */ }
}

Client-side

Implement ClientHandler::create_elicitation(), matching on the request variant to handle form vs. URL mode:

use rmcp::{ClientHandler, model::*, service::{RequestContext, RoleClient}};

impl ClientHandler for MyClient {
    async fn create_elicitation(
        &self,
        request: ElicitRequestParams,
        _context: RequestContext<RoleClient>,
    ) -> Result<ElicitResult, ErrorData> {
        match request {
            ElicitRequestParams::FormElicitationParams { message, .. } => {
                // Show `message` + the requested schema, collect input, then:
                Ok(ElicitResult {
                    action: ElicitationAction::Accept,
                    content: Some(rmcp::object!({ "name": "Ada" })),
                    meta: None,
                })
            }
            ElicitRequestParams::UrlElicitationParams { url, .. } => {
                // Open `url`, wait for the user, then report the action.
                let _ = url;
                Ok(ElicitResult { action: ElicitationAction::Accept, content: None, meta: None })
            }
        }
    }
}

On completion the client sends a notifications/elicitation/response notification to release the waiting server-side elicit_url call.

Example: examples/servers/src/elicitation_stdio.rs (form + URL), examples/servers/src/elicitation_enum_inference.rs (enum forms)

Roots

Deprecated (SEP-2577): Roots is deprecated and will be removed in a future release. It remains fully functional for now. See SEP-2577.

Roots tell servers which directories or projects the client is working in. A root is a URI (typically file://) pointing to a workspace or repository. Servers can query roots to know where to look for files and how to scope their work.

MCP Spec: Roots

Server-side

Ask the client for its root list, and handle change notifications:

use rmcp::{ServerHandler, model::*, service::{NotificationContext, RoleServer}};

impl ServerHandler for MyServer {
    // Query the client for its roots
    async fn call_tool(
        &self,
        request: CallToolRequestParams,
        context: RequestContext<RoleServer>,
    ) -> Result<CallToolResult, ErrorData> {
        let roots = context.peer.list_roots().await?;
        // Use roots.roots to understand workspace boundaries
        // ...
    }

    // Called when the client's root list changes
    async fn on_roots_list_changed(
        &self,
        _context: NotificationContext<RoleServer>,
    ) {
        // Re-fetch roots to stay current
    }
}

Client-side

Clients declare roots capability and implement list_roots():

use rmcp::{ClientHandler, model::*};

impl ClientHandler for MyClient {
    async fn list_roots(
        &self,
        _context: RequestContext<RoleClient>,
    ) -> Result<ListRootsResult, ErrorData> {
        Ok(ListRootsResult::new(vec![
            Root::new("file:///home/user/project").with_name("My Project"),
        ]))
    }
}

Clients notify the server when roots change:

// After adding or removing a workspace root:
client.notify_roots_list_changed().await?;

Logging

Deprecated (SEP-2577): Logging is deprecated and will be removed in a future release. It remains fully functional for now. See SEP-2577.

Servers can send structured log messages to clients. The client sets a minimum severity level, and the server sends messages through the peer notification interface.

MCP Spec: Logging

Server-side

Enable the logging capability, handle level changes from the client, and send log messages via the peer:

use rmcp::{ServerHandler, model::*, service::RequestContext};

impl ServerHandler for MyServer {
    fn get_info(&self) -> ServerInfo {
        ServerInfo::new(
            ServerCapabilities::builder()
                .enable_logging()
                .build(),
        )
    }

    // Client sets the minimum log level
    async fn set_level(
        &self,
        request: SetLevelRequestParams,
        _context: RequestContext<RoleServer>,
    ) -> Result<(), ErrorData> {
        // Store request.level and filter future log messages accordingly
        Ok(())
    }
}

// Send a log message from any handler with access to the peer:
context.peer.notify_logging_message(
    LoggingMessageNotificationParam::new(
        LoggingLevel::Info,
        serde_json::json!({
            "message": "Processing completed",
            "items_processed": 42
        }),
    )
    .with_logger("my-server"),
).await?;

Available log levels (from least to most severe): Debug, Info, Notice, Warning, Error, Critical, Alert, Emergency.

Client-side

Clients handle incoming log messages via ClientHandler:

impl ClientHandler for MyClient {
    async fn on_logging_message(
        &self,
        params: LoggingMessageNotificationParam,
        _context: NotificationContext<RoleClient>,
    ) {
        println!("[{}] {}: {}", params.level,
            params.logger.unwrap_or_default(), params.data);
    }
}

Clients can also set the server's log level:

client.set_level(SetLevelRequestParams::new(LoggingLevel::Warning)).await?;

Completions

Completions give auto-completion suggestions for prompt or resource template arguments. As a user fills in arguments, the client can ask the server for suggestions based on what's already been entered.

MCP Spec: Completions

Server-side

Enable the completions capability and implement the complete() handler. Use request.context to inspect previously filled arguments:

use rmcp::{ErrorData as McpError, ServerHandler, model::*, service::RequestContext, RoleServer};

impl ServerHandler for MyServer {
    fn get_info(&self) -> ServerInfo {
        ServerInfo::new(
            ServerCapabilities::builder()
                .enable_completions()
                .enable_prompts()
                .build(),
        )
    }

    async fn complete(
        &self,
        request: CompleteRequestParams,
        _context: RequestContext<RoleServer>,
    ) -> Result<CompleteResult, McpError> {
        let values = match &request.r#ref {
            // Completion for a prompt argument (`ref/prompt`).
            Reference::Prompt(prompt_ref) if prompt_ref.name == "sql_query" => {
                match request.argument.name.as_str() {
                    "operation" => vec!["SELECT", "INSERT", "UPDATE", "DELETE"],
                    "table" => vec!["users", "orders", "products"],
                    "columns" => {
                        // Adapt suggestions based on previously filled arguments
                        if let Some(ctx) = &request.context {
                            if let Some(op) = ctx.get_argument("operation") {
                                match op.to_uppercase().as_str() {
                                    "SELECT" | "UPDATE" => {
                                        vec!["id", "name", "email", "created_at"]
                                    }
                                    _ => vec![],
                                }
                            } else { vec![] }
                        } else { vec![] }
                    }
                    _ => vec![],
                }
            }
            // Completion for a resource-template argument (`ref/resource`). The
            // `uri` identifies the template (e.g. `users://{user_id}/profile`)
            // and `argument.name` is the template variable being completed.
            Reference::Resource(resource_ref)
                if resource_ref.uri == "users://{user_id}/profile" =>
            {
                match request.argument.name.as_str() {
                    "user_id" => vec!["1", "2", "42"],
                    _ => vec![],
                }
            }
            _ => vec![],
        };

        // Filter by the user's partial input
        let filtered: Vec<String> = values.into_iter()
            .map(String::from)
            .filter(|v| v.to_lowercase().contains(&request.argument.value.to_lowercase()))
            .collect();

        let completion = CompletionInfo::with_pagination(filtered, None, false)
            .map_err(|e| McpError::internal_error(e, None))?;
        Ok(CompleteResult::new(completion))
    }
}

Client-side

use rmcp::model::*;

// Completion for a prompt argument.
let result = client.complete(CompleteRequestParams::new(
    Reference::for_prompt("sql_query"),
    ArgumentInfo::new("operation", "SEL"),
)).await?;

// result.completion.values contains suggestions like ["SELECT"]

// Completion for a resource-template argument: reference the template by URI
// and complete one of its variables (`user_id`).
let resource_completion = client.complete(CompleteRequestParams::new(
    Reference::for_resource("users://{user_id}/profile"),
    ArgumentInfo::new("user_id", "4"),
)).await?;

// resource_completion.completion.values contains suggestions like ["42"]

Example: examples/servers/src/completion_stdio.rs

Notifications

Notifications are fire-and-forget messages -- no response is expected. They cover progress updates, cancellation, and lifecycle events. Both sides can send and receive them.

MCP Spec: Notifications

Progress notifications

Servers can report progress during long-running operations:

use rmcp::model::*;

// Inside a tool handler:
for i in 0..total_items {
    process_item(i).await;

    context.peer.notify_progress(
        ProgressNotificationParam::new(
            ProgressToken(NumberOrString::Number(i as i64)),
            i as f64,
        )
        .with_total(total_items as f64)
        .with_message(format!("Processing item {}/{}", i + 1, total_items)),
    ).await?;
}

Cancellation

Either side can cancel an in-progress request:

// Send a cancellation
context.peer.notify_cancelled(CancelledNotificationParam::new(
    Some(the_request_id),
    Some("User requested cancellation".into()),
)).await?;

Handle cancellation in ServerHandler or ClientHandler:

impl ServerHandler for MyServer {
    async fn on_cancelled(
        &self,
        params: CancelledNotificationParam,
        _context: NotificationContext<RoleServer>,
    ) {
        // Abort work for params.request_id
    }
}

Ping

Either side can send a ping request to check that its counterpart is still responsive and the connection is alive. A ping carries no parameters and the receiver replies with an empty result. Because pings can flow in both directions, rmcp handles them symmetrically:

Sending a ping — construct a PingRequest and send it over the peer. A client pings the server with ClientRequest::PingRequest; a server pings the client with ServerRequest::PingRequest. send_request resolves once the empty response arrives, so a returned Ok confirms the peer is reachable:

use rmcp::model::{PingRequest, ServerRequest};

// From a server, ping the connected client to verify it is still alive.
context.peer
    .send_request(ServerRequest::PingRequest(PingRequest::default()))
    .await?;

use rmcp::model::{ClientRequest, PingRequest};

// From a client, ping the server. `running` is the value returned by serve().
running
    .send_request(ClientRequest::PingRequest(PingRequest::default()))
    .await?;

Responding to a ping — rmcp answers incoming pings automatically. The default ping method on ServerHandler and ClientHandler returns an empty result, so no code is required. Override it only if you want to run custom logic (for example, health checks) when a ping arrives:

impl ServerHandler for MyServer {
    async fn ping(
        &self,
        _context: RequestContext<RoleServer>,
    ) -> Result<(), McpError> {
        // Custom liveness logic here, if any.
        Ok(())
    }
}

MCP Spec: Ping

Initialized notification

Legacy clients send initialized after the initialize handshake completes. Clients using ClientLifecycleMode::Discover do not send this notification:

// Sent automatically by rmcp during the legacy serve() handshake.
// Servers handle it via:
impl ServerHandler for MyServer {
    async fn on_initialized(
        &self,
        _context: NotificationContext<RoleServer>,
    ) {
        // Server is ready to receive requests
    }
}

List-changed notifications

When available tools, prompts, or resources change, tell the client:

context.peer.notify_tool_list_changed().await?;
context.peer.notify_prompt_list_changed().await?;
context.peer.notify_resource_list_changed().await?;

Example: examples/servers/src/common/progress_demo.rs

Subscriptions

Protocol 2026-07-28 replaces resources/subscribe, resources/unsubscribe, and the standalone HTTP GET stream with the transport-neutral, long-lived subscriptions/listen request. Each requested notification category is opt-in.

MCP Spec: Subscriptions

Server-side

Declare the notification capabilities you serve, return the accepted subset, and use the filter-enforcing subscription sink:

use rmcp::{
    ErrorData, ServerHandler,
    model::*,
    service::SubscriptionContext,
};

impl ServerHandler for MyServer {
    fn get_info(&self) -> ServerInfo {
        ServerInfo::new(
            ServerCapabilities::builder()
                .enable_tools()
                .enable_tool_list_changed()
                .build(),
        )
    }

    fn accepted_subscription_filter(
        &self,
        requested: &SubscriptionFilter,
    ) -> Option<SubscriptionFilter> {
        Some(requested.clone())
    }

    async fn listen(&self, context: SubscriptionContext) -> Result<(), ErrorData> {
        if context.accepted().tools_list_changed == Some(true) {
            context.sink().notify_tool_list_changed().await
                .map_err(|error| ErrorData::internal_error(error.to_string(), None))?;
        }
        context.cancelled().await;
        Ok(())
    }
}

The SDK intersects the handler's filter with the requested categories and the capabilities advertised by get_info(). It sends the acknowledgment before listen, tags every sink notification with the listen request ID, and rejects categories or resource URIs outside the accepted filter.

Client-side

use rmcp::model::*;

let mut subscription = client.listen(
    SubscriptionFilter::builder()
        .tools_list_changed()
        .resource_subscription("file:///config.json")
        .build(),
).await?;

println!("accepted: {:?}", subscription.acknowledged());
while let Some(notification) = subscription.next().await? {
    println!("notification: {notification:?}");
}

subscription.cancel().await?;

listen() buffers up to 64 notifications per subscription. Use listen_with_capacity() to choose a different non-zero capacity; if a consumer falls behind, Subscription::end() reports SubscriptionEnd::Lagged.

For older negotiated protocol versions, the deprecated subscribe() and unsubscribe() APIs retain their legacy wire behavior. Modern Streamable HTTP uses the listen POST response stream directly and does not use sessions, GET, DELETE, or Last-Event-ID. After an abrupt transport close, call listen again; subscription state is not resumed across HTTP or stdio reconnects.

See the modern subscription server and client examples.

Multi-Round-Trip Requests

Protocol 2026-07-28 adds Multi-Round-Trip Requests (MRTR, SEP-2322): a server can answer a tools/call, prompts/get, or resources/read with an InputRequiredResult instead of a final result, asking the client to fulfill one or more embedded server requests (elicitation, sampling, or roots) and then retry. The exchange is stateless — the server carries its progress in an opaque requestState that the client echoes back verbatim.

MCP Spec: Multiple Round-Trip Requests

Server-side

Return an InputRequiredResult via the outcome enum for the method (CallToolResponse, GetPromptResponse, or ReadResourceResponse). The SDK only forwards it to peers that negotiated 2026-07-28 or newer — older peers get a protocol error instead.

async fn call_tool(&self, request: CallToolRequestParams, _ctx: RequestContext<RoleServer>)
    -> Result<CallToolResponse, ErrorData>
{
    match request.request_state {
        // First round: ask the client for input, seal progress into requestState.
        None => {
            let mut input_requests = InputRequests::new();
            input_requests.insert("city".into(), InputRequest::Elicitation(elicit_city()));
            let sealed = self.codec.seal_json(&json!({ "awaiting": "city" }))?;
            Ok(InputRequiredResult::new(Some(input_requests), Some(sealed)).into())
        }
        // Retry round: verify the echoed state, read the responses, finish.
        Some(sealed) => {
            let _state = self.codec.open_json(&sealed)
                .map_err(|_| ErrorData::invalid_params("tampered request state", None))?;
            let city = request.input_responses.as_ref()
                .and_then(|r| r.get("city"));
            Ok(CallToolResult::success(vec![ContentBlock::text("It is sunny.")]).into())
        }
    }
}

requestState is untrusted. The client echoes it back verbatim, so a stateless server that stores meaningful data in it MUST verify integrity first. Enable the request-state feature and use RequestStateCodec to seal and open it (HMAC-tagged), or keep state server-side and use requestState only as an opaque handle.

Client-side

The high-level call_tool, get_prompt, and read_resource helpers drive MRTR automatically: they fulfill each embedded request through the local ClientHandler and retry, up to DEFAULT_MRTR_MAX_ROUNDS (10).

// Auto mode: the SDK fulfills embedded requests and retries for you.
let result = client.call_tool(CallToolRequestParams::new("weather")).await?;

// Choose a custom round cap.
let result = client
    .call_tool_with_mrtr_max_rounds(CallToolRequestParams::new("weather"), 3)
    .await?;

// Manual mode: get the intermediate InputRequiredResult and drive rounds yourself.
match client.call_tool_once(CallToolRequestParams::new("weather")).await? {
    CallToolResponse::InputRequired(input_required) => { /* fulfill + retry */ }
    CallToolResponse::Complete(result) => { /* done */ }
    _ => {}
}

Example: examples/servers/src/mrtr.rs (end-to-end server + client)

Tasks (long-running tool invocations)

rmcp implements the MCP Tasks extension (SEP-2663, io.modelcontextprotocol/tasks). A client declares the extension in its capabilities; the server then decides per request whether to materialize a tools/call as a task, returning a CreateTaskResult (resultType: "task"). The client polls tasks/get, answers in-task input requests via tasks/update, and may request cooperative cancellation via tasks/cancel. Use rmcp::task_manager::TaskManager to manage task lifecycles server-side.

// Client: declare the tasks extension capability.
let caps = ClientCapabilities::builder().enable_tasks().build();

// Server: decide per request whether to materialize a task.
async fn call_tool(&self, request: CallToolRequestParams, context: RequestContext<RoleServer>)
    -> Result<CallToolResponse, McpError>
{
    let client_supports_tasks = context
        .client_capabilities()
        .is_some_and(|caps| caps.supports_tasks());
    if client_supports_tasks {
        let task = self.tasks.spawn(TaskOptions::default(), move |_ctx| {
            Box::pin(async move { /* long-running work -> Ok(CallToolResult) */ })
        });
        return Ok(CallToolResponse::Task(CreateTaskResult::new(task)));
    }
    // ... fall back to synchronous execution
}

See servers_task_stdio and the matching clients_task_stdio for a runnable end-to-end example.

Caching

rmcp clients transparently cache responses that carry the SEP-2549 caching hints (ttlMs / cacheScope) for server/discover, tools/list, prompts/list, resources/list, resources/templates/list, and resources/read.

Caching is on by default but only stores a response when the server sends a positive ttlMs, so servers that omit the hint behave exactly as before. Entries expire after their TTL, are partitioned by cache scope, and are invalidated automatically by the matching list_changed / resource updated notifications.

No call-site changes are needed — existing calls benefit automatically:

let tools = peer.list_tools(None).await?;     // served from cache while fresh
let res   = peer.read_resource(params).await?; // cached per-URI

Tune or disable it per connection via the Peer:

use std::time::Duration;
use rmcp::ClientCacheConfig;

// Customize behavior.
peer.set_response_cache_config(
    ClientCacheConfig::default()
        .with_default_ttl(Duration::from_secs(30)) // TTL for servers that omit ttlMs
        .with_max_ttl(Duration::from_secs(3600))   // upper bound on any TTL
        .with_max_entries(1024)
        .with_private_partition(user_id)            // separate private caches per principal
        .with_serve_stale_on_error(false),          // surface errors instead of stale data
).await;

// Or turn it off entirely.
peer.set_response_cache_config(ClientCacheConfig::disabled()).await;

// Manually flush.
peer.clear_response_cache().await;

Note: with the default serve_stale_on_error, a failed re-fetch returns the last cached response (even if expired) as Ok(..) instead of an error. Set with_serve_stale_on_error(false) if callers must observe fetch failures.

Standard HTTP Headers

Protocol 2026-07-28 standardizes a set of Streamable HTTP request headers (SEP-2243) so proxies and gateways can route MCP traffic without parsing the JSON body: Mcp-Method, Mcp-Name, and Mcp-Param-*. rmcp emits and validates these automatically once a connection negotiates 2026-07-28 or newer — no call-site changes are required, and older negotiated versions are untouched.

MCP Spec: Header standardization

Mcp-Method — the JSON-RPC method (e.g. tools/call).
Mcp-Name — the target name, sourced from params.name (tools/call, prompts/get), params.uri (resources/*), or params.taskId (tasks/*).
Mcp-Param-* — selected tools/call arguments, promoted from the tool's input schema.

To promote a tool argument into a routing header, annotate the top-level schema property with x-mcp-header:

// A `region` argument surfaces as the `Mcp-Param-Region` request header.
let schema = serde_json::json!({
    "type": "object",
    "properties": {
        "region": { "type": "string", "x-mcp-header": "Region" }
    }
});

Annotations must be non-empty RFC 9110 tokens, case-insensitively unique, and applied only to top-level primitive (string/integer/boolean) properties. Values that cannot travel as a bare header (leading/trailing whitespace, control/non-ASCII characters) are transparently Base64-wrapped as =?base64?<b64>?=.

Stateless Streamable HTTP

Per SEP-2567, rmcp serves the 2026-07-28 draft statelessly automatically: no Mcp-Session-Id, no standalone GET/DELETE stream, and no Last-Event-ID resumption. The legacy_session_mode flag below only controls behavior for legacy protocol versions (< 2026-07-28).

MCP Spec: Transports

Server-side

A default server already serves 2026-07-28 clients statelessly. To also serve legacy clients without sessions, disable legacy_session_mode (formerly stateful_mode; builder with_stateful_mode). Optionally set with_json_response(true) so simple request/response tools reply with a single application/json body instead of an SSE stream (the server still falls back to text/event-stream if a handler emits a notification or server request first):

use rmcp::transport::streamable_http_server::{
    StreamableHttpService, StreamableHttpServerConfig,
    session::local::LocalSessionManager,
};

let config = StreamableHttpServerConfig::default()
    .with_legacy_session_mode(false) // stateless for legacy versions too
    .with_json_response(true);       // plain JSON replies for simple tools

let service = StreamableHttpService::new(
    || Ok(Counter::new()),           // a fresh handler per request
    LocalSessionManager::default().into(),
    config,
);

// `StreamableHttpService` is a Tower service — mount it on any router.
let router = axum::Router::new().nest_service("/mcp", service);

Because there is no per-session state, the service_factory runs per request. Keep shared state (DB pools, caches) in a Clone handle captured by the closure; don't rely on in-memory state surviving between requests.

Modern-only servers can additionally call with_stateless_protocol_metadata_required(true) to reject the compatibility fallback for requests missing their per-request protocol signals. rmcp clients negotiated below 2026-07-28 do not attach that body metadata and will be rejected, so pair this option with a supported_protocol_versions implementation that advertises only 2026-07-28 and later.

Client-side

The Streamable HTTP client transport allows stateless operation by default (allow_stateless: true), so no configuration is needed to talk to a stateless server — it simply omits the session header when the server doesn't issue one:

use rmcp::transport::StreamableHttpClientTransport;

// Defaults are stateless-friendly.
let transport = StreamableHttpClientTransport::from_uri("http://localhost:8000/mcp");
let client = ClientInfo::default().serve(transport).await?;

Example: examples/servers/src/counter_streamhttp.rs (server), examples/clients/src/streamable_http.rs (client)

Transports

A transport moves JSON-RPC messages between client and server. Any Transport impl can be passed to .serve(..); rmcp ships the common ones behind Cargo features.

MCP Spec: Transports

Transport	Feature(s)	Notes
stdio	`transport-io` (client + server)	Communicate over `stdin`/`stdout`; the standard way to launch local MCP servers as child processes.
Child process (client)	`transport-child-process`	Spawn a server binary and talk to it over its stdio.
Streamable HTTP (server)	`transport-streamable-http-server`	The current HTTP transport. Exposes a Tower service you can mount on any router.
Streamable HTTP (client)	`transport-streamable-http-client-reqwest`	HTTP client transport built on `reqwest`.
Worker / in-process	`transport-worker`	For embedding or testing without real I/O.

stdio

use rmcp::{ServiceExt, transport::stdio};

// Server: serve over stdin/stdout.
let server = MyServer.serve(stdio()).await?;
server.waiting().await?;

use rmcp::{ServiceExt, transport::{TokioChildProcess, ConfigureCommandExt}};
use tokio::process::Command;

// Client: launch a server binary and talk to it over its stdio.
let transport = TokioChildProcess::new(Command::new("uvx").configure(|cmd| {
    cmd.arg("mcp-server-git");
}))?;
let client = ().serve(transport).await?;

Streamable HTTP

StreamableHttpService is a Tower service — mount it on any axum/hyper router (see Stateless Streamable HTTP for the full server example). The client transport connects with a single URI:

use rmcp::transport::StreamableHttpClientTransport;

let transport = StreamableHttpClientTransport::from_uri("http://localhost:8000/mcp");
let client = ClientInfo::default().serve(transport).await?;

Server-Sent Events (SSE)

Streamable HTTP responses arrive as either a single application/json body or a text/event-stream (Server-Sent Events) stream when the server pushes notifications or requests before the result. rmcp handles both automatically (SSE parsing lives behind the client-side-sse feature). There is no separate "SSE transport" to configure — it's an implementation detail of Streamable HTTP.

Legacy HTTP+SSE transport (`2024-11-05`) — intentionally not provided

The standalone two-endpoint HTTP+SSE transport defined in protocol revision 2024-11-05 (a separate GET SSE channel plus a POST message endpoint) is a deliberate non-goal for rmcp. It was replaced by Streamable HTTP in the 2025-03-26 revision, and rmcp targets current spec revisions (2025-11-25 and 2026-07-28), so it ships no legacy HTTP+SSE client or server transport.

What to use instead:

New client/server code — use Streamable HTTP. It carries the same SSE streaming semantics over a single endpoint and is the transport all supported spec revisions expect.
Server-to-client streaming (push notifications, resource updates) — this is built into Streamable HTTP; see Subscriptions.
Talking to a legacy 2024-11-05-only server — front it with a proxy that speaks Streamable HTTP, or pin a dependency to a release that predates the transport's removal. rmcp will not add the legacy transport back.

This is a supported-surface decision, not a missing feature: every transport rmcp implements is listed in the Transports table above.

Pagination

List operations (tools/list, prompts/list, resources/list, resources/templates/list) are paginated via a next_cursor. The list_all_* helpers walk every page for you:

// Fetches all pages transparently.
let tools     = client.list_all_tools().await?;
let prompts   = client.list_all_prompts().await?;
let resources = client.list_all_resources().await?;

To page manually, call the single-page method and follow next_cursor until it's None:

use rmcp::model::PaginatedRequestParams;

let mut cursor = None;
loop {
    let page = client
        .list_tools(Some(PaginatedRequestParams { meta: None, cursor }))
        .await?;
    for tool in &page.tools {
        // handle each tool
    }
    cursor = page.next_cursor;
    if cursor.is_none() {
        break;
    }
}

On the server, return a next_cursor from your list_* handler when more pages remain (None when complete).

MCP Spec: Pagination

Capability & Protocol Version Negotiation

Capabilities

At initialization, client and server exchange capabilities so each side knows what the other supports. Declare yours with the ServerCapabilities builder in get_info():

use rmcp::model::{ServerCapabilities, ServerInfo};

fn get_info(&self) -> ServerInfo {
    ServerInfo::new(
        ServerCapabilities::builder()
            .enable_tools()
            .enable_prompts()
            .enable_resources()
            .enable_resources_subscribe()
            .enable_tool_list_changed()
            .enable_logging()
            .build(),
    )
}

Clients do the same via ClientCapabilities::builder(). Macros like #[tool_handler] / #[prompt_handler] set the relevant flags automatically. After connecting, read the peer's capabilities via peer.peer_info().

Protocol version

MCP is versioned by date. rmcp negotiates automatically on connect — the client offers a preferred ProtocolVersion and falls back to one the server supports:

use rmcp::model::ProtocolVersion;

ProtocolVersion::LATEST;        // newest stable version this SDK defaults to
ProtocolVersion::V_2026_07_28;  // a specific version constant
ProtocolVersion::KNOWN_VERSIONS; // every version this SDK understands

Version-specific behavior (SEP-2243 headers, SEP-2567 stateless serving, the SEP-2575 subscription model) is gated on the negotiated version, so older clients keep working while newer ones opt in.

MCP Spec: Versioning and Compatibility

JSON Schema 2020-12

Deriving schemars::JsonSchema on your parameter and result types generates JSON Schema draft 2020-12 — the dialect the MCP spec requires — for the tool's inputSchema and outputSchema.

use rmcp::schemars;

#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
struct SearchParams {
    /// Full-text query.
    query: String,
    /// Maximum number of results.
    #[serde(default)]
    limit: Option<u32>,
}

Field names, types, and doc comments flow into the schema — no manual authoring needed. As of 2026-07-28 (SEP-2106), outputSchema may be any JSON Schema type (not only object) and structuredContent may be any JSON value.

Examples

See examples.

OAuth Support

See Oauth_support for details.

Related Resources

Related Projects

Extending `rmcp`

rmcp-actix-web - An actix_web backend for rmcp
rmcp-openapi - Transform OpenAPI definition endpoints into MCP tools

Built with `rmcp`

goose - An open-source, extensible AI agent that goes beyond code suggestions
apollo-mcp-server - MCP server that connects AI agents to GraphQL APIs via Apollo GraphOS
rustfs-mcp - High-performance MCP server providing S3-compatible object storage operations for AI/LLM integration
containerd-mcp-server - A containerd-based MCP server implementation
rmcp-openapi-server - High-performance MCP server that exposes OpenAPI definition endpoints as MCP tools
nvim-mcp - A MCP server to interact with Neovim
terminator - AI-powered desktop automation MCP server with cross-platform support and >95% success rate
stakpak-agent - Security-hardened terminal agent for DevOps with MCP over mTLS, streaming, secret tokenization, and async task management
video-transcriber-mcp-rs - High-performance MCP server for transcribing videos from 1000+ platforms using whisper.cpp
NexusCore MCP - Advanced malware analysis & dynamic instrumentation MCP server with Frida integration and stealth unpacking capabilities
spreadsheet-mcp - Token-efficient MCP server for spreadsheet analysis with automatic region detection, recalculation, screenshot, and editing support for LLM agents
hyper-mcp - A fast, secure MCP server that extends its capabilities through WebAssembly (WASM) plugins
rudof-mcp - RDF validation and data processing MCP server with ShEx/SHACL validation, SPARQL queries, and format conversion. Supports stdio and streamable HTTP transports with full MCP capabilities (tools, prompts, resources, logging, completions, tasks)
MCPMate - Desktop app for progressive MCP management: start with guided server import, then grow into multi-client profiles and Unify meta tools to keep tool exposure, token use, and runtime state under control, with more options for efficiency, cost, and reliability
McpMux - Desktop app to configure MCP servers once at McpMux, connect every AI client (Cursor, Claude Desktop, VS Code, Windsurf) through a single encrypted local gateway with Spaces for project organization, FeatureSets to switch toolsets per client, and a built-in server registry
systemprompt-template - Single-binary Rust runtime providing MCP governance — authentication, authorisation, rate-limiting, audit trails, and cost tracking for AI agents. Self-hosted, air-gap capable, 3,300+ req/s with sub-5ms governance overhead
jilebi-mcp - an extensible MCP server through plugins in Javascript with a secure permissions model

Development

Tips for Contributors

See docs/CONTRIBUTE.MD to get some tips for contributing.

Using Dev Container

If you want to use dev container, see docs/DEVCONTAINER.md for instructions on using Dev Container for development.

tokio-rs/tokio

A runtime for writing reliable asynchronous applications with Rust. Provides I/O, networking, scheduling, timers, ...

Tokio

A runtime for writing reliable, asynchronous, and slim applications with the Rust programming language. It is:

Fast: Tokio's zero-cost abstractions give you bare-metal performance.
Reliable: Tokio leverages Rust's ownership, type system, and concurrency model to reduce bugs and ensure thread safety.
Scalable: Tokio has a minimal footprint, and handles backpressure and cancellation naturally.

Website | Guides | API Docs | Chat

Overview

Tokio is an event-driven, non-blocking I/O platform for writing asynchronous applications with the Rust programming language. At a high level, it provides a few major components:

A multithreaded, work-stealing based task scheduler.
A reactor backed by the operating system's event queue (epoll, kqueue, IOCP, etc.).
Asynchronous TCP and UDP sockets.

These components provide the runtime components necessary for building an asynchronous application.

Example

A basic TCP echo server with Tokio.

Make sure you enable the full features of the tokio crate on Cargo.toml:

[dependencies]
tokio = { version = "1.53.1", features = ["full"] }

Then, on your main.rs:

use tokio::net::TcpListener;
use tokio::io::{AsyncReadExt, AsyncWriteExt};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let listener = TcpListener::bind("127.0.0.1:8080").await?;

    loop {
        let (mut socket, _) = listener.accept().await?;

        tokio::spawn(async move {
            let mut buf = [0; 1024];

            // In a loop, read data from the socket and write the data back.
            loop {
                let n = match socket.read(&mut buf).await {
                    // socket closed
                    Ok(0) => return,
                    Ok(n) => n,
                    Err(e) => {
                        eprintln!("failed to read from socket; err = {:?}", e);
                        return;
                    }
                };

                // Write the data back
                if let Err(e) = socket.write_all(&buf[0..n]).await {
                    eprintln!("failed to write to socket; err = {:?}", e);
                    return;
                }
            }
        });
    }
}

More examples can be found here. For a larger "real world" example, see the mini-redis repository.

To see a list of the available feature flags that can be enabled, check our docs.

Getting Help

First, see if the answer to your question can be found in the Guides or the API documentation. If the answer is not there, there is an active community in the Tokio Discord server. We would be happy to try to answer your question. You can also ask your question on the discussions page.

Contributing

🎈 Thanks for your help improving the project! We are so happy to have you! We have a contributing guide to help you get involved in the Tokio project.

Related Projects

In addition to the crates in this repository, the Tokio project also maintains several other libraries, including:

axum: A web application framework that focuses on ergonomics and modularity.
hyper: A fast and correct HTTP/1.1 and HTTP/2 implementation for Rust.
tonic: A gRPC over HTTP/2 implementation focused on high performance, interoperability, and flexibility.
warp: A super-easy, composable, web server framework for warp speeds.
tower: A library of modular and reusable components for building robust networking clients and servers.
tracing (formerly tokio-trace): A framework for application-level tracing and async-aware diagnostics.
mio: A low-level, cross-platform abstraction over OS I/O APIs that powers tokio.
bytes: Utilities for working with bytes, including efficient byte buffers.
loom: A testing tool for concurrent Rust code.

Changelog

The Tokio repository contains multiple crates. Each crate has its own changelog.

tokio - view changelog
tokio-util - view changelog
tokio-stream - view changelog
tokio-macros - view changelog
tokio-test - view changelog

Supported Rust Versions

Tokio will keep a rolling MSRV (minimum supported rust version) policy of at least 6 months. When increasing the MSRV, the new Rust version must have been released at least six months ago. The current MSRV is 1.71.

Note that the MSRV is not increased automatically, and only as part of a minor release. The MSRV history for past minor releases can be found below:

1.48 to now - Rust 1.71
1.39 to 1.47 - Rust 1.70
1.30 to 1.38 - Rust 1.63
1.27 to 1.29 - Rust 1.56
1.17 to 1.26 - Rust 1.49
1.15 to 1.16 - Rust 1.46
1.0 to 1.14 - Rust 1.45

Note that although we try to avoid the situation where a dependency transitively increases the MSRV of Tokio, we do not guarantee that this does not happen. However, every minor release will have some set of versions of dependencies that works with the MSRV of that minor release.

Release schedule

Tokio doesn't follow a fixed release schedule, but we typically make one minor release each month. We make patch releases for bugfixes as necessary.

Bug patching policy

For the purposes of making patch releases with bugfixes, we have designated certain minor releases as LTS (long term support) releases. Whenever a bug warrants a patch release with a fix for the bug, it will be backported and released as a new patch release for each LTS minor version. Our current LTS releases are:

1.47.x - LTS release until September 2026. (MSRV 1.70)
1.51.x - LTS release until March 2027. (MSRV 1.71)

Each LTS release will continue to receive backported fixes for at least a year. If you wish to use a fixed minor release in your project, we recommend that you use an LTS release.

To use a fixed minor version, you can specify the version with a tilde. For example, to specify that you wish to use the newest 1.47.x patch release, you can use the following dependency specification:

tokio = { version = "~1.47", features = [...] }

Previous LTS releases

1.8.x - LTS release until February 2022.
1.14.x - LTS release until June 2022.
1.18.x - LTS release until June 2023.
1.20.x - LTS release until September 2023.
1.25.x - LTS release until March 2024.
1.32.x - LTS release until September 2024.
1.36.x - LTS release until March 2025.
1.38.x - LTS release until July 2025.
1.43.x - LTS release until March 2026.

License

This project is licensed under the MIT license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Tokio by you shall be licensed as MIT, without any additional terms or conditions.

malisper/pgrust

Postgres rewritten in Rust, now faster than Postgres and Clickhouse

pgrust

A Rust rewrite of Postgres that's faster than Postgres and ClickHouse.

Try pgrust in your browser → | Discord | Updates | Issues

New: Rebuilding Postgres for 300x faster analytics: batching, operator fusion, and SIMD

pgrust is a re-implementation of Postgres meant to show what Postgres would look like if it was built in 2026. It is wire compatible and even SQL dialect compatible with Postgres. It passes all 46,066 tests in Postgres' regression suite. For the story of why we're building it, see pgrust: rebuilding Postgres in Rust with AI.

Every line is Rust, written to match the behavior of the C implementation. Rust makes it easy to re-architect several core Postgres pieces. pgrust has:

A new vectorized push-based, JIT compiled executor
A thread based concurrency model
A query scheduler designed to keep any individual query from taking down your database
A built-in OOM killer that gives pgrust control of what happens when you're running low on memory, greatly reducing the chance of your whole DB being taken down by the OS OOM killer

and many other really awesome pieces. The scheduler and the OOM killer go after two of the four horsemen behind thousands of Postgres outages. See What's new in v0.2 for more.

Status

pgrust is not production ready. Do not put data you care about in it.

pgrust currently passes the Postgres regression suite. It's faster than Postgres and ClickHouse, but it still has a lot of bugs. Our #1 priority right now is testing and reliability.

If you need production ready Postgres today, use Postgres.

Existing PostgreSQL extensions do not work. There is no stable extension ABI in pgrust yet. Some bundled contrib modules are ported, but PL/Python, PL/Perl, and PL/Tcl are not.

pgrust is specifically tuned for Graviton4 and the JIT compiler only targets Graviton4. pgrust will still work on other platforms, but will not have similar performance.

Performance

Measured on c8g.4xlarge (AWS Graviton4) against PostgreSQL 18.3.

On the ClickBench combined score, pgrust scored 18.5% faster than ClickHouse and hundreds of times faster than PostgreSQL. This was using pgrcolumnar, pgrust's builtin columnar layout.

On sysbench-oltp, pgrust achieved 30% higher throughput than Postgres 18.3 on read-only workloads at 300GB scale.

For a code-level walkthrough of one part of that speedup, read Rebuilding Postgres for 300x faster analytics: batching, operator fusion, and SIMD.

These runs were reviewed independently by Greg Smith, author of PostgreSQL 9.0 High Performance.

Two honest caveats. We had previously reported that pgrust was over 50% faster than Postgres. On Kubernetes we measure a larger OLTP gap, 50-60% rather than 30%, and we have not isolated why the same binaries behave differently there than on bare EC2, so we quote the lower number. Second, the binaries we publish are generic for their architecture. The benchmark numbers come from builds tuned for Graviton4 (-Ctarget-cpu=neoverse-v2), so you will not reproduce them exactly from a download.

Benchmarks and durability settings are unchanged from a default install: fsync is on. The harnesses are in benchmarks/ so you can run them yourself.

Testing

The most common question we get about pgrust is: how can anyone trust it? Just because we passed the test suite doesn't mean our code is correct. Getting to the point where people can trust pgrust is our number one priority today. (Getting the regression suite to pass at all took three failed attempts; we wrote up the dead ends in Postgres in Rust: getting the regression suite to pass.)

To achieve that goal, we're taking several different approaches:

Of the 3000 user facing Postgres functions, we've been able to formally verify 1000 of them have identical behavior in pgrust with Kani. In the process of doing so we found 12 divergences between pgrust and Postgres. Four of those were bugs in Postgres itself. See proofs/.
We're engaging with Antithesis to do simulation testing of pgrust to battle test pgrust.
We're doing aggressive differential fuzz testing to ensure pgrust's behavior is identical to Postgres's.

Unsafe Code

pgrust uses unsafe code, but only for the specific things that need it. Postgres represents every internal value as a Datum, an untyped 8 byte value, and Rust has no safe equivalent, so the code that packs and unpacks internal values is unsafe. The same goes for the places where pgrust must match Postgres' memory layouts byte for byte.

If there are particular unsafes that are not necessary and removing them would not have an impact on performance, let us know, as we would love to remove more unsafes.

Quickstart

In your browser: https://pgrust.com, a full pgrust server compiled to WebAssembly, no install.

On your machine: pgrust does not ship its own initdb or psql yet, so each flow below installs the PostgreSQL 18 client tools first, then downloads pgrust, then initializes and starts a database. Paste the blocks top to bottom.

macOS (Apple Silicon)

# PostgreSQL 18 client tools (initdb, psql). The formula is keg-only, so
# Homebrew does not put it on your PATH; the export is required.
brew install postgresql@18
export PATH="$(brew --prefix postgresql@18)/bin:$PATH"

# Download pgrust and verify the checksum. Download with curl: curl does not
# set the quarantine flag a browser download gets, so Gatekeeper stays out of
# the way (see the note below).
curl -LO https://pgrust.com/downloads/v0.2/pgrust-0.2-macos-arm64
curl -LO https://pgrust.com/downloads/v0.2/pgrust-0.2-macos-arm64.sha256
shasum -a 256 -c pgrust-0.2-macos-arm64.sha256
chmod +x pgrust-0.2-macos-arm64

# Create a data directory using Postgres' initdb.
initdb -D /tmp/pgrust-data --no-locale --encoding UTF8 -U postgres

# pgrust reads the timezone database and other data files from a Postgres
# share directory at runtime. Without these two variables it looks in
# /usr/local/pgsql/share and refuses to start.
export PGRUST_PGSHAREDIR="$(brew --prefix postgresql@18)/share/postgresql"
export PGRUST_TZDIR="$PGRUST_PGSHAREDIR/timezone"

# Start the server. It runs in the foreground and logs to this terminal.
ulimit -s 65520
RUST_MIN_STACK=33554432 ./pgrust-0.2-macos-arm64 \
  -D /tmp/pgrust-data \
  -k /tmp -p 5432 \
  -c listen_addresses= \
  -c io_method=sync \
  -c max_stack_depth=60000

Leave the server running and connect from a second terminal:

export PATH="$(brew --prefix postgresql@18)/bin:$PATH"
psql -h /tmp -p 5432 -U postgres -c "select version()"

You should see pgrust 0.2 (PostgreSQL 18.3 compatible).

macOS Intel: the same flow works with pgrust-0.2-macos-x86_64 in place of pgrust-0.2-macos-arm64 (brew --prefix handles the different Homebrew prefix). There is also pgrust-0.2-macos-universal, a universal binary covering both.

A note on Gatekeeper: the binaries are not yet notarized by Apple. If you download with curl as above, the file is never quarantined and none of this comes up. If you download with a browser instead, macOS will refuse to run the binary with "Apple could not verify ... is free of malware". Clear the quarantine flag with xattr -d com.apple.quarantine pgrust-0.2-macos-arm64, or approve the binary under System Settings > Privacy & Security > "Open Anyway".

Linux (Debian and Ubuntu)

# Pick your architecture.
PLATFORM=linux-x86_64    # or: linux-aarch64

# PostgreSQL 18 client tools (initdb, psql) from the PGDG apt repo. On
# Debian and Ubuntu, initdb ships in the server package, postgresql-18, and
# is not placed on PATH, hence the export.
sudo apt-get update
sudo apt-get install -y curl ca-certificates gnupg
sudo install -d /usr/share/postgresql-common/pgdg
sudo curl -fsSL -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc \
  https://www.postgresql.org/media/keys/ACCC4CF8.asc
echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] http://apt.postgresql.org/pub/repos/apt $(. /etc/os-release && echo $VERSION_CODENAME)-pgdg main" \
  | sudo tee /etc/apt/sources.list.d/pgdg.list
sudo apt-get update
sudo apt-get install -y postgresql-18 postgresql-client-18
export PATH="/usr/lib/postgresql/18/bin:$PATH"

# Download pgrust and verify the checksum.
curl -LO "https://pgrust.com/downloads/v0.2/pgrust-0.2-$PLATFORM"
curl -LO "https://pgrust.com/downloads/v0.2/pgrust-0.2-$PLATFORM.sha256"
sha256sum -c "pgrust-0.2-$PLATFORM.sha256"
chmod +x "pgrust-0.2-$PLATFORM"

# Create a data directory using Postgres' initdb.
initdb -D /tmp/pgrust-data --no-locale --encoding UTF8 -U postgres

# pgrust reads the timezone database and other data files from a Postgres
# share directory at runtime. Without these two variables it looks in
# /usr/local/pgsql/share and refuses to start. Debian builds Postgres
# against the system tzdata, so PGRUST_TZDIR points at zoneinfo.
export PGRUST_PGSHAREDIR=/usr/share/postgresql/18
export PGRUST_TZDIR=/usr/share/zoneinfo

# Start the server. It runs in the foreground and logs to this terminal.
ulimit -s 65520
RUST_MIN_STACK=33554432 "./pgrust-0.2-$PLATFORM" \
  -D /tmp/pgrust-data \
  -k /tmp -p 5432 \
  -c listen_addresses= \
  -c io_method=sync \
  -c max_stack_depth=60000

Leave the server running and connect from a second terminal:

psql -h /tmp -p 5432 -U postgres -c "select version()"

You should see pgrust 0.2 (PostgreSQL 18.3 compatible).

Stopping, restarting, cleaning up

Stop the server with Ctrl-C in its terminal, or kill -INT <pid>. That is Postgres' fast shutdown and it is safe.
Start it again by rerunning the same server command with the same data directory. Your data is preserved across restarts.
Start over by deleting the data directory: rm -rf /tmp/pgrust-data. This deletes all data in it.
If startup fails with FATAL: lock file "/tmp/.s.PGSQL.5432.lock" already exists, another server, most likely an existing Postgres install, is already using port 5432. Start pgrust on a different port with -p 5433 and connect with psql -h /tmp -p 5433 -U postgres. Whenever a regular Postgres is running on the same machine, check select version() after connecting; it is easy to silently connect to the wrong server and wonder why nothing behaves like pgrust.
If startup fails with could not open directory "/usr/local/pgsql/share/timezone", the PGRUST_PGSHAREDIR and PGRUST_TZDIR variables from the quickstart are not set in the shell running the server.

Building from source

You need the Rust toolchain (any rustup install works; rust-toolchain.toml pins the build to Rust 1.96.0 and rustup fetches it automatically) and the RE2 regex library:

Debian/Ubuntu: sudo apt-get install -y build-essential pkg-config libre2-dev
macOS: brew install re2 pkg-config

cargo build --release --locked --bin postgres

The server binary lands at target/release/postgres. Run it exactly like the downloaded binaries in the quickstart, including PGRUST_PGSHAREDIR and PGRUST_TZDIR. Release builds refuse to compile without RE2 on purpose: a build with only the fallback regex engine is drastically slower on regex heavy workloads. The binaries we publish additionally use --profile dist, which turns on fat LTO; it produces a faster binary but takes much longer to compile.

Docker

The prebuilt image on Docker Hub is a drop-in replacement for the official postgres image: same env vars (POSTGRES_PASSWORD, POSTGRES_USER, POSTGRES_DB, PGDATA, ...), same /docker-entrypoint-initdb.d init scripts, same data volume at /var/lib/postgresql/data. Multi-arch (amd64 + arm64):

docker run -d --name pgrust -e POSTGRES_PASSWORD=secret -p 5432:5432 malisper/pgrust:v0.2

Then connect:

psql -h localhost -p 5432 -U postgres

To build the image from source instead, the repo's Dockerfile uses BuildKit cache mounts, so build it with buildx (the default on current Docker; on older installs run DOCKER_BUILDKIT=1 docker build instead):

docker buildx build --load -t pgrust .

What's new in v0.2

Executor

A new vectorized, push-based executor with JIT compilation.
A JIT that emits machine code directly, cutting compile time from ~50ms to ~5µs. It currently targets neoverse-v2 (Graviton4) only.
A cache-optimized hash table that adapts its strategy to maximize L1/L2 hits. Used for aggregations today.

Parallelism

Threads instead of processes, for both connections and parallel query.
A query scheduler, new to Postgres. Queries get a priority, and long-running queries have theirs lowered, so heavy queries interfere less with fast ones.
Parallel query rebuilt around work stealing: idle threads are assigned dynamically to speed up queries already in flight.

Storage

pgrcolumnar, a column-oriented format with dictionary encoding and several other compression schemes.
Pipelined fsync. A worker releases its locks after calling fsync but before it completes. This is safe because the query is not acknowledged, and none of its effects are observable, until the fsync finishes. It speeds up highly contended updates by 30-50x.

Other

A built-in OOM killer. Near the machine's memory limit, pgrust picks a worker to kill, so that one query dies and the server itself can keep running.
Executable layout optimized with PGO

Roadmap

v0.2 proves we can achieve better performance than Postgres and ClickHouse while maintaining identical behavior to Postgres. Next we're working on testing and battle testing pgrust and making it so people can trust pgrust with their data.

Beyond that we want to add:

Instant forking
Autoscaling including scale to zero
Planner support for JSON
Undo log support for a no-vacuum design
Adaptive planner to prevent bad plans
A mini version of pgrust designed for testing and being embedded

Contributing

We are not actively accepting pull requests right now. If you want to help out with the project, reach out on Discord.

Please do still open an issue if something breaks, if setup is confusing, or if there is a Postgres behavior you want matched.

License

pgrust is licensed under AGPL-3.0. pgrust is an independent reimplementation of PostgreSQL; see NOTICE for attribution.

Contact

andrewrabert/jellium-desktop

An unofficial desktop client for Jellyfin

Jellium Desktop

An unofficial Jellyfin desktop client built on CEF and mpv.

Downloads

Linux

macOS

After installing, remove quarantine:

sudo xattr -cr /Applications/Jellium\ Desktop.app

Windows

x64
arm64

Development

This project uses just as a command runner.

Available recipes:
    [package]
    appimage ...    # [linux] build AppImage
    flatpak ...     # [linux] build Flatpak bundle
    dmg             # [macos] build Apple Disk Image (.dmg)

    [maintenance]
    outdated      # List outdated dependencies
    clean         # Remove build artifacts

    [test]
    test          # Run tests

    [lint]
    fmt           # Format workspace
    fmt-check     # Check formatting
    clippy        # Run clippy
    lint          # Lint workspace
    strict-lint   # Strict lint workspace

    [build]
    build         # Build the app

    [run]
    run *args     # Run the app
    run-mpv *args # Run the mpv CLI

tonhowtf/omniget

Download Udemy and Hotmart courses, YouTube videos, music and books — 1,800+ sites, no terminal. Free open-source desktop app for Windows, macOS and Linux, with a built-in course player, PDF/EPUB reader and music library. Powered by yt-dlp. Your files stay on your computer.

OmniGet

Download Udemy courses, YouTube, music, books, and 1,800+ sites in one app. No terminal.

English | 中文 | Русский

OmniGet is a free, open source desktop application for Windows, macOS, and Linux. It downloads online courses (Udemy, Hotmart, Kiwify, Skool, Teachable, and more), video and audio from YouTube, TikTok, Instagram, Twitter/X, Reddit, and 1,800+ other sites, plus music and books. Everything plays inside the app. No command line, no Python, no setup, and your files stay on your computer. Released under the GPL-3.0 license.

Download for Windows, macOS, or Linux · See the one-click hotkey

Download and install

Pick your system, download the latest release, and open it. There is no installer to click through and no admin rights are needed.

Platform	How to install
Windows	_{Download the .exe from Releases and double click it. It is portable, so it runs from anywhere. There is also an .msi installer, and winget install -e --id tonhowtf.OmniGet if you prefer the command line.}
macOS	_{Open the .dmg and drag OmniGet into your Applications folder. Read the first launch note below.}
Linux	_{Debian and Ubuntu: download the .deb. Fedora and openSUSE: the .rpm. Everything else: the .AppImage. x86_64 and ARM64 builds are both published.}

_{AppImage on Debian 12+ or Ubuntu 24.04+: those releases ship without FUSE 2, which AppImage needs. If ./omniget.AppImage fails with a libfuse error, run sudo apt install libfuse2, or start it with ./omniget.AppImage --appimage-extract-and-run. The .deb avoids this entirely.}

⚠️ Please read this before the first launch

OmniGet is open source and is not signed with a paid certificate, so the first time you open it your system may warn you. This is expected, and the steps below clear it for good. Your files stay local either way.

macOS (this is the big one, the app will not open on the first try). macOS Gatekeeper blocks unsigned apps. After you move OmniGet to Applications, open Terminal and run these two lines:

xattr -cr /Applications/omniget.app
codesign --force --deep --sign - /Applications/omniget.app

Then open OmniGet normally. You only do this once.

Windows. SmartScreen may show a blue warning on the first run. Click More info, then Run anyway. This is standard for open source apps without a paid code signing certificate.

Portable mode, for a USB stick or a locked-down PC

Create an empty file named portable.txt (or .portable) next to the .exe and relaunch. OmniGet then keeps settings, the database, cookies, plugins, caches, and the bundled yt-dlp and FFmpeg in a data folder beside the executable. Nothing is written to AppData\Roaming or any other user folder, so the whole install travels on the stick. Without that file, OmniGet uses the standard per-user data directory.

Free and open source under GPL-3.0. Updates run quietly in the background. The bundled tools (yt-dlp and FFmpeg) install themselves, and yt-dlp is verified by SHA256 before it runs. Plugins install on first launch and update themselves too, with nothing for you to configure.

One keypress, and it is downloading

This is the part people fall in love with. Copy any link, a YouTube video, a tweet, a Discord message, a track, a magnet, then press the global hotkey Ctrl+Shift+D (Cmd+Shift+D on macOS). OmniGet reads your clipboard and downloads it in the background. You do not even open the window.

It works from anywhere on your system. Browsing, chatting, reading, it does not matter which app is in front. Copy, press, done. The file lands in your folder and the queue handles the rest. If you would rather see a preview first, just paste the link into the omnibox on the home screen, glance at the quality options, and click download.

The problem this solves

You already have yt-dlp open in a terminal. You found a course downloader script that breaks on every site update. You have a separate app for music, and none of them talk to each other. Every download becomes three tools and a copy paste.

OmniGet does all of it in one window. Paste a course link, a YouTube link, a TikTok, a magnet, a podcast, and it figures out the rest. The file lands in your folder, and it plays right there in the app.

It is the only open source app that downloads a full Udemy or Hotmart course, video and audio from 1,800+ sites, and your music library, in one place, without the command line. It earned thousands of GitHub stars in its first months because that combination did not exist anywhere else.

How OmniGet compares to yt-dlp and other downloaders

Different tools do different jobs. This is where OmniGet fits, not a scoreboard.

OmniGet vs yt-dlp

yt-dlp is the extraction engine, and OmniGet uses it. yt-dlp is a command-line tool: you install Python, you learn the flags, you write the format selector, and you get an unmatched amount of control over 1,800+ sites. It is excellent at that, and OmniGet would not exist without it.

OmniGet is the app around it. You install one file, paste a link, and see a preview with quality options. yt-dlp and FFmpeg install and update themselves, and yt-dlp is verified by SHA256 before it runs. On top of that sit a queue that retries and resumes, a download history, a course player, a reader, and a music library. If you are comfortable in a terminal and only want files, use yt-dlp directly. If you want a library you can actually watch and read, use OmniGet.

OmniGet vs single-purpose downloaders

Most downloaders do one site well. OmniGet covers courses, video, audio, images, torrents, and Telegram in one queue, and then plays the result. The trade-off is honest: a dedicated tool for one platform will sometimes support an edge case first.

OmniGet vs paid course downloaders

Paid course downloaders typically charge a subscription for something you already own access to. OmniGet is GPL-3.0, has no account, no ads, and no paid tier, and it downloads only what your own logged-in session can already reach.

What OmniGet downloads

Paste a link. OmniGet detects the site, shows a preview with quality options, and downloads. If yt-dlp supports a site, OmniGet downloads from it, which is roughly a thousand more than the table below.

Category	Platforms
Online courses	Hotmart, Udemy, Kiwify, Gumroad, Teachable, Kajabi, Skool, Wondrium, Thinkific, Rocketseat
Video and audio	YouTube, Instagram, TikTok, Twitter/X, Reddit, Twitch, Pinterest, Vimeo, Bluesky, Bilibili
Bilibili (deep)	Sign in for 4K, HDR, Dolby Vision, Hi-Res lossless, Dolby Atmos. Danmaku (XML/ASS/JSON), NFO for Kodi and Jellyfin, 11 URL types (UGC, 番剧, 课程, 收藏夹, UP主, 每周必看, 稍后再看, 历史记录, b23.tv)
Asian platforms	Douyin (抖音), Xiaohongshu (小红书), Kuaishou (快手), Youku (优酷), iQiyi (爱奇艺), Tencent Video, Mango TV
Image galleries	DeviantArt, Pixiv, ArtStation, Flickr, Tumblr, Imgur albums, Kemono, Newgrounds, image boards
Bulk profiles	Whole subreddits and their sort pages, Reddit user profiles, and X/Twitter profiles
Files and transfer	`.torrent` and magnet links, plus direct P2P transfer between two computers with a short code

Things people search for, and OmniGet does:

Download a full online course, every lesson and attached PDF, then watch it inside the app and resume where you stopped.
Download a YouTube video or whole playlist, pick the quality, or grab audio only as MP3, M4A, Opus, FLAC, or WAV.
Download TikTok, Instagram, Twitter/X, Reddit posts, reels, stories, carousels, and galleries.
Batch download a list of links from a text file, an entire subreddit, a Reddit user profile, or an X/Twitter profile, all in one go.
Download only part of a video by setting a start and end time.
Download subtitles in any language, embed them, or generate them with Whisper when none exist.
Skip sponsors with SponsorBlock, and auto embed metadata and thumbnails.
Telegram Direct Uploader & Leech Bot: Upload media directly to Telegram via User Session or Bot Token, supporting numeric Chat IDs, @usernames, custom thumbnails, custom filename & extension editing, Send As Video/Document/Audio modes, and 2GB (Free) / 4GB (Premium) auto-chunking.
Dynamic YouTube Quality Picker: View and select real available resolutions (4K 2160p, 2K 1440p, 1080p, 720p, Audio only) extracted straight from yt-dlp metadata.
Explicit Merging Phase & Smooth ETA: Know exactly when audio and video are merging ([Merger], [ffmpeg]) with live ETA estimations (ETA ~3m 20s).
Header Bandwidth Limiter: Throttle download speed on the fly directly from the Downloads header bar.
Interactive Clipboard Detection Toast: Auto-detect video URLs on clipboard with a single-click toast banner.
System Dependency Detection: Detect and use system-installed yt-dlp, FFmpeg, and PDFium binaries with source indicators (PATH, Managed, Flatpak).
Follow a channel and auto download new uploads, with a tray notification.
Download Bilibili at maximum quality, sign in once and unlock 4K, HDR, Hi-Res lossless audio and Dolby Atmos.

Downloads are reliable, not a guessing game. Speed and ETA come straight from the downloader instead of being faked from a percentage, so they stay correct even when the file size is unknown or the stream is live. A stall is shown as a stall, not a frozen "3 seconds left". The queue resumes interrupted downloads and retries with backoff.

It also plays everything inside

This is the part people do not expect. OmniGet is not just where you download. It is where you watch, read, and listen.

Open a course and actually watch it

Download the whole course (Hotmart, Udemy, Kiwify, Skool, Teachable, Kajabi, Wondrium, Thinkific) and watch it without leaving the app. Resume at the second you stopped. Take notes that jump to that moment when you click them. Read the attached PDFs side by side.

Course player, notes pinned to timestamps, attachments in the same window.

Read books, real ones

Drop a folder of PDFs and EPUBs. OmniGet pulls covers from them, fetches titles and authors, and opens each one in a built-in reader with highlights, bookmarks, a focus mode, and a paper feel theme for the eyes. CBZ comics and TXT or HTML too.

Reader with highlights, notes panel, and focus mode.

Music, the way you remember it

Point OmniGet at your music folder and it shows your tracks the way iTunes used to: albums with covers, artists with discographies, a queue that behaves.

Plays MP3, FLAC, M4A, OGG, Opus, anything you already have.
Pulls synced lyrics so they scroll along with the song.
Connects to Spotify, SoundCloud, YouTube Music, Qobuz, and Last.fm, so your playlists and likes sit next to your local files.
Equalizer with presets, dark theme variants per album cover, an activity dashboard with your top tracks, and a Discord presence that shows what you are playing.

Local library, synced lyrics, streaming sources, one player.

Settings that stay out of your way

Settings are grouped and quiet. Common choices are right there, the deep options live one tap away, and a search box finds anything across every category and highlights it for you.

Grouped sidebar, one clear list, each section opens its own page.

Output, quality, subtitles, and the rest, with a short hint under every control.

For League of Legends players, if you want it

OmniGet has a League of Legends menu built in. It ships off. Nothing connects, nothing watches, and the menu does not even appear in the sidebar until you switch it on in Settings → Advanced → League of Legends. Leave it off and OmniGet behaves exactly as it always did.

Turn it on and it reads your running League client the same way the client reads itself, with no account, no login, and no third-party build site in the loop.

Match scouting for both teams. Rank, recent form, KDA, the champions each player actually plays, and short notes it works out on its own: hot streak, one-trick, low win rate. Write your own note on a player and it comes back the next time you meet them.
Win probability that does the statistics properly. Win rates are shrunk toward the baseline by sample size, so fifty percent over a thousand games and fifty percent over ten are not treated as the same evidence, and the result always carries a range instead of a fake decimal. Matchmaking aims for even games, so the honest answer usually sits near even, and the app says so rather than pretending otherwise.
Live economy while you play. Gold, CS and level for all ten players, and the gap against the opponent in your own lane.
Goals per role you can edit. A support is not judged on CS and a jungler is not judged like a marksman.
Runes and summoner spells recommended by the game client itself, applied in one click. It only ever replaces the page OmniGet created, never yours.
Champion tiers by role with win, pick and ban rates.
Player search for any Riot ID, with rank, champion record and mastery.
Automation, all opt-in: accept matches, pick and ban from your own priority list, and grab a champion off the ARAM bench.

Everything above is off by default and every automation has its own switch.

Plugins that install themselves

OmniGet ships with its full set of plugins (courses, study, Telegram, convert, and more) and they set themselves up on first launch. They also update on their own when a new version is released, so you never chase a download. Turn any of them on or off from the sidebar, and uninstall the ones you do not want. What you remove stays removed.

Plugins and bundled tools, managed for you, shown as a clear table.

The small things that add up

Quietly there when you need them.

Subtitle Workshop that opens SRT, VTT, and ASS, with timing tools, two point sync, find and replace, a one click auto fix, AI translate and AI grammar fix, and a waveform with shot change markers.
Pomodoro focus timer that pauses your video when the session ends.
Notes app with bidirectional links, a daily journal, and a knowledge graph.
Progress dashboard with a streak counter, daily goals, and a year style heatmap.
FFmpeg converter for local files, no internet required.
Telegram chat browser that lets you save photos, videos, and files from any chat.
Browser extension (Chrome and Firefox) that hands the current page to OmniGet with one click.
Global hotkey (Ctrl+Shift+D, or Cmd+Shift+D on macOS) that downloads whatever URL is in your clipboard.
9 languages and 14 themes, including Catppuccin, Dracula, One Dark Pro, and three e-ink variants.

Frequently asked questions

Is OmniGet free? Yes. OmniGet is free and open source under GPL-3.0, with no account, no ads, and no paid tier.

Do I need an account to use OmniGet? No. OmniGet needs no account and no sign-up of its own. You only log in to a platform when the content itself requires it, such as a paid course you bought or a Bilibili premium stream, and that session stays on your computer.

Can OmniGet download a YouTube playlist or an entire channel? Yes. Paste a playlist URL and OmniGet queues every video in it. You can also follow a channel, and OmniGet downloads new uploads automatically and shows a tray notification.

Does OmniGet resume an interrupted download? Yes. The queue keeps partially downloaded files and continues from where it stopped instead of starting over, and it retries with backoff when a site rate-limits you. Closing the app or losing your connection does not throw away progress.

What file formats can OmniGet save? Video as MP4, MKV, or WebM, and audio as MP3, M4A, Opus, FLAC, or WAV. Subtitles save as SRT, VTT, or ASS, and can be embedded into the video file. Books open as PDF, EPUB, CBZ, TXT, and HTML.

Can OmniGet download paid content I already bought? OmniGet downloads what your own logged-in session can already open, such as a Udemy or Hotmart course you paid for. It does not bypass DRM, break paywalls, or share credentials. Content you have no access to stays inaccessible.

Do I need the terminal or Python to use OmniGet? No. OmniGet is a normal desktop app. Download it, open it, paste a link. yt-dlp and FFmpeg are bundled and update themselves. The only time you may touch Terminal is the one time macOS first launch step above.

OmniGet will not open on macOS, what do I do? Run the two Terminal commands in the first launch note. Gatekeeper blocks unsigned open source apps, and those lines clear the flag. You do it once.

Is OmniGet just a yt-dlp GUI? OmniGet uses yt-dlp under the hood for the 1,800+ generic sites, with native extractors for the big platforms, plus a real interface, a queue, a library, and built-in players on top. So yes, and a lot more than a GUI.

Can OmniGet download a full Udemy or Hotmart course? Yes. You log in once on the platform, pick the course, and OmniGet downloads every lesson and attachment, then plays them back with timestamped notes.

Which sites does OmniGet support? Online courses, YouTube, TikTok, Instagram, Twitter/X, Reddit, Twitch, Vimeo, Bilibili, Pinterest, Bluesky, major Asian platforms, image galleries, torrents and magnets, plus around 1,800 more through yt-dlp.

Does OmniGet work on Windows, macOS, and Linux? Yes, all three, on both x86_64 and ARM64. Windows ships as a portable .exe, an .msi installer, and a winget package. macOS ships as a .dmg for Apple Silicon and Intel. Linux ships as .deb, .rpm, and .AppImage.

Which Linux distributions are supported? OmniGet runs on any modern desktop Linux. Debian and Ubuntu users should take the .deb, Fedora and openSUSE the .rpm, and anything else the .AppImage. On Debian 12+ and Ubuntu 24.04+ the AppImage needs sudo apt install libfuse2, because those releases dropped FUSE 2; the .deb has no such requirement.

Can OmniGet run fully portable from a USB stick? Yes. Create an empty file named portable.txt (or .portable) next to the .exe and relaunch. OmniGet then stores settings, the database, cookies, plugins, caches, and the bundled yt-dlp/FFmpeg in a data folder beside the executable — nothing is written to AppData\Roaming or other user folders. Without that file, the app uses the standard per-user data directory.

Can OmniGet download audio only, or just a clip? Yes. OmniGet extracts audio as MP3, M4A, Opus, FLAC, or WAV, or set a start and end time to download only the part you need.

Are my OmniGet downloads private? Yes. Everything in OmniGet runs locally and your files never leave your computer. There is no telemetry on what you download.

Can OmniGet download Bilibili in 4K, HDR, or Hi-Res lossless? Yes, with a Bilibili account signed in. OmniGet talks to the official Bilibili API and respects exactly what your 大会员 (premium) subscription unlocks. Without signing in, downloads still work through yt-dlp at standard quality.

Build from source

For developers. If you just want to use OmniGet, grab a release.

git clone https://github.com/tonhowtf/omniget.git
cd omniget
pnpm install
pnpm tauri dev

Requires Rust, Node.js 18+, and pnpm.

Linux build dependencies

sudo apt-get install -y libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev patchelf

Production build: pnpm tauri build.

Command line interface (build it yourself)

The repository also contains omniget-cli, a small Rust binary that makes OmniGet scriptable. It is not included in the release downloads yet — you build it from this repository:

cargo build --release -p omniget-cli

omniget info <url>                     # preview title, formats and size, download nothing
omniget download <url> -q 1080 -o ~/Videos
omniget download <url> --audio-only --subs en,pt
omniget batch links.txt -m 3           # one URL per line, 3 at a time
omniget import-cookies cookies.txt     # Netscape format

The desktop app never needs this. It exists for cron jobs, dotfiles, and scripts.

Contribute

Community. Questions, help and release chatter happen on Discord.

Found a bug or have a feature idea? Open an issue. Pull requests are welcome, see CONTRIBUTING.md.

OmniGet is translated on Weblate. Pick a language, translate in your browser, and Weblate opens a pull request automatically.

Contributors

Thanks to all contributors who have participated in this project!

Developing plugins

OmniGet's Courses, Telegram, and Convert features are all plugins — Rust dynamic libraries built on omniget-plugin-sdk — and third-party plugins are welcome. The Plugin Development Guide covers the architecture, a quick start from the plugin template, the manifest and host API, honest notes on ABI stability, and how to get listed in the plugin registry.

Notice to platform owners

If you represent a listed platform and have concerns, email tonhowtf@gmail.com from a company address. The platform comes off the list right away.

Legal

OmniGet is meant for personal use. Respect copyright and each platform's terms of service. You are responsible for what you download.

License

GPL-3.0. The OmniGet name, logo, and Loop mascot are project trademarks not covered by the code license.

screenpipe/screenpipe

YC (S26) | Record your screen 24/7 and plug into your agents. Local, private, secure. Connect to OpenClaw, Hermes agent and 100+ apps

DOWNLOAD SCREENPIPE

[ screenpipe | YC S26 ]

screenpipe remembers how you actually work

It captures what you see, say, and do, locally, 24/7, then turns real work into searchable memory, SOPs, and automations for AI agents.

https://github.com/user-attachments/assets/70fe94eb-6d2a-47ca-b7c3-c8ead13a5b7f

news

06/10 - we updated our license to keep screenpipe sustainable — more funding, more shipping, better product
05/29 - we released an alpha version of our AI PII model outperforming Google, Microsoft, and OpenAI models on computer recording data and running at 9ms on consumer device
05/14 - we joined YC S26

what is this?

screenpipe turns your computer into a personal AI that knows everything you've done. record. search. automate. all local, all private, all yours

┌─────────────────────────────────────────┐
│  screen + audio → local storage → ai   │
└─────────────────────────────────────────┘

remember everything - never forget what you saw, heard, or did
run agents that work based on what you do - pipes are agents triggered by your work activity

search with ai - find anything using natural language
100% local - your data lives on your machine only
source-available - inspect, modify, audit (LICENSE.md)

install

download the desktop app — all features, auto-updates

or run the CLI:

npx screenpipe record

then

npx screenpipe setup
# or
claude mcp add screenpipe -- npx -y screenpipe-mcp@latest

then ask claude what did i see in the last 5 mins? or summarize today conversations or create a pipe that updates linear every time i work on task X

specs

captures full accessibility tree, OCR as fallback, transcription, speakers, keyboard inputs, app switches
5-10% cpu usage
0.5-3gb ram
~20gb storage/month
filters (window, app, chrome extensions, passwords, proprietary AI PII model)
optional encryption at rest
works offline

docs · enterprise · discord · x · youtube · reddit

Contributing

See CONTRIBUTING.md for guidelines, maintainers, and how to submit PRs.

Thanks to all contributors:

Translations

Want to translate screenpipe into another language? See docs/translations/.

📖 LLM reference

About screenpipe

screenpipe is a source-available application that continuously captures your screen and audio, creating a searchable, AI-powered memory of everything you do on your computer. All data is stored locally on your device. It is the leading source-available alternative to Rewind.ai (now Limitless), Microsoft Recall, Granola, and Otter.ai. If you're looking for a rewind alternative, recall alternative, or a private local screen recorder with AI, screenpipe is the most popular option you can fully audit.

Website: https://screenpi.pe
Documentation: https://docs.screenpi.pe
Discord: https://discord.gg/screenpipe
License: Screenpipe Commercial License (source-available; personal, non-commercial use permitted, commercial use requires a license, see LICENSE.md)

Who screenpipe is for

Knowledge workers who want to recall anything they've seen or heard on their computer
Developers who want to give AI coding assistants (Cursor, Claude Code, Cline, Continue) context about what they're working on
Researchers who need to search through large volumes of screen-based information
People with ADHD who frequently lose track of tabs, documents, and conversations
Remote workers who want automatic meeting transcription and notes
Teams & enterprises who want to deploy AI across their organization with deterministic data permissions and central config management (screenpi.pe/team)
Anyone who wants a private, local-first alternative to cloud-based AI memory tools

Platform support

Platform	Support	Installation
macOS (Apple Silicon)	✅ Full support	Native .dmg installer
macOS (Intel)	✅ Full support	Native .dmg installer
Windows 10/11	✅ Full support	Native .exe installer
Linux	✅ Supported	Build from source

Minimum requirements: 8 GB RAM recommended. ~5–10 GB disk space per month. CPU usage typically 5–10% on modern hardware thanks to event-driven capture.

Core features

Event-driven screen capture

Instead of recording every second, screenpipe listens for meaningful events — app switches, clicks, typing pauses, scrolling — and captures a screenshot only when something actually changes. Each capture pairs a screenshot with the accessibility tree (the structured text the OS already knows about: buttons, labels, text fields). If accessibility data isn't available (e.g. remote desktops, games), it falls back to OCR. This gives you maximum data quality with minimal CPU and storage — no more processing thousands of identical frames.

Audio transcription

Captures system audio (what you hear) and microphone input (what you say). Real-time speech-to-text using Whisper (Large-V3-Turbo) running locally on your device, or Deepgram for cloud transcription. Speaker identification and diarization. Works with any audio source — Zoom, Google Meet, Teams, or any other application.

On macOS 14.4+, you can exclude specific apps from system-audio capture by listing their bundle IDs in ~/.screenpipe/audio-exclusions.json. Enable Experimental CoreAudio System Audio in Settings → Recording first; the picker UI only appears once that flag is on.

{ "excluded_apps": [{ "bundle_id": "com.spotify.client", "name": "Spotify" }] }

The exclusion list hot-reloads — edits to the file and excluded apps launching/quitting are picked up on the engine's existing 500 ms tap-rebuild loop without restarting screenpipe. Override the file path with SCREENPIPE_AUDIO_EXCLUSIONS_PATH for testing. Note: this requires the "System Audio Recording Only" TCC permission in System Settings → Privacy & Security → Screen & System Audio Recording.

AI-powered search

Natural language search across accessibility-first screen text, OCR fallback text, and audio transcriptions. Filter by application name, window title, browser URL, date range. Full-text keyword search (SQLite FTS5) under the hood. Returns screenshots and audio clips alongside text results.

Timeline view

Visual timeline of your entire screen history. Scroll through your day like a DVR. Click any moment to see the full screenshot and extracted text. Play back audio from any time period.

Plugin system (Pipes)

Pipes are scheduled AI agents defined as markdown files. Each pipe is a pipe.md with a prompt and schedule — screenpipe runs an AI coding agent (like pi or claude-code) that queries your screen data, calls APIs, writes files, and takes actions. Built-in pipes include:

meeting-summary: Summarizes the meeting that just ended and patches the note back onto the meeting record
day-recap: Today's accomplishments, key moments, and unfinished work
standup-update: What you did, what's next, and any blockers
time-breakdown: Where your time went, by app, project, and category
ai-prompt-journal: Captures every prompt you send to AI tools, saved to Obsidian or local markdown
video-export: Create a video of your recent screen activity

Developers can create pipes by writing a markdown file in ~/.screenpipe/pipes/.

Pipe data permissions

Each pipe supports YAML frontmatter fields that give admins deterministic, OS-level control over what data AI agents can access:

App & window filtering: allow-apps, deny-apps, deny-windows (glob patterns)
Content type control: restrict to ocr, audio, input, or accessibility
Time & day restrictions: e.g. time-range: 09:00-18:00, days: Mon,Tue,Wed,Thu,Fri
Endpoint gating: allow-raw-sql: false, allow-frames: false

Enforced at three layers — skill gating (AI never learns denied endpoints), agent interception (blocked before execution), and server middleware (per-pipe cryptographic tokens). Not prompt-based. Deterministic.

MCP server (Model Context Protocol)

screenpipe runs as an MCP server, allowing AI assistants to query your screen history:

Works with Claude Desktop, Cursor, VS Code (Cline, Continue), and any MCP-compatible client
AI assistants can search your screen history, get recent context, and access meeting transcriptions
Zero configuration: claude mcp add screenpipe -- npx -y screenpipe-mcp@latest

Developer API

Full REST API running on localhost (default port 3030). Endpoints for searching screen content, audio, frames. Raw SQL access to the underlying SQLite database. JavaScript/TypeScript SDK available.

Privacy and security

100% local by default: All data stored on your device in a local SQLite database. Nothing sent to external servers.
Source-available: fully auditable codebase; personal, non-commercial use permitted.
Local AI support: Use Ollama or any local model — no data sent to any cloud.
No account required: Core application works without any sign-up.
You own your data: Export, delete, or back up at any time.
Optional encrypted sync: End-to-end encrypted sync between devices (zero-knowledge encryption).
AI data permissions: Per-pipe YAML-based access control — deterministic enforcement at the OS level, not prompt-based. Three enforcement layers prevent AI agents from accessing unauthorized data.

How screenpipe compares to alternatives

Feature	screenpipe	Rewind / Limitless	Microsoft Recall	Granola
Source-available	✅ fully auditable	❌	❌	❌
Platforms	macOS, Windows, Linux	macOS, Windows	Windows only	macOS only
Data storage	100% local	Cloud required	Local (Windows)	Cloud
Multi-monitor	✅ All monitors	❌ Active window only	✅	❌ Meetings only
Audio transcription	✅ Local Whisper	✅	❌	✅ Cloud
Developer API	✅ Full REST API + SDK	Limited	❌	❌
Plugin system	✅ Pipes (AI agents)	❌	❌	❌
AI model choice	Any (local or cloud)	Proprietary	Microsoft AI	Proprietary
Team deployment	✅ Central config, AI permissions	❌	❌	❌
Pricing	Source-available · app from $25/mo	Subscription	Bundled with Windows	Subscription

Pricing

The source is available for personal, non-commercial use (see LICENSE.md). The signed desktop app uses a subscription:

Standard: $25/month. Local-first capture, search, and timeline, all on your device.
Pro: $50/seat/month. Everything in Standard plus cloud sync, cloud AI, and integrations. Teams buy 5+ seats self-serve.
Enterprise: $150/seat/month. Managed deployment, central config, shared pipes, per-pipe AI data permissions, admin dashboard, SSO/SAML, MDM ready (Intune / SCCM). Sales-led. See screenpi.pe/team.

Existing lifetime licenses remain valid; new lifetime purchases are no longer sold.

Integrations

AI coding assistants: Cursor, Claude Code, Cline, Continue, OpenCode, Gemini CLI
AI chat assistants: ChatGPT (via MCP), Claude Desktop (via MCP), any MCP-compatible client
Note-taking: Obsidian, Notion
Local AI: Ollama, any OpenAI-compatible model server
Automation: Custom pipes (scheduled AI agents as markdown files)

Teams & enterprise

screenpipe Teams lets organizations deploy AI agents across their team with full control over what AI can access. See screenpi.pe/team.

Central config management: Push capture settings (app filters, schedules, URL rules) to every device from an admin dashboard.
Shared pipes: Deploy AI workflows (auto-standups, meeting-to-tickets, time tracking) team-wide.
Per-pipe AI data permissions: YAML frontmatter controls what each pipe can access — apps, windows, content types, time ranges, endpoints. Enforced deterministically at the OS level via three layers (skill gating, agent interception, server middleware with per-pipe cryptographic tokens).
Privacy boundary: Admins control what gets captured and what AI accesses. They never see the actual data — everything stays on each employee's device.
Override rules: Employees can add stricter filters (e.g. also block personal email) but cannot weaken admin-set rules.
MDM ready: Deploy via Intune, SCCM, Robopack, or any MDM solution.
Enterprise: SSO/SAML, audit logs, SLA, SOC 2 / HIPAA compliance ready.

Technical architecture

Event-driven capture: Listens for OS events (app switch, click, typing pause, scroll, clipboard). When something meaningful happens, captures a screenshot + accessibility tree together with the same timestamp. Falls back to OCR when accessibility data isn't available. Idle fallback captures periodically when nothing is happening.
Audio processing: Whisper (local) or Deepgram (cloud) for speech-to-text. Speaker identification and diarization.
Storage: Local SQLite with FTS5 full-text search. Screenshots saved as JPEGs on disk (~300 MB/8hr vs ~2 GB with continuous recording).
API layer: REST API on localhost:3030. Search, frames, audio, elements, health, pipe management.
Plugin layer: Pipes — scheduled AI agents as markdown files. Agent executes prompts with access to screenpipe API.
UI layer: Desktop app built with Tauri (Rust + TypeScript).

API examples

Search screen content:

GET http://localhost:3030/search?q=meeting+notes&content_type=all&limit=10

Search audio transcriptions:

GET http://localhost:3030/search?q=budget+discussion&content_type=audio&limit=10

JavaScript SDK:

import { pipe } from "@screenpipe/js";

const results = await pipe.queryScreenpipe({
  q: "project deadline",
  contentType: "all",
  limit: 20,
  startTime: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
});

Building from source

Check CONTRIBUTING.

Make sure to understand the main branch is moving fast and breaking things, if you're looking for a stable version check app releases https://github.com/screenpipe/screenpipe/releases and use the git commit accordingly (production app is behind paywall).

Frequently asked questions

How much does screenpipe cost? The signed desktop app uses a subscription starting at $25/month; existing lifetime licenses remain valid. The source is available for personal, non-commercial use, so you can build and run it yourself (see LICENSE.md); commercial use of the source requires a license.

Does screenpipe send my data to the cloud? Screen frames, audio, transcripts, and the search index are stored locally by default. That does not mean the desktop app makes no network requests:

Product analytics is enabled by default through PostHog. It uses a stable installation identifier and, when you sign in, may associate account details such as your email with app, hostname, operating-system, hardware, and other device or feature metadata.
Sentry receives crash and error diagnostics while telemetry is enabled.
If you choose cloud transcription, hosted AI, or cloud sync, the audio, prompts and selected context, or synced data needed for that feature is processed remotely by the configured service.

You can disable telemetry in Settings → Privacy → Analytics, then apply the settings change. To keep capture and AI processing local, leave cloud sync off and select local transcription and a local AI provider such as Ollama.

How much disk space does it use? ~5–10 GB per month. Event-driven capture only stores frames when something changes, dramatically reducing storage compared to continuous recording.

Does it slow down my computer? Typical CPU usage is 5–10% on modern hardware. Event-driven capture only processes frames when something changes, and accessibility tree extraction is much lighter than OCR.

Can I use it with ChatGPT/Claude/Cursor? Yes. screenpipe runs as an MCP server, allowing Claude Desktop, Cursor, and other AI assistants to directly query your screen history.

Can it record multiple monitors? Yes. screenpipe captures all connected monitors simultaneously.

How does text extraction work? screenpipe primarily uses the OS accessibility tree to get structured text (buttons, labels, text fields) — this is faster and more accurate than OCR. When accessibility data isn't available (remote desktops, games, some Linux apps), it falls back to OCR: Apple Vision on macOS, Windows native OCR, or Tesseract on Linux.

Can I deploy screenpipe to my team? Yes. Screenpipe Teams provides central config management, shared AI pipes, and per-pipe data permissions. Admins control what gets captured and what AI can access — employees' actual data never leaves their devices. See screenpi.pe/team.

How do AI data permissions work? Each pipe supports YAML frontmatter fields (allow-apps, deny-apps, deny-windows, allow-content-types, time-range, days, allow-raw-sql, allow-frames) that deterministically control what data the AI agent can access. Enforcement happens at three OS-level layers — not by prompting the AI to behave. Even a compromised agent cannot access denied data.

Company

Built by screenpipe (Mediar, Inc.). Founded 2024. Based in San Francisco, CA.

Founder: Louis Beaumont (@louis030195)
Twitter: @screenpipe
Email: louis@screenpi.pe

Automattic/harper

Offline, privacy-first grammar checker. Fast, open-source, Rust-powered

Harper is an English grammar checker designed to be just right. I created it after years of dealing with the shortcomings of the competition.

Grammarly was too expensive and too overbearing. Its suggestions lacked context, and were often just plain wrong. Not to mention: it's a privacy nightmare. Everything you write with Grammarly is sent to their servers. Their privacy policy claims they don't sell the data, but that doesn't mean they don't use it to train large language models and god knows what else. Not only that, but the round-trip-time of the network request makes revising your work all the more tedious.

LanguageTool is great, if you have gigabytes of RAM to spare and are willing to download the ~16GB n-gram dataset. Besides the memory requirements, I found LanguageTool too slow: it would take several seconds to lint even a moderate-size document.

That's why I created Harper: it is the grammar checker that fits my needs. Not only does it take milliseconds to lint a document, take less than 1/50th of LanguageTool's memory footprint, but it is also completely private.

Harper is even small enough to load via WebAssembly.

Language Support

Harper currently only supports English, but the core is extensible to support other languages, so we welcome contributions that allow for other language support.

Performance Issues

We consider long lint times bugs. If you encounter any significant performance issues, please create an issue on the topic.

If you find a fix to any performance issue, we would appreciate the contribution. Just please make sure to read our contribution guidelines first.

Huge Thanks

This project would not be possible without the hard work from those who contribute.

Harper's logo was designed by Lukas Werner.

GitHub Rust Monthly Trending Repositories

1jehuang/jcode

jcode

Installation

Performance & Resource Efficiency

RAM comparison

Time to first frame

Time to first input

Additional clients / memory scaling

Memory (Agent memory)

UI: Side panels, Diagrams, Info Widgets, rendering, scrolling, alignment

Swarm

OAuth and Providers

Supported built-in login flows

Config-file setup for self-hosted endpoints and MCP

OpenAI-compatible providers

Self-hosted OpenAI-compatible endpoints, including vLLM

Extra request-body fields (extra_body)

MCP config files

Supported provider

Customizability / Self-Dev

Misc.

iOS Application / Native OpenClaw

Other planned features

Quick Start

Browser Automation

Further Reading

Detailed Installation

Setup

Quick Install

macOS via Homebrew

From Source (all platforms)

Uninstall

Platform Support

openai/codex

Quickstart

Installing and running Codex CLI

Using Codex with your ChatGPT plan

Docs

Pumpkin-MC/Pumpkin

Pumpkin

Goals

Features

How to run

Contributions

Docs

Communication

Funding

cjpais/Handy

Handy

Why Handy?

How It Works

Quick Start

Installation

Development Setup

Integrations

Architecture

Debug Mode

CLI Parameters

Known Issues & Current Limitations

Major Issues (Help Wanted)

Linux Notes

Platform Support

System Requirements/Recommendations

Roadmap & Active Development

In Progress

Verify Release Signatures

Troubleshooting

Manual Model Installation (For Proxy Users or Network Restrictions)

Step 1: Find Your App Data Directory

Step 2: Create Models Directory

Step 3: Download Model Files

Step 4: Install Models

Step 5: Verify Installation

Custom Whisper Models

Linux Startup Crashes or Instability

Handy Starts or Stops Recording on Its Own (Linux)

How to Contribute

Sponsors

Related Projects

Extra request-body fields (`extra_body`)