{"id":50671991,"url":"https://github.com/gadzan/xacpx","last_synced_at":"2026-07-03T05:01:56.774Z","repository":{"id":347310336,"uuid":"1192613325","full_name":"gadzan/xacpx","owner":"gadzan","description":"Remote agent control from chat Drive acpx agent sessions — Codex, Claude Code, Gemini — from WeChat, Feishu, Yuanbao, and other message channels. No terminal required.","archived":false,"fork":false,"pushed_at":"2026-07-02T07:54:43.000Z","size":7145,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T08:26:04.297Z","etag":null,"topics":["acpx","claude-code","codex","gemini","opencode","weixin-agent-sdk"],"latest_commit_sha":null,"homepage":"https://gadzan.github.io/xacpx/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gadzan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-26T11:46:20.000Z","updated_at":"2026-07-02T07:51:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"ba09ac2e-1415-458c-91b6-0944e436d775","html_url":"https://github.com/gadzan/xacpx","commit_stats":null,"previous_names":["gadzan/weacpx","gadzan/xacpx"],"tags_count":124,"template":false,"template_full_name":null,"purl":"pkg:github/gadzan/xacpx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gadzan%2Fxacpx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gadzan%2Fxacpx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gadzan%2Fxacpx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gadzan%2Fxacpx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gadzan","download_url":"https://codeload.github.com/gadzan/xacpx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gadzan%2Fxacpx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35072845,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acpx","claude-code","codex","gemini","opencode","weixin-agent-sdk"],"created_at":"2026-06-08T12:03:45.044Z","updated_at":"2026-07-03T05:01:56.720Z","avatar_url":"https://github.com/gadzan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xacpx\n\n![xacpx.png](xacpx_banner.png)\n\n\u003e Remotely drive Codex, Claude Code, and other acpx sessions from WeChat, Feishu, or Yuanbao.\n\n[![npm](https://img.shields.io/npm/v/@ganglion/xacpx?style=flat-square)](https://www.npmjs.com/package/@ganglion/xacpx)\n[![Node.js Version](https://img.shields.io/node/v/@ganglion/xacpx?style=flat-square)](https://nodejs.org)\n[![zread](https://img.shields.io/badge/Ask_Zread-_.svg?style=flat-square\u0026color=00b0aa\u0026labelColor=000000\u0026logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS42MDE1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K\u0026logoColor=ffffff)](https://zread.ai/gadzan/xacpx)\n[![License](https://img.shields.io/npm/l/@ganglion/xacpx?style=flat-square)](./LICENSE)\n\nEnglish · **[中文](./docs/zh/README_zh.md)**\n\n## What is this\n\n`xacpx` is a tool that lets you control ACP agents such as Codex / Claude Code / Gemini / OpenCode directly from WeChat, Feishu, or Yuanbao. It connects chat messages to your agent CLI sessions through `acpx`, so you can, right from your phone:\n\n- Create and switch between sessions\n- Have the agent keep working in a specific project directory\n- View streaming replies, final results, and tool-call summaries\n- Adjust permission policies\n- Orchestrate multiple agents when needed\n\nIf you need to code or work remotely on a temporary basis, `xacpx` gives you a fast, convenient **remote entry point** so you can get things done from WeChat or Feishu anytime, anywhere.\n\n\u003e For everyday use, remember `/ss` first: it creates or reuses an xacpx logical session. If you want to attach to an existing native session of a local agent such as Codex, use `/ssn`; see [native sessions](./docs/native-sessions.md).\n\n## 5-minute quick start\n\n### Prerequisites\n\n- Node.js 22+ or Bun\n- A working agent CLI you intend to use, such as Codex / Claude Code / Gemini / OpenCode\n- A phone with WeChat, Feishu, or Yuanbao installed\n\n\u003e The WeChat channel works on top of `weixin-agent-sdk`, the Feishu channel uses Feishu custom-app credentials, and the Yuanbao channel uses `appKey` / `appSecret`; the underlying agent sessions are driven by `acpx`. Normally you don't need to install `acpx` globally.\n\n### Install\n\n```bash\nnpm install -g @ganglion/xacpx --registry=https://registry.npmjs.org\n# or\nbun add -g @ganglion/xacpx\n```\n\n### Log in and start\n\n```bash\nxacpx login    # shows a QR code; scan it with WeChat\nxacpx start    # start the background service\n```\n\nTo use Feishu or Yuanbao instead of WeChat, see \"Other channels\" below first.\n\n### Create your first session in WeChat\n\nSend these messages in WeChat:\n\n```text\n/ss codex -d /absolute/path/to/your/repo\n/help\n```\n\nThen just send plain text:\n\n```text\nhello\n```\n\nIf everything works, plain text goes into the current session and the agent's reply comes back to WeChat.\n\n### Other channels\n\nWeChat is the built-in default channel. Feishu and Yuanbao are distributed as official plugin packages, and third-party channels follow the same plugin flow. If you can't remember the package names, run `xacpx plugin known` first.\n\n```bash\n# Feishu\nxacpx plugin add @ganglion/xacpx-channel-feishu\nxacpx channel add feishu     # enter appId/appSecret when prompted\nxacpx restart\n\n# Yuanbao\nxacpx plugin add @ganglion/xacpx-channel-yuanbao\nxacpx channel add yuanbao    # enter appKey/appSecret when prompted\nxacpx restart\n```\n\nFull credentials, parameters, and management commands (`enable/disable/rm`): [channel-management.md](./docs/channel-management.md). To write your own channel plugin: [plugin-development.md](./docs/plugin-development.md).\n\n## Your everyday workflow\n\nThe most common sequence is just four steps:\n\n1. **Start the background service**: `xacpx start`\n2. **Create or switch sessions**: `/ss ...`, `/use ...`\n3. **Send plain text directly**: any text not starting with `/` goes to the current session\n4. **Check status or cancel when needed**: `/status`, `/cancel`\n\n### Reply modes\n\n`xacpx` supports three reply modes (switch per session with `/replymode`):\n\n- `stream`: stream back intermediate text\n- `final`: return only the final result\n- `verbose`: the default; streaming text plus tool-call summaries\n\nFor example, in `verbose` mode you'll see:\n\n```text\n📖 sed -n '1,220p' README.md\n🔍 rg -n 'session new' src tests\n💻 bun test tests/unit/main.test.ts\n✏️ Edit parse-command.ts\n```\n\n## Command cheat sheet\n\nThe essentials to get going. Full references: **CLI → [cli-reference.md](./docs/cli-reference.md)**, **chat commands → [commands.md](./docs/commands.md)**.\n\n**Terminal (on the host):**\n\n| Command | Description |\n|------|------|\n| `xacpx login` / `logout` | Log in / out of WeChat |\n| `xacpx start` / `stop` / `restart` / `status` | Manage the background service |\n| `xacpx update` | Update xacpx and installed plugins |\n| `xacpx doctor` | Run environment diagnostics |\n| `xacpx channel add \u003cname\u003e` | Add a message channel (Feishu / Yuanbao / …) |\n| `xacpx ws add` / `xacpx agent add \u003cname\u003e` | Register a workspace / agent |\n\n**Chat (in WeChat / Feishu / Yuanbao):**\n\n| Command | Description |\n|------|------|\n| `/ss \u003cagent\u003e -d \u003cpath\u003e` | Create or reuse a session in a project directory |\n| `/ss new \u003cagent\u003e --ws \u003cname\u003e` | Force-create a new session |\n| `/ssn \u003cagent\u003e -d \u003cpath\u003e` | Attach to a local agent's [native session](./docs/native-sessions.md) |\n| `/use \u003calias\u003e` | Switch the current session |\n| `/status` · `/cancel` | Show status · stop the current task |\n| `/model` · `/mode` | Switch the LLM model · set the acpx mode |\n| `/replymode stream\\|verbose\\|final` | Change how replies stream |\n| `/lt \u003ctime\u003e \u003cmessage\u003e` | Schedule a one-time future message ([/later](./docs/later-command.md)) |\n| `/dg \u003cagent\u003e \u003ctask\u003e` | Delegate a subtask to another agent |\n| `/pm set read` · `/config set \u003cpath\u003e \u003cvalue\u003e` | Permissions · whitelisted config |\n\n## Multi-agent orchestration \u0026 MCP\n\nThe current session acts as the coordinator; delegated subtasks (`/dg`, `/tasks`,\n`/task approve`) run as independent worker sessions and need human confirmation by\ndefault. External MCP hosts such as Codex or Claude Code can drive xacpx's\norchestration directly by configuring `xacpx mcp-stdio` as a stdio MCP server\n(`delegate_request` / `delegate_batch` support MCP Tasks).\n\n- When to delegate vs. open a parallel group: [xacpx-group-usage-guide.md](./docs/xacpx-group-usage-guide.md)\n- External MCP setup, identity rules, tool list, troubleshooting: [external-mcp.md](./docs/external-mcp.md)\n\n## Common scenarios\n\n```text\n# Keep watching a local project from your phone\n/ss codex -d /absolute/path/to/backend\ntake a look at today's API timeout issue\n\n# Switch between two projects in the same chat\n/ss codex -d /absolute/path/to/backend\n/ss new codex -d /absolute/path/to/frontend\n/ss\n/use backend:codex\n\n# Attach to an existing local Codex native session\n/ssn codex -d /absolute/path/to/backend\n/ssn 1\n```\n\n## Self-hosted relay hub (optional)\n\nIf you run several xacpx instances and want to drive them all from one browser dashboard, you can self-host the **relay hub**. Each instance dials out to the hub over WebSocket and registers; you log in to a multi-tenant web dashboard and manage every instance's sessions — chat, scheduled tasks, and orchestration — from one place. The hub ships as an npm package (`@ganglion/xacpx-relay`) with the dashboard **bundled in**, served on a single port, with a single **access token** for both web login and connector pairing.\n\n```bash\nnpm i -g @ganglion/xacpx-relay\nxacpx-relay add token        # prints the access token once\nxacpx-relay start            # defaults: --host 0.0.0.0 --http-port 8787\n\n# On each instance host:\nxacpx plugin add @ganglion/xacpx-channel-relay   # requires xacpx \u003e= 0.11.0\nxacpx channel add relay --url wss://relay.example.com --token \u003caccess-token\u003e --name my-box\nxacpx restart\n```\n\nFull walkthrough — pairing, TLS/reverse-proxy, systemd, backups, troubleshooting: **[Self-Hosting the Relay Hub](https://gadzan.github.io/xacpx/guide/relay-self-hosting)** (or [relay-deployment.md](./docs/relay-deployment.md) for the terse runbook).\n\n## Config and runtime files\n\n- Config file: `~/.xacpx/config.json`\n- State file: `~/.xacpx/state.json`\n- Runtime log: `~/.xacpx/runtime/app.log`\n\nMore runtime files are placed under `~/.xacpx/runtime/`. For the full config field reference, see [config-reference.md](./docs/config-reference.md).\n\n## Running from source\n\n```bash\nbun install\nbun run login\nbun run dev\n```\n\nFor development, debugging, and contribution details, see [developments.md](./docs/developments.md).\n\n## More docs\n\n**Install \u0026 configure**\n- [channel-management.md](./docs/channel-management.md) — configure WeChat / Feishu / Yuanbao / third-party channels\n- [plugin-development.md](./docs/plugin-development.md) — write your own channel plugin\n- [config-reference.md](./docs/config-reference.md) — full config field reference\n- [config-command.md](./docs/config-command.md) — change config from chat\n\n**Everyday use**\n- [cli-reference.md](./docs/cli-reference.md) — full terminal CLI reference\n- [commands.md](./docs/commands.md) — full chat-command reference\n- [later-command.md](./docs/later-command.md) — scheduled tasks (`/later`)\n- [native-sessions.md](./docs/native-sessions.md) — attach to a local agent's native session\n- [xacpx-group-usage-guide.md](./docs/xacpx-group-usage-guide.md) — when to delegate vs. open a group\n- [external-mcp.md](./docs/external-mcp.md) — external MCP coordinator integration\n\n**Troubleshoot \u0026 verify**\n- [faq.md](./docs/faq.md) — common questions (`/ss new` fails, `/mode \u003cid\u003e`, …)\n- [doctor-command.md](./docs/doctor-command.md) — `xacpx doctor` diagnostics and `--fix`\n- [testing.md](./docs/testing.md) — test layout and how to run tests\n\n**Develop \u0026 contribute**\n- [developments.md](./docs/developments.md) — develop, debug, or contribute from source\n- [code-wiki.md](./docs/code-wiki.md) — architecture map\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgadzan%2Fxacpx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgadzan%2Fxacpx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgadzan%2Fxacpx/lists"}