LingShu

Purpose and Positioning

LingShu is a fully open-source, model-agnostic execution-oriented agent, belonging to the category of execution-oriented coding agents such as Codex / Claude Code, rather than the category of chat applications. Its design orientation differs from similar tools: the complete native application and runtime are open-sourced under Apache-2.0, the model backend is replaceable, and code is only one of multiple deliverables. This comparison is a positioning statement, not a benchmark test or a claim of superiority.

Main Capabilities

• Deliver complete reports, not just outlines: Starting from a brief description, LingShu can organize a structured narrative, generate a real, editable presentation or document, register and preview that file, iterate on revisions, and then hand it to an independent checker for verification.
• Bring your own model: OpenAI, Anthropic, DeepSeek, MiniMax M3, or custom compatible endpoints can be used; the agent layer is not bound to a single model provider.
• Fully inspectable runtime: The Swift application, orchestration, tools, task records, artifact ledger, memory, and Computer Use implementation are all released under Apache-2.0.
• Delegate real work: The main agent can plan tasks, dispatch isolated worker sessions, invoke tools, and hand results to an independent checker.
• Deliver files rather than claims: Documents, presentations, code, scripts, and reports are written to disk, tracked, previewable, and checked before completion.
• Use the Mac natively: LingShu can read accessibility snapshots and operate authorized applications through native macOS APIs; this Computer Use path does not depend on Codex.
• Preserve context: Task records, local artifacts, memory, and distilled subtask summaries are available across sessions.

Flagship Workflow: Complete Report

A presentation or document-type request can run as a trackable delivery loop:

1. Understand the brief and source materials, and determine the expected deliverables and acceptance criteria.
2. Organize the story, content, and layout, using local tools to create a real .pptx, .docx, or other required report format.
3. Register the file in the task artifact ledger, open it in the built-in preview, and revise the actual output.
4. Before declaring the task complete, hand the result to an independent checker.
5. For presentations, optionally build a narration queue, present the document, and answer questions based on its content.

The final output is a local file that canOpen, editable, previewable, and usable by subsequent tasks, rather than a fabricated filename in chat. Output quality still depends on the configured model, source materials, and local toolchain; important reports should be manually reviewed before external use.

Public real-world example

Project Aurora is a fictional release-grade project, created as a privacy-safe, reproducible LingShu task. A brief specification produced an editable four-page presentation and a one-page document; subsequent independent rendering drove multiple rounds of revision until the final manuscript passed structural checks and page-by-page visual review. This example honestly describes the run: the first checker missed defects exposed by external rendering, and LingShu continued revising and re-verifying under the same goal, rather than presenting the first output as a finished product.

The main conversation remains serial to protect context; long-running or delegated work uses isolated sessions, then returns a distilled completion record to the main agent. During execution, the model can only update the parts of the runtime graph that are still pending; the GoalSpec and acceptance boundaries remain fixed. A worker, tool, or checker can pause for its exact session to wait for human participation and resume from that checkpoint, rather than restarting the goal.

How to use

Environment requirements: macOS 14 or later; or the Windows 10/11 x64 technical preview; requires an API token from a supported model provider, or a compatible custom endpoint.

macOS installation (signed and notarized): With Homebrew, the app and the lingshu CLI are installed together. You can also install manually from the Universal DMG: download the DMG and its .sha256 file from the v0.1.0-alpha.9 release page, and verify the download in Terminal:shasum -a 256 -c LingShu-0.1.0-12-macOS-universal.dmg.sha256, then open the DMG, drag 灵枢.app into Applications, and launch it. Select a language, connect a model provider, and send a small request. The public DMG is Universal (arm64 + x86_64), signed with a Developer ID certificate, notarized by Apple, and carries a stapled notarization ticket. Grant macOS permissions only when the selected capability requires them.

Windows installation (technical preview): Download Nous-Windows-x64-Setup.exe and SHA256SUMS.txt, and verify in PowerShell:Get-FileHash .\ Nous-Windows-x64-Setup.exe - Algorithm SHA256 and Get-Content .\SHA256SUMS.txt, then run the installer, choose a language, connect a model provider, and send a small request.

First trackable task: After choosing a language and connecting a model, start with a small local deliverable instead of immediately granting broad computer permissions, for example: "Create a one-page DOCX project brief, save it locally, preview it, and have an independent verifier check the result." A complete first run has three visible signals: a real .docx appears in the LingShu workspace; the file opens in the built-in preview; and the task record shows both the artifact and the independent verifier result.

Building from source: This additionally requires Xcode Command Line Tools with Swift 6. Run the packaged .app rather than the bare Swift executable, so macOS associates the correct icon, signing identity, and privacy permissions. On first launch, LingShu checks whether a usable brain channel exists; if not, setup onboarding allows you to choose a provider and enter its token. Custom providers also require an endpoint and model name.

CLI and External Connectors

Every app build includes the lingshu command-line client. It is a lightweight entry point to the same serial main conversation: it does not create a second agent runtime, nor does it bypass model selection, memory, authorization, task records, or human-in-the-loop gating. Homebrew automatically exposes the built-in client; manual DMG installations can add it to PATH as documented. It can then be used in single-request/single-response mode from a terminal, a Feishu bot, a webhook worker, Shortcuts, or another local process. If an exact task pauses due to login, QR code scanning, file selection, confirmation, or another human step, the JSON output returns needs_user_action, typed materials, and a message ID; it can be resumed from the same checkpoint. By default, this client communicates only with LingShu's loopback control service.

Permissions and Security

• LingShu requests macOS permissions only when a capability requires them. Computer control may require Accessibility and Screen Recording; voice and visual perception may require microphone, speech recognition, and camera access.
• Sensory streams are processed by LingShu in memory and are not archived by default.
• Content sent to a configured remote model or perception provider leaves the Mac and is subject to that provider's retention and privacy terms.
• Model credentials are stored in the macOS Keychain; secrets in task tracking are redacted where supported.
• High-risk, non-Reversible, account, authorization, or public-release operations require explicit user confirmation.
• Native Computer Use is limited by permission scope and, where possible, re-verifies the UI after operations.

Applicable Scenarios and Limitations

Applicable scenarios: Workflows that require locally generating and verifying presentations, documents, code, scripts, and reports; scenarios where you want to choose your own model provider; tasks that require operating native Mac applications under authorization; sustained work that requires preserving context and artifacts across sessions.

Limitations: LingShu is in alpha and under active development; it is not yet a finished consumer-grade product. It can run local files and applications, but requires explicit macOS authorization; you should review the permissions requested and back up important work. The Windows technical preview and the macOS app execute the same Runtime/LingShuCore::RuntimeKernel implementation, but the Windows version intentionally does not provide direct Windows computer control or real-time perception. The Windows preview has not yet been Authenticode-signed and may display a SmartScreen warning; verify the published SHA-256 before installing. The repository contains more than 100,000 lines of source and test code, over 180 Swift test files, and more than 1,500 tests; these numbers describe engineering depth and do not guarantee that every environment-dependent test will pass on every Mac. Output quality depends on the configured model, source materials, and local toolchain. Official builds are pinned to Developer ID Team KM7N84AC9Y and the current signing certificate fingerprint; modifying official binaries invalidates the signature, and forks must use their own signing identity.

License and References

LingShu is licensed under the Apache License 2.0, and third-party components retain their own licenses. The project was created and is maintained by Roy Zhao. Architectural references include the bilingual architecture and value map, the architecture overview, and the Chinese architecture field guide. You can ask questions and share workflows in GitHub Discussions, report reproducible defects via the issue tracker, and report security issues privately in accordance with SECURITY.md.