How to Forward WeChat Chat History to Codex and Claude on macOS with Dukou

Dukou (渡口) is a free, open-source macOS utility that adds five destinations to WeChat’s “Forward to Other Apps” menu, including Codex, Claude, the clipboard, and a Dropover-style stash shelf. It is MIT-licensed and ships as a signed, notarized Universal 2 app.

The problem it solves is easy to run into. Since WeChat 4.1.13 for macOS, you can multi-select messages and use merged forwarding to send them to a third-party app. WeChat itself packages the text, images, and videos into a ZIP and attaches a chronological TXT transcript, with no database access and no decryption involved. The share menu, however, only lists apps that ship a share extension, and Finder, Terminal, Codex, and Claude all lack one. Dukou registers those missing destinations as system extensions. Install it, flip on the entries you want, and the forwarding menu gains five working routes.

WeChat 4.1.13’s Forward to Other Apps menu, with Dukou’s five entries lined up beside the built-in share services

The Dukou overview screen, with entry toggles, Quick WeChat Forward, the stash shelf, and records

The Five Forwarding Entries Dukou Adds to WeChat

Each entry is an independent system share extension, and every one can be switched on or off inside Dukou under “Settings → Entries,” so there is no trip to System Settings. Tapping an entry never opens a panel. The file lands on disk immediately, and the extension finishes copying before macOS reclaims its temporary files, which means a batch shows up complete or not at all.

One step beyond the manual flow sits “Quick WeChat Forward” (experimental), which exports, verifies, and pastes recent messages from a chosen group by name and count, no manual multi-select required. Forwarding 500 messages takes about 20 seconds end to end, and the feature gets its own section below.

How to Install Dukou on macOS

Three installation routes exist, and all of them start from the same requirements. You need macOS 14 or later. The “Send to Codex” and “Send to Claude” entries require ChatGPT.app or Claude.app on the machine. Building from source additionally requires Xcode 26 (Swift 6.2), with mise optional.

Install with Homebrew

The fastest route is a single cask command.

brew install --cask qzz0518/tap/dukou

Later updates run through brew upgrade --cask dukou, or you can wait for the app’s built-in Sparkle updater to prompt you.

Install from a DMG

Download the latest Dukou-*.dmg from the Releases page, open it, and drag Dukou into Applications. Homebrew and Releases serve the identical package, a Developer ID-signed and Apple-notarized Universal 2 DMG that runs on both Intel and Apple Silicon Macs.

Build from source

git clone https://github.com/qzz0518/Dukou.git
cd Dukou
mise run reinstall   # assembles and signs dist/Dukou.app, installs to ~/Applications

Without mise, the equivalent is two commands.

CONFIG=release Scripts/make-app.sh
Scripts/install-dev-build.sh

If you build yourself, the signing choice matters more than it looks. The build scripts automatically select a stable Developer ID or Apple Development identity from your keychain. macOS stores accessibility (TCC) grants against the code signature, so an ad-hoc signature changes on every rebuild and drops the grant along with it. A self-built copy that keeps losing its accessibility permission and drags you back into System Settings is almost certainly suffering from ad-hoc signing.

Setting Up Dukou for the First Time

Two things need settling at first launch, and the four-step wizard walks you through the first one. Newly installed share extensions ship disabled, and they never appear in WeChat’s forwarding menu until you enable them in Dukou’s “Settings → Entries.” If the WeChat menu looks empty right after install, that toggle page is the first place to look.

The second item is the Accessibility permission, which powers auto-paste. Skipping it is safe and the remaining entries keep working; Dukou re-prompts the first time a forward fails without it.

With both settled, the whole flow reads as follows. Multi-select messages in WeChat, pick merged forwarding, choose “Forward to Other Apps,” then tap one of Dukou’s entries. The interface, all five menu items, and the error messages ship in both Simplified Chinese and English.

How to Use Each of the Five Targets

Stash to Dukou, a Dropover-style shelf

The entry drops the file straight onto the shelf, with no confirmation dialog in between. The shelf is a floating square that never steals focus and lives in a screen corner of your choosing, so typing continues uninterrupted while it holds your batch. Drag a file from the icon into any app, and an accepted drop consumes the batch; once everything has been dragged off, the shelf removes itself. The files themselves survive every step and move into the Records page.

Records give each batch an entry showing which route it took, how it ended, and how much disk it occupies. Batches no longer on the shelf age out after a retention period (7 days by default) and move to the Trash, where they can be sent back to the shelf whenever you need them again.

Send to Codex or Claude with auto-activate and paste

Both entries require ChatGPT.app or Claude.app installed. On tap, Dukou brings the target app to the foreground and pastes the files, together with your attached prompt, into its input field. The target can be running in the background or even minimized, and the delivery still lands. Activation goes through NSWorkspace, and the paste is a synthetic ⌘V issued via CGEvent under a system authorization, so no private APIs are involved anywhere. The Accessibility permission from setup is exactly what authorizes that synthetic ⌘V.

Copy to Clipboard

The plainest entry. File URLs go onto the clipboard and the operation ends there, leaving paste timing and destination entirely to you. Reach for it when the target app sits outside your supported list, or when you want manual control over the moment of pasting.

Send to Custom, your own app list

Settings hold a list of apps you maintain yourself. A single target receives the files directly on tap; multiple targets produce a small card beside the cursor for picking. The same list backs the shelf’s right-click menu and the Records page’s “Send To ▸” menu, so one edit updates every surface. Terminal-class applications get a dedicated treatment, receiving only a quoted file path that drops straight into a command line.

Attach a prompt to every send

Forwards headed to Codex, Claude, custom apps, or the quick-forward flow paste a saved prompt first and the files second. Terminal-class apps receive the prompt prepended to the file path. One summary-style prompt ships built in, you can store up to 3 of your own, and switching between them takes a click. The agent receives the files already knowing what to do with them, which removes the step of retyping instructions on every send.

What Happens When a Forward Fails

Three failure modes come up in practice, a missing target app, a missing permission, and a target that never made it to the foreground. The fallback covers all three identically. By the time the alert appears, the files have already been written to the clipboard, and the alert itself offers a “Stash to shelf” button so you can park the batch and drag it manually. The inverse rule holds too. A successful forward produces no notification at all.

How Quick WeChat Forward Works

This experimental feature removes even the manual multi-select. You supply a group name and a message count, and Dukou drives WeChat through the Accessibility APIs to perform the multi-select and merged forward itself, then verifies the exported ZIP and pastes it into whatever app you are currently using. The target can be backgrounded or minimized and the delivery still arrives.

The performance numbers give a sense of scale. Forwarding 500 messages takes about 20 seconds end to end, and runs beyond 100 messages split into batches automatically. A status pill in a screen corner reports progress while the run executes, and cancelling is possible at any moment.

The mouse and keyboard belong to Dukou for the duration of a run, and you cannot compete with it for input. Pick a window when you do not need the machine.

How Dukou Handles Your Chat Data

A tool sitting between WeChat and your clipboard earns scrutiny, so here is the complete path of the data.

The no-network property of the extensions gets enforced by tooling. The five share extensions hold no network entitlements at all, and Scripts/check-release-config.sh in the repo continuously asserts that fact, so a configuration regression fails the check outright. Updates carry EdDSA signatures. On the API side, activation uses NSWorkspace and pasting uses CGEvent plus a system authorization, with no private API anywhere in the chain. The one design tradeoff worth naming is the unsandboxed main app, which exists solely because pkd refuses sandboxed processes, while the five extensions that actually touch chat files all remain sandboxed.

Building and Developing Dukou from Source

The project splits into three targets. DukouCore holds the inbox protocol, manifests, forwarding intents, and batch state, along with the pure logic of WeChat automation kept separately testable. DukouShare is the share extension itself, restricted to import and disk write with no interface. DukouApp is the resident app covering the shelf, auto-paste, permission onboarding, the settings window, WeChat automation, and Sparkle updates. Tests covers the inbox, batch state, forwarding targets, and WeChat record parsing.

The five .appex bundles share a single executable, distinguished from one another by DKShareAction. The handoff between extension and app runs through a two-phase inbox. The extension copies files into the App Group’s Inbox/Staging, writes the manifest and intent, then renames the whole directory to Inbox/Ready in one atomic operation. The main app watches the directory and consumes the intent, which is read-once-and-delete, so each batch executes exactly once and never delivers twice. That atomic rename is the mechanism behind the all-or-nothing delivery mentioned earlier, and it explains why an interface-free extension hurries to finish copying before the system reclaims its temporary files.

Day-to-day development commands are registered under mise.

For release work, mise run release handles the entire pipeline from a clean tag through build, signing, notarization, stapling, and appcast generation, and release-dry-run produces a candidate artifact for inspection before the real thing.

Known Limitations of Dukou

The README is upfront about the project’s stage. The five entries, the shelf, auto-paste, and Sparkle updates have been verified end to end on the author’s machine. Three areas remain unverified, large files, multi-monitor setups, and the permission onboarding flow on a brand-new machine. If your usage lands in one of those, reporting what you find on GitHub Issues is the most useful feedback you can give.

Quick-Start Checklist

• [ ] Install with brew install --cask qzz0518/tap/dukou, or grab the DMG from Releases and drag it into Applications
• [ ] Launch Dukou and follow the four-step wizard; enable your entries under “Settings → Entries” (they ship disabled and stay hidden until enabled)
• [ ] Grant Accessibility if you want auto-paste; skipping is safe, and Dukou re-prompts on the first failure
• [ ] In WeChat, multi-select messages, pick merged forwarding, choose “Forward to Other Apps,” tap a Dukou entry
• [ ] Save up to 3 prompts in settings so every agent send carries instructions ahead of the files
• [ ] Add frequently used apps to the custom target list; enable path-only pasting for terminal apps
• [ ] Records keep for 7 days by default, then move to Trash, restorable to the shelf at any time
• [ ] Update via brew upgrade --cask dukou, or wait for the Sparkle prompt

FAQ

Q: Does Dukou read WeChat’s message database or decrypt anything?

A: No. WeChat itself exports the selected messages as a ZIP plus a TXT transcript, and Dukou treats that package as an opaque file, copying it without unzipping or inspecting the contents.

Q: Why doesn’t Dukou show up in WeChat’s forwarding menu after I install it?

A: Newly installed share extensions ship disabled. Open Dukou’s “Settings → Entries” and switch on the ones you want; only enabled entries appear in the menu.

Q: Why does auto-paste need the Accessibility permission?

A: The paste is Dukou pressing ⌘V on your behalf through CGEvent, which requires a system authorization. Without the grant, only auto-paste is affected and the other entries keep working.

Q: I built Dukou from source and the Accessibility permission keeps failing. Why?

A: Ad-hoc signatures change on every rebuild, and macOS stores TCC grants against the code signature. Build with the repo’s own scripts, which select a stable Developer ID or Apple Development identity from your keychain.

Q: Does Dukou send my chat history anywhere online?

A: No. The five extensions are sandboxed with no network entitlements, and the main app’s only network activity is Sparkle checking for and downloading updates you confirmed, all signature-verified.

Q: How long does Quick WeChat Forward take for 500 messages?

A: About 20 seconds end to end, with automatic batching beyond 100 messages. Dukou owns the mouse and keyboard during the run, and the corner status pill lets you cancel at any time.

Q: If the target app is closed or in the background, does the forward get lost?

A: No. The files are always written to the clipboard first, and the failure alert includes a “Stash to shelf” button.

Q: Do the shelf and records take up disk space forever?

A: No. Records that are no longer on the shelf move to the Trash after the retention period (7 days by default) and can be sent back to the shelf whenever needed.