ATBClone (macOS Application Cloning Engine)

September 14, 2026 ยท View on GitHub

ไธญๆ–‡็‰ˆ English | ๐ŸŒ Online Docs | ๐Ÿ“– User Guide (EN) | ็”จๆˆทไฝฟ็”จๆ‰‹ๅ†Œ (ไธญๆ–‡)

ATBClone (macOS Application Cloning Engine)

Tests

๐Ÿš€ ATBClone is a modern application multi-instancing and clone management engine designed for macOS. It supports isolated user data directories, independent network proxies (HTTP / SOCKS5), automated recipe matching, ad-hoc code re-signing, and sandbox removal.

๐Ÿ“– Looking for a beginner-friendly tutorial? Visit our online documentation at clone.aitobox.com, or check out the English User Manual | ไธญๆ–‡ไฝฟ็”จๆ‰‹ๅ†Œ.

ATBClone Clones Dashboard

๐Ÿ“ฅ Download

Visit the GitHub Releases page to download the latest release of ATBClone.

ATBClone provides two distribution packages with identical core functionality:

Distribution PackageTarget AudienceDescription
ATBClone-arm-x.x.x.dmg๐Ÿ‘ถ General Users (Strongly Recommended)macOS Native GUI desktop application installer (.dmg). Provides a modern, visual card-based interface with zero terminal knowledge required.
ATBCloneCli.tar.gzโšก Power Users / DevelopersStandalone binary command-line tool archive (ATBCloneCli). Zero Python dependencies required; ideal for terminal power users, automation scripts, and CI/CD pipelines.

๐Ÿ’ก User Guidance:

  • Beginners / Everyday Users: Please prioritize downloading and using the GUI app (.dmg). It offers an intuitive visual interface for one-click cloning, app launching, status monitoring, and settings.
  • Advanced Users / Developers: Use the CLI tool (ATBCloneCli / atbclone) for fast terminal interaction, batch scripting, deep application probing, and headless workflows.

โœจ Key Features

  • ๐Ÿ“ฆ Dual-Engine Cloning Mechanism:
    • Hard Clone: Designed for native and social applications (WeChat, QQ, Telegram, AI clients, Chrome, Edge, Arc, etc.). Duplicates the entire App Bundle, modifies Info.plist and Bundle Identifier, injects isolated HOME / TMPDIR data directories via in-process dynamic library injection (libatbclone_env.dylib) or Mach-O binary launcher hijack, optionally strips App Sandbox restrictions, and performs ad-hoc code re-signing.
    • Soft Clone: Designed for modern code editors and browsers (Cursor, VS Code, Firefox, Brave, Tor, Zed, etc.). Generates a lightweight wrapper bundle, automatically injecting isolated --user-data-dir / --profile launch arguments and proxy environment variables.
  • ๐Ÿ” Intelligent App Prober: Automatically inspects Mach-O architectures, frameworks, and code signing sandbox entitlements for any application without a pre-configured recipe, dynamically determining the optimal soft/hard clone strategy and generating recommended recipes.
  • ๐ŸŒ Isolated Network Proxies: Configure dedicated HTTP or SOCKS5 proxies (with authentication support) per cloned application without interfering with host system or primary application traffic.
  • ๐Ÿ“‘ Recipe Engine: 34+ built-in recipes for popular apps and AI Agent tools, with local override support via ~/ATBClone/recipes/.
  • ๐Ÿช„ Interactive Wizard: Step-by-step interactive CLI guide supporting terminal drag-and-drop application paths, automatic name incrementing, custom data directory configuration, and on-the-fly proxy setup.
  • ๐Ÿ”„ Lifecycle Management: View cloned apps (list), re-clone after primary app updates while preserving user and chat data (update), and safely remove clones with interactive prompts or flag controls (remove with --with-data / --keep-data).
  • ๐Ÿ›ก๏ธ Security & Privilege Elevation: Writing to ~/ATBClone/Apps requires no admin privileges; writing to /Applications uses native single-prompt macOS osascript authorization; robust path escaping via shlex.quote throughout.

๐Ÿ’ก Tip for Everyday Users: If you prefer not to use the terminal, download ATBClone-arm-x.x.x-arm.dmg from GitHub Releases, open the DMG, drag ATBClone.app to your Applications folder, and launch it directly.

The native macOS desktop interface provides a visual, streamlined experience:

  1. Dashboard & Clone Cards:
    • Displays all cloned applications in a modern card layout showing app icons, cloning strategies, proxy statuses, and creation timestamps.
    • Launch cloned apps, update after primary app upgrades (preserving chat history and data), or safely remove clones with a single click.
  2. Visual Clone Creation:
    • Drag and drop or browse for any .app bundle from your system.
    • Automatically matches built-in recipes or runs the App Prober on unlisted applications.
    • Customize clone name, display title, custom icon, dedicated data directory (e.g. on external SSDs), and independent HTTP / SOCKS5 proxies.
  3. Built-in Recipe Library:
    • Explore 34+ pre-configured application recipes (WeChat, QQ, Chrome, Cursor, ChatGPT, Claude, etc.) categorized by type, complete with sandbox stripping rules and isolation strategies.
  4. App Prober (Deep Architecture Inspection):
    • Inspect any unknown macOS app's Mach-O architecture, frameworks, and sandbox entitlements, and generate custom recipe YAML files with one click.
  5. System Diagnostics (Doctor):
    • Self-check system prerequisites, Xcode command-line tools, codesigning utilities, and storage permissions to ensure optimal stability.
  6. Multi-language & System Tray:
    • Fully localized across multiple languages (English, ็ฎ€ไฝ“ไธญๆ–‡, ็น้ซ”ไธญๆ–‡, ๆ—ฅๆœฌ่ชž, ํ•œ๊ตญ์–ด, Deutsch, Franรงais, ะ ัƒััะบะธะน, Espaรฑol) with macOS menu bar tray integration.

(For developers running the GUI from source: run bash scripts/run_gui.sh or python -m atbclone.gui)

๐Ÿš€ Command Line Interface (CLI โ€” For Power Users & Scripting)

โšก For Advanced Users & Automation: The CLI tool (atbclone or standalone binary ATBCloneCli) provides full control over the cloning engine with scriptable commands, rich terminal tables, and automation support.

1. Interactive Wizard (CLI Guided Mode)

No need to memorize CLI optionsโ€”follow the interactive prompts in your terminal:

atbclone wizard

Workflow: Drag and drop .app path โž” Auto-match recipe โž” Set clone name โž” Set display name and icon โž” Select destination directory โž” Custom data directory (if supported) โž” Optional proxy setup โž” Confirm and create.

2. Command Line Quick Clone (clone)

Basic Clone (Auto-incremented name, defaults to ~/ATBClone/Apps)

atbclone clone /Applications/WeChat.app

Specify Clone Name and Output Directory

atbclone clone /Applications/WeChat.app --name "WeChat-Work" --output-dir ~/ATBClone/Apps

Custom Data Storage Directory (--data-dir)

For applications that support data isolation (Chromium series, Firefox, WeChat, etc.), you can specify a custom data storage directory (e.g. on an external SSD or dedicated workspace):

atbclone clone /Applications/Chrome.app --name "Chrome-Custom" --data-dir /Volumes/ExternalSSD/ChromeData

Note: The prober automatically detects if the application supports data isolation; attempting to set --data-dir on unsupported applications (e.g. Zed) will fail with a friendly error.

Clone Applications without Pre-configured Recipes (Auto-triggers Prober)

When cloning an app without a built-in recipe, ATBClone automatically runs App Prober to inspect the architecture and sandbox entitlements, dynamically generates the optimal recipe, and executes the clone:

atbclone clone /Applications/ATBCmder.app --name "ATBCmder-Work"

Configure Dedicated Network Proxies (HTTP / SOCKS5)

# Configure HTTP proxy with credentials (passwords stored securely in macOS Keychain)
atbclone clone /Applications/Telegram.app \
  --name "Telegram-Proxy" \
  --proxy-host 127.0.0.1 \
  --proxy-port 7890 \
  --proxy-type http \
  --proxy-user alice \
  --proxy-password "my_secret_token"

# Configure SOCKS5 proxy
atbclone clone /Applications/ChatGPT.app \
  --name "ChatGPT-US" \
  --proxy-host 127.0.0.1 \
  --proxy-port 1080 \
  --proxy-type socks5

Injection Strategy Selection (--injection-strategy)

For Hard Clone apps, customize how isolated environment variables (HOME, TMPDIR, proxies) are injected into the cloned application:

# Auto mode (default): probes Mach-O load command headroom, prefers in-process dylib injection, falls back to launcher if headroom < 56 bytes
atbclone clone /Applications/WeChat.app --injection-strategy auto

# Force dylib injection (guarantees native macOS system notifications and Menu Bar status icons)
atbclone clone /Applications/WeChat.app --injection-strategy dylib

# Force Mach-O binary launcher hijack
atbclone clone /Applications/Chrome.app --injection-strategy launcher

Options: auto (default/recommended), dylib (in-process dynamic library, Darwin PIDVersion preserved), launcher (C binary launcher hijack).

3. List Cloned Applications (list)

View all clones managed by ATBClone in a Rich-formatted table:

atbclone list

Example output:

โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”“
โ”ƒ ๅ็งฐ     โ”ƒ ๅŽŸ APP  โ”ƒ Bundle ID            โ”ƒ ็ญ–็•ฅ       โ”ƒ ๅˆ›ๅปบๆ—ถ้—ด         โ”ƒ ไปฃ็†                   โ”ƒ
โ”กโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ฉ
โ”‚ ๅพฎไฟก2    โ”‚ ๅพฎไฟก    โ”‚ com.tencent.xinWeChat โ”‚ hard_clone โ”‚ 2026-08-18 22:30 โ”‚ ๆœชๅผ€ๅฏ                 โ”‚
โ”‚ TG-Proxy โ”‚ Telegramโ”‚ ru.keepcoder.Telegram โ”‚ hard_clone โ”‚ 2026-08-18 22:45 โ”‚ http://127.0.0.1:7890  โ”‚
โ”‚ Chrome2  โ”‚ Chrome  โ”‚ com.google.Chrome    โ”‚ hard_clone โ”‚ 2026-08-18 23:00 โ”‚ ๆœชๅผ€ๅฏ                 โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ดโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ดโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ดโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”˜

4. Synchronize Clones After Primary App Updates (update)

When the primary application is updated via the Mac App Store or website, update your clone with a single command while preserving all chat history, logins, and data:

atbclone update WeChat2

5. Remove Clones (remove)

When executing remove in an interactive terminal, ATBClone prompts whether to also delete the data directory:

atbclone remove WeChat2
# Interactive prompt: Also delete data directory /Users/.../ATBClone/Data/WeChat2? [y/N]

Explicitly Remove Application and Data Directory (--with-data)

atbclone remove WeChat2 --with-data

Explicitly Remove Application Only and Keep Data (--keep-data)

atbclone remove WeChat2 --keep-data

Note: If the application or data directory is located in a root/admin path (e.g. /Applications), privilege escalation will be requested automatically once to clean up safely.

6. Recipe Management & Custom Extensions (recipe)

List All Built-in Recipes

atbclone recipe list

View Recipe Details for a Specific Bundle ID

atbclone recipe show com.tencent.xinWeChat

Custom & Override Recipes

Place a custom YAML recipe in ~/ATBClone/recipes/<bundle_id>.yaml to automatically take precedence:

# Example: ~/ATBClone/recipes/com.example.customapp.yaml
bundle_id: com.example.customapp
app_name: CustomApp
strategy: hard_clone
app_type: cocoa # Options: cocoa, electron, chromium, firefox, generic
strip_sandbox: false # false (recommended): utilizes macOS native container isolation; true: strips App Sandbox
environment_injection:
  HOME: '{{ATB_DATA_DIR}}/Home'
  TMPDIR: '{{ATB_DATA_DIR}}/Tmp'
proxy:
  enabled: true
  type: http
  host: 127.0.0.1
  port: 7890

7. Deep Application Probing & Recipe Generation (probe)

Perform deep architecture and code signing inspection on any local .app bundle, analyze its engine (Chromium / Electron / Gecko / Native) and sandbox status, and output a recommended ATBClone Recipe YAML:

Basic Probing with Terminal Summary

atbclone probe /Applications/ATBCmder.app

Probe and Save Directly to Local Repository (~/ATBClone/recipes/<bundle_id>.yaml)

atbclone probe /Applications/ATBCmder.app --save

Export Generated Recipe to a Specific Path

atbclone probe /Applications/ATBCmder.app -o /path/to/recipe.yaml

Output in Machine-Readable JSON

atbclone probe /Applications/ATBCmder.app --json

8. View Version & System Information (version)

# View detailed system and runtime environment information
atbclone version

# Output version number only
atbclone version --short
# or
atbclone --version

๐Ÿ“‹ Built-in Recipes

CategoryApplicationBundle IdentifierStrategyApp TypeStrip Sandbox
Instant Messaging & CollaborationWeChatcom.tencent.xinWeChatHard Clonecocoaโœ”
WeCom (ไผไธšๅพฎไฟก)com.tencent.WeWorkMacHard Clonechromiumโœ”
QQcom.tencent.qqHard Cloneelectronโœ”
Lark (้ฃžไนฆ)com.electron.larkHard Cloneelectronโœ”
Telegram (Native Swift)ru.keepcoder.TelegramHard Clonecocoaโœ”
Telegram Desktoporg.telegram.desktopHard Clonegenericโœ”
LINEjp.naver.line.macHard Clonecocoaโœ”
KakaoTalkcom.kakao.KakaoTalkMacHard Clonecocoaโœ”
Slackcom.tinyspeck.slackmacgapHard Cloneelectronโœ”
Discordcom.hnc.DiscordHard Cloneelectronโœ”
Skypecom.skype.skypeHard Cloneelectronโœ”
AI ClientsClaudecom.anthropic.claudefordesktopHard Cloneelectronโœ”
ChatGPT (Codex)com.openai.codexHard Clonecocoaโœ”
ChatGPT (Standard)com.openai.chatHard Clonecocoaโœ”
Geminicom.google.GeminiMacOSHard Clonecocoaโœ”
Antigravitycom.google.antigravityHard Cloneelectronโœ”
Antigravity IDEcom.google.antigravity-ideHard Cloneelectronโœ”
BrowsersGoogle Chromecom.google.ChromeHard Clonechromiumโ€”
Microsoft Edgecom.microsoft.edgemacHard Clonechromiumโ€”
Brave Browsercom.brave.BrowserSoft Clonechromiumโ€”
Firefoxorg.mozilla.firefoxSoft Clonefirefoxโ€”
Tor Browserorg.torproject.torbrowserSoft Clonefirefoxโ€”
Arc Browsercompany.thebrowser.BrowserHard Clonechromiumโ€”
Media & EntertainmentBilibili (ๅ“”ๅ“ฉๅ“”ๅ“ฉ)com.bilibili.bilibiliPCHard Cloneelectronโœ”
Douyin (ๆŠ–้Ÿณ)com.bytedance.douyin.desktopHard Cloneelectronโœ”
Netease Music (็ฝ‘ๆ˜“ไบ‘้Ÿณไน)com.netease.163musicHard Clonechromiumโœ”
Steamcom.valvesoftware.steamHard Clonecocoaโœ”
Productivity & UtilitiesWPS Officecom.kingsoft.wpsoffice.macHard Clonecocoaโœ”
VideoFusion (ๅ‰ชๆ˜ ไธ“ไธš็‰ˆ)com.lemon.lvproHard Clonechromiumโœ”
CapCutcom.lemon.lvoverseasHard Clonechromiumโœ”
Developer ToolsCursorcom.todesktop.230313mzl4w4u92Soft Cloneelectronโ€”
VS Codecom.microsoft.VSCodeSoft Cloneelectronโ€”
Android Studiocom.google.android.studioHard Clonegenericโœ”
Zeddev.zed.ZedSoft Clonegenericโ€”

KakaoTalk validation: Concurrent launch with the original app and notifications have been checked. Clone login, separate-account data isolation, and login persistence after restarting the clone have not yet been verified.

๐Ÿ› ๏ธ Prerequisites & Development Setup

  • Operating System: macOS 13.0+ (Apple Silicon arm64 / Intel x86_64)
  • Python: Python 3.12+ (strictly required for build_cli.sh compilation; Conda recommended)
  • System Tools: Xcode Command Line Tools installed (provides codesign, xcode-select, PlistBuddy)
# 1. Install Xcode Command Line Tools (if not already installed)
xcode-select --install

# 2. Activate Conda environment and install in development mode
conda activate ATBClone
pip install -e ".[dev,gui]"

# 3. Run environment self-check
atbclone doctor

๐Ÿท๏ธ Semantic Version Management

The project adheres to semantic versioning x.y.z (current version: 1.1.1) and provides a dedicated version management script at scripts/manage_version.py:

# 1. Check version consistency across configuration files
python scripts/manage_version.py --show

# 2. Bump semantic version (patch: 1.1.1 -> 1.1.2, minor: 1.1.1 -> 1.2.0, major: 1.1.1 -> 2.0.0)
python scripts/manage_version.py --bump patch
python scripts/manage_version.py --bump minor
python scripts/manage_version.py --bump major

# 3. Set an explicit version
python scripts/manage_version.py 1.1.1

# 4. Preview changes without writing to disk
python scripts/manage_version.py --bump patch --dry-run

The script automatically updates version declarations in pyproject.toml, src/atbclone/__init__.py, and other configuration files.

๐Ÿ—๏ธ Standalone Binary Packaging (Build)

The project includes automated build scripts to package both the CLI and GUI into standalone binaries:

# 1. Build CLI standalone binary (dist/ATBCloneCli)
bash scripts/build_cli.sh

# 2. Build GUI DMG installer (dist/ATBClone-1.1.1.dmg)
bash scripts/build_gui.sh

The resulting standalone binary will be generated under dist/:

# Verify the built binary
./dist/ATBCloneCli --help
./dist/ATBCloneCli version
./dist/ATBCloneCli doctor
./dist/ATBCloneCli probe /Applications/ATBCmder.app

๐Ÿงช Running Tests

This project follows TDD and automated test verification practices, with full unit and integration test suites:

PYTHONPATH=src conda run -n ATBClone python -m pytest tests/ -v

๐Ÿ“‚ Directory & Storage Architecture

~/ATBClone/
โ”œโ”€โ”€ config.yaml           # User configuration & preferences (language, tray, etc.)
โ”œโ”€โ”€ clones.yaml           # Global clone state tracking registry
โ”œโ”€โ”€ recipes/              # User custom recipe directory (optional overrides)
โ””โ”€โ”€ Data/                 # Isolated data directories per clone
    โ”œโ”€โ”€ WeChat2/
    โ”‚   โ”œโ”€โ”€ Home/         # Isolated user home directory
    โ”‚   โ””โ”€โ”€ Tmp/          # Isolated temporary directory
    โ””โ”€โ”€ Chrome2/          # Isolated Chrome User Data directory

src/atbclone/
โ”œโ”€โ”€ cli/                  # CLI command layer (Click + Rich)
โ”‚   โ”œโ”€โ”€ cmd_clone.py      # Main clone command (supports auto-probing)
โ”‚   โ”œโ”€โ”€ cmd_doctor.py     # Environment checks
โ”‚   โ”œโ”€โ”€ cmd_list.py       # Clone listing
โ”‚   โ”œโ”€โ”€ cmd_probe.py      # Deep app architecture probing & recipe generation
โ”‚   โ”œโ”€โ”€ cmd_recipe.py     # Recipe management
โ”‚   โ”œโ”€โ”€ cmd_remove.py     # Clone removal
โ”‚   โ”œโ”€โ”€ cmd_update.py     # Clone update & sync
โ”‚   โ”œโ”€โ”€ cmd_version.py    # Version & system information
โ”‚   โ””โ”€โ”€ cmd_wizard.py     # Interactive wizard
โ”œโ”€โ”€ core/                 # Core domain models & cloning engines
โ”‚   โ”œโ”€โ”€ app_inspector.py  # App metadata inspection & auto-numbering
โ”‚   โ”œโ”€โ”€ app_prober.py     # Deep probing, sandbox inspection & recipe extraction
โ”‚   โ”œโ”€โ”€ clone_task.py     # Clone task entity
โ”‚   โ”œโ”€โ”€ engines.py        # Soft & Hard cloning execution engines
โ”‚   โ”œโ”€โ”€ models.py         # Domain models
โ”‚   โ””โ”€โ”€ state.py          # YAML state management
โ”œโ”€โ”€ gui/                  # Native macOS GUI desktop application layer (Toga / Briefcase)
โ”‚   โ”œโ”€โ”€ components/       # Reusable UI widgets (cards, sidebar, top bar)
โ”‚   โ”œโ”€โ”€ services/         # GUI service bridge (clone, doctor, probe, recipe, tray)
โ”‚   โ””โ”€โ”€ views/            # GUI views (dashboard, recipes, probe, doctor, settings, logs)
โ”œโ”€โ”€ executor/             # Low-level executors (Subprocess / AppleScript elevation)
โ”‚   โ””โ”€โ”€ runner.py
โ””โ”€โ”€ recipes/              # Recipe models, loaders & 34 built-in rules
    โ”œโ”€โ”€ builtin/          # Built-in YAML recipes
    โ”œโ”€โ”€ loader.py         # Recipe matching & priority loader
    โ””โ”€โ”€ models.py         # Pydantic validation models

๐Ÿ“– User Manual & Documentation

For a comprehensive walkthrough of ATBClone GUI, custom recipes, engine mechanics, and troubleshooting, visit the online documentation at clone.aitobox.com:

๐Ÿ“„ License & Release Notes