LingShu
Bring your own model to produce and verify code, documents, presentations, and authorized Mac actions locally.
- Source repo
- RoyZhao1991/LingShu
- Stars
- ★ 12
- Last updated
- 1mo ago
- License
- Apache-2.0
- Primary language
- Rust
- FA score
- 71/100 · Some gaps
At a glance
- Works with
- Universal · cross-platformOpenAI API · Claude API
- You'll need
- Typical use
- A project lead preparing an internal or client report can turn one brief into editable PPTX and DOCX files, review them in the built-in preview, and inspect the independent checker result.
- Main limitation
- The project is explicitly alpha-stage and under active development, so it is not a finished consumer product and environment-dependent behavior may vary.
- Source review
- 71/100 · Some gaps
What does this agent do, and when should you use it?
LingShu is an Apache-2.0 local execution agent whose native application, runtime, orchestration, tools, memory, and artifact records are published as open source. Its macOS application and Windows technical preview use the same `Runtime/LingShuCore::RuntimeKernel`, with access through the desktop UI, bundled `lingshu` CLI, and a loopback HTTP JSON-RPC control plane. The main conversation stays serialized while isolated workers, local tools, and authorized macOS Computer Use perform delegated work before an independent checker reviews the result. Deliverables are real PPTX, DOCX, PDF, code, script, and media files that can be registered, previewed, revised, and reused by later tasks. The model gateway supports OpenAI, Anthropic Claude, DeepSeek, MiniMax M3, and custom compatible endpoints while keeping the runtime, memory, and artifacts on the user's computer; content sent to remote providers remains subject to their terms. The project is alpha software intended for development and controlled local workflows rather than a finished consumer product.
LingShu converts a request into a structured GoalSpec and fixed acceptance boundary, then executes the unfinished work through a mutable runtime workflow, serial task queue, isolated workers, local tools, and authorized Computer Use. It can read and write files, run shell commands, edit code, execute tests, inspect Git changes, and create, register, preview, and revise PPTX, DOCX, PDF, Markdown, code, scripts, and local media. Completed files enter an artifact ledger and can be passed to an independent checker before the task is declared complete; the documented public sample also shows revision and re-verification after an external render exposed defects missed by the first check. On macOS, Computer Use reads accessibility snapshots, performs indexed UI actions, falls back to screen information, and verifies the interface again after actions when possible. A worker, tool, or checker can pause its exact session for login, QR scanning, file selection, confirmation, or a physical action, then resume through lingshu answer <message-id>. The gateway implements OpenAI Responses, Chat Completions, Anthropic Messages, streaming, and compatible custom routes; multimodal handling first tries native model vision and falls back to image parsing when necessary.
- A project lead preparing an internal or client report can turn one brief into editable PPTX and DOCX files, review them in the built-in preview, and inspect the independent checker result.
- A developer who wants a local engineering loop can use LingShu to edit source files, run tests, inspect Git changes, and register the resulting code or reports as traceable artifacts.
- A team already using OpenAI, Claude, DeepSeek, MiniMax, or a private compatible endpoint can keep one local orchestration layer instead of tying its workflow to a single model vendor.
- A macOS user who must operate native applications can grant the required Accessibility and Screen Recording permissions for indexed UI actions with post-action verification.
- An operator maintaining a Feishu bot, webhook worker, Shortcut, or another local integration can send requests through the
lingshuCLI into the same serialized conversation used by the desktop app. - A human-in-the-loop workflow can pause for authentication, QR scanning, file selection, confirmation, or a physical step and resume the same execution checkpoint afterward.
How do you install or deploy this agent?
macOS requires version 14 or later. Homebrew installs both the application and bundled CLI:
brew install --cask RoyZhao1991/tap/lingshuFor a manual installation, download the Universal DMG and its checksum file from the v0.1.0-alpha.9 release, then verify it:
shasum -a 256 -c LingShu-0.1.0-12-macOS-universal.dmg.sha256Drag 灵枢.app into Applications. If installed manually, expose the bundled CLI on PATH:
mkdir -p "$HOME/.local/bin"
ln -sf "/Applications/灵枢.app/Contents/MacOS/lingshu" "$HOME/.local/bin/lingshu"
export PATH="$HOME/.local/bin:$PATH"Windows 10/11 x64 users can download Nous-Windows-x64-Setup.exe and SHA256SUMS.txt, then compare the installer hash in PowerShell:
Get-FileHash .\Nous-Windows-x64-Setup.exe -Algorithm SHA256
Get-Content .\SHA256SUMS.txtThe Windows build is a technical preview and is not yet Authenticode-signed. Building from source additionally requires Xcode Command Line Tools with Swift 6:
git clone https://github.com/RoyZhao1991/LingShu.git
cd LingShu
bash Scripts/build-app.sh debug
open "dist/灵枢.app"On first launch, choose a language and configure an API token for OpenAI, Anthropic Claude, DeepSeek, or MiniMax M3. A custom provider also requires its endpoint and model name, plus a token when required. On macOS, credentials are stored in Keychain.
How do you use this agent?
Begin with a small traceable request that does not require broad computer permissions, such as: “Create a one-page project brief in DOCX, save it locally, preview it, and have an independent checker verify the result.” Confirm that a real .docx appears in the Workspace, opens in the built-in preview, and is listed in the task record alongside the checker result.
The CLI submits work to the same serialized main conversation as the app:
lingshu ask "Summarize today's project status"
echo "Create a one-page report" | lingshu ask --json
lingshu status --jsonWhen JSON output reports needs_user_action with a message ID, complete the requested human step and resume that checkpoint:
lingshu answer <message-id> "completed"Grant macOS Accessibility, Screen Recording, Microphone, Speech Recognition, or Camera permission only when the selected capability needs it. Review important reports and high-risk operations before external use.
What are this agent's strengths and limitations?
- It produces files rather than merely claiming completion: PPTX, DOCX, PDF, code, and scripts are written to disk, registered in an artifact ledger, previewed, and independently checked.
- The model layer can use OpenAI, Anthropic Claude, DeepSeek, MiniMax M3, or a compatible custom endpoint without binding the agent runtime to one vendor.
- The native app,
RuntimeKernel, orchestration, Computer Use implementation, memory, and task records are available under Apache-2.0 for inspection and self-hosted use. - The app, CLI, and connectors share the same serialized conversation, model configuration, memory, authorization gates, and task records.
- Exact-session pause and resume supports practical workflows that require authentication, QR scans, file choices, confirmations, or other human intervention.
- The project is explicitly alpha-stage and under active development, so it is not a finished consumer product and environment-dependent behavior may vary.
- Full Computer Use and realtime perception are macOS capabilities; the Windows technical preview deliberately excludes direct computer control and realtime audio/video perception.
- The Windows installer is not Authenticode-signed and may trigger SmartScreen, requiring users to verify its published SHA-256 manually.
- Adopters must supply a model API token or compatible endpoint, and remote inference introduces provider charges as well as provider-specific privacy and retention terms.
- Computer control and perception can require sensitive Accessibility, Screen Recording, Microphone, Speech Recognition, and Camera permissions.
- Independent checking is not infallible: the public sample documents defects that the first checker missed and an external render later exposed.
How does this agent compare with similar options?
LingShu positions itself in the execution-agent category established by OpenAI Codex and Claude Code rather than as a chat application. Unlike their software-engineering-first focus, LingShu treats code, PPTX, DOCX, PDF, local media, and authorized Mac actions as first-class deliverables. Its complete native application and agent runtime are Apache-2.0 and its model backend is selectable across OpenAI, Claude, DeepSeek, MiniMax, and compatible endpoints; the source also notes that Codex exposes an Apache-2.0 CLI while the official Claude Code repository is all rights reserved. This is a positioning comparison, not a performance benchmark, and output quality still depends on the selected model, source material, and local toolchain.
Key facts side by side with the most closely related agents.
| Agent | Source review | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|
| LingShu This agent | 71 · Some gaps | ★ 12 | 1mo ago | Rust | OpenAI API · Claude API |
| Lotti Private Logbook | 80 · Good | ★ 1.2k | 4d ago | Dart | OpenAI API · Claude API |
| MagenticLite | 68 · Some gaps | ★ 10k | 2mo ago | Python | — |
| Open Cowork | 65 · Some gaps | ★ 2.2k | 10d ago | TypeScript | Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
The materials describe capability-triggered permissions, explicit confirmation for high-risk or public actions, disclosure that remote-provider data leaves the device, macOS Keychain storage, and risks from third-party plugins and scripts; CI also uses narrow declared permissions. Deductions apply because these controls are mainly documented rather than demonstrated in implementation code, Windows credential handling is unclear, trace redaction is qualified as only where supported, and no dependency audit, vulnerability scan, or strong supply-chain pinning is shown; Actions use version tags rather than immutable revisions. Backups are advised, but there is no general rollback mechanism for file, command, or UI effects. Authorship, licensing, and third-party attribution paths are clear, although publisher identity remains unverified.
The README, security policy, CI workflow, and supplied terminal scenarios are broadly consistent, with timeouts, running-state checks, and regression assertions. Requirements, model protocols, platform differences, and some fallback behavior are documented. Deductions reflect that nothing was executed and major claims such as 1,500+ tests, the shared kernel, and end-to-end verification cannot be fully checked from the supplied files; document-generation tooling and some environment dependencies are also incomplete. Structured needs_user_action and OCR capability-gap behavior show attention to failures, but detailed exit codes and error fields are only referenced in an unavailable guide.
The source thoroughly identifies users and scenarios including first-run tasks, report production, coding, connectors, human collaboration, and computer control. Platform exclusions, alpha status, model-quality dependence, perception fallbacks, and permission boundaries are unusually explicit, justifying full marks for scenarios and boundaries. Trigger precision is deducted because the confirmation and capability-trigger rules lack implementation evidence, while environment fit is reduced by macOS 14, Swift 6, permission, local-toolchain, and experimental-device constraints.
The README has strong navigation and coherent sections for architecture, setup, safety, status, development, and community. macOS, Windows, source-build, and installer-integrity instructions are concrete. Alpha limitations, missing Windows computer control, experimental virtual audio, and provider/environment variability are clearly disclosed, and the complete Apache-2.0 license is present. Deductions apply because LingShu, the Chinese app name, Nous, and Grok appear across surfaces, weakening naming stability; examples are good but a full FAQ is absent; and the changelog, roadmap, and several guides are referenced but not supplied. A maintainer and reporting paths are named, though the maintenance commitment is limited and identity is unverified.
The materials present directly usable outputs including editable PPTX, DOCX, PDF, code, previews, artifact registration, and independent checking. The candid account of a sample requiring revision after external rendering strengthens output-usability evidence. Multi-provider operation, local runtime control, persistent task records, and finished-document delivery offer plausible value beyond a basic chat interface. Deductions reflect that most benefits are self-reported without independent comparison, while API expense, inference cost, permission administration, human review, and environment setup are not quantified; alpha-stage risk also limits confidence in the cost-benefit claim.
The README associates installation versions, samples, CI, architecture, security, release, and change claims with concrete repository artifacts, while the supplied LICENSE, SECURITY, CI, and terminal scenarios corroborate part of the narrative. Deductions apply because many cited architecture, configuration, sample-history, changelog, and release-smoke artifacts were not supplied, and central runtime claims lack corresponding implementation excerpts. Fact and inference separation is strong: the comparison is explicitly not called a benchmark, and the source candidly distinguishes claims from model variability, environmental constraints, alpha status, and a checker miss.
- This is a static review of only the supplied files; the application, tests, installers, and release smoke checks were not executed.
- The project is alpha software capable of running commands, modifying files, and controlling authorized macOS applications; retain backups and manually review high-impact actions.
- Data sent to models, perception services, websites, plugins, or external agents may leave the device; review each provider's retention terms, tool permissions, and transmission scope.
- The Windows preview is not Authenticode-signed, and the supplied material does not establish credential protection equivalent to the macOS Keychain design.
- No dependency vulnerability scan, immutable Actions revision pinning, or general action-rollback evidence is shown; add supply-chain review and recovery planning before deployment.
FAQ
Do I have to use or purchase one specific model?
What information leaves the local machine?
Does Windows have the same capabilities as macOS?
Runtime/LingShuCore::RuntimeKernel for GoalSpec handling, queues, worker/checker sessions, tool loops, human-action resume, artifacts, and persistence. Windows is a technical preview and does not provide direct computer control or realtime audio/video perception.