Tech — 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.