LingShu
Bring your own model to produce and verify code, documents, presentations, and authorized Mac actions locally.
- Source repo
- RoyZhao1991/LingShu
- Stars
- ★ 11
- Last updated
- 3mo ago
- License
- Apache-2.0
- Primary language
- Rust
- FA score
- 69/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- 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.
- Not a fit if
- Production users who need a finished, stable product rather than alpha software
- Windows users who need direct computer control or realtime audio/video perception
- Source review
- 69/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 | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| LingShu This agent | 69 · Some gaps | Desktop appFree + model costs | ★ 11 | 3mo ago | Rust | OpenAI API · Claude API |
| Lotti Private Logbook | 78 · Good | Desktop appFree + model costs | ★ 1.2k | today | Dart | OpenAI API · Claude API |
| MagenticLite | 66 · Some gaps | CLIFree + model costs | ★ 10k | 3mo ago | Python | — |
| Presenton – Open-Source AI Presentation Generator & API | 65 · Some gaps | Self-hosted serviceFreemium | ★ 12k | 2d ago | TypeScript | — |
How does FollowAgents rate this agent?
Why each dimension lost points
The README, SECURITY.md, and permission troubleshooting guide say macOS permissions are requested by capability, sensitive or irreversible actions require explicit confirmation, and data sent to remote models or perception providers leaves the machine. The code excerpt shows API keys read through the system credential store and reports credential errors. These support ordinary handling of permissions, confirmation, data flows, credentials, and external effects. Dependency security scores 1 because the supplied evidence includes no dependency inventory or vulnerability-handling evidence. Rollback scores 1 because the excerpts do not show operation-level undo or recovery. Maintainer attribution and a private vulnerability reporting path are clear, supporting 2 for source attribution.
The README describes a shared Rust RuntimeKernel, the Windows Tauri excerpt calls it directly, and the CI workflow plus error-return examples support ordinary self-consistency and visible failures. The test-count and CI claims, and cross-environment availability, cannot be confirmed from this static sample. No lockfile or supply-chain evidence is included, so dependency availability scores 1; self-consistency and failure messages score 2 each.
The README gives concrete development, document, presentation, and authorized Mac workflow scenarios, and clearly states that Windows lacks direct computer control and realtime perception, alongside permission needs and alpha status. These support 3 for audience and scenarios and capability boundaries. The supplied SKILL.md trigger phrases are specific, but they are samples of embedded Grok shell skills and do not establish LingShu's overall triggering behavior, so trigger precision scores 1. Platform requirements are clear, but capabilities and signing status differ by platform, so environment fit scores 2.
The README links to architecture, CLI, security, platform, configuration, permissions, contribution, and roadmap documents; installation steps, examples, limitations, and recovery guidance are concrete. The license text matches the Apache-2.0 metadata, so information architecture, installation notes, examples and FAQ, known limitations, and license score 3. Version references and a CHANGELOG link exist, but the supplied sample does not include the changelog contents, so versioning scores 2. The maintainer is named, but maintenance commitments are limited; the Windows installer is named Nous while the product is LingShu, so naming stability scores 1 and maintenance responsibility scores 2.
The material describes and illustrates files that can be saved, previewed, revised, and independently checked, leaving editable and reusable outputs; output usability scores 3. Replaceable models and delegated tasks indicate value beyond chat, but the sample does not establish comparative gains in practice, so marginal value scores 2. The product depends on paid model APIs, broad local capabilities, and local tooling, while costs and benefits are not quantified, so cost-benefit scores 1.
The README links internal documentation for feature, boundary, and installation claims, and acknowledges a sample checker missed defects found by external rendering. The code excerpts corroborate parts of the credential and task-resume descriptions. Support across sources remains incomplete, and performance, test-count, and release-smoke claims are documentation claims rather than results verified by this static review, so claim traceability and cross-source corroboration score 2. The README labels its positioning comparison as neither a benchmark nor a superiority claim and says outputs depend on the model, source material, and toolchain; fact and inference separation scores 3.
- The project is alpha-stage; results depend on the model provider, environment, and local toolchain, so important outputs need human review.
- Remote model or perception services receive content the user chooses to send. The Windows preview is not Authenticode-signed and lacks direct computer control and realtime audio/video perception.
- The supplied material does not establish dependency security, operation rollback, or the actual execution of the README's test and release-check claims.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/lingshu)<a href="https://followagents.com/en/agents/lingshu"><img src="https://followagents.com/badge/lingshu.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Windows x64 technical preview built and tested on GitHub's Windows runner. Preview 0.1.0-27 replaces the default-looking setup flow with a LingShu-branded light-and-teal installer across welcome, location, maintenance, progress, completion, and uninstall surfaces. It also repairs upgrades from the legacy oyzhao publisher registry layout to Roy Zhao, including custom installation directories, while preserving %LOCALAPPDATA%\LingShu conversation and long-term-memory data. The release workflow now exercises preview.25-to-current upgrade, same-version reinstall, uninstall, and data preservation …View on GitHub ↗
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.Can it perform risky actions without asking?
Is a passing checker result sufficient for external publication?
Thanks — we use this to improve the page.