{"id":50671991,"url":"https://github.com/gadzan/xacpx","last_synced_at":"2026-06-08T12:03:48.879Z","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-06-02T08:07:34.000Z","size":3179,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T08:12:24.595Z","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-06-02T08:07:26.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":55,"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":34061123,"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-06-08T02:00:07.615Z","response_time":111,"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-06-08T12:03:48.857Z","avatar_url":"https://github.com/gadzan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xacpx\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[![xacpx.png](https://s41.ax1x.com/2026/06/05/pmZXIv6.png)](https://imgchr.com/i/pmZXIv6)\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## Who it's for\n\n`xacpx` suits users who want lightweight, on-demand multi-agent work. You can watch tasks, send commands, and view results from WeChat, Feishu, or Yuanbao, and manage multiple sessions within the same chat.\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 [docs/native-sessions.md](./docs/native-sessions.md) for advanced details.\n\n## 5-minute quick start\n\n### Prerequisites\n\nBefore you start, you need at least:\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 to WeChat\n\n```bash\nxacpx login\n```\n\nThe terminal will show a QR code; scan it with WeChat to log in.\n\nIf you want to use Feishu or Yuanbao instead of WeChat, see \"Switch / add other channels\" below first.\n\n### Start the service\n\n```bash\nxacpx start\n```\n\n### Create your first session in WeChat\n\nSend these two messages in WeChat:\n\n```text\n/ss codex -d /absolute/path/to/your/repo\n/help\n```\n\nThen just send plain text, for example:\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### Switch / add 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, check the official plugin list first:\n\n```bash\nxacpx plugin known\n# Install: xacpx plugin add \u003cpackage\u003e\n```\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\nFor full credential configuration, parameters, and management commands such as `enable/disable/rm`, see [docs/channel-management.md](./docs/channel-management.md). If you want to write your own channel plugin, see [docs/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**: let the current session keep working\n4. **Check status or cancel the current task when needed**: `/status`, `/cancel`\n\n### 1) Create a session\n\nThe most common command:\n\n```text\n/ss codex -d /absolute/path/to/your/repo\n```\n\nIt uses `codex`, binds this working directory, and automatically switches to the new session.\n\n### 2) Send plain messages\n\nAny text not starting with `/` is sent to the current session.\n\n```text\nFix this recent API timeout issue\n```\n\n### 3) View replies\n\n`xacpx` supports three common reply modes:\n\n- `stream`: stream back intermediate text\n- `final`: return only the final result\n- `verbose`: the default; in addition to streaming text, also shows 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### 4) Switch sessions\n\n```text\n/ss\n/use backend:codex\n```\n\nThis lets you switch between sessions for different projects and different agents within the same WeChat chat.\n\n## Common CLI commands\n\nThese commands run in a terminal on your computer.\n\n| Command | Description |\n|------|------|\n| `xacpx login` | Log in to WeChat |\n| `xacpx logout` | Clear the WeChat login credentials saved on this machine |\n| `xacpx run` | Run in the foreground, useful for debugging |\n| `xacpx start` | Start the service in the background |\n| `xacpx status` | Show background status, PID, config path, and log path |\n| `xacpx stop` | Stop the background instance |\n| `xacpx restart` | Restart the background instance so channel config changes take effect |\n| `xacpx update [--all\\|\u003cname\u003e]` | Check and update xacpx and installed plugins; when plugins are installed, it interactively lets you choose what to update |\n| `xacpx channel list\\|show\\|add\\|rm\\|enable\\|disable [--account \u003cid\u003e]` | Manage message channels; `--account \u003cid\u003e` targets one bot when several share a channel (multi-bot) |\n| `xacpx plugin list\\|add\\|update\\|remove\\|enable\\|disable\\|doctor\\|known` | Manage plugins: list/install/update/remove, toggle, run `doctor`, or list official packages with `known` |\n| `xacpx plugin add @ganglion/xacpx-channel-feishu \u0026\u0026 xacpx channel add feishu` | Install and add the Feishu channel; prompts for Feishu app credentials |\n| `xacpx plugin add @ganglion/xacpx-channel-yuanbao \u0026\u0026 xacpx channel add yuanbao` | Install and add the Yuanbao channel; prompts for Yuanbao appKey/appSecret |\n| `xacpx doctor` | Run environment diagnostics |\n| `xacpx version` | Show the current version |\n| `xacpx agent list` | List agents registered on this machine |\n| `xacpx agent add \u003cname\u003e` | Add an agent from a built-in template; an existing agent of the same name with a different config is not overwritten |\n| `xacpx agent rm \u003cname\u003e` | Remove an agent |\n| `xacpx workspace list` | List workspaces registered on this machine |\n| `xacpx workspace add [name] [--raw]` | Register the current directory as a workspace; without `name`, uses the current directory name, and names with special characters are normalized automatically |\n| `xacpx workspace rm \u003cname\u003e` | Remove a workspace |\n| `xacpx later list` / `xacpx lt list` | List this machine's pending scheduled tasks in the terminal |\n| `xacpx later cancel \u003cid\u003e` / `xacpx lt cancel \u003cid\u003e` | Cancel a pending scheduled task in the terminal |\n\nThe first time you run `xacpx start` or `xacpx run`, if there are no sessions, workspaces, or plugins, the CLI asks whether to register the current directory as a workspace and lets you choose a built-in agent template; after the service starts, it creates the initial acpx session through the normal session-creation flow.\n\n`workspace` can also be abbreviated as `ws`:\n\n```bash\nxacpx ws add\nxacpx ws list\nxacpx ws rm backend\n```\n\n### How to use the `workspace` CLI\n\n`xacpx workspace` maintains the `workspaces` config in `~/.xacpx/config.json` on your local machine. It's good for registering frequently used project directories in the terminal first, then referencing them directly in WeChat with `--ws \u003cname\u003e`.\n\n| Command | Description |\n|------|------|\n| `xacpx workspace list` | List registered workspaces and their paths |\n| `xacpx workspace add` | Register the current directory as a workspace, defaulting the name to the current directory name (normalized automatically) |\n| `xacpx workspace add \u003cname\u003e` | Register the current directory under a specific name (normalized if it contains special characters) |\n| `xacpx workspace add [name] --raw` | Keep the original name (including spaces, etc.); later commands must quote it |\n| `xacpx workspace rm \u003cname\u003e` | Remove a specific workspace |\n\nCommon usage:\n\n```bash\ncd /absolute/path/to/backend\nxacpx workspace add backend\n\ncd /absolute/path/to/frontend\nxacpx ws add frontend\n\nxacpx ws list\nxacpx ws rm frontend\n```\n\nOnce registered, you can use it directly in WeChat:\n\n```text\n/ss codex --ws backend\n/ss new claude --ws frontend\n```\n\nNote: `workspace add` always registers the **directory the terminal is currently in**. Without a name, it uses the current directory name as the workspace name. Names containing spaces, Chinese characters, etc. are normalized automatically to `[a-zA-Z0-9._-]+` (for example, the directory `My Project` is saved as `My-Project`), with `-2`, `-3` appended on collisions. To keep the original name, add `--raw`; afterwards `xacpx workspace rm`, `/ws rm`, and `--ws \u003cname\u003e` all need quoting, for example `xacpx workspace rm \"My Project\"`.\n\n### How to use the `agent` CLI\n\n`xacpx agent` maintains the `agents` config in `~/.xacpx/config.json` on your local machine; `agents` is an equivalent alias.\n\n| Command | Description |\n|------|------|\n| `xacpx agent list` | List registered agents |\n| `xacpx agent templates` | List the built-in templates you can add |\n| `xacpx agent add \u003cname\u003e` | Add an agent from a built-in template, e.g. `kimi`, `opencode` |\n| `xacpx agent rm \u003cname\u003e` | Remove a specific agent |\n\nCommon usage:\n\n```bash\nxacpx agent templates\nxacpx agent add kimi\nxacpx agents list\nxacpx agent rm kimi\n```\n\n### How to use `doctor`\n\n```bash\nxacpx doctor\nxacpx doctor --verbose\nxacpx doctor --smoke\nxacpx doctor --smoke --agent codex --workspace backend\n```\n\nNotes:\n\n- `--verbose` expands the details of each check\n- `--smoke` additionally runs a minimal real transport-level prompt check\n- `--agent` / `--workspace` only affect `--smoke`\n- Without `--smoke`, the related checks show as `SKIP`\n\n### How to use `update`\n\n`xacpx update` checks for and installs new versions of xacpx itself and your installed channel plugins.\n\n```bash\nxacpx update            # interactive: pick what to update\nxacpx update --all      # update everything (core + all plugins) non-interactively\nxacpx update \u003cname\u003e     # update a single target (the core, or a specific plugin package)\n```\n\nNotes:\n\n- When plugins are installed, the bare `xacpx update` is interactive and lets you choose which targets to update.\n- In a non-interactive environment, updating the core or plugins needs explicit confirmation: use `xacpx update --all`, or name the target with `xacpx update \u003cname\u003e`.\n- `update` covers the core package and channel plugins; to manage a single plugin's version directly, see `xacpx plugin update \u003cname\u003e` ([docs/plugin-development.md](./docs/plugin-development.md)).\n- After updating, run `xacpx restart` so a running daemon loads the new version.\n- Cross-package rename migration: this project was renamed `weacpx` → `xacpx`. If you still have the legacy `weacpx` package installed, running `weacpx update` will offer to migrate you across to `xacpx` automatically (you confirm the switch). Already on `xacpx`? Just use `xacpx update` as a normal self-update.\n\n## Common chat commands\n\nThese commands are sent in a WeChat or Feishu chat. For the full command reference, see [docs/commands.md](./docs/commands.md).\n\n### Agent management\n\nThe default config usually already includes `codex` and `claude`. If you want to use another acpx-supported agent, you can add it from a built-in template with `/agent add \u003cname\u003e`.\n\n| Command | Description |\n|------|------|\n| `/agents` | List agents |\n| `/agent add gemini` | Add the `Gemini` agent |\n| `/agent add opencode` | Add the `OpenCode` agent |\n| `/agent rm \u003cname\u003e` | Remove an agent |\n\nThe current built-in templates align with acpx's built-in agents:\n\n```text\ncodex, claude, pi, openclaw, gemini, cursor, copilot, droid,\nfactory-droid, factorydroid, iflow, kilocode, kimi, kiro,\nopencode, qoder, qwen, trae\n```\n\nThese templates only write `driver`; the actual launch command is resolved by acpx. For example, `/agent add kimi` saves `{ \"driver\": \"kimi\" }`. For full command docs see [docs/commands.md](./docs/commands.md), and for config fields see [docs/config-reference.md](./docs/config-reference.md).\n\n### Workspace management\n\n| Command | Description |\n|------|------|\n| `/workspaces` / `/workspace` / `/ws` | List workspaces |\n| `/ws new \u003cname\u003e -d \u003cpath\u003e [--raw]` | Add a workspace; `path` is an absolute path on your computer, and Windows does not distinguish forward/back slashes; names with special characters such as spaces/Chinese are normalized automatically, and --raw keeps the original name |\n| `/workspace rm \u003cname\u003e` | Remove a workspace |\n\n### Sessions\n\n| Command | Description |\n|------|------|\n| `/sessions` / `/session` / `/ss` | List sessions |\n| `/ss \u003cagent\u003e (-d \u003cpath\u003e \\| --ws \u003cname\u003e)` | Create or reuse your current most-used session |\n| `/ss new \u003cagent\u003e (-d \u003cpath\u003e \\| --ws \u003cname\u003e)` | Force-create a new session |\n| `/ssn \u003cagent\u003e (-d \u003cpath\u003e \\| --ws \u003cname\u003e)` | Attach to an existing native session of a local agent; see [native sessions](./docs/native-sessions.md) |\n| `/use \u003calias\u003e` | Switch the current session |\n| `/status` | Show the current session status |\n| `/mode` / `/mode \u003cid\u003e` | View or set the underlying `acpx` mode |\n| `/replymode` | Show the current reply mode |\n| `/replymode stream` | Streaming replies |\n| `/replymode verbose` | Streaming + tool-call summaries |\n| `/replymode final` | Return only the final result |\n| `/replymode reset` | Fall back to the global default reply mode |\n| `/session reset` | Reset the current session context |\n| `/clear` | Shortcut alias for `/session reset` |\n| `/cancel` / `/stop` | Stop the current task |\n\nWe suggest remembering these three first:\n\n```text\n/ss codex -d /absolute/path/to/repo\n/use \u003calias\u003e\n/cancel\n```\n\nTo attach to an existing native session of a local agent such as Codex, use `/ssn codex -d /absolute/path/to/repo`; for full semantics see [docs/native-sessions.md](./docs/native-sessions.md).\n\n### Scheduled tasks (/later)\n\nHave the agent automatically receive a message at some point in the future. **By default it runs in a temporary session created just for that task** (inheriting the agent and workspace of the current session at creation time, with a fresh conversation history, destroyed once finished); adding `--bind` sends it to the current session bound at creation time. When the time comes, the message is delivered as a normal prompt and the result is pushed back to the original chat.\n\n| Command | Description |\n|------|------|\n| `/lt \u003ctime\u003e \u003cmessage\u003e` | Create a scheduled task (runs in a temporary session by default; `/later` is a synonym) |\n| `/lt --bind \u003ctime\u003e \u003cmessage\u003e` | Send to the current session instead |\n| `/lt list` | List globally pending tasks |\n| `/lt cancel \u003cid\u003e` | Cancel a pending task |\n\nThe most common examples:\n\n```text\n/lt in 2h check whether CI passes        # temporary session (default)\n/lt --bind tomorrow 09:00 review the PR    # bound to the current session\n/lt list\n```\n\nNotes:\n\n- Runs in a temporary session by default; `--bind` binds to the current session. The default mode can be changed via the config `later.defaultMode` (`temp` / `bind`, default `temp`)\n- Only one-time tasks are supported; the time must be more than 10 seconds and within 7 days from now\n- The time format is a fixed whitelist (relative time / today·tomorrow·day-after-tomorrow / weekday + time); natural language is not supported\n- In normal conversation, the agent can also create, list, and cancel scheduled tasks via the current session's internal tools (`scheduled_create` / `scheduled_list` / `scheduled_cancel`); routing and permissions are resolved by the daemon from the current chat session, and the external `mcp-stdio` does not expose these tools\n- You can also manage pending tasks from the terminal with `xacpx later list` / `xacpx later cancel \u003cid\u003e`; the CLI only lists and cancels, it does not create scheduled tasks\n- For full time formats, temporary/bound modes, task status, and limits, see [docs/later-command.md](./docs/later-command.md)\n\n### Config and permissions\n\n| Command | Description |\n|------|------|\n| `/config` | Show the config paths that can be changed via chat commands |\n| `/config set \u003cpath\u003e \u003cvalue\u003e` | Change a whitelisted config item |\n| `/pm` / `/permission` | Show the current permission mode |\n| `/pm set allow` | Switch to `approve-all` |\n| `/pm set read` | Switch to `approve-reads` |\n| `/pm set deny` | Switch to `deny-all` |\n| `/pm auto` | Show the current non-interactive permission policy |\n| `/pm auto deny` | Switch to `deny` |\n| `/pm auto fail` | Switch to `fail` |\n\nThe most common examples:\n\n```text\n/config set wechat.replyMode final\n/pm set read\n/pm auto deny\n```\n\n\u003e `/config set language en` (or `zh`) switches the xacpx interface language; it otherwise follows your system locale. See [docs/config-reference.md](./docs/config-reference.md).\n\n### Multi-agent orchestration\n\nThe README keeps only the most common user-facing commands.\n\n| Command | Description |\n|------|------|\n| `/dg \u003cagent\u003e \u003ctask\u003e` | Quickly delegate a subtask |\n| `/tasks` | List tasks under the current main line |\n| `/task \u003cid\u003e` | Show details of a single task |\n| `/task approve \u003cid\u003e` | Approve a `needs_confirmation` task |\n| `/task cancel \u003cid\u003e` | Cancel a task; cancelling a not-yet-approved task is equivalent to rejecting it |\n\nThe most common examples:\n\n```text\n/dg claude review the 3 high-risk points of the current plan\n/tasks\n/task approve task_123\n```\n\nNotes:\n\n- The current session is the coordinator session\n- What gets delegated out are independent subtask sessions\n- Delegation requests initiated by the agent require human confirmation by default\n- If you're using an external MCP host (Codex / Claude Code), use `delegate_batch` to dispatch multiple parallel subtasks at once: pass a `tasks` array, a group is created automatically under the hood, and all results are injected back at once with no need to maintain a groupId manually\n\nIf you want to first understand when to delegate and when to dispatch multiple subtasks in parallel, see:\n\n- [docs/xacpx-group-usage-guide.md](./docs/xacpx-group-usage-guide.md)\n\n\n### MCP integration: external coordinator\n\nIf you want external MCP hosts such as Codex or Claude Code to use xacpx's multi-agent orchestration directly, you can configure `xacpx mcp-stdio` as a stdio MCP server.\n\n`delegate_request` supports MCP Tasks: a host that supports this capability can make the delegation request return a native task handle immediately, then get status, results, or cancel the task via `tasks/get` / `tasks/result` / `tasks/cancel`; the worker's `[PROGRESS] ...` output shows up in the `statusMessage` of `tasks/get` / `tasks/list`; in the `input_required` state, `tasks/result` returns a next-step hint and ends this result stream rather than blocking for a long time; after the client calls tools such as `task_get` / `task_approve` / `coordinator_answer_question` per the hint, it continues polling `tasks/get` / `tasks/result`. A host that does not support MCP Tasks can still use the compatibility tools `task_get` / `task_list` / `task_watch` / `task_cancel`.\n\nThe natural-language creation tool for scheduled tasks is an internal capability of the xacpx current session and does not appear in the external `xacpx mcp-stdio` tool list.\n\nStart the daemon first:\n\n```bash\nxacpx start\n```\n\nWe recommend keeping the MCP config simple and not binding a workspace in the launch arguments:\n\n```json\n{\n  \"mcpServers\": {\n    \"xacpx\": {\n      \"command\": \"xacpx\",\n      \"args\": [\"mcp-stdio\"]\n    }\n  }\n}\n```\n\nWhen an external host calls `delegate_request`, pass `workingDirectory`, and xacpx will make the delegated worker work in that directory:\n\n```json\n{\n  \"targetAgent\": \"claude\",\n  \"task\": \"review the risks of this change\",\n  \"workingDirectory\": \"/absolute/path/to/your/repo\"\n}\n```\n\nOn Windows, if the MCP host won't resolve a `command` with arguments for you, put `node.exe` in `command` and the xacpx script and arguments in `args`:\n\n```json\n{\n  \"type\": \"stdio\",\n  \"command\": \"C:\\\\Program Files\\\\nodejs\\\\node.exe\",\n  \"args\": [\n    \"C:\\\\path\\\\to\\\\xacpx\\\\dist\\\\cli.js\",\n    \"mcp-stdio\"\n  ]\n}\n```\n\nFor more identity rules, `workingDirectory` semantics, the tool list, flow diagrams, and troubleshooting, see [docs/external-mcp.md](./docs/external-mcp.md).\n\n## Common scenarios\n\n### Keep watching a local project from your phone\n\n```text\n/ss codex -d /absolute/path/to/backend\ntake a look at today's API timeout issue\n```\n\n### Switch between two projects in the same chat\n\n```text\n/ss codex -d /absolute/path/to/backend\n/ss new codex -d /absolute/path/to/frontend\n/ss\n/use backend:codex\n/use frontend:codex\n```\n\n### Attach to an existing local Codex native session\n\n```text\n/ssn codex -d /absolute/path/to/backend\n/ssn 1\n```\n\nFor more filtering, aliases, and troubleshooting, see [docs/native-sessions.md](./docs/native-sessions.md).\n\n## Config and runtime files\n\nDefault file locations:\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/`.\n\n## FAQ\n\n### What if `/ss new` fails?\n\nIf session creation fails in WeChat, the most common cause is not a wrong `xacpx` command format, but that the underlying session was not created successfully.\n\nYou can try these two steps first:\n\n1. Confirm in the terminal that the current project directory and the agent itself work\n2. If you're familiar with `acpx`, manually create a session first, then attach to it from WeChat\n\nFor example, you can create a session locally first:\n\n```bash\n./node_modules/.bin/acpx --verbose --cwd /absolute/workspace/path codex sessions new --name existing-demo\n```\n\nThen attach to it from WeChat:\n\n```text\n/ss attach demo -a codex --ws backend --name existing-demo\n```\n\n### What is the `\u003cid\u003e` in `/mode \u003cid\u003e`?\n\nThe valid values for `/mode` depend on the agent you're currently using; `xacpx` does not normalize these values for you.\n\nCurrently the more clearly known values are:\n\n- `codex`: `plan`\n- `cursor`: `agent`, `plan`, `ask`\n\nIf you're unsure whether a value works, check the corresponding agent's docs first; if you get it wrong, you'll usually get an error such as an invalid argument.\n\n## Running from source\n\nIf you're using the repo source directly:\n\n```bash\nbun install\nbun run login\nbun run dev\n```\n\n## More docs\n\nIf what you're about to do is one of the following, you can continue from here:\n\n### Installation and configuration\n\n- Want to configure WeChat, Feishu, Yuanbao, or a third-party plugin channel: [docs/channel-management.md](./docs/channel-management.md)\n- Want to write your own channel plugin: [docs/plugin-development.md](./docs/plugin-development.md)\n- Want the full config field reference: [docs/config-reference.md](./docs/config-reference.md)\n- Want to change config from WeChat: [docs/config-command.md](./docs/config-command.md)\n\n### Everyday use\n\n- Want the full chat-command reference: [docs/commands.md](./docs/commands.md)\n- Want to schedule a one-time future message with scheduled tasks (`/later`): [docs/later-command.md](./docs/later-command.md)\n- Want to understand when to delegate and when to open a group: [docs/xacpx-group-usage-guide.md](./docs/xacpx-group-usage-guide.md)\n\n### Troubleshooting and verification\n\n- Want to run tests or understand the test layout: [docs/testing.md](./docs/testing.md)\n\n### Development and contribution\n\n- Want to develop, debug, or contribute from source: [docs/developments.md](./docs/developments.md)\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"}