Synergy

Persistent, recoverable AI agent work.

An open-source workspace for software and knowledge work that keeps sessions, agents, files, Browser, tools, and automation connected in one runtime.

Website · Documentation · Quick Start · Contributing

_{Built by the Holos team at Shanghai Innovation Institute.}

Work that continues

AI agent work often outlives a single conversation. Synergy treats it as durable workspace state. A task can move between Web, Desktop, CLI, background execution, and specialist agents while preserving its project, history, files, tools, and operating context.

Choose Atlas for general assistance, Forge for coding, or Pico for lightweight work. Their CLI names are atlas, forge, and pico; for example, synergy send --agent forge "Fix the failing test". Existing configurations and conversations upgrade automatically.

Historical conversations prepare when opened. Full history import and usage rebuilds require an explicit request; storage admission documents upgrade and recovery behavior.

Synergy runs as a standalone local workspace. Connecting a Holos agent adds account identity, messaging, and presence without replacing local projects, providers, sessions, or data.

What makes Synergy different

• Durable by default — Keep recoverable sessions attached to an explicit home or project Scope, with complete history even when older model context is compacted.
• One runtime, every surface — Use the same sessions and state from the Web workbench, Desktop app, CLI, server API, and SDK.
• First-class agent coordination — Delegate to specialist subagents, plan durable Blueprints, run independently reviewed BlueprintLoops, keep focused work moving with Light Loop, or orchestrate a tree of persistent specialist workers with Boss Mode.
• Files and Browser stay in context — Browse, edit, create, copy, move and delete Workspace files alongside Desktop browser pages with saved website logins without moving the task into a separate tool or disposable environment. Review and restore file changes against their original Workspace.
• Compute starts when needed — Select native or Docker execution independently of durable Workspace files. API-only work allocates no container; local, S3 and OSS object stores preserve files across compute reclamation. See resource configuration.
• Knowledge compounds — Retain reusable memory and learned experience in Library while authoring Notes and Blueprints as durable documents.
• Visual results stay interactive — Explore charts, simulations, calendars and variants in the conversation, retain parameters, review changes with the agent and export interactive HTML. See visual results.
• Local-first and extensible — Add providers, tools, Skills, commands, MCP servers, plugins and Channels while keeping local ownership of projects and data.

Read the product overview for the complete product model, including Lattice Pathways, Agenda, Channels, Library, Holos, and extension boundaries.

Inside the workspace

Agenda — schedule recurring and one-off agent runs on Day/Week/Month calendar views, with run history.	Library — durable memory and evaluated experiences, with reward-signal analytics per behavioral dimension.
Notes — agents write durable notes and Blueprints as they work, searchable and scoped per project.	Plugins — extend Synergy with skills, tools, and UI from the official and local registries.

Benchmarks

On the DeepSWE v1.1 benchmark — 113 real repository engineering tasks — the same model completes far more work under Synergy than under its stock harness. Running deepseek-v4-flash with the coding agent Forge lifts Pass@1 from 53% to 67.3% (+14.3pp, 1.27×) at $0.54/task, landing on the cost-performance Pareto front.

 

_{Pass@1 across 19 leaderboard configurations (left) and the cost-performance frontier (right): the coding agent (orange) vs the official mini-swe-agent run of the same model (yellow).}

_{Failure anatomy: 76/113 tasks fully passed; 24 of the 37 unsolved tasks miss by only 1–2 tests.}

 

_{Resource profile (left): passed tasks average $0.60 over ~2.3h. Efficiency vs the top-5 official models and the cheapest baseline (right): $0.54/task — 7–40× cheaper, with token/step counts aggregated across subagents.}

Methodology: official leaderboard numbers from deepswe.datacurve.ai (v1.1, fetched 2026-08-22); Synergy numbers from local full-benchmark runs. All costs are computed at the API prices in effect before 2026-08-17 00:00 (Beijing time) — prior to DeepSeek's across-the-board price increase and peak/off-peak pricing.

Quick Start

Desktop

Choose a project in the task composer or start without project files. See project task entry for file locations and independent copies.

Download the latest installer from GitHub Releases. Desktop installers include the app and expose the packaged runtime as the synergy CLI.

Platform	Installer
macOS	.pkg
Windows	NSIS .exe
Linux	.deb

Portable artifacts are also published, but they do not configure a system CLI. Windows Desktop and CLI releases currently support x64.

CLI and Web

Install the current release:

curl -fsSL https://raw.githubusercontent.com/SII-Holos/synergy/main/install | bash

Configure a model provider, start the background runtime, and open the Web client:

synergy config wizard
synergy start
synergy web

Run one task directly from the terminal:

synergy send "summarize this repository"

Useful runtime commands:

synergy status
synergy logs
synergy doctor
synergy stop

The CLI installer places the launcher and its sealed module graph under ~/.synergy/; setting SYNERGY_HOME=/path changes that root to /path/.synergy/. It does not install the Electron Desktop app.

You can keep one Synergy installation per channel — the standalone CLI, a supported package-manager install (npm, yarn, pnpm, or bun), and the Desktop app — but only one should be the synergy command your shell runs. synergy doctor lists every detected installation channel and exits nonzero when channels conflict or an installed version cannot be verified. The curl installer and the npm package postinstall warn about other channels they detect and never auto-uninstall them. Homebrew's synergy formula is unrelated to this project and is not detected or managed.

Upgrade with synergy upgrade, or install a specific version by passing --version <version> to the installer. When multiple channels are installed, synergy upgrade stops instead of guessing: rerun with --method <npm|yarn|pnpm|bun|desktop|standalone> to select an installed, healthy channel.

synergy uninstall keeps its existing defaults and removes data, cache, config, and state unless you pass --keep-data or --keep-config. To remove only one installation channel while preserving shared data, cache, config, and state, run synergy uninstall --installation-only --method <channel>; standalone removal deletes only installer-owned files under ~/.synergy/ and the exact shell PATH entries the installer wrote.

The built-in Browser is Desktop-local and uses Electron's bundled Chromium, with peer workbench page tabs and reusable website logins; separate and temporary profiles live in Browser settings. CLI and Web use search, fetch and MCP integrations. macOS Desktop also supports native application Computer Use in Full Access mode, with independently checked Accessibility and Screen Recording permissions. Native observations report image quality and action availability; coordinate actions require a verified image submitted to the selecting model request. Computer Use prefers background delivery. The agent can explicitly request foreground observation or input when needed; actions never automatically escalate or replay, and a fresh observation verifies the result. See Native Computer Use.

Holos is optional. Connect an agent from the Web account surface or run synergy holos login.

See the CLI reference, configuration reference, and release notes for complete setup and runtime details.

For headless tasks, versioned experiment settings, durable execution evidence and cost comparisons, see Rollout execution.

Product Surfaces

Surface	Purpose
Web	Primary workbench for sessions, project files, Notes, Library, Agenda, plugins, settings, and operational views.
Desktop	Electron product with a managed packaged server, native Browser presentation, local folder selection, protocol handling, keep-awake while running, and updates.
CLI	Runtime management, one-off send execution, configuration, sessions, integrations, diagnostics, and development workflows.
Server API and SDK	Shared contract used by first-party clients and integrations.

Develop Synergy

Synergy is a Bun monorepo using TypeScript ESM modules. The pinned package manager is declared in package.json.

Install Rust with Cargo for the native PTY and Linux process ownership library, then prepare a source checkout:

bun dev prepare

See the development reference for preparation requirements and macOS Desktop native-driver build status.

Common development flows:

bun dev server
bun dev app --open
bun dev web
bun dev desktop
bun dev desktop --managed
bun dev send "your message"

Default local preflight:

bun run verify plan
bun run verify local --test test/script/dev-entrypoints.test.ts

For Bun embedding, use openAgentRuntime({ home, components }) from packages/agent-runtime and select optional component factories explicitly. For lower-level hosts, packages/harness exposes the execution and lifecycle APIs, and packages/local-runtime supplies local tools, native execution and provider SDKs. packages/cli keeps the same synergy command, with commands supplied by the selected components; the complete product composes optional capabilities in packages/presets. Hosts can compose independent Runtime instances in one process with explicit home, environment and storage ownership. Home sessions work without a local workspace. Node.js uses the managed HTTP SDK or attaches to an existing runtime. See Embedding, Installable packages, Runtime and Scope and the package map.

Install the minimal CLI with Bun, then select capabilities:

bun add --global @ericsanchezok/synergy-cli
synergy install mcp lsp
synergy install web
synergy install desktop

The existing @ericsanchezok/synergy distribution and Desktop installer retain the complete product by default. Use synergy install, list, update and remove to manage optional packages. Components, process plugins, company presets and native applications share package discovery while retaining distinct trust and capability approval. See installation commands for sources, unattended approval and recovery.

Local performance experiments use the benchmark workspace: independent harness/model matrices, frozen inputs, native rollout evidence and paired reports. Task solving, reference execution and verification each have a fixed three-hour budget. Run bun bench run benchmark/configs/local24-boyue.yaml after configuring its model endpoint and credential reference. Formal tasks start directly in unattended sessions. Adaptive working-set reservations keep independent cells running within live resource limits; reports retain per-task failures and unknown usage. The local-24 preset uses GLM 5.3 Flash with explicit low reasoning.

Core runtime tests run from packages/harness:

cd packages/harness
bun test
bun run test:ci # Isolated batches; CI adds coverage in the same execution

Frontend package suites run through their standard scripts and are included in bun run quality:

bun run --cwd apps/web test
bun run --cwd packages/ui test

Browser capability or App bootstrap changes also verify the source boundary and a genuine non-loopback HTTP origin:

bun test --cwd apps/web test/testing/browser-crypto-contract.test.ts
bun run --cwd apps/web build
bun apps/web/script/private-http-smoke.ts

CI planning, bounded execution, diagnostics and justified runtime growth are documented in CI verification. Review new and affected existing tests with testing-guide.

Tests live under each package's test/ directory; repository-level tests live under the root test/ directory. bun run quality:quick enforces this layout.

Frontend product copy is extracted into English and Simplified Chinese catalogs, plus a development-only pseudo catalog. Changes to visible text or locale formatting also run:

bun run --cwd apps/web i18n:extract
bun run localization:check

When developing Synergy while using Synergy itself, start an isolated second instance with a separate SYNERGY_HOME and explicit ports. Never stop or replace the instance hosting your active session. The development reference contains the complete workflow.

Develop Plugins

Plugin authors can start without cloning this repository:

bunx @ericsanchezok/synergy-plugin-kit create my-plugin --template tool-ui
cd my-plugin
bun install
synergy-plugin build
synergy-plugin validate --runtime-discovery

UI API 6 supports replaceable workbenches, typed frontend services and structured Skins. synergy-plugin preview runs an isolated production host for authoring.

Start with the plugin documentation and the @ericsanchezok/synergy-plugin API reference.

Documentation

The documentation home routes readers by product area and task.

• Product overview — product purpose, objects, workflows, and boundaries
• Architecture — runtime invariants and implementation ownership
• CLI reference — installed and source-checkout commands
• Configuration reference — domains, precedence, providers, and instructions
• Storage and paths — persistent state and workspace layout
• Plugin documentation — definitions, generated artifacts, capabilities, runtime, UI, and publishing
• Oryn maintenance — repository Actions, triage and validated repairs
• Contributing — repository setup and pull request workflow

Coding agents and LLM tools should begin with llms.txt. Read AGENTS.md only when modifying the Synergy repository; plugin authors do not need the repository agent guide.

About Shanghai Innovation Institute

Shanghai Innovation Institute (SII / 上海创智学院) is a research institute dedicated to AI and large model innovation, based in Shanghai. The Holos team at SII builds Synergy as part of its open-source AI platform work.

🌐 https://www.sii.edu.cn

Contributing and Security

Contributions, bug reports, and feature ideas are welcome. Read CONTRIBUTING.md, follow the Code of Conduct, and use the repository's security reporting process for vulnerabilities rather than opening a public issue.

Synergy is open source under the MIT License.

Agent records use transactional SQLite by default, with an explicit PostgreSQL option. Binary evidence uses checksummed packs. Existing Home data upgrades through resumable migration. Optional whole-database optimization runs in an explicit maintenance window; committed data opens without waiting for space reclamation. Desktop offers retry, maintenance continuation and startup diagnostics when launch fails. Eligible upgrades admit new work while history prepares in the background. Open old conversations on demand, or pause background preparation from the status bar. Preserve frozen originals and protected snapshot paths until the independent recovery backup is complete. See Agent storage and storage operations.