# zhigeng: a right-Command key that drafts replies, and a codebase still called fold-runtime

> A macOS menu bar app for voice input and contextual reply drafting that keeps its context in files you control and routes three model roles through your own keys. The source is PolyForm Noncommercial rather than open source, and the repository is still named fold-runtime internally.

**Littlesheepxy/zhigeng** — 知更 — 本地 AI 的上下文与记忆层。Mac 上用语音输入、情境代回并调度 Codex / Claude Code；iOS 正在成为随身记忆终端和本地 Agent 遥控器。Local-first · BYOK.

- Repository: https://github.com/Littlesheepxy/zhigeng
- Website: https://zhigeng.app
- Stars: 486 · Forks: 20
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/littlesheepxy-zhigeng

## PolyForm Noncommercial is source-available, and the page lists what it forbids

The license is named on the page: PolyForm Noncommercial 1.0.0, described as source-open with a non-commercial grant. It is not one of the OSI licenses, and the difference is stated as a two-column table rather than left to the reader.

Permitted: viewing, learning from and researching the source; personal and non-commercial self-use and modification; taking part in trial feedback and issue discussion. Forbidden: using the source or derivative works to build a commercial product; taking on clients, selling services or turning it into a SaaS; and redistributing with the copyright notice removed.

So the accurate description is source-available, and the third prohibition is the one that trips people up: a modified copy that drops attribution is not a permitted derivative under these terms.

This sits next to a commercial website at zhigeng.app serving a signed, notarized DMG, which is coherent, since the license permits the author's own product while restricting third parties. Commercial cooperation and licensing go through a single email address given on the page. The repository's license metadata, however, reports NOASSERTION rather than the named license, which is what GitHub records when it cannot match a file to a standard identifier.

## The package is still fold-runtime, scoped @fold/*, on disk at ~/.fold

The user-facing product is 知更, romanized Zhigeng. Inside the repository the earlier name survives everywhere. The page says so directly: the product name shown to users is 知更, while the engineering package names in this repository are still `@fold/*`.

The root package is named `fold-runtime`, is marked private, and describes itself as Fold Runtime, a local context agent for macOS. The npm scripts filter on `@fold/desktop`, `@fold/site` and `@fold/asr-proxy`. The turbo dev command excludes `@fold/site` by filter.

The rename stopped at the filesystem boundary too. The local Whisper model path in the example environment is `~/.fold/models/ggml-small.bin`, so a user's data directory is created under the old name, and the documentation screenshots live in a `docs/readme/` directory rather than anything named after the product.

That is ordinary rename debt in a young project, but it has a practical cost. Anyone writing automation, a launch agent or a support document has to match on `fold`, and anyone auditing which service talks to which endpoint has two names to hold in mind for the same product.

## Speech can run locally, but the language model calls are BYOK cloud requests

The local-first claim is split, and the project is explicit about where the line sits. Speech recognition can be entirely on the machine, using SenseVoice or Whisper. Large model inference cannot be made to work locally by downloading something, so the page says plainly that you supply your own cloud API key in settings, under BYOK, and that the key is stored only in the local keychain.

What that key buys is split across three distinct roles, each with its own provider and model. A planner role handles agent task planning and is tuned for quality. A fast role handles transcription cleanup and the text path for reply drafts, and is tuned for speed. A vision role turns a screenshot straight into a draft, with thinking disabled.

The defaults in the example environment:

```bash
FOLD_PLANNER_PROVIDER=moonshot
FOLD_PLANNER_MODEL=k3
FOLD_FAST_PROVIDER=openrouter
FOLD_FAST_MODEL=google/gemini-3.1-flash-lite
FOLD_VISION_MODEL=glm-5v-turbo
```

So one feature can call three different vendors, and the vision path degrades rather than failing: with a Zhipu key present it uses vision automatically, and on failure falls back to OCR plus the fast text model. That is a sensible design for cost and latency, and it is also the reason the key configuration is more involved than a single API key implies.

## A .env.example with seven providers, an ASR proxy and one unexplained hub URL

The example environment file is the most informative document in the repository, and it is long. Beyond the three model roles it covers speech in several forms.

Cloud ASR goes through a DashScope path with two websocket endpoints, one for inference and one for realtime, plus a proxy port. The proxy has commented-out `ASR_PROXY_REQUIRE_AUTH` and `ASR_PROXY_SKIP_AUTH` flags, and the desktop connects to it over `ws://localhost:3003`. The provider selector accepts `auto`, `local-funasr`, `local-whisper` and `dashscope`, and the local engine line is commented out with SenseVoice named as the default, an Alibaba open-source model.

A second, unrelated ASR block exists for iOS, using a Volcano Engine streaming recognition resource identifier. So the Mac and the iPhone reach for different speech vendors.

Keys for OpenRouter and Zhipu are live in the example, with OpenAI, Anthropic, DeepSeek and Moonshot commented out as alternatives for the planner role.

One line has no explanation anywhere: `FOLD_HUB_URL` points at a separate service on a `.cn` domain. Whether it fetches models, phones home for updates or does something else is not described in what is written down, and it is set to a live value rather than left blank.

## Every dev script is prefixed with dotenv -c, and install prepares a whisper addon

The root scripts show a consistent pattern that is worth noting before you run anything. Nearly every one that starts a process is wrapped in `dotenv -c --`, which loads the environment file first. The desktop dev script runs a native rebuild for `@fold/desktop`, then starts the ASR proxy and the desktop app in parallel. The generic dev script first runs a helper that ensures `better-sqlite3` is in a usable state, then hands off to turbo with a concurrency of 12 while excluding the site package.

There is also a `postinstall` hook that fires on every `pnpm install` and runs a script preparing a whisper addon inside the desktop app. The four commands in the project's own instructions are:

```bash
pnpm install
cp .env.example .env
pnpm desktop:dev
pnpm site:dev
```

The copy line is annotated as optional, with a note that a mock path lets you walk the flow without filling in any key. That matters, because the project otherwise looks like it needs five vendor credentials before it will start.

Two more scripts suggest how the team works: an end-to-end smoke test that runs a shell script, and an agent stress test driven through tsx. There is a voice hotword pipeline script and a recipe statistics script alongside them. Packaging a signed and notarized DMG is a single command, `pnpm desktop:pack`, and it needs a Developer ID and notarization credentials on the machine doing it.

## pnpm is pinned to 10.14.0 and only seven packages may run build scripts

The package manager is not merely chosen, it is pinned to an exact version, `pnpm@10.14.0`, through the package manager field. Node is 20 or newer. TypeScript is pinned exactly at 5.9.2 while the other development dependencies carry caret ranges.

The install allowlist is the more interesting configuration. `onlyBuiltDependencies` names exactly seven packages that are permitted to execute install scripts: a macOS input package in the project's own scope, `better-sqlite3`, `electron`, `esbuild`, `uiohook-napi`, a computer-use package, and `sherpa-onnx-node`.

Read together, those seven explain most of what the application does. A global hotkey library and a macOS input package are how a right-Command press is captured system-wide. A computer-use package is how the app can act rather than only suggest. `sherpa-onnx-node` is the runtime behind local SenseVoice recognition. `better-sqlite3` is the store the scripts keep repairing before launching.

Gating all of that behind an explicit allowlist is the right default for a package manager that blocks install scripts, and it also means an upstream package that starts needing a build step will fail closed rather than silently.

## One Apple Silicon release, a menu bar app, and three near-duplicate ideas for input

There is a single release, v0.0.1, dated 2026-08-26, and the download is a single Apple Silicon DMG that the page describes as signed and notarized. There is no beta code to enter. The last push to the default branch is dated 2026-09-01.

The interaction model is a menu bar resident app that watches the current window, the conversation on screen and the clipboard, without taking focus. Then there are three gestures layered on the same key. A short press of right Command starts structured voice input, which is described as drafting rather than dictation: corrections heal, filler words are dropped, and tone shifts depending on whether the target is Feishu, WeChat or email. A long press of right Command produces several candidate replies for the conversation in front of you, and choosing one inserts it into the real input box so you decide whether to send. Option Space hands a task to a local agent, with simple work done directly and code or heavy work passed to Codex or Claude Code.

Every one of those three is logged. Voice input, reply drafts and local actions all land in an activity view that keeps the original alongside the organized result, and a separate trace records which apps and windows you worked in plus your copy history.

So the privacy story is about storage: the memory is local, viewable, switchable and deletable. What leaves the machine is the model traffic, per the key configuration.

## The iOS keyboard is not in the DMG, and it keeps the fold naming too

The iOS side is a keyboard extension for iOS 17 and newer, currently in development and not publicly released. It is explicitly not part of the macOS DMG, and progress is tracked separately in `apps/ios/README.md`.

The stated goal is parity with existing Chinese input methods rather than a separate app, with a system keyboard, speak-and-type, smart candidates and voice input, instead of opening another application and pasting. It would also carry the same memory and profile and send instructions to a local agent on a home or office Mac.

The listed progress is more specific than the goal. A keyboard extension with Live Activity for input in any app, hold-to-speak transcription, and an in-house pinyin engine named `ZhigengCore` doing its own segmentation and candidates for whole-sentence input and correction. Dictation uses a Volcano Engine streaming recognizer inside the main app, while the desktop side stays on SenseVoice, Whisper or a cloud option. Alignment of people, hotwords and habits across devices is described as gradually being completed.

The iPhone acting as a remote control for an agent on your Mac is listed as still in development, not as working.

Two structural notes: the repository root also holds `Experiments/`, `prototypes/` and a `design-qa.md` next to `docs/`, and the Star History heading appears twice in the page.

## Conclusion

Zhigeng is a macOS-only, Apple Silicon product built on two ideas: dictate intent rather than words, and keep the resulting context in files you control rather than inside a vendor account. Two things to weigh first. The source is PolyForm Noncommercial, so reading, modifying and personal use are fine while commercial products, client work and SaaS are explicitly ruled out, and the metadata field reports NOASSERTION rather than the named license. And the local-first claim is narrower than it sounds: speech recognition can run locally on SenseVoice or Whisper, but the language model calls are BYOK cloud requests routed across a planner, a fast model and a vision model, with several provider keys to fill in.

## FAQ

### What does zhigeng do on macOS?

It sits in the menu bar without taking focus, watching the current window, conversation and clipboard. A short press of right Command starts structured voice input, a long press produces several candidate replies for the conversation on screen, and Option Space hands a task to a local agent.

### Is zhigeng local-first, or does it call a cloud service?

Both, in different places. Speech recognition can run entirely locally on SenseVoice or Whisper, but the language model calls use your own cloud API keys stored in the local keychain. The example environment routes a planner model, a fast model and a vision model as separate roles.

### Can I use zhigeng commercially?

Not under the repository license, which is PolyForm Noncommercial 1.0.0. The page permits viewing, learning, researching, and personal or non-commercial modification, and forbids commercial products, taking on clients or selling services, and redistributing without the copyright notice.

### Is the zhigeng iOS version available yet?

Not publicly, and it is not in the macOS DMG. It is being built as an iOS 17 or newer keyboard extension and portable memory terminal with its own streaming recognition provider, and progress is tracked in `apps/ios/README.md`.

### How do I run zhigeng from source?

With pnpm: `pnpm install`, then copy `.env.example` to `.env` if you have keys, then `pnpm desktop:dev` or `pnpm site:dev`. Keys are optional because a mock path lets you walk the flow, and `pnpm install` triggers a postinstall step that prepares a whisper addon.

## Sources

- [Issues](https://github.com/Littlesheepxy/zhigeng/issues)
- [Littlesheepxy/zhigeng on GitHub](https://github.com/Littlesheepxy/zhigeng)
- [Project website](https://zhigeng.app)
- [README](https://github.com/Littlesheepxy/zhigeng/blob/main/README.md)
- [Releases](https://github.com/Littlesheepxy/zhigeng/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/littlesheepxy-zhigeng