Connect your first computer with Shennian
Install the desktop app and sign in. Shennian checks and prepares the local service automatically. Once ready, you can pick this computer from your phone, browser, or desktop app and control Claude Code, Codex, OpenCode, Nian, and other Agents.
Start
Desktop install
Use the desktop app for ordinary computers. Download the installer for your system from shennian.net, open it, and sign in. The desktop app adds this computer to your account and checks the Shennian Client, background connection, Node.js runtime, and common Agent CLIs.
Desktop app
Best for Mac, Windows, and Linux desktops. Use .deb or AppImage on graphical Linux; use the CLI for servers, SSH boxes, and headless machines.
Ask an AI to install it
Send the install guide link to Claude, Codex, Gemini, or Cursor and let it install the CLI and check your computer before pairing.
1
Download and open the desktop app
Install Shennian from the website, open it, and sign in. Phone, Web, and desktop all use the same account.
2
Wait for automatic setup
The desktop app checks the local Shennian Client, background connection, Node.js runtime, and common Agent clients such as Claude Code, Codex, and OpenCode.
3
Use it from any device
When setup is done, the computer appears in your machine list. Pick it from your phone, browser, or desktop app, launch an Agent, and send a task.
Servers and pure command-line machines still use CLI pairing. Desktop auto-setup is mainly for everyday computers.
Command-line install
Use the CLI for servers, NAS devices, SSH boxes, and headless machines. It requires Node.js 18 or later. After installation, run shennian to scan or paste a pairing token and start the background daemon.
npm install -g shennian@latest
shennian
shennian
Pair when needed, then start the background daemon.
shennian pair
Pair this computer again with a fresh QR code or token.
shennian start
Start the background service and enable auto-start.
shennian stop
Stop the background service and disable remote access.
shennian status
Show whether the background service is online and where logs are stored.
shennian logs -n 100
Print recent background service logs for debugging.
shennian upgrade
Upgrade the CLI to the latest npm release.
Sign-in and pairing
Phone, Web, and desktop use the same account. Desktop machines join by signing in; CLI machines join by scanning a QR code or pasting a token. Pair once, then the daemon reconnects automatically.
1
Sign in on desktop
Open Shennian Desktop on the target computer and sign in. Phone, Web, and desktop clients on the same account will see this machine.
2
Pair a CLI machine
Run shennian on the target machine to get a QR code and an sn- pairing token, then scan or paste it from the phone app or Web.
3
Confirm it is online
When the machine is online, you can choose it from any device, start Agents, resume sessions, and browse files.
Run shennian pair again only after the machine was removed, the token expired, or the account changed. For daily troubleshooting, start with shennian status and logs.
Phone App / Web control
Once a computer is online, you can control the same Agent session from phone, browser, or desktop. The Agent still runs on the original computer; Shennian syncs the session, status, files, and actions to the current device.
Sessions follow your account
The Agent still runs on the original computer; Shennian connects phone, browser, and desktop to the same control surface.
Send your first message
Daily use comes down to three actions: choose a machine, choose an Agent, and send a message. Confirm the working directory and type the task like a chat message; output, tool calls, and progress stream back into Shennian.
Choose an online machine
The machine list shows status, operating system, version, and available Agents for each computer. Choose the machine first, then decide who should do the work.
1
Choose a machine
Open My Machines and pick an online computer. After desktop auto-setup completes, it appears here automatically.
2
Choose an Agent
Pick Claude Code, Codex, OpenCode, Nian, or another connected Agent, then confirm the working directory.
3
Send a message
Type the task like a chat message. Agent output, tool calls, and progress stream back into Shennian.
4
Take over anytime
When you leave your desk, continue from your phone: add instructions, review results, and download files while the task keeps running on the original computer.
Plans and credits
Basic installation, pairing, and remote control can be completed first. Some capabilities check plan and credit status, such as Agent Uses WeChat, which requires Pro / Team entitlement and available credits.
Check your plan
Profile → Billing shows your current plan, available credits, and purchase options.
WeChat requires entitlement
The Use WeChat machine dashboard checks account conditions. If it asks for Pro / Team or more credits, handle billing first.
Team and organization access
Team, organization, and machine-permission entries live under Profile → Space and permissions for shared-machine management.
Credits are used by consumption-based capabilities such as multimodal recognition, structured reads, and external-message send confirmation. Ordinary remote control is not billed per message.
Use Agents
Use built-in Agent Nian
Nian is Shennian’s built-in Agent. It does not require a third-party local CLI and is useful for quick questions, content cleanup, lightweight tasks, and install guidance.
No extra CLI required
After signing in, you can use the built-in Agent immediately for first-time experience and lightweight daily work.
Use Codex
Codex is useful for code edits, project understanding, test fixes, and engineering tasks. Shennian syncs Codex output, tool calls, and progress from the original computer to phone, Web, and desktop.
1
Prepare Codex CLI on the target computer
Install and sign in to Codex using its official flow, then confirm that codex runs directly in the local terminal.
2
Choose an online machine in Shennian
Once the machine is online, Shennian detects available Agents and models. Choose Codex and confirm the working directory.
3
Send engineering work
Describe the edit, investigation, or test task like a chat message. The task still runs on the original computer while you follow it from any device.
If Codex does not appear in Shennian, first confirm that codex runs in the target computer terminal, then refresh the Agent list or restart the daemon.
Use Claude Code
Claude Code is useful for long-context code understanding, cross-file changes, and local project collaboration. Install and sign in to Claude Code on the target computer first.
1
Prepare Claude Code on the target computer
Confirm that claude runs directly in the local terminal and that sign-in, model choice, and upstream account setup are complete.
2
Choose machine and workdir
In Shennian, choose an online machine and Claude Code, then set the project working directory to start a session.
3
Continue from any device
Later you can ask follow-ups, add requirements, or inspect files from phone while Claude Code keeps working on the original computer.
Claude Code installation, sign-in, and account authorization remain owned by the local CLI. Shennian controls the session surface and multi-device sync.
Other Agents
OpenCode, Gemini CLI, Cursor Agent, and similar local Agents can connect through the same Shennian entry. Their install, sign-in, and authorization still follow their own CLI rules.
One entry point
Shennian detects commands, shows available entries, and syncs sessions to phone, Web, and desktop.
Make it run locally first
If an Agent is missing from the list, first confirm that it can run independently in the target computer terminal.
Refresh detection
After installing a new Agent, refresh the Agent list or restart the daemon so Shennian can detect commands and models again.
Custom Agent integration
Custom Agent integration is the stable developer-facing protocol. Implement a local command, and Shennian turns phone/browser messages into stdin while streaming JSON Lines from stdout back to every client. Your Agent does not need to speak WebSocket, HTTP, or database protocols.
1. Declare capabilities
Implement /caps to return the display name, model list, spawn mode, and whether resume is supported. Shennian uses this to render the Agent and model picker.
2. Receive one turn
Implement /run and read the user message from stdin. The CLI passes --workdir, --session, --model, --resume, and attachment paths when available.
3. Stream events
Write one JSON object per line to stdout. Emit delta or tool-call early so users see progress, then final to complete the turn.
Complete data flow
A minimal Agent has only two entry points: /caps for discovery and /run for one user message. The JSONL below is the public format Shennian expects to read.
# 1) capabilities discovery
my-agent /caps
{"name":"My Agent","models":["demo"],"defaultModel":"demo","mode":"spawn","resume":true}
# 2) one user turn
echo "review this project" | my-agent /run --workdir /path/to/project --session sn-123 --model demo
{"state":"delta","text":"Received. I am checking the project.\n"}
{"state":"tool-call","name":"list_dir","args":{"path":"."}}
{"state":"tool-result","name":"list_dir","result":"README.md src/ package.json"}
{"state":"delta","text":"README.md needs a Quick Start section."}
{"state":"final","agentSessionId":"native-session-123","usage":{"inputTokens":42,"outputTokens":128}}
Public event format
These state values are the stable v1 output protocol for custom Agents. Shennian fills internal runId / seq values and syncs the stream to phone, browser, and desktop clients.
delta
Streaming text chunk. Use it for normal replies, or add thinking:true to render reasoning content.
final
Turn complete. Every successful reply must end with final, optionally including usage and agentSessionId.
error
Turn failed and ended. The message is shown to the user.
tool-call
Show a local tool invocation. The Agent runs the tool itself; Shennian only renders progress.
tool-result
Show a local tool result, useful for directory listing, file reads, searches, and progress replay.
The recommended first valid event is delta, for example {"state":"delta","text":"Received. Starting now.\n"}. start / init are Shennian internal normalization events, and notify is reserved for future proactive messages; do not use them as v1 success signals.
Session resume
If /caps returns resume:true, the Agent may include its own agentSessionId in final. Shennian passes that value back through --resume on the next turn; the Agent owns context persistence.
{"state":"final","agentSessionId":"native-session-123"}
# next turn: Shennian passes --resume native-session-123
Attachments and workdir
Shennian passes user-selected files as local absolute paths through --attachment and passes --workdir for the target project. Your Agent can read project files, images, PDFs, and other assets like any CLI.
my-agent /run --workdir /path/to/project --attachment /path/to/screenshot.png --attachment /path/to/spec.pdf
Node.js Demo
Save this as my-agent.js. It is a complete spawn-mode Agent with no dependencies.
#!/usr/bin/env node
const command = process.argv[2]
if (command === '/caps') {
console.log(JSON.stringify({
name: 'My Agent',
models: ['demo'],
defaultModel: 'demo',
mode: 'spawn',
resume: true,
version: '1.0.0'
}))
process.exit(0)
}
if (command === '/run') {
const input = await new Promise((resolve) => {
let text = ''
process.stdin.setEncoding('utf8')
process.stdin.on('data', (chunk) => (text += chunk))
process.stdin.on('end', () => resolve(text.trim()))
})
console.log(JSON.stringify({ state: 'delta', text: '收到：' + input + '\n' }))
console.log(JSON.stringify({ state: 'final', agentSessionId: 'demo-session' }))
process.exit(0)
}
console.error('unknown command: ' + command)
process.exit(1)
Register and refresh
chmod +x /absolute/path/my-agent.js
shennian agent add my-agent --command "node /absolute/path/my-agent.js"
shennian agent list
shennian stop && shennian start
Start from the demo, replace the reply logic with your own model or tool calls, then register it. No external SDK is required.
Internal formats not to depend on
• Do not output start / init as custom Agent success signals; they are Shennian internal events.
• notify is reserved for future proactive messages. In current spawn mode, do not use it to complete a reply.
• Do not depend on Relay frames, database tables, built-in Claude / Codex adapter private parsers, or the full internal structure of ~/.shennian/config.json.
Core Capabilities
Files and attachments
Shennian keeps local project files, uploaded attachments, and Agent-generated results in one control surface. From a session, you can enter the workdir, search files, preview text, images, and HTML, download a file or folder ZIP, and upload screenshots or documents from your phone.
Give file context to the Agent
When an Agent needs a file, reference it with @ in the conversation. Markdown files can also be previewed, edited, and exported as source or PDF.
Projects and sessions
In Shennian, a project is primarily carried by the working directory. Choose the directory when launching an Agent; later messages, attachments, and file browsing revolve around it.
Workdir carries the project
After choosing a directory, Agent file access, attachment references, and result downloads use that local context.
A session records one workflow
A session records the machine, Agent, model, workdir, messages, tool calls, and result files for one workflow.
Resume and isolate
Resume context from the session list. Switching Agents creates a new session so different Agent contexts do not pollute each other.
Use Skills
Skills are Agent capability bundles installed on a specific machine, not abstract account switches. After installation, Agents on that machine can invoke the capability by convention.
Install to a machine
Install a Skill on the computer that needs it. Different machines under the same account can have different bundles.
Invoke in chat
Select a Skill in chat or let the Agent invoke it by rule, giving that concrete capability to the current machine’s Agent.
Repair environment
If a Skill needs extra local components, Shennian surfaces setup requirements and repair or troubleshooting entry points.
The official “Agent Uses WeChat / Use WeChat” Skill is the first full example: install it to a machine, let the Agent call shennian wechat, then troubleshoot permissions and credits.
Multi-device control
Phone, Web, and desktop use the same account. Once the computer is online, you can open the same session from any device to add instructions, review Agent output, inspect files, and download results.
Keep going away from the computer
The Agent does not move to the phone; the task still runs on the original computer while you switch control surfaces.
Notifications and status sync
Shennian syncs connection state, message state, Agent progress, and file-operation results, helping you tell whether an issue is in the network, daemon, or Agent itself.
Connection state
The UI can show connecting, receiving, sending, network error, CLI unreachable, and related states.
Execution progress
Agent output, tool calls, queued work, and file-operation results stream back to the current device.
Error location
When an Agent errors, permissions are missing, or an external capability is unavailable, start with the page state and the relevant troubleshooting command.
In product copy, this can be understood as realtime status sync. In the custom Agent protocol, notify is still reserved for future use and should not be treated as an open proactive notification API.
Machine management
Machines are the first layer of Shennian. The machine list shows each computer’s online state, system, version, available Agents, and sharing markers; machine details handle rename, unbind, re-pair, Agent refresh, and model-list refresh.
Status and version
Quickly tell whether a machine is online, whether the connector needs an upgrade, and whether the system supports a capability.
Agent and model discovery
Refresh installed Agents, model lists, and workdir entries so every machine shows its real local capability.
Shared access
Accept shared machines through an invite code or QR code, then collaborate with view-only, can-use, full-control, or admin permissions.
Agent Uses WeChat
Overview
Agent Uses WeChat lets an Agent in Shennian use WeChat on your computer. It mainly does two things: send messages to a specific WeChat conversation and receive new messages from that conversation. WeChat still runs locally, and Shennian does not host your WeChat account.
Prerequisites
Desktop app or CLI installed
Use Shennian Desktop for ordinary computers, or Shennian CLI for developer machines. The machine must be signed in or paired and stay online.
WeChat and Agent on one machine
Current support is for Mac or Windows desktop WeChat. WeChat, the Shennian connector, and the bound Agent session must run on the same machine.
Mac Helper permissions
On macOS, open Agent Uses WeChat from Shennian Desktop to install or repair Helper and grant Screen Recording, Accessibility, Automation, and related system permissions.
Pro / Team and credits
Agent Uses WeChat is an external-message capability. Your account needs Pro / Team entitlement and available credits for visual recognition, structured reads, and send confirmation.
Principles and safety
Shennian has Computer Use capability: it uses a multimodal model to understand the computer screen and operate WeChat like a person, such as opening a target conversation, reading visible messages, typing, and sending replies.
Computer Use
It uses local screen understanding, screenshots, clicks, typing, and clipboard actions. The actions happen on your computer.
Visible read and write only
The core capability is sending to a named WeChat conversation and receiving new visible messages from that same conversation.
No low-level sensitive parsing
Shennian does not parse WeChat transport, protocol, database, or other sensitive internals, does not inject into WeChat, and does not bypass the WeChat client.
No WeChat message storage
Shennian does not store WeChat messages as cloud chat records and does not upload your WeChat history as a backup.
When a Shennian conversation is bound, Shennian records only the last few messages as a cursor marker to know what has already been seen and where to continue next. This marker is not a full chat history.
Agent Uses WeChat CLI
`shennian wechat` is the command entry for Agents to use local WeChat. Start with doctor. read / write default to human- and Agent-readable output; add JSON only for scripts.
shennian wechat doctor
shennian wechat read --conversation "ClientA" --limit 5
shennian wechat write --conversation "ClientA" --text "收到，我稍后回复"
# Bind one-off CLI tool calls to an existing Shennian Agent session
shennian wechat read --conversation "ClientA" --limit 5 --session-id <shennian-session-id>
shennian wechat write --conversation "ClientA" --text "..." --session-id <shennian-session-id>
# Machine-readable output for scripts
shennian wechat read --conversation "ClientA" --limit 5 --format json
shennian wechat write --conversation "ClientA" --text "..." --json
Install the Skill for external Agents
To let Codex, Claude Code, PolyCode, or another Skill-capable Agent use this WeChat capability directly, send it the text below and ask it to install the Skill using its own Skill mechanism.
请安装神念官方 Use WeChat Skill：
https://shennian.net/skills/use-wechat
Run read only when the user explicitly asks to read a specific WeChat conversation. Before sending, confirm the exact destination and content. Shennian does not host your WeChat account or bypass the WeChat client.
Bind Shennian and WeChat conversations
The CLI is good for one-off reads and writes. Binding is for ongoing work with a WeChat contact or group: new WeChat messages enter the linked Shennian Agent conversation, and Agent replies return to that same WeChat conversation.
1
Open the Shennian Agent conversation
Start Claude Code, Codex, OpenCode, Nian, or a custom Agent on the prepared machine, then open the corresponding Shennian conversation.
2
Open the Use WeChat binding page
From the conversation header, open External Messages or External Channels, then choose Use WeChat. This binds the current Shennian conversation.
3
Enter the WeChat conversation name
Enter the contact or group name exactly as it appears in WeChat’s left conversation list, turn Enabled on, and save. One Shennian Agent conversation binds to one WeChat conversation name.
4
Let new messages enter the Agent
After binding, Shennian checks that local WeChat conversation on a schedule. New messages enter the linked Shennian session, and Agent replies go back to the same WeChat conversation.
The first scan after binding only establishes a baseline; it does not ingest history into the Agent. Later scans deliver only new messages. Cross-machine binding and cloud-hosted personal WeChat are not current goals.
Daily use
After binding, keep this machine online and WeChat signed in. You can continue talking to the Agent from phone, Web, or desktop, while actual WeChat reads and writes still happen on the bound computer. If unavailable, run shennian wechat doctor or open Settings → Agent Uses WeChat / Use WeChat to inspect machine status.
Managed WeCom groups
Managed WeCom groups are an external-message capability for enabled customers: bind your own WeCom account in Shennian, then connect one WeCom group to one Shennian Agent session. When someone @mentions the hosted WeCom account in the group, the message enters that Agent; when the Agent needs to reply, it sends back to the same bound group.
Entitlements and prerequisites
Hidden managed_wecom entitlement required
The entry appears only for accounts manually enabled with managed_wecom. Pro, Team, or a generic enterprise tier does not necessarily include this hidden capability.
A supported external-channel Agent session
Group binding is attached to a specific Shennian session. Use Manager / Nian / Codex / Claude Code or another session that supports external-channel instructions and send commands.
A WeCom account that can scan in
Scan with your own WeCom mobile app. The first version allows one hosted WeCom account per Shennian account; re-scan if it goes offline or expires.
Entry and group binding
Bind the WeCom account from Profile first, then open the target Agent session and configure External messages from the session header.
1
Profile → WeCom
Sign in to Shennian Web/App and open Profile. With managed_wecom enabled, the WeCom entry is visible; otherwise the page says it is for enterprise customers.
2
Choose area and scan
Choose your common login area, start binding or re-login, and scan with WeCom mobile. If WeCom shows a 6-digit verification code, enter it back in Shennian.
3
Sync group conversations
After the account becomes online, sync conversations. The page shows bindable WeCom groups; if a new group is missing, confirm the account is in it and refresh sync.
4
Agent session → External messages
Open the Agent session that should handle the group, click the External messages entry in the header, choose WeCom, then pick the synced group.
5
Set listen/reply and save
The default is mention-only; you can switch to all messages. Confirm Allow reply and the custom constraints before saving. One Shennian session currently binds one WeCom group.
WeCom app, bot, credentials, and callback
Users do not create a WeCom custom app, group bot, Secret, Token, Webhook, or callback URL in the current implementation. Shennian Server and the QiWe hosting layer manage them.
No user-created app or bot
The implemented flow hosts a scanned-in WeCom account; it is not a WeCom admin-console app or group-bot webhook setup.
Server-managed credentials and callback
QiWe API tokens, device guid, and callback secrets stay on Shennian Server. Clients and daemons never hold platform secrets; the server sets callbacks automatically.
Area improves scan stability
Shennian recommends an area from your request IP and lets you override it to the normal WeCom login area, reducing unusual new-device prompts.
How group messages trigger and reply
Default: @mention the hosted account
Group chats default to listenMode=mention_only: ordinary messages are kept as short-lived server context; when someone @mentions the hosted WeCom account, Shennian sends the relevant context to the bound Agent.
Agent replies through the binding
The Agent does not need group IDs. Regular Agents use shennian external send; Manager uses shennian manager external send. The server routes by the current Shennian session binding. Turn Allow reply off to receive only.
Text first, media as attachments
Inbound images, files, videos, and audio are delivered as short-lived attachments into the local workdir. Replies are text by default; send-image/send-file are used only when explicitly needed.
Binding does not dump old group history into the Agent. It only affects future triggered messages. Use all-messages mode only for low-noise dedicated groups; use mention-only for customer groups.
Unbind, pause, and re-scan
Turn off Enabled or delete the binding in the session External messages page to stop that group from entering the session. In Profile → WeCom, bound groups can open their session or remove the group binding. The bottom Unbind action removes the hosted WeCom account and its bindings. If the account is offline, expired, or revoked, use Re-login / Refresh QR to scan again.
Permissions and safety
Server-side entitlement checks
Account binding, conversation sync, group binding, and send APIs all require managed_wecom; Manager binding also requires external-message/Manager capability. Old clients or direct API calls cannot bypass this.
Minimum binding scope
One binding connects one Shennian session to one WeCom group. Replies go to that group; Agents cannot choose arbitrary groups or see platform secrets.
Can be disabled anytime
You can disable one session binding, turn off replies, or unbind the entire WeCom account. External-message cache and short-lived attachments are cleaned by server policy.
Troubleshooting
No WeCom entry
Check that the signed-in account has managed_wecom. Pro/Team without this hidden entitlement still does not show the entry.
QR expired or account stays offline
Refresh QR / re-login and confirm on WeCom mobile. If a 6-digit code appears, enter it in Shennian. Try the usual login area if needed.
No groups after sync
Confirm the hosted account is in the target external group, then sync again. The current page primarily lists group conversations; direct messages are not the default target.
Group messages do not wake the Agent
Default mode requires @mentioning the hosted WeCom account. Also check that External messages are enabled, the correct group is selected, the account is online, and the bound machine/session can receive work.
Agent received but did not reply to group
Check Allow reply. The Agent must use shennian external send or shennian manager external send, not just a normal Shennian chat reply.
Troubleshooting
Troubleshooting
For ordinary computers, start with the desktop auto-setup state. For CLI machines, check the daemon first and re-pair only when needed.
Machine is offline
Confirm that the desktop app or CLI daemon is running and the current network can reach shennian.net.
Agent is unavailable
Confirm the corresponding Claude Code, Codex, OpenCode, or other Agent client is installed and initialized.
Agent Uses WeChat unavailable
Run shennian wechat doctor, or check Helper, permissions, WeChat sign-in, entitlement, and credits from the Use WeChat machine dashboard.
Upgrade failed
If Shennian keeps failing to upgrade, remove the global npm package first, then install the latest release again.
shennian status
shennian logs -n 100
shennian stop && shennian start
shennian pair
Restarting the daemon disconnects the app from this computer for a few seconds and may interrupt active local Agent sessions.
Human support
Scan the QR code to add Shennian enterprise WeChat support. Send your issue screenshot, machine status, and visible error.
