Open Source Project #250: Cindy — An Out-of-the-Box Open Source AI Agent That Links Your Computers and Phone, and Brings Claude Code, Codex and Pi Together

Introduction

Your work computer, home desktop, laptop and phone belong together.

This is article 250 in the "One Open Source Project a Day" series. Today's project is Cindy (makecindy/cindy).

Most AI coding assistants today are "one terminal on one machine": Claude Code here, Codex there, a new session whenever you switch devices, and on the phone you can mostly just watch. Cindy targets that gap: it doesn't replace the agents you already use; it connects them to your devices.

The README opens with: "Cindy is an open-source AI agent, ready out of the box and yours to shape." Its tagline, in Chinese, is "想到，就能做到" — roughly, "Consider it done."

What You'll Learn

• What Cindy is, and why it integrates existing engines instead of building a new one
• How multi-device handoff, model sharing and phone remote desktop are designed
• What companions, group chat and Orca multi-agent collaboration each solve
• The plugin and Skill system, and engineering governance such as "backward compatibility of installed plugins is a red line"
• The real state of privacy and telemetry (the README is unusually direct about it)
• Repo structure, how the rules docs are organized, and where it fits

Prerequisites

• Basic use of coding agents such as Claude Code or Codex
• A rough idea of MCP and Skills
• To read the source: Electron, React Native / Expo and pnpm monorepos

Project Background

Overview

Cindy is an AI agent client for macOS, Windows, Linux, iOS and Android. The repo contains the open-source desktop and mobile clients and their shared packages.

Its core claims are three:

1. All your devices, one Cindy: open a session from another device, continue the conversation, and access its files
2. Keep your favourite agents: Claude Code, Codex and Pi side by side, and a session can switch engines
3. Real work in your actual tools: operate your files, browser and apps, with answers that can include charts, interactive controls and rich HTML

Team

• Organization: makecindy
• Created: 2026-07-22
• Contributors: top committers include dashhuang, zqchris, MagicLizi and DavidShenXD (each over 1,000 commits)
• Website: cindy.app
• Release cadence: v0.1.108 through v0.1.118 shipped within two weeks, mixing stable and beta builds

The README also states that the backend service lives in a separate repository and is not part of this monorepo. What is open is the clients.

Project Data

As of GitHub on 2026-10-27; treat as a snapshot:

• ⭐ GitHub Stars: ~7,100
• 🍴 Forks: ~850
• 🐛 Open issues: ~2,080
• 📦 Latest release: v0.1.118-beta (latest stable is v0.1.115)
• 📄 License: Apache-2.0
• 🌐 Website: cindy.app
• 💻 Languages: overwhelmingly TypeScript, plus JavaScript, Swift, Python, Rust, Kotlin and others

Main Features

What It Does

Cindy is a unified working interface, with several agent engines beneath it and all your devices beside it:

Use Cases

1. Pick up desktop work on your phone

   • Open a session from another device, continue the conversation and access its files without copying anything into a new chat

2. Borrow a model configured on another computer

   • Use providers set up elsewhere, including subscriptions, API providers and local models

3. Reach your whole desktop when chat isn't enough

   • Built-in remote desktop on the phone lets you open apps, type and operate the machine

4. Let a lead run a team of agents

   • Different agents for planning, parallel implementation and independent review, with a shared goal and acceptance criteria

5. Automations and chat channels

   • Recurring routines, and handing over work from channels such as Slack and Telegram

Quick Start

For users: download the client from cindy.app/download. Linux users can follow docs/linux.md in the repo (Ubuntu, Arch Linux and Omarchy).

The login screen has a Skip Sign-In option: use local agents only. The app then shows the account as "Not signed in", and server-backed capabilities are unavailable.

For developers:

git clone https://github.com/makecindy/cindy.git
cd cindy
git lfs pull
pnpm install

Requirements: Node.js 22.x, pnpm 10.x (v11 not yet supported), Git LFS.

Start desktop development against the official service:

# Mainland China Cindy account
pnpm restart:desktop:remote --region=cn
 
# Global Cindy account
pnpm restart:desktop:remote --region=global

The README stresses choosing cn or global explicitly, not relying on the internal default.

Models and Cost

The README is clear on this:

• The client is free
• You can authorize a subscription you already pay for (including Claude Code or Codex plans), connect your own API keys, use a local model, or use Cindy's managed model service
• Provider limits and billing still apply; a free client does not mean unlimited model usage

Core Features

1. Multi-device handoff

   • Devices on one account find each other and sessions continue across them; project files stay on their computer, so this isn't whole-disk sync

2. Cross-device model sharing

   • Share a provider from one computer to your other devices, and even to other accounts through share links

3. Phone remote desktop

   • Built in, with its own permissions

4. Three engines side by side

   • Claude Code, Codex and Pi; the session stays in Cindy, and switching engines hands off or rebuilds engine context rather than making internal states identical

5. Companions and group chat

   • Give a companion a role, instructions, Skills and recurring work, or put several into a group chat

6. Orca collaboration

   • A Lead session splits work, assigns, accepts and summarizes; several Worker sessions run in parallel or in sequence

7. Plugins, Skills and SkillHub

   • Discover Skills and plugins in SkillHub, plus an official plugin repo, cindy-official-plugins

8. Rich answers

   • Charts, interactive controls and rich HTML instead of a wall of text

Advantages

Why look at it?

• It takes a different path: instead of racing to build a stronger agent, it builds the device, role and collaboration layer above agents
• The repo is itself a sample of engineering governance for a large AI-assisted project; its AGENTS.md is very detailed
• The privacy notes lay almost everything out, including known exceptions

Deep Dive

Repo Structure

The README's table:

None of these binaries are committed: Claude Code, Codex and ripgrep are downloaded per platform by pnpm install, and the Android platform-tools are fetched with a pinned version and sha256 verification before Windows packaging.

packages/ holds over thirty packages. Notable ones:

• maker-core: the core, agent abstraction (BaseAgent), session orchestration and event stream, with zero Electron dependency
• device-link and device-link-protocol: device linking and its protocol
• orca-workflow: multi-agent collaboration workflow
• model-providers, model-compat, anthropic-compat-proxy, responses-anthropic-bridge, responses-chat-bridge: model providers and bridges between protocols
• maker-cc-manager, maker-pi-manager, maker-remote-ssh: daemons for Claude Code and Pi on remote SSH machines
• maker-scheduler: cron engine and scheduled tasks
• plugin-protocol, lizi-mcps: plugin protocol and built-in MCPs
• design-tokens: design tokens
• voice-input-core: voice input

Architecture Invariants

docs/dev-rules/architecture-invariants.md gathers a few high-impact rules:

1. Packages stay decoupled from render and main: a package is a module that could one day be offered on its own; it must not import Desktop Renderer components or reverse-import Desktop Main, and anything related is injected through init or runtime config and callbacks
2. No runtime dynamic import() in the main process: dependencies are always top-level static imports, because dynamic imports bring uncertainty to bundling, load timing and error paths
3. The main layout tree: the layout is a global recursive split/pane tree; panel identity is only panelKind, and a current position such as "left column" must never serve as business identity; chat-main must be exactly one in the whole tree, always visible, not closable, not collapsible, with a minimum width of 400px
4. Layout is user-level configuration, not session data, and must be in place with the first frame; never paint a default layout and then jump to the user's

One considerate rule: unregistered, dormant or detached panels may stay in the saved layout without rendering, and must be restored in place once re-injected, so don't clean up unknown panelKind values and destroy the position memory.

Multi-Device Links: device-link

Everything cross-device rests on device-link: a protocol with a relay that phone-to-desktop and desktop-to-desktop all go through.

The provider-sharing contract (docs/provider-sharing-contract.md) shows how strict the protocol design is:

• The relay envelope has an optional providerShare scope, and a single frame must not carry both sharedTask and providerShare
• Capability negotiation: the client declares provider-share-v1 in its hello, the relay answers with the same capability, and both sides must declare it or the relay replies VERSION_MISMATCH
• The source field is written only by the relay; a value supplied by the sender is never trusted
• Invite links are one-time secrets: 43 characters of base64url (randomBytes(32)), expiring in 5 minutes, with only the sha256 stored on the server; a guest's request expires in 24 hours and carries a 4-digit pairing code
• Rejected frames get a relay-error, always with the code DEVICE_OFFLINE, so the reason isn't exposed
• A share does not close when the sharer goes offline

Provider sharing and "shared tasks" are two independent authorizations, and the product rules allow the Mainland China edition and Global to share with each other.

The remote-desktop.md doc shows the same product care: hovering never starts desktop capture or takes over another viewer; the close confirmation appears only after a connection is established; closing the window immediately retires local input and heartbeat authority while the lease cleanup runs in the background, so a missing or failed remote reply cannot keep the window open.

Engine Integration: Claude Code, Codex, Pi

Cindy integrates engines rather than replacing them. The clearest sign is a red line in AGENTS.md about Pi:

Native Pi capability must not regress. Cindy may not refuse, disable or make irreversible anything Pi natively allows (installs, updates, extension loading, agent self-repair) on grounds of static analysis, compatibility hints, content fingerprints, host approval or new "security enhancements"; an explicit user command is authorization. Cindy may only add skippable prompts and a smoother GUI, and must never make Cindy's Pi harder to use than the same version of native Pi.

That is a restrained product principle: a wrapper must not make the engine underneath worse.

The four binaries bundled with the desktop app (claude, codex, ripgrep, pi) are version-pinned in tools/<kind>/latest.json and updated by tools/update.mjs.

Orca: Multi-Agent Collaboration

docs/dev-rules/orca-team-architecture.md is Orca's single authoritative document, over 120k characters. The core model:

• A Lead session splits tasks, assigns work, accepts results and summarizes
• Several Worker sessions run in parallel or in sequence
• A Worker is a full session, not a one-off subagent: it has its own model, effort, tool-call stream, context and visible history

What's implemented: multiple Workers (with role, label, focused-worker switching, soft and hard limits, archiving), a split view with the Lead and the focused Worker side by side, local Claude Code, Codex and Pi as either Lead or Worker, and SSH remote sessions as well. A remote Codex connects to the local MCP bridge through an SSH remote-forward.

The doc also states the current boundaries plainly:

• An Orca Team is still strictly bound to a single Lead session; Workers can't be shared across Leads
• Switching the focused Worker replaces the single Worker pane; it isn't several side by side
• There's no unarchive in the UI once a Worker is archived
• workflow_run / CC Workflow orchestration isn't in yet
• With device-link collaboration, the Lead / Worker / team are all orchestrated inside the controlled machine's process; the controller just routes through the tunnel

Part 2 of the document covers future plans: the execution-unit vision, a three-state split, Worker lifecycle types, Side Chat, and nine control-plane mechanisms.

Companions and Capability Inheritance

A companion is an agent with an identity: a role, instructions, Skills and recurring work. docs/dev-rules/agent-capabilities.md shows a design evolving:

• New companions inherit the tools and connections Cindy has enabled (toolsetMode: inherit, mcpMode: inherit), and explicit choices at creation win
• The old format can't reliably tell whether an allowlist came from the user or the system, so on 2026-10-02 the product decided to open all old allowlists up uniformly instead of guessing from empty versus non-empty
• Existing ask / auto / full-access modes keep their value
• The doc honestly records a known boundary: messages forwarded from group channels, other companions and automations reuse that agent's capabilities and permission mode, and there's no "lower the whole turn's permission by trigger source" yet

This kind of writing is rare. It records not just what is, but why it was decided that way and what isn't done.

The Plugin System and the "Installed Plugins Stay Compatible" Red Line

Plugin (.cindy) rules live in docs/dev-rules/plugin-security-and-authoring.md (nearly 100k characters). The red line AGENTS.md pulls out is:

Backward compatibility of installed plugins is a red line. Any plugin-system change (approval-state schema, fingerprint format, manifest validation, install layout, package format) must be backward compatible: after upgrading, with no action by the user, plugins that were installed, approved and enabled must keep working, and the user must never be asked to reinstall, reconfirm permissions or reconfigure. If that can't be done, the change must ship an automatic migration from old data. A missed migration is a P0.

PRs that touch the plugin foundation always go through an allowlist confirmation gate and need an explicit Approve from the releaser, regardless of diff size.

Plugin discovery is progressive: ghost_list → ghost_info → ghost_call, specified in ghost-progressive-discovery.md. In the latest v0.1.118, approved plugins can see a task's run state and messages, receive key events, and trigger tidy-up or interruption within allowed bounds, with operations they initiate through the host counted in usage.

Log Upload and Redaction: Three Invariants

The three invariants in log-upload-and-redaction.md show the attitude toward privacy:

1. Record boundary: the write side's continuation-line escaping and the read side's splitting are two halves of one invariant; breaking either lets privacy escape
2. Allowlist direction: deny-by-default, and it must not become a denylist, since debug-level feature logs are the main source of leaked user content
3. Marker generation plus atomic clear: with concurrent instances, timestamps alone would delete another instance's freshly written crash marker

Redaction rules only grow, never shrink; loosening any rule counts as a privacy change and needs re-review.

Engineering Governance: An Entry Point for AI Collaborators

The repo sets up explicit entry points for how AI takes part in development:

• AGENTS.md is the single source of project instructions for both Codex and Claude Code; CLAUDE.md holds only @AGENTS.md, so rules aren't maintained twice
• Rules fall in three groups: development rules in docs/dev-rules/, product rules in docs/product-rules/, design rules in docs/design-rules/
• The root AGENTS.md keeps only rules that apply to every task, risk entry points and a document index; module-specific rules sit in nested AGENTS.md files
• Each kind of change has a "must read first" document: read orca-team-architecture.md before touching Orca, the redaction rules before touching log upload
• Tests have a value bar: a new test must verify an observable result through a real production entry point and state the basis, the coverage gap and the minimal failing input; pnpm check:test-hygiene blocks violations in CI, and the baseline only goes down
• Commits need a DCO sign-off (git commit -s); no CLA

A small detail: product terms have a glossary (i18n/GLOSSARY.md), and the boundaries of "task / conversation / message" are fixed. The session is called a "task" to users, "conversation" is used only for the exchange inside a task, a single exchange is a "message", and "task" must be disambiguated when it appears in a sentence with task.

Privacy and Telemetry

The README is candid here. A summary:

• Official distribution builds include TapDB usage analytics: device identifiers, OS and app version, startup and activity events. After sign-in events are associated with your account ID, so it isn't fully anonymous. TapDB does not collect chat content, file content or working-directory data
• You can turn it off without editing code: on desktop, Settings → About → Usage statistics; on mobile, Usage statistics in Settings. It defaults to on
• A known mobile exception: enterprise SSO skips the policy-acceptance step. If no consent record exists and that sign-in is restored after a restart, the current migration can mark even a new installation as consented; with TapDB configured and statistics enabled, reporting can then start without explicit policy acceptance. Turning Usage statistics off prevents this. The README links the source files directly
• Online heartbeats and diagnostic logs are separate mechanisms, unaffected by the usage-statistics switch. Desktop sends heartbeats to Cindy services only during a verified cloud sign-in (account ID, platform, version); local mode sends none
• Desktop native crash dumps stay local and are never uploaded automatically. Diagnostic logs can be uploaded manually, and a separate, default-off automatic crash-log upload option exists
• Building from source doesn't require keeping analytics: desktop development builds don't initialize TapDB by default

The client connects to Cindy's official cloud services by default, which is intentional: external developers don't need to self-host a server; sign in with your own Cindy account in a dev build and develop and test directly against the official servers.

Scope and Limits

• The backend isn't open: the clients are open, the server is in another repo. Many capabilities (cloud companion sync, the device-link relay, the managed model service) depend on official services, and they're unavailable in "Skip Sign-In" mode
• Official services by default: endpoint manifests are in config/endpoint.json and endpoint.global.json, and desktop auto-updates also come from the official CDN
• There is telemetry: official builds ship with usage statistics on by default; it can be turned off, but note the known mobile exception above
• Very young and fast-moving: created in July 2026, over ten releases in two weeks, about 2,000 open issues, beta and stable channels in parallel. Fine if you're willing to keep up; not for anyone expecting stability
• Free is not zero cost: the client is free, model usage is still billed by providers
• A wide permission surface: agents can operate files, the browser, apps and even a remote desktop. Device links need the machines online, signed into the same account, with the relevant permissions enabled; remote access isn't whole-disk sync
• Orca's current boundaries: single-Lead binding, no side-by-side Workers, irreversible archiving, and so on (see above)
• Docs are mostly in Chinese: the rules in AGENTS.md and docs/dev-rules/ are largely Chinese, while the README and contribution guide have English versions

Links and Resources

Official

• 🌟 GitHub: https://github.com/makecindy/cindy
• 🌐 Website: https://cindy.app
• ⬇️ Download: https://cindy.app/download
• 💰 Pricing: https://cindy.app/pricing
• 🐛 Issues: https://github.com/makecindy/cindy/issues

Related

• Official plugins: makecindy/cindy-official-plugins
• Contributing guide: CONTRIBUTING.en.md in the repo
• Repo map: docs/dev-rules/repo-map.md in the repo
• Orca architecture: docs/dev-rules/orca-team-architecture.md in the repo
• Linux install: docs/linux.md in the repo

Summary and Outlook

Key Takeaways

1. Integrate, don't replace: Claude Code, Codex and Pi coexist, and Cindy builds the device, role and collaboration layer
2. Your computer is the server: multi-device handoff, model sharing and phone remote desktop, with no rental or self-hosting
3. Multi-agent collaboration has an explicit model: Orca's Lead plus full-session Workers, not one-off subagents
4. Heavy engineering governance: architecture invariants, a "must read first" rules index, the backward-compatibility red line and a test value bar show how a big AI-assisted repo keeps order
5. Candid privacy notes: telemetry, how to turn it off and the known mobile exception are all stated, though the closed backend and default official services are tradeoffs to weigh yourself

Who It's For

• Developers who use Claude Code and Codex across several computers and a phone and want sessions to hand off between them
• People who want to organize several agents into a "lead plus team" with independent review
• Engineers studying how a large AI-assisted project writes its rules docs; the organization of AGENTS.md plus docs/dev-rules/ is a useful reference
• Anyone building agent plugins or Skills who wants to plug into an existing client

Suggestions

Download the client, use "Skip Sign-In" to try local agents, and get a feel for the interface and engine switching; then decide whether to sign in for multi-device features. If privacy matters, first turn off usage statistics under Settings → About, and read the README's Privacy & telemetry section carefully. To read the source, start with the "locate by user behaviour" table in docs/dev-rules/repo-map.md; it's far faster than browsing directories.

Explore PrimeSkills — curated AI agent and skill tools, each validated in real workflows. No hype, just tools that actually work.

Visit my homepage for more insights and interesting products.