LingShu

A fully open-source, model-agnostic macOS execution agent in the Codex / Claude Code category.

Code is one deliverable, not the boundary: ship verified software, presentations, documents, and authorized Mac workflows.

Use OpenAI, Claude, DeepSeek, MiniMax, or a compatible endpoint. Keep the agent runtime, orchestration, tools, memory, and artifacts on your Mac.

English | 简体中文

Official website · Download signed macOS alpha · Inspect a real sample · Quick start · Community · 中文

_{16-second replay assembled from a real Project Aurora task record and its real deliverables. Captions were added; steps and outputs were not fabricated. This is a replay, not a continuous real-time recording.}

[!IMPORTANT]
LingShu is an alpha-stage project under active development. It can operate local files and apps after explicit macOS authorization. Review requested permissions and keep backups of important work.

Where LingShu Fits

Codex and Claude Code set the standard for execution-oriented coding agents. LingShu belongs in that same agent category—not the chat-app category—but makes a different architectural choice: the complete native app and runtime are Apache-2.0 open source, the model backend is replaceable, and code is one deliverable among several.

This is a positioning comparison, not a benchmark or claim of superiority. Product surfaces change; the current references are the official Codex repository, Codex product page, Claude Code repository, and Claude Code product page. Model capability and output quality vary by provider.

LingShu's differentiators are architectural:

• Finish the report, not just the outline. From one brief, LingShu can structure the narrative, create a real editable presentation or document, register and preview the file, iterate on it, and send it to an independent checker.
• Bring your own brain. Use OpenAI, Anthropic, DeepSeek, MiniMax M3, or a custom compatible endpoint without coupling the agent layer to one model vendor.
• Inspect the complete runtime. The Swift app, orchestration, tools, task records, artifact ledger, memory, and Computer Use implementation are published under Apache-2.0.
• Delegate real work. A main agent can plan work, dispatch isolated worker sessions, invoke tools, and hand results to an independent checker.
• Deliver files, not 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 apps through native macOS APIs. This Computer Use path does not require Codex.
• Preserve context. Task records, local artifacts, memories, and distilled child-task summaries remain available across sessions.

Flagship Workflow: Complete Reports

LingShu does not stop at “here is a slide outline.” A presentation or document request can run as one traceable delivery loop:

1. Understand the brief and source material, then define the expected deliverable and acceptance criteria.
2. Structure the story, content, and layout; create a real .pptx, .docx, or other requested report format with local tools.
3. Register the file in the task artifact ledger, open it in the built-in preview, and revise the actual output.
4. Hand the result to an independent checker before declaring the task complete.
5. For presentations, optionally build a narration queue, present the deck, and answer questions against its content.

The result is a local file that remains openable, editable, previewable, and available to later tasks—not a filename invented in chat. Output quality still depends on the configured model, source material, and local toolchain, so important reports should be reviewed before external use.

Real Public Sample

Project Aurora is a fictional release-quality initiative created as a privacy-safe, reproducible LingShu task. One brief produced an editable four-slide deck and a one-page document; independent rendering then drove several revisions until the final deck passed structural checks and page-by-page visual review.

• View the final PDF
• Download the editable PPTX
• Download the one-page DOCX
• Read the exact brief, revision history, and known checker limitation

The sample is deliberately honest about the run: the first checker missed defects that an external render exposed. LingShu continued the same goal through revision and re-verification rather than presenting the first output as finished.

What It Can Do

How It Works

flowchart LR
    U["App / CLI / connector"] --> B["LingShu main agent"]
    B --> G["Structured GoalSpec"]
    G --> R["Mutable runtime workflow"]
    R --> Q["Serial task queue"]
    Q --> W1["Isolated worker"]
    Q --> W2["Local tools"]
    Q --> W3["Authorized Computer Use"]
    W3 --> H["Human collaboration when needed"]
    H --> V["Independent verifier"]
    W1 --> V["Independent verifier"]
    W2 --> V
    W3 --> V
    V --> A["Artifacts + task record"]
    A --> M["Local memory"]
    M --> B

The main conversation remains serialized 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 may update only the still-pending portion of the runtime graph; the GoalSpec and acceptance boundary remain fixed. A worker, tool, or checker can pause its exact session for human participation and resume from that checkpoint instead of restarting the goal.

Quick Start

Requirements

• macOS 14 or later
• An API token for one supported model provider, or a compatible custom endpoint

Install the Signed Alpha (Recommended)

With Homebrew, the app and lingshu CLI are installed together:

brew install --cask RoyZhao1991/tap/lingshu

Or install the Universal DMG manually:

1. Download the DMG and its .sha256 file from the v0.1.0-alpha.6 release.

2. In Terminal, verify the download:

   shasum -a 256 -c LingShu-0.1.0-9-macOS-universal.dmg.sha256
   

3. Open the DMG, drag 灵枢.app to Applications, and launch it.

4. Choose a language, connect a model provider, and send a small first 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 a capability you choose requires them.

Run a First Traceable Task

After choosing a language and connecting a model, start with a small local deliverable instead of granting broad computer permissions immediately:

Create a one-page project brief in DOCX, save it locally, preview it, and have an independent checker verify the result.

This exercises the complete path a new user should inspect first: goal understanding, local file creation, artifact registration, built-in preview, and verification. The task should finish with a real file in LingShu's Workspace and a visible task record.

Whether it succeeds, partly succeeds, or fails, share a privacy-safe 15-minute Alpha first-run report. Use GitHub Discussions for setup questions. Never include an API token or private file contents.

Build From Source

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"

Run the packaged .app, not the bare Swift executable, so macOS can associate the correct icon, signing identity, and privacy permissions with LingShu.

On first launch, LingShu checks whether a working brain channel exists. If not, the setup guide lets you choose a provider and enter its token. Custom providers additionally require an endpoint and model name.

CLI and External Connectors

Every app build includes a lingshu command-line client. It is a thin entrance to the same serialized main conversation: it does not create a second agent runtime or bypass model selection, memory, authorization, task records, or human-interaction gates.

Homebrew exposes the bundled client automatically. For a manual DMG installation, add it to your path with:

mkdir -p "$HOME/.local/bin"
ln -sf "/Applications/灵枢.app/Contents/MacOS/lingshu" "$HOME/.local/bin/lingshu"
export PATH="$HOME/.local/bin:$PATH"

Then use one-request/one-response mode from a terminal, Feishu bot, webhook worker, Shortcut, or another local process:

lingshu ask "Summarize today's project status"
echo "Create a one-page report" | lingshu ask --json
lingshu status --json

If the exact task pauses for login, QR scanning, file selection, confirmation, or another human step, JSON output returns needs_user_action, typed materials, and a message ID. Resume that same checkpoint with:

lingshu answer <message-id> "completed"

The client talks only to LingShu's loopback control service by default. See CLI and connector guide for exit codes, JSON fields, environment variables, and a Feishu/webhook integration pattern.

Supported Brain Presets

API credentials are stored in macOS Keychain, remain local runtime configuration, and must never be committed. See runtime configuration notes.

Permissions and Safety

LingShu requests macOS permissions only when a capability needs them. Computer control can require Accessibility and Screen Recording; voice and visual perception can require Microphone, Speech Recognition, and Camera access.

• Sensory streams are processed in memory by LingShu and are not archived by default.
• Content sent to a configured remote model or perception provider leaves the Mac and is governed by that provider's retention and privacy terms.
• Model credentials are stored in macOS Keychain; secrets are redacted from task traces where supported.
• High-risk, irreversible, account, authorization, or external-publication actions require explicit user confirmation.
• Native Computer Use is permission-scoped and verifies the UI again after actions when possible.

See SECURITY.md and the perception audit for the current boundaries.

Project Status

LingShu is usable for development and controlled local workflows, but it is not yet a finished consumer product.

The repository contains more than 100,000 lines of source and test code, more than 180 Swift test files, and more than 1,500 tests. These numbers describe engineering depth, not a guarantee that every environment-dependent test passes on every Mac.

Development

swift test
bash Scripts/smoke-e2e.sh

For a signed, notarized website build, see Scripts/release-website.sh. Official builds are pinned to Developer ID Team KM7N84AC9Y and the current signing-certificate fingerprint, which is also recorded in the release manifest. Apple Developer credentials and private keys are never stored in the repository. Changing an official binary invalidates its signature; forks must use their own signing identity.

Architecture references:

• Shareable bilingual architecture and value map
• Architecture overview
• Canonical architecture field guide (Chinese)
• Roadmap
• Changelog

Community

• Ask setup questions and share workflows in GitHub Discussions.
• Report reproducible defects through the issue tracker.
• Start with a good first issue if you want to contribute code or documentation.
• Report security issues privately as described in SECURITY.md, not in a public issue.

Contributing

Bug reports, focused pull requests, provider adapters, tests, documentation, and reproducible performance measurements are welcome. Start with CONTRIBUTING.md, follow the Code of Conduct, and report vulnerabilities privately as described in SECURITY.md.

License

LingShu is licensed under the Apache License 2.0. Third-party components retain their own licenses; see THIRD_PARTY_NOTICES.md.

Created and maintained by Roy Zhao.