@n1creator/openacp-cli 2026.712.11 → 2026.712.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +126 -329
  2. package/dist/cli.js +15 -16
  3. package/dist/cli.js.map +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,426 +1,223 @@
1
- OpenACP — self-hosted bridge that connects 28+ AI coding agents (Claude Code, Codex, Gemini, Cursor) to chat, REST, and SSE, with native bridge-agnostic speech-to-text. Your machine, your keys, your data.
2
-
3
1
  <div align="center">
4
2
 
5
3
  # OpenACP
6
4
 
7
- **Control AI coding agents from Telegram, Discord & Slack — or automate them through REST and SSE**
5
+ **Run AI coding agents from chat, automation, or your own integration.**
8
6
 
9
- Send a message. The agent writes code. You see everything — in real time.
7
+ Self-hosted sessions for Codex, Cursor, Claude Code, Gemini, and other ACP agents — with native speech-to-text, scoped proxy routing, and real-time control from Telegram, Discord, Slack, REST, or SSE.
10
8
 
11
9
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
12
10
  [![Node.js >= 20](https://img.shields.io/badge/Node.js-%3E%3D%2020-green.svg)](https://nodejs.org/)
13
11
  [![ACP Protocol](https://img.shields.io/badge/Protocol-ACP-purple.svg)](https://agentclientprotocol.org/)
14
12
  [![npm](https://img.shields.io/npm/v/@n1creator/openacp-cli.svg)](https://www.npmjs.com/package/@n1creator/openacp-cli)
15
- [![Twitter Follow](https://img.shields.io/twitter/follow/openacp_ai?style=social)](https://x.com/openacp_ai)
16
13
 
17
- [Documentation](https://openacp.gitbook.io/docs) · [Quick Start](#quick-start) · [Features](#features) · [Agents](#supported-agents) · [Contributing](CONTRIBUTING.md) · [Discussions](https://github.com/an1creator/OpenACP/discussions)
14
+ [Quick Start](#quick-start) · [Capabilities](#capabilities) · [Agents](#agents) · [Documentation](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook) · [Contributing](CONTRIBUTING.md)
18
15
 
19
- <img src="docs/images/banner.jpg" alt="OpenACP — Control AI coding agents from Telegram, Discord and Slack" width="100%" />
16
+ <img src="docs/images/banner.jpg" alt="OpenACP — control AI coding agents from messaging and automation clients" width="100%" />
20
17
 
21
18
  </div>
22
19
 
23
- ---
24
-
25
- > **N1 Creator distribution.** This repository publishes the maintained fork as
26
- > `@n1creator/openacp-cli` and `@n1creator/openacp-plugin-sdk`. Existing OpenACP
27
- > workspaces remain compatible; migrate by replacing the global CLI package and
28
- > restarting the same instance. The maintained CLI includes native local
29
- > faster-whisper STT and keeps the speech pipeline independent from any one
30
- > messaging adapter.
31
-
32
- ## What is OpenACP?
20
+ OpenACP runs on your machine and connects messaging or API clients to local ACP agent processes. It owns session lifecycle, permissions, streaming, files, speech, and routing; the selected agent works in your configured workspace with its own provider credentials.
33
21
 
34
- OpenACP is a self-hosted bridge that connects AI coding agents to messaging and automation channels. Chat through Telegram, Discord, or Slack, or send prompts and attachments through REST/SSE — the agent reads your codebase, writes code, runs commands, and streams results back in real time.
22
+ > **N1 Creator distribution.** This repository is the maintained
23
+ > [`an1creator/OpenACP`](https://github.com/an1creator/OpenACP) fork. Its public
24
+ > packages are [`@n1creator/openacp-cli`](https://www.npmjs.com/package/@n1creator/openacp-cli)
25
+ > and [`@n1creator/openacp-plugin-sdk`](https://www.npmjs.com/package/@n1creator/openacp-plugin-sdk).
35
26
 
36
- Built on the open [Agent Client Protocol (ACP)](https://agentclientprotocol.org/). Your machine, your keys, your data.
37
-
38
- ```
39
- You (Telegram / Discord / Slack / REST / SSE)
40
- ↓
41
- OpenACP (bridge + session manager + speech service)
42
- ↓
43
- AI Agent (Claude Code, Codex, Gemini, Cursor, ...)
44
- ↓
45
- Your Codebase
27
+ ```text
28
+ Telegram / Discord / Slack / REST / SSE
29
+ ↓
30
+ OpenACP session bridge
31
+ ├─ permissions and streaming
32
+ ├─ speech and file handling
33
+ └─ scoped network routing
34
+ ↓
35
+ Codex / Cursor / Claude / Gemini / ACP agent
36
+ ↓
37
+ Your workspace
46
38
  ```
47
39
 
48
- ## Why OpenACP?
49
-
50
- | Without OpenACP | With OpenACP |
51
- |----------------|-------------|
52
- | *"Its usage is currently focused on its dedicated terminal REPL and specific IDE integrations"* | Control from Telegram, Discord, or Slack — any device, anywhere |
53
- | *"Codex Desktop App only works with local projects. It does not support development on remote hosts"* | Full remote development support — run agents on your server, manage from your phone |
54
- | *"There's no way to trigger Claude Code sessions from external issue trackers"* | REST API for CI/CD integration and external triggers |
55
- | *"Being able to use a proper mobile app UI would be much better than having to access sessions through ssh + tmux"* | Native Telegram/Discord UI — no SSH, no terminal on mobile |
56
- | *"Cline is really burning up OpenRouter tokens and my wallet"* | Built-in usage tracking and monthly budget limits per session |
57
-
58
- ## Use Cases
59
-
60
- - **Remote coding** — Tired of being chained to your desk to run Claude Code? Review PRs, fix bugs, and deploy from your phone via Telegram while away from your desk.
61
- - **Team visibility** — Share a Discord channel where everyone sees what the AI agent is doing in real time — no more black-box coding sessions.
62
- - **Multi-agent workflows** — Start with Claude Code for planning, switch to Codex for implementation, use Gemini for review — all in one chat thread, no reconfiguration.
63
- - **CI/CD integration** — Trigger agent sessions from GitHub Actions or any issue tracker via the REST API.
64
- - **Voice-driven workflows** — Send audio from any compatible bridge; OpenACP transcribes it locally before the agent receives the prompt.
65
- - **Self-hosted AI gateway** — Keep API keys and code on your own infrastructure. No third-party cloud, no vendor lock-in.
66
- - **Local LLM support** — Run agents against self-hosted models (Ollama, LM Studio) via ACP-compatible adapters. Your models, your data.
67
-
68
40
  <div align="center">
69
41
  <table>
70
42
  <tr>
71
- <td align="center"><img src="docs/images/menu.png" width="250" alt="OpenACP control panel showing session management, agent selection, and settings menu in Telegram" /><br /><b>Control Panel</b><br />Manage sessions, agents, and settings</td>
72
- <td align="center"><img src="docs/images/agent-working.png" width="250" alt="AI coding agent reading files, planning changes, and writing code through OpenACP Telegram interface" /><br /><b>Agent at Work</b><br />Plans, reads files, writes code</td>
43
+ <td align="center"><img src="docs/images/menu.png" width="250" alt="OpenACP control panel in Telegram" /><br /><b>Control Panel</b><br />Sessions, agents, and settings</td>
44
+ <td align="center"><img src="docs/images/agent-working.png" width="250" alt="An AI coding agent working through OpenACP" /><br /><b>Agent at Work</b><br />Plans, tools, and output in real time</td>
73
45
  </tr>
74
46
  <tr>
75
- <td align="center"><img src="docs/images/tool-calls.png" width="250" alt="Real-time tool call streaming showing agent actions like file reads, edits, and command execution" /><br /><b>Real-time Tool Calls</b><br />See every action the agent takes</td>
76
- <td align="center"><img src="docs/images/skills.png" width="250" alt="OpenACP agent skills menu with options for brainstorming, TDD, debugging, and code review" /><br /><b>Agent Skills</b><br />Brainstorming, TDD, debugging & more</td>
47
+ <td align="center"><img src="docs/images/tool-calls.png" width="250" alt="Real-time tool calls in OpenACP" /><br /><b>Tool Calls</b><br />Review actions as they happen</td>
48
+ <td align="center"><img src="docs/images/skills.png" width="250" alt="Agent skills in OpenACP" /><br /><b>Agent Skills</b><br />Reusable coding workflows</td>
77
49
  </tr>
78
50
  </table>
79
51
  </div>
80
52
 
81
- ## Installation
82
-
83
- **Requirements:** Node.js 20+ (the installer handles this for you)
53
+ ## Quick Start
84
54
 
85
- ### macOS
55
+ **Requirement:** Node.js 20 or newer.
86
56
 
87
57
  ```bash
88
- curl -fsSL https://raw.githubusercontent.com/an1creator/OpenACP/main/scripts/install.sh | bash
58
+ npm install -g @n1creator/openacp-cli
59
+ openacp
89
60
  ```
90
61
 
91
- ### Linux
62
+ The first run opens an interactive setup wizard. Choose one or more connectors, provide their credentials, select a workspace and default agent, then choose foreground or daemon mode.
92
63
 
93
64
  ```bash
94
- curl -fsSL https://raw.githubusercontent.com/an1creator/OpenACP/main/scripts/install.sh | bash
65
+ openacp doctor # validate the installation
66
+ openacp status # inspect the running instance
67
+ openacp logs # follow daemon logs
95
68
  ```
96
69
 
97
- > Works on Debian/Ubuntu, Fedora/RHEL, Arch, and other distros. Also supports WSL (Windows Subsystem for Linux).
70
+ Platform-specific setup is in the maintained [Telegram](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/platform-setup/telegram.md), [Discord](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/platform-setup/discord.md), and [Slack](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/platform-setup/slack.md) guides.
98
71
 
99
- ### Windows
72
+ ## Capabilities
100
73
 
101
- Open PowerShell and run:
74
+ ### Agents and sessions
102
75
 
103
- ```powershell
104
- powershell -c "irm https://raw.githubusercontent.com/an1creator/OpenACP/main/scripts/install.ps1 | iex"
105
- ```
76
+ - Run modern Codex and Cursor ACP processes alongside Claude Code, Gemini CLI, and other ACP-compatible agents.
77
+ - Read model, mode, and reasoning choices from each agent at runtime instead of maintaining a hard-coded model list.
78
+ - Keep one persistent session per topic, thread, or API session; resume it after process restarts.
79
+ - Switch agents with `/switch`, transfer work between terminal and chat with `/handoff`, and cancel safely with `/cancel`.
80
+ - Review permission requests through connector controls or configure narrowly scoped approval behavior.
106
81
 
107
- > Requires PowerShell 5.1+ (built into Windows 10/11).
82
+ ### Connectors and automation
108
83
 
109
- ### Manual install via npm
84
+ | Interface | Session mapping | Highlights |
85
+ |-----------|-----------------|------------|
86
+ | Telegram | Forum topics | Commands, buttons, streaming, files, voice |
87
+ | Discord | Threads | Commands, interactions, files, streaming |
88
+ | Slack | Channels and threads | Socket Mode, commands, files, streaming |
89
+ | REST + SSE | API session IDs | Automation, attachments, live event streams |
110
90
 
111
- If you do not have Node.js yet, install it first. For example, on macOS or Linux with `nvm`:
91
+ The core session pipeline is connector-neutral. An external adapter gets the same session, attachment, speech, permission, and agent-routing behavior when it implements the standard adapter contract.
112
92
 
113
- ```bash
114
- curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
115
- export NVM_DIR="$HOME/.nvm"
116
- [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
117
- nvm install --lts
118
- nvm use --lts
119
- ```
93
+ ### Native speech-to-text
120
94
 
121
- Then install OpenACP with npm:
95
+ STT is a built-in OpenACP service, not Telegram-specific glue. Any compatible bridge can submit a standard `audio` attachment:
122
96
 
123
- ```bash
124
- npm install -g @n1creator/openacp-cli
125
- openacp
126
- # → Interactive setup wizard starts:
127
- # → ? Choose your platform: Telegram / Discord / Slack
128
- # → ? Enter your bot token: ********
129
- # → ? Select workspace directory: ~/projects
130
- # → ? Choose default AI agent: Claude Code
131
- # → ✓ Configuration saved. Starting OpenACP...
132
- # → 🚀 OpenACP is running. Send a message to your bot!
97
+ ```text
98
+ audio attachment
99
+ ├─ agent supports native audio → pass the original attachment
100
+ └─ otherwise → local faster-whisper or Groq STT → append transcript to prompt
133
101
  ```
134
102
 
135
- ---
136
-
137
- After installation, the **interactive setup wizard** walks you through everything:
138
-
139
- 1. Choose your platform (Telegram, Discord, Slack, or multiple)
140
- 2. Connect your bot (token validation + auto-detection)
141
- 3. Pick a workspace directory
142
- 4. Select your default AI agent
143
- 5. Choose run mode (foreground or daemon)
144
-
145
- That's it. Send a message to your bot and start coding.
146
-
147
- > **Need detailed setup for a specific platform?** See the [Platform Setup guides](https://openacp.gitbook.io/docs/platform-setup).
148
-
149
- ## Features
150
-
151
- ### Channels and Bridges
103
+ - `local-whisper` runs on the OpenACP host without an API key and reuses its environment and model cache.
104
+ - Groq provides an optional hosted STT path.
105
+ - Failed transcription preserves the original audio instead of silently dropping it.
106
+ - Providers and local model settings are available through plugin settings and the API.
152
107
 
153
- | Platform | Status | Highlights |
154
- |----------|--------|------------|
155
- | **Telegram** | Stable | Forum topics per session, streaming, permission buttons, voice |
156
- | **Discord** | Stable | Thread-based sessions, slash commands, button interactions |
157
- | **Slack** | Stable | Socket Mode, channel-based sessions, thread organization |
158
- | **REST API / SSE** | Stable | Session automation, base64 file/audio attachments, streamed events |
108
+ Local Whisper requires Python 3 and either `uv` or `python3-venv`; its runtime is prepared on first use. See [Voice and Speech](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/using-openacp/voice-and-speech.md).
159
109
 
160
- ### Core
110
+ ### Scoped proxy routing
161
111
 
162
- - **28+ AI agents** — Claude Code, Codex, Gemini, Cursor, Copilot, and [more](#supported-agents)
163
- - **Session management** — Each conversation gets its own thread/topic with auto-naming
164
- - **Session persistence** — Sessions survive restarts, with configurable TTL
165
- - **Permission control** — Approve or deny agent actions via buttons, with optional auto-approve
166
- - **Real-time streaming** — See agent thinking, tool calls, and output as they happen
167
- - **Agent switching** — Switch agents mid-conversation with `/switch`; history carries over automatically
168
- - **Dynamic model options** — Model, mode, and reasoning choices come from each ACP agent at runtime instead of a hard-coded model list
169
- - **Agent-aware audio routing** — Pass audio directly to agents that support it; otherwise transcribe it through the shared STT service
170
- - **Scoped proxy routing** — Route Telegram, individual ACP agents, services, or plugin flows independently through HTTP, HTTPS, SOCKS5, or SOCKS5H profiles
171
-
172
- ### Developer Tools
173
-
174
- - **Tunnel & port forwarding** — Expose local ports to the internet (Cloudflare, ngrok, bore, Tailscale)
175
- - **Built-in file viewer** — Monaco Editor with syntax highlighting, diffs, and markdown preview
176
- - **Session transfer** — Move sessions between terminal and chat (`/handoff`)
177
- - **Agent switch** — Change which AI agent handles your session mid-conversation (`/switch`)
178
- - **Voice & speech** — Bundled local faster-whisper or Groq STT for every compatible bridge, plus optional Edge TTS
179
- - **Usage tracking** — Token counts, cost reports, optional monthly budget limits
180
- - **Context resume** — Resume sessions with full conversation history
181
-
182
- ### Native Speech-to-Text Across Bridges
183
-
184
- The maintained package includes the `local-whisper` provider in the built-in
185
- `@openacp/speech` service. STT runs in the shared session pipeline rather than
186
- inside Telegram, so the same behavior applies to Telegram voice messages,
187
- REST/SSE audio attachments, and external adapters that submit a standard
188
- attachment with `type: "audio"`.
112
+ Proxy profiles describe endpoints; routes decide which traffic uses them. OpenACP supports **HTTP, HTTPS, SOCKS5, and SOCKS5H**, with independent scopes for channels, agents, services, and plugins.
189
113
 
190
114
  ```text
191
- audio attachment from any compatible bridge
192
- → agent supports native audio? send audio directly
193
- → otherwise: local faster-whisper or Groq STT
194
- → append transcript to the prompt and call the agent
115
+ global: direct
116
+ channels.telegram: profile:primary
117
+ agents.codex: profile:primary
118
+ agents.cursor: direct
119
+ services.default: direct
195
120
  ```
196
121
 
197
- - **Private local mode** — `local-whisper` runs on the OpenACP host with no API key.
198
- - **Bundled runtime** — The CLI ships the transcription script and reuses the model/venv cache at `~/.cache/codex/transcribe-voice`.
199
- - **Pluggable providers** — Select local Whisper or Groq, or register another STT provider through the plugin SDK.
200
- - **Safe fallback** — If transcription fails, OpenACP keeps the original audio attachment instead of discarding it.
201
- - **Audio-aware agents** — Agents advertising native audio capability receive the original attachment without unnecessary transcription.
122
+ - In Telegram, open **Settings → Proxy Management** or use `/proxy`; other connectors can expose the same connector-neutral command model.
123
+ - CLI and REST automation are available through `openacp proxy` and `/api/v1/proxy`.
124
+ - `direct` removes inherited proxy environment variables from the selected ACP process; `inherit` follows the parent scope.
125
+ - Credentials are write-only, stored separately in a mode-0600 secret store, and never returned in route or status data.
126
+ - Protected JSON imports accept a write-only **Quick URL** in `proxyUrl`; it requires an explicit port and is mutually exclusive with separate endpoint or credential fields.
127
+ - Telegram deletes credential replies before use; environments without that guarantee use protected CLI/API input files.
202
128
 
203
- Local Whisper needs Python 3 plus `uv` or `python3-venv`; its environment and
204
- selected model are prepared on the first transcription. Configure it through
205
- `/settings`, the plugin settings API, or `openacp config`. See
206
- [Voice and Speech](docs/gitbook/using-openacp/voice-and-speech.md) for settings,
207
- formats, providers, and troubleshooting.
129
+ See [Scoped Proxy Routing](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/features/proxy-routing.md) for route precedence, secure inputs, testing, and recovery.
208
130
 
209
- ### Scoped Proxy Routing
131
+ ### Operations and extension
210
132
 
211
- OpenACP can proxy only the flows that need it instead of exporting one proxy for
212
- the whole daemon. Profiles (where to connect) are separate from routes (what uses
213
- the profile), and every route is `direct`, `inherit`, or `profile:<id>`.
133
+ - Managed foreground or daemon lifecycle on Linux and macOS.
134
+ - REST API, SSE event stream, and JSON-capable CLI for automation.
135
+ - Health checks, structured logging, usage tracking, tunnels, and `openacp doctor` diagnostics.
136
+ - Plugin SDK and lifecycle for custom adapters, services, commands, and middleware.
214
137
 
215
- ```text
216
- global: direct
217
- channels.telegram: profile:usa
218
- agents.codex: profile:usa
219
- agents.cursor: direct
220
- services.default: direct
221
- ```
138
+ ## Agents
139
+
140
+ OpenACP uses ACP-compatible agent definitions and the public [ACP agent registry](https://agentclientprotocol.com/get-started/registry).
222
141
 
223
- Telegram polling, outgoing Bot API calls, and Telegram file downloads share the
224
- `channels.telegram` route. ACP subprocesses receive a per-agent environment;
225
- `direct` explicitly removes inherited proxy variables. Local REST/SSE traffic is
226
- not globally intercepted. Credentials live in a separate mode-0600 secret store
227
- and never appear in route files, agent definitions, status responses, or
228
- structured OpenACP logs.
229
-
230
- In Telegram, open **Settings → Proxy Management** or use `/proxy` directly.
231
- Both paths render the same connector-neutral proxy home; other adapters can use
232
- that `/proxy` command model too. CLI and REST automation remain available through
233
- `openacp proxy` and `/api/v1/proxy`. Channel changes are tested before they are
234
- saved. See [Scoped Proxy Routing](docs/gitbook/features/proxy-routing.md).
235
-
236
- ### Operations
237
-
238
- - **Daemon mode** — Run as a background service with auto-start on boot
239
- - **CLI API** — Full REST API for automation (`openacp api ...`)
240
- - **Fast first session** — A liveness-checked warm pool keeps the default agent ready, avoiding a full subprocess spawn on the first API session
241
- - **Consistent health reporting** — `/api/health` merges persisted and live-only sessions so active and total counts describe the same population
242
- - **Secret-safe agent inspection** — Agent list, reload, and detail API responses redact environment values while preserving variable names
243
- - **Plugin system** — Install adapters as npm packages
244
- - **Doctor diagnostics** — `openacp doctor` checks everything and suggests fixes
245
- - **Structured logging** — Pino with rotation, per-session log files
246
-
247
- > **Full feature documentation** — [Documentation](https://openacp.gitbook.io/docs)
248
-
249
- ## Supported Agents
250
-
251
- OpenACP uses the [ACP Registry](https://agentclientprotocol.com/get-started/registry) — new agents are available as soon as they're registered.
252
-
253
- | Agent | Type | Description |
254
- |-------|------|-------------|
255
- | [Claude Code](https://github.com/anthropics/claude-code) | npx | Anthropic's Claude coding agent |
256
- | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | npx | Google's Gemini CLI |
257
- | [Codex CLI](https://github.com/openai/codex) | npx | OpenAI's coding assistant |
258
- | [GitHub Copilot](https://github.com/github/copilot-cli) | npx | GitHub's AI pair programmer |
259
- | [Cursor](https://www.cursor.com/) | binary | Cursor's coding agent |
260
- | [Cline](https://github.com/cline/cline) | npx | Autonomous coding agent |
261
- | [goose](https://github.com/block/goose) | binary | Open source AI agent by Block |
262
- | Amp | binary | The frontier coding agent |
263
- | [Auggie CLI](https://www.augmentcode.com/) | npx | Augment Code's context engine |
264
- | [Junie](https://www.jetbrains.com/) | binary | AI coding agent by JetBrains |
265
- | [Kilo](https://github.com/kilocode/kilo) | npx | Open source coding agent |
266
- | [Qwen Code](https://github.com/QwenLM/qwen-code) | npx | Alibaba's Qwen assistant |
267
- | ...and more | | [Full registry →](https://agentclientprotocol.com/get-started/registry) |
142
+ | Agent | Integration |
143
+ |-------|-------------|
144
+ | [Codex CLI](https://github.com/openai/codex) | ACP process with runtime model, mode, and reasoning options |
145
+ | [Cursor](https://www.cursor.com/) | Local Cursor ACP process |
146
+ | [Claude Code](https://github.com/anthropics/claude-code) | ACP-compatible package process |
147
+ | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ACP-compatible package process |
148
+ | Other agents | Install or define another ACP-compatible process |
268
149
 
269
150
  ```bash
270
- openacp agents # Browse all agents
271
- openacp agents install <name> # Install from registry
151
+ openacp agents
152
+ openacp agents install <name>
272
153
  ```
273
154
 
274
- ## CLI Overview
155
+ Agent CLIs may require their own installation, account, or provider credentials.
156
+
157
+ ## CLI Reference
275
158
 
276
159
  ```bash
277
- # Server
278
- openacp # Start (first run = setup wizard)
279
- openacp start / stop / restart # Daemon management
280
- openacp status # Check daemon status
281
- openacp logs # Tail daemon logs
282
-
283
- # Configuration
284
- openacp config # Interactive config editor
285
- openacp reset # Re-run setup wizard
286
- openacp doctor # System diagnostics
287
-
288
- # Sessions & API (requires running daemon)
160
+ # Lifecycle
161
+ openacp
162
+ openacp start | stop | restart
163
+ openacp status
164
+ openacp doctor
165
+
166
+ # Sessions and local API
289
167
  openacp api new [agent] [workspace]
290
168
  openacp api status
291
- openacp api health
292
- openacp api cancel <id>
169
+ openacp api cancel <session-id>
293
170
 
294
- # Updates
295
- openacp update # Install the latest maintained npm release
296
-
297
- # Tunnels
298
- openacp tunnel add <port> [--label name]
299
- openacp tunnel list
300
-
301
- # Scoped proxy routing (requires running daemon)
171
+ # Scoped proxy routing
302
172
  openacp proxy status
303
- openacp proxy import usa --env-file ~/.openacp/secrets/proxy.env
304
- openacp proxy create backup --from-json ~/.openacp/secrets/backup-proxy.json
305
- openacp proxy update backup --from-json ~/.openacp/secrets/backup-proxy.json
306
- openacp proxy set channels.telegram profile:usa
307
- openacp proxy set agents.codex profile:usa
173
+ openacp proxy import primary --env-file ~/.openacp/secrets/proxy.env
174
+ openacp proxy set channels.telegram profile:primary
175
+ openacp proxy set agents.codex profile:primary
308
176
  openacp proxy test --scope channels.telegram
309
- ```
310
-
311
- The protected JSON file supports a Quick URL mode: use either separate
312
- `protocol`, `host`, and `port` fields or one write-only `proxyUrl` such as
313
- `{"proxyUrl":"socks5h://user:password@proxy.example:1080"}`. The two forms are
314
- mutually exclusive. A URL must include an explicit port; credentials are parsed
315
- and stored separately, and the original URL is never persisted or returned.
316
177
 
317
- The connector-neutral `/proxy` interface requires `network:proxy:manage` before
318
- showing status, profiles, routes, diagnostics, or tests. It provides add/edit,
319
- candidate test-before-save, credential clearing, paginated route controls, and
320
- atomic delete-with-reassignment. Telegram deletes credential replies before use;
321
- if that guarantee is unavailable, OpenACP refuses the value and directs the
322
- operator to a mode-0600 CLI/API input file.
323
-
324
- Use a unique Telegram bot for each OpenACP instance. Command synchronization has
325
- one heartbeat-backed owner per public bot ID and a second instance will not
326
- modify the first instance's command menus.
178
+ # Updates
179
+ openacp update
180
+ ```
327
181
 
328
- > **Full CLI reference** — [CLI Commands](https://openacp.gitbook.io/docs/api-reference/cli-commands)
182
+ The complete command contract is in [CLI Commands](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/api-reference/cli-commands.md).
329
183
 
330
184
  ## Documentation
331
185
 
332
- | Section | Description |
333
- |---------|-------------|
334
- | [Getting Started](https://openacp.gitbook.io/docs/getting-started) | What is OpenACP, quickstart for users & developers |
335
- | [Platform Setup](https://openacp.gitbook.io/docs/platform-setup) | Step-by-step guides for Telegram, Discord, Slack |
336
- | [Using OpenACP](https://openacp.gitbook.io/docs/using-openacp) | Commands, sessions, agents, permissions, voice |
337
- | [Self-Hosting](https://openacp.gitbook.io/docs/self-hosting) | Installation, configuration, daemon, security |
338
- | [Features](https://openacp.gitbook.io/docs/features) | Tunnel, context resume, usage tracking, and more |
339
- | [Extending](https://openacp.gitbook.io/docs/extending) | Plugin system, building adapters, contributing |
340
- | [API Reference](https://openacp.gitbook.io/docs/api-reference) | CLI commands, REST API, config schema, env vars |
341
- | [Troubleshooting](https://openacp.gitbook.io/docs/troubleshooting) | Common issues and FAQ |
186
+ | Area | Maintained reference |
187
+ |------|----------------------|
188
+ | Start and configure | [Getting Started](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/getting-started) · [Self-Hosting](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/self-hosting) |
189
+ | Connect clients | [Platform Setup](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/platform-setup) |
190
+ | Use sessions and commands | [Using OpenACP](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/using-openacp) |
191
+ | Speech, proxy, handoff | [Features](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/features) |
192
+ | CLI, REST, config, env | [API Reference](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/api-reference) |
193
+ | Build plugins and adapters | [Extending](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/extending) |
194
+ | Diagnose failures | [Troubleshooting](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/troubleshooting) |
342
195
 
343
- ## Known Limitations
196
+ ## Updating and Migration
344
197
 
345
- - **Early stage** — OpenACP is under active development; expect breaking changes between minor versions
346
- - **Single user** — Currently designed for individual use; multi-user/team support is planned
347
- - **Remote host** — Agents run on the same machine as OpenACP; to use on a remote server, install OpenACP on that server
348
- - **Agent availability** — Some agents require their own API keys and local installation
349
- - **Platform features** — Not all messaging platform features are supported equally (e.g., Slack threads vs Telegram forum topics)
350
- - **No Windows daemon** — Daemon mode (auto-start on boot) currently supports macOS and Linux only
351
-
352
- ## FAQ
353
-
354
- ### Why use Telegram or Discord instead of just the terminal?
355
- Most AI coding agents are locked to a terminal REPL or IDE. OpenACP lets you send messages, review code diffs, approve or deny actions, and monitor progress from any device — phone, tablet, or browser — without opening a laptop.
356
-
357
- ### How is OpenACP different from MCP?
358
- MCP (Model Context Protocol) is a standard for giving AI models access to tools and data sources. OpenACP uses the **Agent Client Protocol (ACP)** to manage full coding agent *sessions* — starting agents, streaming output, handling permissions, and routing results to your messaging platform. The two protocols are complementary: your agents can use MCP tools while OpenACP manages the session layer.
359
-
360
- ### Can I auto-approve agent actions?
361
- Yes. By default, OpenACP shows a permission button for destructive actions. You can configure [auto-approve rules](https://openacp.gitbook.io/docs/using-openacp) to skip confirmation for specific action types (e.g., read-only operations) while still requiring approval for file writes or shell commands.
362
-
363
- ### How do I control API spending?
364
- Set a monthly budget limit in your config. OpenACP tracks token usage and cost in real time and will pause the agent when the limit is reached. Run `openacp config` to set limits per session.
365
-
366
- ### Can I use a local or self-hosted LLM?
367
- Yes, if the model has a compatible agent CLI. Any agent that implements the ACP protocol can be registered. Community adapters exist for Ollama and LM Studio — run `openacp agents` to browse available options.
368
-
369
- ### Does speech input only work in Telegram?
370
- No. STT is part of the shared session pipeline. Telegram already converts voice and audio messages into standard audio attachments, while the REST API and SSE bridge accept base64 audio attachments. Any external adapter gets the same behavior when it submits an attachment with `type: "audio"`. If the selected agent supports native audio, OpenACP passes the audio through; otherwise it transcribes it with the configured STT provider.
371
-
372
- ### What happens if the agent gets stuck or the chat hangs?
373
- Use `/cancel` in your chat to stop the current session. Run `openacp doctor` to check for connectivity or configuration issues. OpenACP's session persistence means you can resume with full context intact after a restart.
374
-
375
- ### Does OpenACP send my code to the cloud?
376
- No. OpenACP runs entirely on your machine. AI agents connect directly to your chosen provider using your own API keys. Nothing is routed through OpenACP servers.
377
-
378
- ### Can I use multiple AI agents at the same time?
379
- Each session uses one agent, but you can run multiple sessions simultaneously — one per thread/topic in your chat. Switch agents between sessions or start a new session with a different agent at any time.
380
-
381
- ### Is OpenACP free?
382
- Yes. OpenACP is MIT-licensed and free to self-host. You only pay for the AI provider API keys you choose to use.
383
-
384
- ### How do I update OpenACP?
385
198
  ```bash
386
199
  openacp update
387
200
  ```
388
201
 
389
- On Telegram, administrators can also run `/update`; OpenACP waits for npm to
390
- finish and then requests a managed daemon restart. Do not run a second npm
391
- install or stop the service while that update is in progress.
392
-
393
- To migrate from the upstream npm package:
202
+ The managed updater installs the latest `@n1creator/openacp-cli` release and requests a daemon restart after npm finishes. To migrate an older global installation:
394
203
 
395
204
  ```bash
396
205
  npm uninstall -g @openacp/cli
397
206
  npm install -g @n1creator/openacp-cli@latest
398
- openacp --dir ~/openacp-workspace restart
207
+ openacp restart
399
208
  ```
400
209
 
401
- ## Security
402
-
403
- OpenACP grants AI agents access to your filesystem and shell. Before using in production:
210
+ See [Updating](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/self-hosting/updating.md) before changing a production instance.
404
211
 
405
- - Run in a sandboxed environment or container when possible
406
- - Review agent permissions — use the built-in permission gate to approve/deny actions
407
- - Never expose your OpenACP instance to the public internet without authentication
408
- - Keep your bot tokens secret — rotate them if compromised
409
- - See the [Security guide](https://openacp.gitbook.io/docs/self-hosting/security) for hardening recommendations
212
+ ## Security
410
213
 
411
- ## Star History
214
+ OpenACP grants selected agent processes access to configured workspaces and may allow shell or file operations. Keep connector tokens and provider credentials secret, review permission policy, avoid exposing the local API without authentication, and use process or container isolation where appropriate.
412
215
 
413
- <a href="https://star-history.com/#an1creator/OpenACP&Date">
414
- <picture>
415
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=an1creator/OpenACP&type=Date&theme=dark" />
416
- <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=an1creator/OpenACP&type=Date" />
417
- <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=an1creator/OpenACP&type=Date" />
418
- </picture>
419
- </a>
216
+ Follow the [Security guide](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/self-hosting/security.md) for the current hardening checklist. Report vulnerabilities through the repository's [Security Policy](https://github.com/an1creator/OpenACP/blob/main/SECURITY.md).
420
217
 
421
218
  ## Contributing
422
219
 
423
- We welcome contributions! See the [contributing guide](CONTRIBUTING.md) for development setup, testing conventions, and PR process. Have questions? Start a thread on [GitHub Discussions](https://github.com/an1creator/OpenACP/discussions).
220
+ Read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project conventions, tests, and pull-request requirements. Project conduct is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
424
221
 
425
222
  ## License
426
223
 
package/dist/cli.js CHANGED
@@ -2276,18 +2276,17 @@ This file provides context for AI coding agents (Claude, Cursor, etc.) working o
2276
2276
 
2277
2277
  OpenACP is an open-source platform that bridges AI coding agents (Claude Code, Codex, etc.) to messaging platforms (Telegram, Discord, Slack) and custom UIs via the Agent Client Protocol (ACP). It features a microkernel plugin architecture where all features \u2014 adapters, services, commands \u2014 are plugins.
2278
2278
 
2279
- - **Website & Docs**: https://openacp.gitbook.io/docs
2279
+ - **Documentation**: https://github.com/an1creator/OpenACP/tree/main/docs/gitbook
2280
2280
  - **GitHub**: https://github.com/an1creator/OpenACP
2281
- - **Plugin Registry**: https://github.com/Open-ACP/plugin-registry
2282
2281
 
2283
2282
  Key documentation pages:
2284
- - [Getting Started](https://openacp.gitbook.io/docs/getting-started) \u2014 What is OpenACP, quickstart
2285
- - [Plugin Development](https://openacp.gitbook.io/docs/extending/building-plugins) \u2014 How to build plugins
2286
- - [Architecture](https://openacp.gitbook.io/docs/extending/architecture) \u2014 System design, plugin lifecycle
2287
- - [Dev Mode](https://openacp.gitbook.io/docs/extending/dev-mode) \u2014 Hot-reload development workflow
2288
- - [CLI Commands](https://openacp.gitbook.io/docs/api-reference/cli-commands) \u2014 Full CLI reference
2289
- - [Platform Setup](https://openacp.gitbook.io/docs/platform-setup) \u2014 Telegram, Discord, Slack guides
2290
- - [Configuration](https://openacp.gitbook.io/docs/self-hosting/configuration) \u2014 Config and settings reference
2283
+ - [Getting Started](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/getting-started) \u2014 What is OpenACP, quickstart
2284
+ - [Plugin Development](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/extending/getting-started-plugin.md) \u2014 How to build plugins
2285
+ - [Architecture](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/architecture) \u2014 System design, plugin lifecycle
2286
+ - [Dev Mode](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/extending/dev-mode.md) \u2014 Hot-reload development workflow
2287
+ - [CLI Commands](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/api-reference/cli-commands.md) \u2014 Full CLI reference
2288
+ - [Platform Setup](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/platform-setup) \u2014 Telegram, Discord, Slack guides
2289
+ - [Configuration](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/self-hosting/configuration.md) \u2014 Config and settings reference
2291
2290
 
2292
2291
  ## Project Overview
2293
2292
 
@@ -2876,16 +2875,16 @@ const ctx = createTestContext({
2876
2875
  \`\`\`bash
2877
2876
  openacp plugin install ${params.pluginName}
2878
2877
  \`\`\`
2879
- 5. Submit to the [OpenACP Plugin Registry](https://github.com/Open-ACP/plugin-registry) for discoverability.
2878
+ 5. Verify installation by the complete npm package name from a clean environment.
2880
2879
 
2881
2880
  ## Useful Links
2882
2881
 
2883
- - [Architecture: Plugin System](https://docs.openacp.dev/architecture/plugin-system)
2884
- - [Architecture: Writing Plugins](https://docs.openacp.dev/architecture/writing-plugins)
2885
- - [Architecture: Command System](https://docs.openacp.dev/architecture/command-system)
2886
- - [Plugin SDK Reference](https://docs.openacp.dev/extending/plugin-sdk-reference)
2887
- - [Getting Started: Your First Plugin](https://docs.openacp.dev/extending/getting-started-plugin)
2888
- - [Dev Mode](https://docs.openacp.dev/extending/dev-mode)
2882
+ - [Architecture: Plugin System](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/architecture/plugin-system.md)
2883
+ - [Architecture: Writing Plugins](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/architecture/writing-plugins.md)
2884
+ - [Architecture: Command System](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/architecture/command-system.md)
2885
+ - [Plugin SDK Reference](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/extending/plugin-sdk-reference.md)
2886
+ - [Getting Started: Your First Plugin](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/extending/getting-started-plugin.md)
2887
+ - [Dev Mode](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/extending/dev-mode.md)
2889
2888
  - [Contributing](https://github.com/an1creator/OpenACP/blob/main/CONTRIBUTING.md)
2890
2889
  `;
2891
2890
  }