xacpx

Remotely drive Codex, Claude Code, and other acpx sessions from WeChat, Feishu, or Yuanbao.

English · 中文

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:

• Create and switch between sessions
• Have the agent keep working in a specific project directory
• View streaming replies, final results, and tool-call summaries
• Adjust permission policies
• Orchestrate multiple agents when needed

If 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.

Chat isn't the only entry point: xacpx also ships a self-hostable relay hub — a multi-tenant web dashboard that drives every one of your xacpx instances from a single browser tab (installable as a PWA on your phone).

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.

• Node.js 22.13+ or Bun
• A working agent CLI you intend to use, such as Codex / Claude Code / Gemini / OpenCode
• A phone with WeChat, Feishu, or Yuanbao installed

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.

npm install -g @ganglion/xacpx --registry=https://registry.npmjs.org
# or
bun add -g @ganglion/xacpx

xacpx login    # shows a QR code; scan it with WeChat
xacpx start    # start the background service

To use Feishu or Yuanbao instead of WeChat, see "Other channels" below first.

Send these messages in WeChat:

/ss codex -d /absolute/path/to/your/repo
/help

Then just send plain text:

hello

If everything works, plain text goes into the current session and the agent's reply comes back to WeChat.

WeChat 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.

# Feishu
xacpx plugin add @ganglion/xacpx-channel-feishu
xacpx channel add feishu     # enter appId/appSecret when prompted
xacpx restart

# Yuanbao
xacpx plugin add @ganglion/xacpx-channel-yuanbao
xacpx channel add yuanbao    # enter appKey/appSecret when prompted
xacpx restart

Full credentials, parameters, and management commands (enable/disable/rm): channel-management.md. To write your own channel plugin: plugin-development.md.

The most common sequence is just four steps:

1. Start the background service: xacpx start
2. Create or switch sessions: /ss ..., /use ...
3. Send plain text directly: any text not starting with / goes to the current session
4. Check status or cancel when needed: /status, /cancel

xacpx supports three reply modes (switch per session with /replymode):

• stream: stream back intermediate text
• final: return only the final result
• verbose: the default; streaming text plus tool-call summaries

For example, in verbose mode you'll see:

📖 sed -n '1,220p' README.md
🔍 rg -n 'session new' src tests
💻 bun test tests/unit/main.test.ts
✏️ Edit parse-command.ts

The essentials to get going. Full references: CLI → cli-reference.md, chat commands → commands.md.

Terminal (on the host):

Chat (in WeChat / Feishu / Yuanbao):

The current session acts as the coordinator; delegated subtasks (/dg, /tasks, /task approve) run as independent worker sessions and need human confirmation by default. External MCP hosts such as Codex or Claude Code can drive xacpx's orchestration directly by configuring xacpx mcp-stdio as a stdio MCP server (delegate_request / delegate_batch support MCP Tasks).

• When to delegate vs. open a parallel group: xacpx-group-usage-guide.md
• External MCP setup, identity rules, tool list, troubleshooting: external-mcp.md

# Keep watching a local project from your phone
/ss codex -d /absolute/path/to/backend
take a look at today's API timeout issue

# Switch between two projects in the same chat
/ss codex -d /absolute/path/to/backend
/ss new codex -d /absolute/path/to/frontend
/ss
/use backend:codex

# Attach to an existing local Codex native session
/ssn codex -d /absolute/path/to/backend
/ssn 1

If you run one or more xacpx instances and want to drive them from a browser instead of (or in addition to) chat, 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 from one place.

What you get:

• A three-pane IM-style dashboard — instance/session tree on the left, live chat in the middle, scheduled tasks & orchestration panel on the right. English + 中文 UI.
• Live streaming replies rendered as markdown, with tool-call and subagent activity inline; cancel running turns from the browser.
• Mobile-ready — installs as a PWA, so it feels like an app on your phone.
• One package, one port — @ganglion/xacpx-relay ships the dashboard bundled in; HTTP API, web socket, and instance gateway share a single port by default. SQLite storage via the built-in node:sqlite/bun:sqlite — no native addons to compile.
• Multi-tenant & token-based — every token is a user who only sees their own instances; tokens and credentials are stored hashed. Onboard teammates with single-use invite links (xacpx-relay add invite) instead of handing out tokens.

npm i -g @ganglion/xacpx-relay
xacpx-relay add token        # prints the access token once
xacpx-relay start            # defaults: --host 0.0.0.0 --http-port 8787

# On each instance host:
xacpx plugin add @ganglion/xacpx-channel-relay   # requires xacpx >= 0.17.0-beta.6
xacpx channel add relay --url wss://relay.example.com --token <access-token> --name my-box
xacpx restart

The same access token works for both web login and connector pairing. Full walkthrough — pairing, invites, TLS/reverse-proxy, systemd, backups, troubleshooting: Self-Hosting the Relay Hub (or relay-deployment.md for the terse runbook).

• Config file: ~/.xacpx/config.json
• State file: ~/.xacpx/state.json
• Runtime log: ~/.xacpx/runtime/app.log

More runtime files are placed under ~/.xacpx/runtime/. For the full config field reference, see config-reference.md.

bun install
bun run login
bun run dev

For development, debugging, and contribution details, see developments.md.

Install & configure

• channel-management.md — configure WeChat / Feishu / Yuanbao / third-party channels
• plugin-development.md — write your own channel plugin
• config-reference.md — full config field reference
• config-command.md — change config from chat

Everyday use

• cli-reference.md — full terminal CLI reference
• commands.md — full chat-command reference
• later-command.md — scheduled tasks (/later)
• native-sessions.md — attach to a local agent's native session
• xacpx-group-usage-guide.md — when to delegate vs. open a group
• external-mcp.md — external MCP coordinator integration

Troubleshoot & verify

• faq.md — common questions (/ss new fails, /mode <id>, …)
• doctor-command.md — xacpx doctor diagnostics and --fix
• testing.md — test layout and how to run tests

Develop & contribute

• developments.md — develop, debug, or contribute from source
• code-wiki.md — architecture map