mizore / notes

gdirect: Direct Google Drive Access from the Terminal — How It Works and Setup Guide

Sun, 25 Oct 2026 00:00:00 +0000

Pulling tens of gigabytes of datasets or backups from Google Drive over a proxy usually burns through expensive data quotas and bottlenecks on proxy node bandwidth; downloading in a browser often drops partway through and forces you to start over. To solve this, I wrote gdirect: a terminal tool for browsing, downloading, uploading, and mounting Google Drive.

This post is organized into three parts: a quick TL;DR on how it "disguises" connections to reach Google directly, a ready-to-use installation and 10-minute illustrated setup guide, and finally a technical deep dive into the underlying source code.

TL;DR: How Do We Connect Directly Without a Proxy?

On networks in mainland China, Google Drive's domains (drive.google.com, www.googleapis.com, drive.usercontent.google.com) are blocked. At the same time, to keep basic services like Chrome updates, Android connectivity checks, and Google Fonts working in mainland China, Google maintains a pool of directly reachable edge servers inside domestic carrier backbones (China Telecom, Unicom, and Mobile)—the domestic IPs (such as Guangzhou Telecom's 183.56.143.147) behind the domains categorized under google-cn in routing rulesets like DustinWin/ruleset_geodata (dl.google.com, g.cn, fonts.googleapis.com, etc.).

Here is the key insight: those domestic google-cn edge nodes run the exact same unified reverse proxy—Google Front End (GFE)—connected over Google's private backbone to the global Drive backends, and they present valid official TLS certificates for *.googleapis.com and *.googleusercontent.com.

gdirect takes advantage of this by "borrowing a domestic google-cn IP at the transport layer while sending authentic Google Drive requests (domains and certificate checks) at the application layer":

Point underlying TCP sockets at domestic google-cn node IPs: Bypassing poisoned system DNS, gdirect starts from a built-in seed IP (183.56.143.147) and candidate pool, connecting directly to port 443. Candidates that pass live probes (verifying an official Google TLS certificate + a valid Drive v3 API response) are cached in local SQLite. During socket creation (via Rust's reqwest::resolve and a custom getaddrinfo hook in patched C++ libaria2), even across multiple cross-domain HTTP 302 redirects mid-download, every target IP is pinned to that domestic google-cn node—so the physical packet path stays inside domestic carrier backbones and never crosses the firewall.
Keep real Google Drive hostnames and strict TLS verification at the upper layers: Once connected to the domestic google-cn IP, application-layer requests still address standard https://www.googleapis.com (API and chunked uploads) and https://drive.usercontent.google.com / https://*.googleusercontent.com (file downloads). The domestic GFE node routes the request by hostname over Google's internal backbone to fetch your Drive data, while the client strictly verifies TLS certificates against the real Google hostnames as usual (and if an ISP middlebox resets connections on cleartext SNI, --sni / --no-sni can rewrite or strip the TLS SNI extension).
Separate the control plane from the data plane: Login and token refreshes (accounts.google.com, oauth2.googleapis.com), which take only a few kilobytes, go through the normal system network (your proxy) so authentication always works; bandwidth-heavy directory listing, multi-connection concurrent downloads, and 32 MiB resumable uploads all go straight through the domestic google-cn IP—saturating your local broadband without spending a single byte of proxy traffic.

Traffic Type	Commands / Domains	Route
Drive API, downloads, uploads	`browse`, `ls`, `download`, `upload` (`www.googleapis.com`, `drive.usercontent.google.com`, `*.googleusercontent.com`)	Scanned domestic `google-cn` IP. Hostnames and TLS certificate verification remain unchanged; `--sni` / `--no-sni` can rewrite or strip TLS SNI
Login & token refresh	`login` and automatic token refresh (`accounts.google.com`, `oauth2.googleapis.com`)	System network (uses system DNS and your proxy)
Disk mount	`mount` (invokes `rclone` under the hood)	System network

Important Note for Users in Mainland China: Even if your proxy client already sets google-cn from DustinWin/ruleset_geodata to DIRECT, running gdirect with your proxy (especially TUN mode) enabled can still end up routing your downloads through the proxy! That's because although gdirect connects to a google-cn IP, its TLS handshake sends Google Drive hostnames (drive.usercontent.google.com, www.googleapis.com). In standard rulesets, those domains belong to google (proxied) rather than google-cn (direct), so a TUN sniffer will inspect the TLS SNI, match the google rule, and hijack the connection into your proxy tunnel. Make sure to pick one of these two setups (see Mainland China Network and Proxy Configuration Guide below for details):

Add direct rules in your proxy client: explicitly route the Drive domains above (or the gdirect process) to DIRECT and exclude them from fake-ip;

Quit your proxy or disable TUN during transfers: keep your proxy on for the one-time gdirect login, then quit the proxy (or turn off TUN mode) when running scan and download.

Installation

Prebuilt binaries are provided for macOS 15+ (Apple Silicon / Intel), Linux x86_64 (glibc 2.35+, e.g. Ubuntu 22.04+, Debian 12+, Fedora, Arch), and Windows x86_64.

Option 1: One-Line Install Script

macOS / Linux:

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

Windows PowerShell:

& ([scriptblock]::Create((Invoke-RestMethod 'https://raw.githubusercontent.com/mizorewww/gdirect/main/scripts/install.ps1')))

powershell

The installer places gdirect and its bundled cacert.pem into ~/.local/bin (%LOCALAPPDATA%\gdirect\bin on Windows).

If you also want to use gdirect mount to mount Google Drive as a local disk, pass --with-mount (-WithMount in PowerShell) to automatically install the mount dependencies (rclone 1.75.2+, plus fuse3 on Linux or WinFsp via winget on Windows):

curl -fsSL https://raw.githubusercontent.com/mizorewww/gdirect/main/scripts/install.sh | bash -s -- --with-mount

Option 2: Homebrew (macOS / Linux)

brew tap mizorewww/gdirect https://github.com/mizorewww/gdirect
brew install mizorewww/gdirect/gdirect
brew install rclone   # Only needed for `gdirect mount`; Linux also requires `fuse3` from your system package manager

To upgrade later, run brew update && brew upgrade gdirect.

One-Time Google Cloud Setup Guide (~10 Minutes)

To avoid rate-limiting (429 Too Many Requests) or bans caused by everyone sharing a single public OAuth client, gdirect does not ship a shared client ID. Instead, you create your own Desktop app OAuth client in your personal Google Cloud project. You only need to do this once, and it is completely free.

1. Create a Project and Enable the Drive API

Open the Google Cloud Console, click the project picker at the top of the page, and click New project in the top-right corner. Name it anything you like (e.g. gdirect), leave Location as No organization for a personal account, click Create, and make sure the new project is selected at the top.
Open the Google Drive API page, confirm your new project is selected at the top, and click Enable.

Once enabled, the page shows the service name drive.googleapis.com with status Enabled.

2. Configure the OAuth App

Open Google Auth Platform and click Get started.
App information: Enter an app name (e.g. gdirect, shown on the consent screen), select your email address as the user support email, and click Next.
Audience: Choose External and click Next (personal accounts cannot choose Internal).
Contact information: Enter your email address and click Next.
Finish: Check the box agreeing to the Google API Services User Data Policy, click Continue, and then click Create.

3. Add the Drive Scope

Open Data Access in the left sidebar and click Add or remove scopes.
In the drawer that opens, select .../auth/drive ("See, edit, create, and delete all of your Google Drive files"). If you don't see it in the table, paste the URL below into Manually add scopes, click Add to table, and then click Update:
```
https://www.googleapis.com/auth/drive
```
Important: After returning to the Data Access page, make sure to click Save at the bottom of the page. Clicking Update in the drawer alone does not persist the change.

4. Create a Desktop Client and Download the JSON

Open Clients in the left sidebar and click Create client. Set Application type to Desktop app (Web application clients, API keys, and service-account JSONs will not work), give it any name (e.g. gdirect Desktop), and click Create.
In the dialog that pops up, click Download JSON before closing the modal. Once closed, Google won't let you download the secret JSON again (if you close it by mistake, just create a new client).

Newly created apps start in Testing mode, where only listed test users are allowed to sign in:

Open Audience in the left sidebar, click Add users under Test users, enter the Google account email you want to use with gdirect, and click Save.

While the app stays in Testing mode, refresh tokens expire after 7 days, requiring gdirect login --reauth once a week.

If you don't want to re-authenticate every week, simply click Publish app at the top of the Audience page to switch the status to In production. A personal app used only by you does not need to go through Google's verification review, and publishing it removes the 7-day token expiration limit.

6. Log In from the Terminal

Run the command below in your terminal, replacing the path with the JSON file you downloaded:

gdirect login --client-secret ~/Downloads/client_secret.json

Your browser will open automatically (if it doesn't, copy the URL printed in the terminal and open it in a browser on the same machine, since the OAuth flow redirects back to a temporary localhost port).
Choose your Google account. Google will warn that "Google hasn't verified this app"—this is completely normal because you just created it yourself:
- Testing mode: Click Continue (not "Back to safety").
- In production: Click Advanced in the bottom-left corner, then click Go to (unsafe).
Verify the app name and Google Drive permission scope, then click Continue.
Back in the terminal, once you see Logged in, you're all set. You can delete the downloaded JSON file now—the client credentials are saved inside local SQLite, and re-authenticating or switching accounts later only requires gdirect login --reauth.

Headless Server Tip: On a remote server without a browser, you can authenticate on your desktop first, or import an existing authorized_user credentials JSON via gdirect login --credentials <PATH>. For scripts, you can also pass an access token directly via the GDIRECT_ACCESS_TOKEN environment variable.

Mainland China Network and Proxy Configuration Guide

The most common question from users in mainland China is: My proxy client (sing-box / Mihomo / Clash) already uses DustinWin/ruleset_geodata and routes google-cn to DIRECT—why does gdirect traffic still get routed through my proxy?

Tracing the Packet Path: How Does a Proxy Sniffer Hijack Direct Traffic?

Even though gdirect disables HTTP/SOCKS proxy environment variables (no_proxy) at the application layer, whenever your proxy client is running—especially in TUN virtual network interface mode—every packet on the machine passes through the proxy's routing engine first. Let's trace what happens step by step:

We borrow a google-cn IP, but send Google Drive hostnames: At the socket layer, gdirect replaces the destination IP with a domestic google-cn edge node (such as 183.56.143.147). However, so that Google's edge router knows which backend service to reach and local TLS certificate verification succeeds, the TLS handshake (ClientHello SNI) and HTTP Host header still carry www.googleapis.com, drive.usercontent.google.com, and *.googleusercontent.com.
Those Google Drive domains are NOT in the google-cn ruleset! If you inspect google-cn in DustinWin/ruleset_geodata, it lists domains that are natively unblocked in mainland China—such as dl.google.com, g.cn, gstatic.cn, fonts.googleapis.com, and clientservices.googleapis.com. Meanwhile, www.googleapis.com, drive.usercontent.google.com, drive.google.com, and *.googleusercontent.com are not in google-cn—they all sit in the proxied google ruleset.
TUN traffic sniffing (sniff) hijacks the connection by domain: When gdirect opens a connection to the domestic IP 183.56.143.147:443, the TUN interface intercepts the packet and uses sniff (TLS SNI inspection) to see that the SNI hostname is drive.usercontent.google.com or www.googleapis.com. The proxy then evaluates its routing rules top-to-bottom using that sniffed domain:
- rule_set: google-cn (DIRECT) $\rightarrow$ Miss (the Drive domain isn't in google-cn);
- rule_set: google (PROXY) $\rightarrow$ Match!
- Because domain rules precede IP rules in almost all proxy templates (or when scan resolves those domains through system DNS and gets handed a 198.18.x.x Fake-IP), a connection physically destined for a domestic China Telecom IP gets misclassified as blocked Google traffic and shoved right back into your proxy tunnel!

Once you see why this happens, picking either one of the two approaches below solves it completely:

Approach 1: Quit Your Proxy (or Turn Off TUN) During `scan` and Downloads

If you don't want to touch your proxy client's routing rules, this is the simplest and cleanest workflow:

Login phase (proxy ON): With your proxy running as usual, run gdirect login --client-secret ... to finish authorization (opening accounts.google.com in the browser and exchanging/refreshing tokens against oauth2.googleapis.com require a proxy).
Scan & transfer phase (quit proxy, or turn off TUN mode):
- Once logged in (gdirect caches a short-lived access_token valid for ~1 hour), quit your proxy client or turn off its TUN mode (if you only use System Proxy without TUN, gdirect ignores system proxy environment variables automatically, though turning off TUN is the most foolproof).
- Run gdirect scan to find the fastest domestic google-cn edge IP over your raw physical broadband.
- Run gdirect download ... or gdirect browse to download at full line speed (if your ISP resets connections on cleartext SNI, pass --no-sni):

gdirect scan
gdirect download FILE_ID
# If you hit connection or TLS resets (libaria2 code 1), strip SNI:
gdirect download FILE_ID --no-sni

Approach 2: Add Direct Rules in Your Proxy Client for Drive Domains (or the `gdirect` Process)

If you keep your proxy and TUN mode running 24/7, the fix is straightforward: since the proxy hijacks traffic after sniffing the Drive hostnames, place a rule before google that routes the gdirect process (or those Drive domains) to DIRECT, just like google-cn:

Domains that must stay on PROXY (used only for login and token refresh):
- accounts.google.com
- oauth2.googleapis.com
Transfer domains to route to DIRECT and exclude from fake-ip:
- drive.usercontent.google.com
- *.googleusercontent.com
- drive.google.com
- www.googleapis.com, drive.googleapis.com, content.googleapis.com

Note: Unlike gdirect, a regular web browser visiting www.googleapis.com does not rewrite the underlying socket IP to a google-cn node. Routing www.googleapis.com to DIRECT globally would break websites in your browser that depend on it. On desktop platforms, matching by PROCESS-NAME (gdirect) is strongly recommended.

For Mihomo (Clash), add the following before your GEOSITE,google rule:

dns:
  fake-ip-filter:
    - "www.googleapis.com"
    - "drive.googleapis.com"
    - "content.googleapis.com"
    - "drive.usercontent.google.com"
    - "drive.google.com"
    - "+.googleusercontent.com"

rules:
  # 1. Keep OAuth login and token refresh on PROXY
  - DOMAIN,accounts.google.com,PROXY
  - DOMAIN,oauth2.googleapis.com,PROXY

  # 2. Recommended: force all other traffic from the gdirect process (scan, API, download, upload) to DIRECT so sniffed domain rules don't hijack it
  - PROCESS-NAME,gdirect,DIRECT

  # 3. Or route by domain (place before GEOSITE,google / RULE-SET,google):
  - DOMAIN,drive.usercontent.google.com,DIRECT
  - DOMAIN-SUFFIX,googleusercontent.com,DIRECT
  - DOMAIN,www.googleapis.com,DIRECT
  - DOMAIN,drive.googleapis.com,DIRECT
  - DOMAIN,content.googleapis.com,DIRECT

yaml

If you use sing-box, add an equivalent process-name or domain direct rule before rule_set: ["google"] in route.rules (while keeping oauth2.googleapis.com proxied) to enjoy zero-proxy-quota full-speed Drive transfers with TUN left on all day.

Daily Usage & Troubleshooting Reference

Common Commands

gdirect                                   # Same as `gdirect browse`, opens the interactive TUI
gdirect browse -o ~/Downloads             # Set download directory (defaults to ./downloads)
gdirect ls root --json                    # List directory contents (supports JSON output)
gdirect download <FILE_ID_OR_SHARE_URL>   # Download a file; re-run the same command to resume after interruption
gdirect download FILE_ID -o file.zip
gdirect download DOC_ID --export application/pdf -o doc.pdf
gdirect upload ./file.zip                 # 32 MiB chunked upload with automatic resume
gdirect upload ./file.zip --parent FOLDER_ID --name backup.zip
gdirect mount                             # Mount at ~/GoogleDrive (uses native NFS on macOS, no FUSE needed)
gdirect unmount                           # Unmount and clean up temporary exported credentials

Inside the gdirect browse TUI, you can drive everything from the keyboard:

Key	Action
`j / k`, `↑ / ↓`	Move selection up or down
`Enter`, `l / →`	Open folder
`h / ←`, `Backspace`	Go to parent folder
`d`	Queue selected item for download (Google Docs, Sheets, and Slides are exported as PDF)
`+ / -`	Adjust concurrent connections (`1–16`) for subsequent downloads and save as default (starts at 8)
`r`	Refresh current folder
`c`	Cancel active download while keeping partial data on disk
`q`	Quit

For tricky network environments, download and browse also expose transport-layer overrides:

--ip IP: Force a specific Google IP, skipping automatic scan results;
--sni HOST / --no-sni: Override the TLS SNI hostname, or omit the SNI extension altogether (certificates are still verified against the real Google hostname);
-j N: Set concurrent connections (1–16) for this command only;
gdirect scan --ips FILE: Probe a custom candidate IP list (one public IP per line, # for comments).

Troubleshooting Quick Reference

Symptom	Fix
`access_denied` or message that the app is being tested	Add your Google account as a Test user, or publish the app (Step 5 of the setup guide)
`redirect_uri_mismatch`	The downloaded JSON is not from a Desktop app client; recreate it following Step 4
`Drive API 403 … insufficient permission`	Enable the Google Drive API in the same project as your OAuth client (Step 1), save the Drive scope (click Save at the bottom in Step 3), then run `gdirect login --reauth`
`refresh credential expired or revoked`	Run `gdirect login --reauth`. If this happens every 7 days, publish the app from Testing to In production (Step 5)

Technical Deep Dive: How Is It Implemented Under the Hood?

If you're curious about how gdirect combines Rust with a custom-patched libaria2 build to pull this off, here is a walkthrough of the source code.

1. Candidate IP Scanning & Dual-Endpoint Verification

When a transfer command runs without a verified IP from the last 24 hours in local SQLite, src/scan.rs kicks off a scan. Up to 256 candidates are assembled from three sources:

The built-in bootstrap seed IP 183.56.143.147 (from Cealing-Host—always re-probed before use, never blindly trusted);
Public IPs returned by system DNS for www.googleapis.com, drive.usercontent.google.com, and drive.google.com;
Historical IPs in SQLite that succeeded within the past 7 days (stale entries older than 7 days are pruned before each scan so the pool never grows unbounded).

Before entering the probe pool, public(ip) filters out private, loopback, link-local, and 198.18.0.0/15 (the default Clash / Mihomo fake-ip range) addresses. Eight worker threads then run probe(ip) concurrently:

src/scan.rsProbing a candidate IP with TLS verification and dual endpointsL78–113 · f4b67ef ↗

78fn probe(ip: IpAddr) -> Result<(i64, Option<String>)> {
79    let client = Client::builder()
80        .no_proxy()
81        .redirect(reqwest::redirect::Policy::none())
82        .connect_timeout(Duration::from_secs(3))
83        .timeout(Duration::from_secs(5))
84        .resolve("www.googleapis.com", SocketAddr::new(ip, 443))
85        .resolve("drive.usercontent.google.com", SocketAddr::new(ip, 443))
86        .build()?;
87    let start = Instant::now();
88    let response = client
89        .get("https://www.googleapis.com/drive/v3/about?fields=user")
90        .send()
91        .map_err(|e| e.without_url())?;
92    ensure!(
93        response.status() == reqwest::StatusCode::UNAUTHORIZED,
94        "unexpected Drive API status {}",
95        response.status()
96    );
97    let data: serde_json::Value = response.json()?;
98    ensure!(data["error"]["code"] == 401, "invalid Drive API response");
99    let response=client.get("https://drive.usercontent.google.com/download?id=0B9P1L--7Wd2vU3VUVlFnbTgtS2c&export=download&confirm=t").send().map_err(|e|e.without_url())?;
100    let status = response.status();
101    let warning = if matches!(
102        status,
103        reqwest::StatusCode::FORBIDDEN | reqwest::StatusCode::NOT_FOUND
104    ) {
105        Some(format!("HTTP {status}"))
106    } else {
107        ensure!(status.is_success(), "Drive download probe HTTP {status}");
108        let mut bytes = Vec::new();
109        response.take(32).read_to_end(&mut bytes)?;
110        (bytes != b"spam\n").then(|| "unexpected content".into())
111    };
112    Ok((start.elapsed().as_millis() as i64, warning))
113}

Three design choices stand out in this probe:

.no_proxy() + .resolve(): Bypasses environment proxy variables and binds www.googleapis.com and drive.usercontent.google.com directly to ip:443 inside the HTTP client while enforcing full TLS certificate verification (chain validation + SAN hostname matching), ruling out ISP captive portals or MITM boxes.
Credential-less API verification: Calls GET /drive/v3/about?fields=user without any user token. A genuine Google Drive API front end always replies with HTTP 401 Unauthorized and JSON error.code == 401. This confirms application-layer routing without ever exposing the user's Bearer token to untrusted candidate IPs.
Download path probe: Requests a tiny public test file from drive.usercontent.google.com. If Google rate-limits the public test file with HTTP 403/404, the IP is still accepted with a warning so long as the Drive API check passed, avoiding false negatives when the public test file is throttled.

How to find more candidate direct IPs for your ISP: If the built-in seed IP 183.56.143.147 has high latency on your regional carrier, pick a few domains from the google-cn list in DustinWin/ruleset_geodata (such as dl.google.com, g.cn, fonts.googleapis.com, or gstatic.cn), resolve them against a domestic DNS server (e.g. dig @223.5.5.5 dl.google.com +short) to get Google edge IPs on your local ISP, save them one per line in ips.txt, and run gdirect scan --ips ips.txt. The scanner will automatically verify their TLS certificates and Drive API routing and pick the fastest node.

2. Custom `libaria2`: Why Patching the C++ Source Was Necessary

For ls and upload, Rust's reqwest with .resolve() is all we need. Downloading multi-gigabyte files, however, requires multi-connection segmented concurrency and crash-safe resume, so gdirect embeds aria2 1.37.0 trimmed down to a static HTTP/HTTPS + OpenSSL 3 library (libaria2).

Here is the catch: Google Drive download requests routinely go through cross-domain HTTP 302 redirects (for instance, from www.googleapis.com or drive.google.com to drive.usercontent.google.com and dynamically generated *.googleusercontent.com hosts). In stock aria2, if you only override the initial URL, aria2 falls right back to system DNS as soon as it follows a 302 redirect to a new hostname; and if you rewrite the hostname in the URL to a raw IP literal, TLS certificate verification fails immediately due to hostname mismatch.

To solve this cleanly, gdirect applies a ~90-line patch (vendor/aria2-1.37.0.patch plus vendor/gdirect_route.h) when compiling libaria2, making four targeted changes at the C++ layer:

(1) Allowlist of Google Drive Transfer Domains

First, vendor/gdirect_route.h defines the exact set of Google Drive hostnames under gdirect's control:

vendor/gdirect_route.hGoogle Drive hostname allowlistL1–12 · f4b67ef ↗

1// gdirect's narrow routing hook for the pinned aria2 1.37.0 build.
2#pragma once
3#include <string>
4extern const char* gdirect_ip;
5extern const char* gdirect_sni;
6inline bool gdirect_host(const std::string& h) {
7  const std::string suffix = ".googleusercontent.com";
8  return h == "drive.google.com" || h == "drive.usercontent.google.com" ||
9         h == "www.googleapis.com" || h == "content.googleapis.com" ||
10         h == "drive.googleapis.com" ||
11         (h.size() > suffix.size() && h.compare(h.size()-suffix.size(), suffix.size(), suffix) == 0);
12}

(2) Intercepting `getaddrinfo` and TLS SNI in `SocketCore.cc`

Upper-layer HTTP requests keep their original URLs untouched (so both the HTTP Host header and OpenSSL's X.509 hostname verification check the real Google domain). Only when SocketCore calls getaddrinfo to open a TCP socket does it swap any hostname matching gdirect_host(host) for the scanned gdirect_ip with AI_NUMERICHOST set, bypassing DNS resolution completely. Right above that, it also hooks tlsSession_->setSNIHostname():

vendor/aria2-1.37.0.patchHooking TLS SNI and getaddrinfo in SocketCore.ccL22–42 · f4b67ef ↗

22@@ -936,7 +941,9 @@
23     // "localhost" will produce TLS alert with GNUTLS.
24     if (tlsctx->getSide() == TLS_CLIENT && !util::isNumericHost(hostname) &&
25         hostname.find(".") != std::string::npos) {
26-      rv = tlsSession_->setSNIHostname(hostname);
27+      const char* sni = gdirect_host(hostname) ? gdirect_sni : nullptr;
28+      rv = (sni && !*sni) ? TLS_ERR_OK :
29+          tlsSession_->setSNIHostname(sni ? std::string(sni) : hostname);
30       if (rv != TLS_ERR_OK) {
31         throw DL_ABORT_EX(fmt(EX_SSL_INIT_FAILURE,
32                               tlsSession_->getLastErrorString().c_str()));
33@@ -1450,6 +1457,10 @@
34   hints.ai_flags = getDefaultAIFlags();
35   hints.ai_flags |= flags;
36   hints.ai_protocol = protocol;
37+  if (host && gdirect_ip && *gdirect_ip && gdirect_host(host)) {
38+    host = gdirect_ip;
39+    hints.ai_flags |= AI_NUMERICHOST;
40+  }
41   return getaddrinfo(host, service, &hints, resPtr);
42 }

When gdirect_sni is nullptr (the default), the original hostname is sent as SNI;
When --sni HOST is passed, the custom SNI hostname is sent instead;
When --no-sni is passed (gdirect_sni points to an empty string ""), it returns TLS_ERR_OK without calling setSNIHostname, causing OpenSSL to send a ClientHello with no SNI extension at all.

(3) Stripping `Authorization` Headers Across Redirects & Redirect Allowlisting

When downloading a private file, the initial request goes to https://www.googleapis.com/drive/v3/files/{id}?alt=media with Authorization: Bearer <token>. Once redirected via HTTP 302 to a pre-signed *.googleusercontent.com URL, forwarding the Authorization header causes Google's content servers to reject the request for carrying two sets of credentials—and risks leaking the token across domains. The patch therefore restricts HttpRequest.cc to emit the Authorization: header only when getHost() == "www.googleapis.com", and enforces in Request.cc that every redirect target must use https and match gdirect_host().

(4) Removing the OpenSSL 3 Legacy Provider Dependency

Under OpenSSL 3, stock aria2 unconditionally calls OSSL_PROVIDER_load(nullptr, "legacy") at startup (for RC4 in BitTorrent encryption), which crashes on systems without the OpenSSL legacy provider module installed. Guarding that call with #ifdef ENABLE_BITTORRENT makes the HTTP-only static build completely self-contained.

3. Overwrite Guards, Large-File Virus-Scan Confirmation Pages, and MD5 Verification

On the Rust side (src/download.rs), three additional safeguards wrap libaria2:

src/download.rsControl-file resume check, HTML confirmation-page parsing, and MD5 verificationL191–248 · f4b67ef ↗

191    // Never treat an unrelated existing file as a resumable download.
192    let control = PathBuf::from(format!("{}.aria2", args.output.display()));
193    if args.output.exists() && !control.exists() {
194        ensure!(
195            matches_md5(&args.output, args.md5.as_deref())?,
196            "output already exists; choose another -o path"
197        );
198        if progress.is_none() {
199            println!("Already downloaded {}", args.output.display());
200        }
201        return Ok(());
202    }
203    if progress.is_none() {
204        eprintln!(
205            "libaria2 1.37.0 · IP={} · SNI={} · certificate verification ON",
206            args.ip
207                .map(|ip| ip.to_string())
208                .unwrap_or_else(|| "system DNS".into()),
209            match args.sni.as_deref() {
210                None => "original",
211                Some("") => "none",
212                Some(sni) => sni,
213            }
214        );
215    }
216    let mut progress = progress;
217    for attempt in 0..3 {
218        download(&args, &url, token.as_deref(), progress.as_deref_mut())?;
219        let mut prefix = Vec::new();
220        fs::File::open(&args.output)?
221            .take(1024 * 1024)
222            .read_to_end(&mut prefix)?;
223        // Public downloads can return the virus-scan confirmation form with HTTP 200.
224        // Only Drive's own HTML pages are inspected; other files stay untouched.
225        if token.is_none() && html_page(&prefix) {
226            let text = String::from_utf8_lossy(&prefix);
227            if text.contains("download-form") {
228                let next = drive::confirmation(&text, &url)?;
229                ensure!(attempt < 2, "Drive confirmation loop");
230                fs::remove_file(&args.output)?;
231                url = next;
232                continue;
233            }
234            if text.contains("accounts.google.com/ServiceLogin")
235                || text.contains("Google Drive - Quota exceeded")
236                || text.contains("Google Drive - Access denied")
237            {
238                bail!(
239                    "Drive returned a login/quota error page; saved for inspection at {}",
240                    args.output.display()
241                );
242            }
243        }
244        ensure!(
245            args.md5.is_none() || matches_md5(&args.output, args.md5.as_deref())?,
246            "MD5 does not match Drive's checksum; the file is kept at {} for inspection",
247            args.output.display()
248        );

Safety check for existing files: If the output file already exists without a companion .aria2 control file, gdirect hashes the local file and compares it against Drive's md5Checksum—printing Already downloaded if they match and refusing to overwrite if they don't.
Unwrapping virus-scan confirmation pages on public large files: When downloading a large public shared file without authentication, Google Drive returns an HTTP 200 HTML page containing <form id="download-form">. Only when the file header starts with <!doctype html or <html does gdirect parse that form to extract the confirm / uuid parameters and re-download the actual binary, ensuring archives or source files that happen to contain the string download-form are never touched.
Post-download MD5 verification: Once libaria2 finishes, gdirect streams the completed file through MD5 and verifies it against Drive's metadata to guarantee that multi-connection chunk reassembly is bit-for-bit exact.

4. 32 MiB Resumable Chunked Uploads

The upload module (src/upload.rs) implements the Google Drive v3 Resumable Upload protocol. Because cross-border direct links can have higher RTT, tiny chunks waste too much time waiting for per-chunk acknowledgments, so the chunk size is set to 32 MiB.

When starting an upload, gdirect looks up any prior session in local SQLite keyed by (canonical local path, target parent folder ID, remote filename):

src/upload.rsProbing the remote upload session for the last committed byte offsetL85–105 · f4b67ef ↗

85        let mut session = saved.filter(|s| s.size == size && s.modified == modified);
86        if let Some(s) = &session {
87            let response = self
88                .client
89                .put(session_url(&s.url)?)
90                .bearer_auth(&token)
91                .header("Content-Range", format!("bytes */{size}"))
92                .header("Content-Length", 0)
93                .send()
94                .map_err(|e| e.without_url())?;
95            match response.status() {
96                StatusCode::OK | StatusCode::CREATED => {
97                    let result = response.json()?;
98                    db.unset(&key)?;
99                    return Ok(result);
100                }
101                StatusCode::PERMANENT_REDIRECT => start = offset(&response, size)?,
102                StatusCode::NOT_FOUND | StatusCode::GONE => session = None,
103                _ => return Err(failure(response)),
104            }
105        }

As long as the local file's size and nanosecond modification timestamp haven't changed, re-running the upload command after an interruption sends Content-Range: bytes */{size} to query Google's committed byte offset from the 308 Permanent Redirect Range header and resumes right where it left off.

5. Localhost Loopback + PKCE OAuth Flow

In src/auth.rs, gdirect login implements the OAuth 2.0 Loopback + PKCE (RFC 7636 S256) flow without pulling in heavy external OAuth SDKs:

src/auth.rsEphemeral localhost listener and PKCE authorization URL constructionL194–213 · f4b67ef ↗

194    let listener = TcpListener::bind(("127.0.0.1", 0))?;
195    listener.set_nonblocking(true)?;
196    let redirect = format!(
197        "http://127.0.0.1:{}/callback",
198        listener.local_addr()?.port()
199    );
200    let state = random_string()?;
201    let verifier = random_string()?;
202    let mut url = url::Url::parse("https://accounts.google.com/o/oauth2/v2/auth")?;
203    url.query_pairs_mut().extend_pairs([
204        ("client_id", client_id),
205        ("redirect_uri", redirect.as_str()),
206        ("response_type", "code"),
207        ("scope", SCOPE),
208        ("access_type", "offline"),
209        ("prompt", "consent select_account"),
210        ("state", state.as_str()),
211        ("code_challenge", challenge(&verifier).as_str()),
212        ("code_challenge_method", "S256"),
213    ]);

It binds an ephemeral non-blocking TCP listener on 127.0.0.1:0, validates the state parameter on the browser callback to prevent CSRF, and exchanges the authorization code plus code_verifier against https://oauth2.googleapis.com/token for a refresh_token. Both the SQLite database and any temporary rclone configuration exported for mount are created with 0600 permissions, and temporary mount credentials are automatically wiped on unmount or mount failure.

Putting Memoh Under the Knife: Specializing an Agent for Cheaper Telegram Group Chats

Mon, 03 Aug 2026 00:00:00 +0000

A while ago, I deployed Memoh as a few Telegram group-chat bots, mainly to burn through an Ollama subscription I couldn't possibly use up on my own (some idiot subscribed to a full year of Ollama at once).

After running it for a bit, I noticed that ten minutes of group chat could burn through half of my 5-hour limit, and a single day would eat half of my weekly quota. That got me thinking: in a pure chat scenario, how can I drive down both the number of LLM calls and the token consumption per call? I made a set of targeted changes for group chat, and my total cost dropped to less than a fifth of what it used to be.

To be clear, this post isn't here to nitpick upstream. Memoh is a thoughtfully designed general-purpose agent framework—multi-step tool loops, a rich toolset, and structured message metadata are all reasonable and even necessary for an agent that "gets work done for you." What I did was specialize it into a chatbot: an agent in a group chat spends most of its life just talking rather than executing tasks, and "talking" inside a general-purpose agent loop has a very unfavorable cost structure.

Where Does the Money Actually Go?

First, here is the breakdown of a real request captured before my optimizations:

Component	Size	Share
Messages (conversation history)	~157.7 KB	68.0%
Tools (tool schemas)	~49.5 KB	21.3%
System (system prompt)	~24.7 KB	10.7%

A single request is over 200 KB—roughly 50,000 tokens. The catch is what a general-purpose agent's tool loop does with that payload: every extra tool call re-reads all 50,000 tokens from scratch. And chat scenarios are packed with tool calls: sending a message is one, replying is one, sending a sticker is another, and after sending, a delivery status comes back for the model to read and confirm. Behind a single outgoing group-chat message, the full context is read 2 to 3 times over.

So my changes followed three directions: make fewer calls, read less per call, and hit the prompt cache on almost everything already read. Every change below includes the actual code from my fork (mizorewww/Memoh, compared against upstream baseline d0c5c735^).

Change 1: Clock Out Right After Sending

Upstream's loop works like this: the model decides to send a message → calls send → the framework returns the delivery status (message ID, platform, target conversation, etc.) as a tool result → the model is invoked a second time, reads the entire context again, says "okay, sent," and finishes. For a group-chat bot, that final call is almost pure waste: the message has already been delivered to the chat, and there is nothing meaningful left for the model to do except echo a confirmation. With the Doubao model, an even worse failure mode showed up: seeing the success result, the model kept calling send over and over in an infinite loop.

My fix wraps the provider in a decorator (internal/agent/runtime/native/terminal_send.go). Once send successfully delivers to the current conversation, the next time the model would be called, the decorator immediately returns FinishReasonStop locally without making a network request at all:

internal/agent/runtime/native/terminal_send.goEnd the turn locally after successful deliveryL76–103 · ad8012c ↗

76type terminalSendProvider struct {
77	sdk.Provider
78	state *terminalSendState
79}
80
81func (p *terminalSendProvider) DoGenerate(ctx context.Context, params sdk.GenerateParams) (*sdk.GenerateResult, error) {
82	if p.state.isDelivered() {
83		return &sdk.GenerateResult{
84			FinishReason: sdk.FinishReasonStop,
85			Response:     sdk.ResponseMetadata{ID: terminalSendResponseID},
86		}, nil
87	}
88	return p.Provider.DoGenerate(ctx, params)
89}
90
91func (p *terminalSendProvider) DoStream(ctx context.Context, params sdk.GenerateParams) (*sdk.StreamResult, error) {
92	if !p.state.isDelivered() {
93		return p.Provider.DoStream(ctx, params)
94	}
95	parts := make(chan sdk.StreamPart, 2)
96	parts <- &sdk.FinishStepPart{
97		FinishReason: sdk.FinishReasonStop,
98		Response:     sdk.ResponseMetadata{ID: terminalSendResponseID},
99	}
100	parts <- &sdk.FinishPart{FinishReason: sdk.FinishReasonStop}
101	close(parts)
102	return &sdk.StreamResult{Stream: parts}, nil
103}

Of course, the protocol requires every tool_call to be paired with a tool_result, so we can't literally drop the result without leaving a dangling tool call in history. Instead, the result is compressed to the bare minimum: a successful send to the current conversation returns just {"ok": true}, only attaching target metadata when sending across conversations; failures return a structured retryable error (error_code + retryable + guidance) so the model has a chance to recover instead of crashing the loop with a Go error:

internal/agent/tool/message.goMinimal send resultL311–324 · ad8012c ↗

311func (p *MessageProvider) execSend(ctx context.Context, session SessionContext, toolCallID string, args map[string]any) (any, error) {
312	if session.SessionType == sessionmode.Discuss {
313		sendResult, err := p.exec.SendDirectForTool(ctx, toMessagingSession(session), "", toolCallID, args)
314		if err != nil {
315			return messageSendErrorResult(err)
316		}
317		resp := map[string]any{"ok": true}
318		if !session.IsSameConversation(sendResult.Platform, sendResult.Target) {
319			resp["platform"] = sendResult.Platform
320			resp["target"] = sendResult.Target
321			resp["delivered"] = "target"
322		}
323		return resp, nil
324	}

There is one more layer in history projection. When future turns read the conversation history, successful send calls are folded into a minimal call/result pair containing only the five audience-visible fields (text, reply_to, sticker_id, attachments, message), stripping delivery internals (bot_id, platform, message_id, etc.) from the prompt context. Note that this folding happens only in the projection layer—the persisted canonical history remains untouched for debugging:

internal/agent/application/service_messages.goMinimal send call in history projectionL232–246 · ad8012c ↗

232func minimalDiscussSendCall(call sdk.ToolCallPart) sdk.ToolCallPart {
233	input := normalizeToolInputMap(call.Input)
234	minimal := make(map[string]any, 5)
235	// Current-conversation routing is implicit. Keep only audience-visible
236	// payload fields and the reply reference needed to understand the exchange.
237	for _, key := range []string{"text", "reply_to", "sticker_id", "attachments", "message"} {
238		if value, ok := input[key]; ok {
239			minimal[key] = value
240		}
241	}
242	return sdk.ToolCallPart{
243		ToolCallID: strings.TrimSpace(call.ToolCallID),
244		ToolName:   "send",
245		Input:      minimal,
246	}

The result: on pure messaging turns, LLM calls drop from 2 to 1—an immediate 50% savings. Multi-step workflows that search the web or call other tools still work normally; the bot simply treats send as the terminal action of the turn.

Change 2: Send Text, Reply, and Sticker in a Single Call

In group chats, a single response is often both a reply to someone and accompanied by a sticker. Previously, that required multiple tool calls, re-reading the entire context each time. I merged them into a single send tool signature:

send(text[optional], reply_to[optional], sticker_id[optional])

Concretely, this involved two changes. First, upstream already had a top-level reply_to parameter alongside a redundant nested message.reply{message_id} object; I removed the nested form, kept only the top-level parameter, and restricted it to message IDs visible in the current turn (returning a retryable error if invisible instead of replying to the wrong message).

Second, I had previously written an MCP server for sending stickers, only to realize that invoking an external MCP tool added an extra LLM round-trip every time. I folded the sticker catalog directly into the sticker_id parameter of send:

internal/agent/runtime/native/telegram_sticker.goTurn the sticker MCP into an internal backend of sendL14–31 · ad8012c ↗

14	"github.com/memohai/memoh/internal/delivery"
15)
16
17const (
18	telegramStickerSendGuidance     = " For Telegram, normally pair every coherent public message with at least one context-appropriate Sticker by setting `sticker_id` in the same send call; omit it only when the catalog has no suitable Sticker. Choose from the full visual descriptions, not from the original emoji alone, and avoid repetitive duplicates."
19	telegramStickerCatalogSchemaKey = "x-memoh-sticker-catalog"
20)
21
22type telegramStickerSchemaEntry struct {
23	ID          string `json:"id"`
24	Description string `json:"description"`
25	Emoji       string `json:"emoji"`
26	Status      string `json:"status"`
27}
28
29// mergeTelegramStickerSendTools converts the Sticker MCP into an internal
30// backend for the first-party send tool. The model sees one send call whose
31// sticker_id enum contains the complete, stable catalog; it never sees a

Within a single send call, the bot delivers the text first and then the sticker; if the sticker fails after the text is already sent, it returns partial success and terminates immediately so the model won't retry and send duplicate text.

I also had a vision model pre-generate a concise visual description (under 50 characters) for every sticker, stored alongside the sticker-set metadata in SQLite. Sorted deterministically by ID, these descriptions are embedded into the send tool schema's description. Once merged, sending a sticker incurs virtually zero extra LLM cost.

Change 3: Move Everything That Changes to the Tail of the Prefix

This is the key to prompt-cache hit rates. Every provider's prompt caching mechanism (Anthropic, OpenAI, DeepSeek, Kimi—all of them) works by prefix matching: the prefix of a request must match byte-for-byte, and the first byte that changes invalidates the cache for everything after it.

To be fair, upstream's default behavior isn't bad across ordinary turns: conversation history is appended at the end, so automatic prefix caches like DeepSeek's catch most of it. The real leak was a frequently rewritten file buried in the middle of the system prompt: upstream placed MEMORY.md between AGENTS.md and PROFILES.md. Because MEMORY.md is rewritten constantly by the memory subsystem, every update invalidated the cache for everything following it. My fix was a one-function change:

internal/agent/runtime/native/fs.goMove MEMORY.md to the tail of the system promptL66–71 · ad8012c ↗

66// systemFileLoadOrder keeps the frequently changing memory summary at the
67// tail of the system prompt. Stable instruction/profile content therefore
68// remains in the reusable prefix when MEMORY.md changes between turns.
69func systemFileLoadOrder() []string {
70	return []string{"AGENTS.md", "PROFILES.md", "MEMORY.md"}
71}

Changing the load order from AGENTS.md → MEMORY.md → PROFILES.md to AGENTS.md → PROFILES.md → MEMORY.md keeps the most stable instructions at the front of the prefix and pushes the most volatile file to the very end of the system prompt. Following the same principle, I cleaned up several other sources of "prefix pollution":

The memory-writing manual (~2.6 KB) is now injected only when a memory provider is actually configured; when set to None, the entire section is omitted:

internal/agent/application/service.goSkip memory instructions when no memory provider is configuredL710 · ad8012c ↗

710MemoryInstructions:    strings.TrimSpace(botSettings.MemoryProviderID) != "",

Platform identity now injects only the active platform's fields, and strips avatar_url (which contained the bot token) from the injected prompt.

The difference is measurable: under the old "dynamically mutate system prompt" path, a forced-reply call measured just 5.1% cache read (a single measurement of that specific code path, not the everyday baseline). After the fix, two consecutive requests in a live group chat sent 52,259 and 52,633 input tokens, of which 52,096 and 52,480 were served from cache—a 99.7% cache hit rate, leaving only ~160 uncached input tokens billed at full price per turn.

Change 4: Invisible Request Slimming

Smaller requests mean cheaper reads on every turn. This part stacks several small reductions together, all exposed as configurable Telegram channel policies stored in bot metadata:

internal/agent/channelpolicy/policy.goFour Telegram channel policy keysL21–24 · ad8012c ↗

21TelegramToolCallsEnabledMetadataKey = "telegram_tool_calls_enabled"
22TelegramEnabledToolsMetadataKey     = "telegram_enabled_tools"
23TelegramSkillsEnabledMetadataKey    = "telegram_skills_enabled"
24TelegramMessageMetadataModeKey      = "telegram_message_metadata_mode"

telegram_tool_calls_enabled is the master switch for tools, telegram_enabled_tools is an explicit allowlist (an empty array disables all tools), and telegram_skills_enabled controls skills. A chat bot doesn't need shell execution or file editing; on my two production bots I enabled only send, turning off 37 tools. The crucial detail is when filtering happens: the allowlist runs before schema generation, so disabled tools don't contribute a single byte to the request:

internal/agent/runtime/native/agent.goFilter tools before schema generationL990–997 · ad8012c ↗

990}
991filtered := make([]sdk.Tool, 0, len(providerTools))
992for _, tool := range providerTools {
993	if cfg.ChannelPolicy.AllowsTool(tool.Name) || cfg.ChannelPolicy.AllowsBackendTool(tool.Name) {
994		filtered = append(filtered, tool)
995	}
996}
997providerTools = filtered

Before optimization, the Tools section accounted for 21.3% of the request (~49.5 KB, roughly 12,000 tokens); now it is almost completely gone. Policy evaluation is fail-closed: if reading the policy fails, it exposes no tools rather than leaking tools that should be disabled.

telegram_message_metadata_mode controls how message metadata headers are projected, defaulting to compact on Telegram. Upstream prepends a full metadata header to every message sent to the model: <message id="..." sender="..." t="..." channel="telegram" conversation="..." type="..." target="...">. The canonical format in SQLite stays unchanged, but the transient projection sent to the LLM strips the per-message repeated timestamp, platform, and conversation name while keeping speaker attribution for group chats:

internal/agent/turn/user_header.goCompact message header projectionL165–183 · ad8012c ↗

165func ProjectUserMessageHeader(content, mode string) string {
166	if strings.ToLower(strings.TrimSpace(mode)) != "compact" || !strings.HasPrefix(strings.TrimSpace(content), "<message") {
167		return content
168	}
169	start := strings.Index(content, "<message")
170	if start < 0 {
171		return content
172	}
173	endRel := strings.Index(content[start:], ">")
174	if endRel < 0 {
175		return content
176	}
177	end := start + endRel
178	compactOpening, ok := projectMessageOpeningTag(content[start : end+1])
179	if !ok {
180		return content
181	}
182	return content[:start] + compactOpening + content[end+1:]
183}

That saves 85–120 characters per message, reduces occurrences of channel="telegram" in a request from 148 down to 2, and shrinks a full-history payload from 221.0 KB to 208.7 KB.

Change 5: Giving Text-Only Models "Eyes"

Some of the primary models I run don't support vision (such as DeepSeek V4 Flash), yet people post images in group chats all day long. I added an auxiliary vision model mechanism: when the primary model declares no vision support and the current turn includes image attachments, a cheap small vision model describes the images first:

internal/agent/application/auxiliary_vision.goTrigger only when the primary model lacks visionL183–196 · ad8012c ↗

183func (s *Service) describeImagesWithAuxiliaryVision(
184	ctx context.Context,
185	req ChatRequest,
186	primarySupportsVision bool,
187	attachments []gatewayAttachment,
188) string {
189	if s == nil || primarySupportsVision {
190		return ""
191	}
192	images := extractNativeImageParts(attachmentsToAny(attachments))
193	return s.describeImagePartsWithAuxiliaryVision(ctx, req, primarySupportsVision, images)
194}
195
196func (s *Service) describeImagePartsWithAuxiliaryVision(

The generated description is appended as an <auxiliary_vision_description> block at the tail of the last user message, once again leaving the cached prefix untouched:

internal/agent/application/auxiliary_vision.goAppend vision descriptions to the tail of the last user messageL454–467 · ad8012c ↗

454func appendAuxiliaryVisionToLastUserMessage(messages []sdk.Message, visionContext string) []sdk.Message {
455	visionContext = strings.TrimSpace(visionContext)
456	if visionContext == "" {
457		return messages
458	}
459	for i := len(messages) - 1; i >= 0; i-- {
460		if messages[i].Role != sdk.MessageRoleUser {
461			continue
462		}
463		messages[i].Content = append(messages[i].Content, sdk.TextPart{Text: "\n\n" + visionContext})
464		return messages
465	}
466	return append(messages, sdk.UserMessage(visionContext))
467}

Bonus Telegram-Specific Polish

A few additional improvements aimed at making the bot feel more natural in Telegram group chats also helped keep costs predictable:

Continuously refreshing the typing indicator throughout any turn where the bot is selected to reply, so group members see "is typing…" instead of 30 seconds of dead silence followed by a wall of text;
Switching context compaction to a rolling-summary mode whose prompt explicitly forbids repeating raw tool-argument JSON; the context budget takes the smaller of the model's context window and the bot's compaction threshold, and truncation boundaries never split a user/tool pair mid-exchange.

How Much Did It Actually Save?

Modeling the savings is straightforward. The input cost of a single LLM call is:

C_{\mathrm{call}} = T \times \left[(1-h) \times P_{\mathrm{in}} + h \times P_{\mathrm{cache}}\right] = T \times P_{\mathrm{in}} \times \left[(1-h) + h \times r\right]

where T is the number of input tokens, h is the cache hit rate, and r = P_cache / P_in is the ratio of cached-input price to uncached-input price. Multiplying by the number of calls N per turn separates the before/after ratio into three independent factors:

\frac{C_{\mathrm{before}}}{C_{\mathrm{after}}} = \frac{N_{\mathrm{old}}}{N_{\mathrm{new}}} \times \frac{T_{\mathrm{old}}}{T_{\mathrm{new}}} \times \frac{f(h_{\mathrm{old}})}{f(h_{\mathrm{new}})}

where $f(h) = (1-h) + h \times r$ . Each of the three factors is grounded in real measurements:

N_old / N_new = 2–3: pure text turns drop from 2 calls to 1, and reply + sticker turns drop from 3 calls to 1. This is structural—no estimation involved;
T_old / T_new ≈ 70K / 52K ≈ 1.35: stripping the unused tool schemas (49.5 KB), dynamic sticker catalog (18.3 KB), and repeated message headers removes ~20K tokens per request;
h_new = 99.7% is measured in production; I set h_old = 95% to be generous to upstream's automatic prefix caching, which works well on ordinary turns and only loses its prefix when MEMORY.md is rewritten.

Using official provider pricing as of 2026-08-03—DeepSeek V4 Flash at $0.0028/$0.14 = 1/50, Claude Sonnet 4.6 at 1/10, Kimi K2.6 at ~1/6, and Doubao seed-1.6 at 1/5—and plugging in conservative numbers (N ratio = 2, h_old = 95%):

Model	r	f(95%) / f(99.7%)	Total Factor 2 × 1.35 × f-ratio	Savings
DeepSeek V4 Flash	1/50	3.0	≈ 8.1×	≈ 88%
Claude Sonnet 4.6	1/10	1.4	≈ 3.8×	≈ 74%
Kimi K2.6	≈1/6	1.2	≈ 3.3×	≈ 70%

The pattern is obvious: the steeper the cache discount, the more leverage you get from pushing the hit rate to 99.7%—DeepSeek's 50× cache discount pushes total savings close to 90%. Meanwhile, the call-count factor N doesn't depend on caching at all; it's free money. This matches what I see on my actual billing dashboard: costs dropped to well under 1/5 of what they were, and the conservative formula gives ~1/8 on DeepSeek even before counting the eliminated output tokens.

Closing Thoughts

All I really did was ask one question at every step of the pipeline: when you put a general-purpose agent framework into a high-frequency group chat, is this read or this LLM call actually necessary? Don't make an extra call just to confirm a sent message, combine text + reply + sticker into a single call, push volatile files to the tail of the prompt prefix, don't send a single byte of unused tool schemas, and let a cheap small vision model look at images first.

Once again, credit goes to upstream for building a solid foundation: the tool loop, history projection, and channel abstractions are cleanly separated. The reason I could pull off this degree of specialization in a little over a week is precisely because those boundaries were well drawn—wrapping the provider for terminal send without touching the core loop, and filtering tools before schema generation, both plugged cleanly into seams the architecture already had. If your use case is "an agent that does multi-step work," upstream's defaults are probably right for you; if, like me, you just want a talkative resident in your Telegram group that won't burn through your wallet, I hope these notes help.

New Blog Features: Language Icons, Source Quotes, Tickers, and Charts

Mon, 22 Jun 2026 00:00:00 +0000

This post was written during the old blog (Next.js + MDX) era. After migrating to the current static site, all of these features happen at build time: TradingView widgets became ticker cards that only load the live chart when you click "Live chart"; ECharts blocks became static SVG charts with hover values; source embeds are pinned commit snippets with line numbers; and language icons became corner language labels on code blocks.

This update pushes the blog's writing experience another step forward: code blocks are easier to scan, code references link straight to GitHub, and financial posts can embed TradingView charts with a tiny shortcode.

What's New

Language Icons on Code Blocks

A language logo and copy button float in the top-right corner of every code block—no title bar, no badge border, and no extra vertical space. When a block has a title or comes from GitHub, a small path line appears above the code and the GitHub link sits tucked into a small icon in the top-right corner.

const feature = 'language icons'
const theme = 'catppuccin'
console.log(feature, theme)

Restyled Inline Code

Inline code in prose like git log --follow, $AAPL, and ::tv AAPL no longer sticks out like a bright patch. In light mode it blends closer to Catppuccin Latte's paper tone, and in dark mode it settles into a low-luminance Mocha surface.

Quoting GitHub Code Directly

When writing a post, enter:

::github-code repo="mizorewww/blog" ref="c067042276d4b4b384c66c0c61fcd4f6716eb599" path="contentlayer.config.ts" lines="251-253" lang="ts" title="contentlayer.config.ts"

It renders as a code block with Shiki syntax highlighting, a language icon, and a direct link to GitHub:

contentlayer.config.tsL251–253 · c067042 ↗

251const githubEmbedPattern = /^::github-(code|diff)\s+(.+)$/
252const tradingViewMiniPattern = /^\$([A-Za-z0-9._:-]+)$/
253const tradingViewAdvancedPattern = /^::(?:tv|tv-advanced|tradingview)\s+(.+)$/

Line-by-Line Diff Highlighting Like GitHub

When writing a post, enter:

::github-diff repo="mizorewww/blog" ref="c067042276d4b4b384c66c0c61fcd4f6716eb599" path="css/prism.css" lines="1-15"

Rendered output:

Changes to css/prism.css in c067042

@@ -8,6 +8,44 @@ figure[data-rehype-pretty-code-figure] [data-rehype-pretty-code-title] {
   @apply flex items-center justify-between gap-3 border-b border-slate-200 bg-white/70 px-4 py-2 text-xs text-slate-600 dark:border-[#405064] dark:bg-white/[0.035] dark:text-white/65;
 }
 
+figure[data-rehype-pretty-code-figure] .code-title-main {
+  @apply inline-flex min-w-0 items-center gap-2;
+}
+
+figure[data-rehype-pretty-code-figure] .code-language-icon {
+  @apply inline-flex h-5 min-w-5 shrink-0 items-center justify-center rounded-[5px] border border-slate-300 bg-slate-100 px-1 font-sans text-[0.62rem] leading-none font-semibold text-slate-600 dark:border-white/15 dark:bg-white/10 dark:text-white/70;
+}
+
+figure[data-rehype-pretty-code-figure] .code-language-icon[data-code-language='ts'],
+figure[data-rehype-pretty-code-figure] .code-language-icon[data-code-language='tsx'] {
+  @apply border-sky-200 bg-sky-50 text-sky-700 dark:border-sky-400/25 dark:bg-sky-400/10 dark:text-sky-200;

diff

Single-Line Tickers Become Mini Charts

Put a ticker on its own line:

$AAPL
$BINANCE:BTCUSDT.P

On the old site, each of these lines turned into a Mini Chart. The current static site doesn't load TradingView scripts upfront—instead, it renders a ticker card linking to TradingView:

NASDAQ:AAPLApple Inc.TradingView ↗

BINANCE:BTCUSDT.PBitcoin / USDT PerpetualTradingView ↗

Shortcode for Advanced Charts

When writing a post, enter:

::tv AAPL interval=60 height=460

On the old site this rendered an interactive Advanced Chart; here it is likewise a ticker card.

Rendering ECharts Directly from Code Blocks

Use an ```echarts code block whose body is the chart's option JSON, with title and height supported in the meta string:

```echarts title="Weekly Visits" height=320
{
  "tooltip": { "trigger": "axis" },
  "xAxis": {
    "type": "category",
    "data": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
  },
  "yAxis": { "type": "value" },
  "series": [
    {
      "name": "Visits",
      "type": "line",
      "smooth": true,
      "areaStyle": {},
      "data": [120, 200, 150, 80, 70, 110, 130]
    }
  ]
}
```

On the old site these were two ECharts instances. The current site draws the same data as static SVG at build time; since there is no pie chart type, the second example is represented as a data table:

Weekly Visits

050100150200TueThuSat200 · Tue

Posts by Category

Category	Posts	Share
Tinkering	40	40%
Dev	32	32%
Notes	18	18%
Other	10	10%

If the JSON is invalid, it gracefully falls back to a regular code block instead of breaking the build. When you need functions or other options that plain JSON cannot express, you can also pass a JS object directly to the <ECharts> component. Charts follow the site's light/dark theme, and the echarts library is lazy-loaded on demand so it stays out of the initial bundle.

How It Works Under the Hood

Turning Shortcodes into Components in Remark

These regular expressions match the ticker chart syntax. $AAPL becomes a Mini Chart and ::tv AAPL becomes an Advanced Chart.

contentlayer.config.tsL251–253 · c067042 ↗

251const githubEmbedPattern = /^::github-(code|diff)\s+(.+)$/
252const tradingViewMiniPattern = /^\$([A-Za-z0-9._:-]+)$/
253const tradingViewAdvancedPattern = /^::(?:tv|tv-advanced|tradingview)\s+(.+)$/

The Mini Chart transform is intentionally conservative: it only triggers when an entire paragraph consists of a single ticker, so mentioning $AAPL in the middle of a sentence won't drop a giant chart into the paragraph.

contentlayer.config.tsL288–295 · c067042 ↗

288function createTradingViewMiniNode(symbol: string): MdastNode | null {
289  if (!isTradingViewTicker(symbol)) {
290    return null
291  }
292
293  return createMdxFlowNode('TradingViewMiniChart', {
294    symbol: normalizeTradingViewSymbol(symbol),
295  })

Advanced Chart adds parameter parsing so attributes like height=460 and interval=60 are forwarded as JSX props.

contentlayer.config.tsL298–313 · c067042 ↗

298function createTradingViewAdvancedNode(source: string): MdastNode | null {
299  const [rawSymbol, ...attrParts] = source.trim().split(/\s+/)
300
301  if (!rawSymbol || !isTradingViewTicker(rawSymbol)) {
302    return null
303  }
304
305  const attrs = parseEmbedAttributes(attrParts.join(' ')) as TradingViewAttrs
306
307  return createMdxFlowNode('TradingViewAdvancedChart', {
308    height: attrs.height,
309    interval: attrs.interval,
310    locale: attrs.locale,
311    symbol: normalizeTradingViewSymbol(rawSymbol),
312    timezone: attrs.timezone,
313  })

Finally, the plugins are wired into Contentlayer's remark pipeline. Because shortcodes are transformed before MDX compilation, no string scanning happens in the browser.

contentlayer.config.tsL1063–1069 · c067042 ↗

1063export default makeSource({
1064  contentDirPath: 'data',
1065  documentTypes: [Blog, Authors],
1066  mdx: {
1067    cwd: process.cwd(),
1068    remarkPlugins: [remarkGfm, remarkTradingViewWidgets, remarkIconShortcodes, remarkGitHubEmbeds],
1069    rehypePlugins: [

Loading TradingView Only on the Client

The official TradingView widget requires injecting an external <script>, so the component stays a client component. On render, it clears the container and inserts the widget mount node and config script; whenever the theme or props change, it rebuilds the widget.

components/TradingViewWidgets.tsxL83–101 · c067042 ↗

83useEffect(() => {
84  const container = containerRef.current
85
86  if (!container) {
87    return
88  }
89
90  container.innerHTML = '<div class="tradingview-widget-container__widget"></div>'
91
92  const script = document.createElement('script')
93  script.async = true
94  script.src = scriptSrc
95  script.text = JSON.stringify(config)
96  container.appendChild(script)
97
98  return () => {
99    container.innerHTML = ''
100  }
101}, [config, scriptSrc])

Ticker symbols are normalized first. Bare AAPL defaults to NASDAQ:AAPL, while an explicit symbol like NYSE:IBM is left untouched.

lib/tradingview.tsL4–20 · c067042 ↗

4export function normalizeTradingViewSymbol(value: string, defaultExchange = 'NASDAQ') {
5  const symbol = value.trim().replace(/^\$/, '').toUpperCase()
6
7  if (!symbol) {
8    return ''
9  }
10
11  if (explicitTradingViewSymbolPattern.test(symbol)) {
12    return symbol
13  }
14
15  if (plainTickerPattern.test(symbol)) {
16    return `${defaultExchange}:${symbol}`
17  }
18
19  return symbol
20}

Enhancing Code Block Title Bars in Rehype

Language icons aren't written by hand in each post; they're injected across the board during the rehype pass. It locates the figure generated by Shiki and ensures a title bar exists.

contentlayer.config.tsL850–868 · c067042 ↗

850function enhanceCodeTitle(node: HastNode) {
851  if (
852    node.tagName !== 'figure' ||
853    node.properties?.['data-rehype-pretty-code-figure'] === undefined
854  ) {
855    return
856  }
857
858  const title = ensureCodeTitle(node)
859  const code = findDescendantElement(node, 'code')
860  const sourceUrl = typeof code?.data?.githubSourceUrl === 'string' ? code.data.githubSourceUrl : ''
861  const language = getCodeLanguage(code)
862  const titleText = getNodeText(title) || getLanguageName(language)
863
864  title.children = [createCodeTitleNode(titleText, language)]
865
866  if (sourceUrl) {
867    title.children.push(createCodeSourceLinkNode(sourceUrl, language))
868  }

The left side of the title bar pairs the language icon with the title text. When no explicit title is provided, it falls back to the language display name—such as TypeScript, Diff, or Markdown.

contentlayer.config.tsL787–799 · c067042 ↗

787function createCodeTitleNode(titleText: string, language: string): HastNode {
788  return {
789    type: 'element',
790    tagName: 'span',
791    properties: { className: ['code-title-main'] },
792    children: [
793      createCodeLanguageIconNode(language),
794      {
795        type: 'element',
796        tagName: 'span',
797        properties: { className: ['code-title-text'] },
798        children: [{ type: 'text', value: titleText || getLanguageName(language) }],
799      },

Visually, the logos come straight from simple-icons brand icons, tree-shaken on demand so they don't bloat first-load JavaScript; languages without a brand icon fall back to a short text badge.

css/prism.cssL11–17 · c067042 ↗

11figure[data-rehype-pretty-code-figure] .code-title-main {
12  @apply inline-flex min-w-0 items-center gap-2;
13}
14
15figure[data-rehype-pretty-code-figure] .code-language-icon {
16  @apply inline-flex h-5 min-w-5 shrink-0 items-center justify-center rounded-[5px] border border-slate-300 bg-slate-100 px-1 font-sans text-[0.62rem] leading-none font-semibold text-slate-600 dark:border-white/15 dark:bg-white/10 dark:text-white/70;
17}

Keeping Inline Code from Stealing Attention

Inline code now uses a low-contrast, subtly bordered token style. It's still unmistakably code, without popping out of the paragraph like a button.

css/tailwind.cssL110–124 · c067042 ↗

110& :where(code):not(pre code) {
111  border: 1px solid color-mix(in oklab, var(--color-slate-300) 72%, transparent);
112  border-radius: 6px;
113  background: linear-gradient(
114    to bottom,
115    color-mix(in oklab, white 92%, var(--color-slate-100)),
116    color-mix(in oklab, var(--color-slate-100) 88%, white)
117  );
118  box-shadow: inset 0 -1px 0 color-mix(in oklab, var(--color-slate-300) 45%, transparent);
119  color: #4c4f69;
120  padding: 0.08rem 0.34rem;
121  font-size: 0.86em;
122  font-weight: 500;
123  line-height: 1.75;
124  word-break: break-word;

GitHub Code and Diffs Still Go Through Shiki

At build time, ::github-code and ::github-diff fetch the real source file or diff and emit a standard code AST node. That means they don't need a custom renderer—Shiki highlights them just like any other code block.

contentlayer.config.tsL543–552 · c067042 ↗

543if (kind === 'code') {
544  const value = selectCodeLines(await getGitHubFile(attrs), attrs.lines)
545  const title =
546    attrs.title ||
547    `${normalizeGitHubRepo(attrs.repo)}:${attrs.path}${attrs.lines ? `#L${attrs.lines}` : ''}`
548
549  return createCodeNode(value, attrs.lang || 'text', title, {
550    showLineNumbers: true,
551    sourceUrl: getGitHubCodeUrl(attrs),
552  })

Diffs follow the exact same path, except the data source is a patch and the language defaults to diff.

contentlayer.config.tsL555–563 · c067042 ↗

555const value = selectCodeLines(await getGitHubDiff(attrs), attrs.lines)
556const title =
557  attrs.title ||
558  `${normalizeGitHubRepo(attrs.repo)}:${attrs.path || `${attrs.base || attrs.ref}...${attrs.head || ''}`}`
559
560return createCodeNode(value || 'No diff matched this query.', attrs.lang || 'diff', title, {
561  showLineNumbers: true,
562  sourceUrl: getGitHubDiffUrl(attrs),
563})

That's why GitHub embeds get the Shiki color theme, language icon, copy button, GitHub link, and diff line backgrounds all at once.

The Mental Model for Writing Posts

For normal posts, you just write Markdown. When you want an icon, write :icon-code:; for a market ticker, write $AAPL or ::tv AAPL; for a data chart, write an ```echarts block; to quote source code, write ::github-code; and to quote a commit diff, write ::github-diff.

The build step turns these shortcodes into stable MDX components or Shiki code blocks, while the runtime only handles interactivity and external widgets. The authoring syntax stays brief, and the rendered page stays predictable.

Fixing Obsidian Web Clipper Not Working on KDE Plasma Wayland

Sun, 10 May 2026 00:00:00 +0000

While using Obsidian on Plasma Wayland, I noticed that whenever Obsidian was already open, clicking Add to Obsidian in Chrome's Obsidian Web Clipper extension created a completely blank note.

The content would only show up properly if I closed Obsidian completely before clipping from Web Clipper.

Cause

This isn't because Web Clipper failed to capture the page—it's because KDE prevented the already-running Obsidian instance from properly receiving focus.

When Web Clipper hands page content over to Obsidian, Obsidian needs to be raised and focused properly to read the incoming data. Under KDE's default window management rules, an Obsidian instance running in the background can be blocked from stealing focus, so the clipped content is never written and you end up with an empty note.

Analysis

The key symptoms are:

Clipping works normally when Obsidian is closed;
Clipping produces an empty note when Obsidian is already open;
This means the browser extension itself is working fine;
The failure happens when Obsidian is already running and KDE prevents it from responding properly to Web Clipper's activation request.

So this is a window focus and activation permission issue in KDE, not a misconfiguration in your Obsidian vault, templates, or Chrome extension.

Solution

Add a window rule for Obsidian in KDE: open System Settings → Window Management → Window Rules and configure it as shown below.

Xiaomi Book Pro 14 on Linux

Sun, 10 May 2026 00:00:00 +0000

The reason I picked up this Xiaomi Book Pro 14 is quite simple: I already have a MacBook Pro that works great for my daily needs, but there are always things that a Mac either can't do or does awkwardly. I needed an x86 thin-and-light to handle the tasks that are "best done on x86."

As someone who can't stand leaving things stock, the first order of business with a new machine was, naturally, installing Arch Linux. I ran into a few pitfalls along the way and thoroughly dug into the fingerprint feature—something I’d never used before. I’m documenting it all here as a record for myself and a reference for anyone who encounters similar issues.

First, here are the specs of my unit:

SoC: Intel Ultra X7 358H
RAM: 32GB LPDDR5x 9600MT/s (Soldered)
GPU: Intel Arc B390

Problem 1: Screen Artifacts

Right after the installation, the screen was glitching out. After some digging, the culprit turned out to be Intel's Panel Self Refresh technology.

The fix is straightforward—just add this line to your kernel parameters:

xe.enable_psr=0

Problem 2: Keyboard Not Recognized

This one was even weirder: the keyboard worked perfectly in the BIOS and GRUB, but became completely unresponsive as soon as the system booted. Getting stuck here during the installation process is incredibly frustrating.

The solution, again, is to add kernel parameters:

i8042.nopnp=1 i8042.dumbkbd=1

Once the screen and keyboard were sorted out, the system was basically usable. What follows is the part I spent the most time on—the fingerprint reader.

Fingerprint: The Main Event

Honestly, I'd never used a device with a fingerprint reader before, so I explored this area quite meticulously and hit many snags. It deserves its own write-up.

Why doesn't `sudo` pop up a fingerprint GUI like macOS?

This was the most irritating part of the whole ordeal. On macOS, sudo can use Touch ID. Why not on Linux?

It's not that "no one thought of it"; it's that the architectures are fundamentally different.

The authentication chain for sudo looks like this:

sudo → PAM → Terminal session or askpass

The beautiful KDE fingerprint authentication dialog, on the other hand, follows a different path:

App → Polkit → KDE Polkit Agent → PAM → fprintd

That GUI is provided by the Polkit agent. It doesn't spring forth from PAM itself, nor is it part of sudo. The PAM module can only participate in the authentication flow; it can't magically transform a terminal-based sudo prompt into a KDE-style identity verification pop-up.

Using sudo -A with SUDO_ASKPASS can indeed pop up a graphical password box, but that's still on sudo's own askpass track, which is separate from the KDE Polkit agent. So, at best, it makes the "enter password" step a GUI, but it can't bring over the fingerprint experience.

macOS can do it because Apple integrated sudo, PAM, Touch ID, the Secure Enclave, and LocalAuthentication at the system level right from the start. On Linux, these components belong to different projects and thus have no natural path to a unified experience.

A Key Limitation of `pam_fprintd`: The PAM Stack is Serial

There's another fundamental limitation with pam_fprintd: in a standard PAM stack, it and password authentication execute in series.

My initial ideal experience was something like this:

For a single sudo prompt, it would simultaneously wait for my password and my fingerprint, using whichever was provided first.

But in reality, this isn't possible. A login manager can use more complex methods to fire up multiple PAM sessions to simulate concurrency, but a regular sudo won't do that.

So, the real-world choices are limited to the following experiences:

Option A: Fingerprint first, fallback to password on failure.
Option B: Password first, fallback to fingerprint if you press Enter with an empty field.
Option C: Only use the Polkit GUI, don't force fingerprint on sudo.
Option D: Use a third-party hack module (not recommended—don't mess around with root authentication).

I eventually settled on Option B, but I tried Option A first. Let me explain why it flopped.

Option A: Fingerprint First, Fallback to Password (Post-Mortem)

My initial, intuitive configuration was this, in /etc/pam.d/sudo:

#%PAM-1.0

auth        sufficient  pam_fprintd.so max-tries=3 timeout=8
auth        include     system-auth
account     include     system-auth
session     include     system-auth

Logically, this looks fine: try the fingerprint first. If it succeeds, great; if not, it'll ask for a password.

But in practice, it broke. I deliberately let the fingerprint recognition fail, then typed the correct password, but sudo still would not let me through. The logs showed entries like this:

pam_unix(sudo:auth): conversation failed
pam_unix(sudo:auth): auth could not identify password for [...]
pam_faillock(sudo:auth): Consecutive login failures ... account temporarily locked

Meanwhile, fprintd was also complaining:

Device was already claimed
Verification was in progress, stopping it

It seems the interaction between sudo, the terminal PAM conversation, pam_fprintd, and the subsequent password stack gets into a messy state. After the fingerprint failed, the password fallback didn't take over cleanly, and it also increased the faillock failure count, temporarily locking my account.

The biggest danger with this kind of problem is that you're modifying the root privilege escalation entry point. If you bork /etc/pam.d/sudo and don't have another root channel, it's easy to lock yourself out.

My recovery method at that time was using a still-functional Polkit:

pkexec sh -c 'cat > /etc/pam.d/sudo <<EOF
#%PAM-1.0
auth        include     system-auth
account     include     system-auth
session     include     system-auth
EOF
faillock --user username --reset
systemctl restart fprintd
'

bash

I suggest keeping this rollback method in mind: first, revert sudo to Arch's default password-only path, then clear faillock, and finally restart fprintd to release any lingering device claims. It's a lifesaver in critical moments.

Option B: Password First, Empty Enter for Fingerprint (My Current Setup)

I later switched to a different approach: the system presents a normal sudo password prompt, but if you just press Enter (submitting an empty password), it falls back to fingerprint verification.

My current configuration in /etc/pam.d/sudo:

#%PAM-1.0

# Prompt for password first; an empty password triggers a fingerprint attempt
auth        sufficient  pam_unix.so try_first_pass likeauth nullok

# Prevent fingerprint prompts in non-tty background sudo processes
auth        [success=1 default=ignore] pam_succeed_if.so service in sudo:su:su-l tty in :unknown
-auth       sufficient  pam_fprintd.so max-tries=3 timeout=8

# Arch's default fallback
auth        include     system-auth
account     include     system-auth
session     include     system-auth

The interactive flow goes like this:

[sudo] password for user:

If you want to enter a password, just type it. If you want to use your fingerprint, press Enter on an empty field, and it will switch to:

Place your right index finger on the fingerprint reader

This approach feels more intuitive in the terminal than "fingerprint first," but it has its own little quirks.

The Catch with Option B: Empty Enter Can Leave a Failure Record

That "empty Enter" step inherently goes through pam_unix.so first. From pam_unix's perspective, an empty string is not a correct password, so it registers an authentication failure before the PAM flow moves on to pam_fprintd.

When you check faillock, you might see a record like this:

user:
When                Type  Source       Valid
2026-05-08 ...      TTY   /dev/pts/1   V

This means that even if the subsequent fingerprint authentication is successful, that initial empty Enter step might still be logged as a failed attempt.

So, if you go with this option, keep a few things in mind:

Don't set faillock's failure threshold too low.
Always leave a working root backdoor while debugging PAM, like a currently functional pkexec.
After consecutive failures, remember to check:

faillock --user "$USER"

bash

And manually reset it if necessary:

faillock --user "$USER" --reset

bash

Also, a side note: if you want the most stable graphical privilege escalation experience, it's best to just prefer Polkit for daily use and not force everything through sudo.

KWallet: Why You Can't Unlock It with a Fingerprint

This is another common point of confusion.

The role of kwallet-pam is, when you log in with your password, to pass that login password to KWallet, allowing the wallet to be automatically unlocked with the same credentials.

There's a line in the logs that says it all:

pam_kwallet5(plasmalogin-autologin:auth): Empty or missing password, doing nothing

This line makes the problem crystal clear: an automatic or fingerprint-based login does not provide the plaintext "user password," so KWallet doesn't get the key it needs.

A fingerprint authentication only answers one question:

Is this person who they claim to be?

KWallet's decryption requires an answer to a different question:

What is the key or password used to open the wallet?

The fingerprint device won't spit out your login password; it only tells the system if the authentication was successful. Therefore, KWallet has no way to decrypt using a fingerprint alone.

There are a few ways to handle this:

Disable automatic login, log in with your password, and keep your KWallet password synchronized with your login password.
Accept reality and manually enter your KWallet password once after reaching the desktop.
Reduce wallet security, for instance, by using a wallet with an empty password—but this is absolutely not recommended, especially if you're storing important keys.

So, this isn't a case of KDE failing to connect things; it's that "authentication" and "decryption" are fundamentally two different things.

`fprintd` Device Contention Issues

During my tinkering, I also encountered this error:

Device was already claimed
Verification was in progress, stopping it

This usually means a previous verification didn't terminate cleanly, or several authentication requests are simultaneously trying to claim the same fingerprint device.

The fix is simple:

systemctl restart fprintd

bash

If you lack sufficient user permissions, use your confirmed-working Polkit backdoor:

pkexec systemctl restart fprintd

bash

This is also why I don't recommend configuring too many authentication entry points to automatically grab the fingerprint reader. The device can serve only one verification request at a time. When multiple PAM or Polkit requests compete for it, the resulting experience becomes incredibly erratic.

Final State Summary

After all that tinkering, here's the current fingerprint and authentication configuration for this machine:

fprintd: Correctly identifies the Goodix device. I have enrolled my right index finger.
KDE User Settings: Fingerprint can be managed through kcm_users.
Polkit: Prioritizes fingerprint, falls back to password on failure.
kio-admin: Installed, allowing graphical root file operations via the admin:// protocol.
sudo: Asks for password first; pressing Enter on empty triggers a fingerprint attempt (max 3 tries).
Plasma Login Manager: PAM is configured for fingerprint, but auto-login bypasses it.
KWallet: Cannot be unlocked with a fingerprint alone.

Conclusion

The Linux compatibility of this Xiaomi Book Pro 14 is far better than I imagined. The few issues I faced all had clear causes and solutions, and in general, it's been a very smooth experience.

Another feeling I have is that tinkering with systems is much faster than it used to be. In the past, I'd have to dig through piles of ArchWiki entries and man pages for a problem. Now, you can just ask ChatGPT "how to fix xxx," and the efficiency is on a whole different level. This time, I even used OpenAI Codex, making the overall debugging process smoother by orders of magnitude.

mizore / notes

gdirect: Direct Google Drive Access from the Terminal — How It Works and Setup Guide

TL;DR: How Do We Connect Directly Without a Proxy?

Installation

Option 1: One-Line Install Script

Option 2: Homebrew (macOS / Linux)

One-Time Google Cloud Setup Guide (~10 Minutes)

1. Create a Project and Enable the Drive API

2. Configure the OAuth App

3. Add the Drive Scope

4. Create a Desktop Client and Download the JSON

5. Allow Your Account to Sign In (and Avoid the 7-Day Expiry)

6. Log In from the Terminal

Mainland China Network and Proxy Configuration Guide

Tracing the Packet Path: How Does a Proxy Sniffer Hijack Direct Traffic?

Approach 1: Quit Your Proxy (or Turn Off TUN) During scan and Downloads

Approach 2: Add Direct Rules in Your Proxy Client for Drive Domains (or the gdirect Process)

Daily Usage & Troubleshooting Reference

Common Commands

Troubleshooting Quick Reference

Technical Deep Dive: How Is It Implemented Under the Hood?

1. Candidate IP Scanning & Dual-Endpoint Verification

2. Custom libaria2: Why Patching the C++ Source Was Necessary

(1) Allowlist of Google Drive Transfer Domains

(2) Intercepting getaddrinfo and TLS SNI in SocketCore.cc

(3) Stripping Authorization Headers Across Redirects & Redirect Allowlisting

(4) Removing the OpenSSL 3 Legacy Provider Dependency

3. Overwrite Guards, Large-File Virus-Scan Confirmation Pages, and MD5 Verification

4. 32 MiB Resumable Chunked Uploads

5. Localhost Loopback + PKCE OAuth Flow

Putting Memoh Under the Knife: Specializing an Agent for Cheaper Telegram Group Chats

Where Does the Money Actually Go?

Change 1: Clock Out Right After Sending

Change 2: Send Text, Reply, and Sticker in a Single Call

Change 3: Move Everything That Changes to the Tail of the Prefix

Change 4: Invisible Request Slimming

Change 5: Giving Text-Only Models "Eyes"

Bonus Telegram-Specific Polish

How Much Did It Actually Save?

Closing Thoughts

New Blog Features: Language Icons, Source Quotes, Tickers, and Charts

What's New

Language Icons on Code Blocks

Restyled Inline Code

Quoting GitHub Code Directly

Line-by-Line Diff Highlighting Like GitHub

Single-Line Tickers Become Mini Charts

Shortcode for Advanced Charts

Rendering ECharts Directly from Code Blocks

How It Works Under the Hood

Turning Shortcodes into Components in Remark

Loading TradingView Only on the Client

Enhancing Code Block Title Bars in Rehype

Keeping Inline Code from Stealing Attention

GitHub Code and Diffs Still Go Through Shiki

The Mental Model for Writing Posts

Fixing Obsidian Web Clipper Not Working on KDE Plasma Wayland

Cause

Analysis

Solution

Xiaomi Book Pro 14 on Linux

Problem 1: Screen Artifacts

Problem 2: Keyboard Not Recognized

Fingerprint: The Main Event

Why doesn't sudo pop up a fingerprint GUI like macOS?

A Key Limitation of pam_fprintd: The PAM Stack is Serial

Option A: Fingerprint First, Fallback to Password (Post-Mortem)

Option B: Password First, Empty Enter for Fingerprint (My Current Setup)

The Catch with Option B: Empty Enter Can Leave a Failure Record

KWallet: Why You Can't Unlock It with a Fingerprint

fprintd Device Contention Issues

Final State Summary

Conclusion

Approach 1: Quit Your Proxy (or Turn Off TUN) During `scan` and Downloads

Approach 2: Add Direct Rules in Your Proxy Client for Drive Domains (or the `gdirect` Process)

2. Custom `libaria2`: Why Patching the C++ Source Was Necessary

(2) Intercepting `getaddrinfo` and TLS SNI in `SocketCore.cc`

(3) Stripping `Authorization` Headers Across Redirects & Redirect Allowlisting

Why doesn't `sudo` pop up a fingerprint GUI like macOS?

A Key Limitation of `pam_fprintd`: The PAM Stack is Serial

`fprintd` Device Contention Issues