docs: refactor README into landing page + separate guide docs
README.md is now a concise landing page with badges, architecture,
highlights (linked titles), quick start, commands, roadmap, and
star history chart.
Detailed documentation moved to docs/guide/:
- getting-started.md: install, setup wizard, agent detection
- telegram-setup.md: bot setup, streaming, skill commands, topics
- usage.md: commands, sessions, workspaces, lazy resume
- configuration.md: full config reference, env vars, logging
- tunnel.md: providers, file/diff viewer, security, endpoints
- plugins.md: install/create channel adapters
- development.md: build, architecture, design decisions, paths
2026-03-20 15:35:59 +07:00
< div align = "center" >
2026-03-19 15:55:33 +07:00
# OpenACP
2026-03-25 22:15:57 +07:00
**Control AI coding agents from Telegram, Discord & Slack**
2026-03-19 15:55:33 +07:00
2026-03-25 22:15:57 +07:00
Send a message. The agent writes code. You see everything — in real time.
2026-03-19 15:55:33 +07:00
2026-03-22 16:01:55 +07:00
[](LICENSE)
docs: refactor README into landing page + separate guide docs
README.md is now a concise landing page with badges, architecture,
highlights (linked titles), quick start, commands, roadmap, and
star history chart.
Detailed documentation moved to docs/guide/:
- getting-started.md: install, setup wizard, agent detection
- telegram-setup.md: bot setup, streaming, skill commands, topics
- usage.md: commands, sessions, workspaces, lazy resume
- configuration.md: full config reference, env vars, logging
- tunnel.md: providers, file/diff viewer, security, endpoints
- plugins.md: install/create channel adapters
- development.md: build, architecture, design decisions, paths
2026-03-20 15:35:59 +07:00
[](https://nodejs.org/)
[](https://agentclientprotocol.org/)
2026-03-22 17:24:02 +07:00
[](https://www.npmjs.com/package/@openacp/cli )
2026-03-27 00:55:18 +07:00
[](https://x.com/openacp_ai)
2026-03-19 15:55:33 +07:00
2026-03-26 10:03:37 +07:00
[Documentation ](https://openacp.gitbook.io/docs ) · [Quick Start ](#quick-start ) · [Features ](#features ) · [Agents ](#supported-agents ) · [Contributing ](https://openacp.gitbook.io/docs/extending/contributing )
2026-03-19 15:55:33 +07:00
docs: refactor README into landing page + separate guide docs
README.md is now a concise landing page with badges, architecture,
highlights (linked titles), quick start, commands, roadmap, and
star history chart.
Detailed documentation moved to docs/guide/:
- getting-started.md: install, setup wizard, agent detection
- telegram-setup.md: bot setup, streaming, skill commands, topics
- usage.md: commands, sessions, workspaces, lazy resume
- configuration.md: full config reference, env vars, logging
- tunnel.md: providers, file/diff viewer, security, endpoints
- plugins.md: install/create channel adapters
- development.md: build, architecture, design decisions, paths
2026-03-20 15:35:59 +07:00
< / div >
2026-03-19 15:55:33 +07:00
docs: refactor README into landing page + separate guide docs
README.md is now a concise landing page with badges, architecture,
highlights (linked titles), quick start, commands, roadmap, and
star history chart.
Detailed documentation moved to docs/guide/:
- getting-started.md: install, setup wizard, agent detection
- telegram-setup.md: bot setup, streaming, skill commands, topics
- usage.md: commands, sessions, workspaces, lazy resume
- configuration.md: full config reference, env vars, logging
- tunnel.md: providers, file/diff viewer, security, endpoints
- plugins.md: install/create channel adapters
- development.md: build, architecture, design decisions, paths
2026-03-20 15:35:59 +07:00
---
2026-03-19 15:55:33 +07:00
2026-03-21 23:05:32 +07:00
## What is OpenACP?
2026-03-19 15:55:33 +07:00
2026-03-25 22:15:57 +07:00
OpenACP is a self-hosted bridge that connects AI coding agents to your messaging platforms. You chat with an AI agent through Telegram, Discord, or Slack — it reads your codebase, writes code, runs commands, and streams results back to you in real time.
2026-03-19 15:55:33 +07:00
2026-03-25 22:15:57 +07:00
Built on the open [Agent Client Protocol (ACP) ](https://agentclientprotocol.org/ ). Your machine, your keys, your data.
2026-03-19 15:55:33 +07:00
docs: refactor README into landing page + separate guide docs
README.md is now a concise landing page with badges, architecture,
highlights (linked titles), quick start, commands, roadmap, and
star history chart.
Detailed documentation moved to docs/guide/:
- getting-started.md: install, setup wizard, agent detection
- telegram-setup.md: bot setup, streaming, skill commands, topics
- usage.md: commands, sessions, workspaces, lazy resume
- configuration.md: full config reference, env vars, logging
- tunnel.md: providers, file/diff viewer, security, endpoints
- plugins.md: install/create channel adapters
- development.md: build, architecture, design decisions, paths
2026-03-20 15:35:59 +07:00
```
2026-03-25 22:15:57 +07:00
You (Telegram / Discord / Slack)
docs: refactor README into landing page + separate guide docs
README.md is now a concise landing page with badges, architecture,
highlights (linked titles), quick start, commands, roadmap, and
star history chart.
Detailed documentation moved to docs/guide/:
- getting-started.md: install, setup wizard, agent detection
- telegram-setup.md: bot setup, streaming, skill commands, topics
- usage.md: commands, sessions, workspaces, lazy resume
- configuration.md: full config reference, env vars, logging
- tunnel.md: providers, file/diff viewer, security, endpoints
- plugins.md: install/create channel adapters
- development.md: build, architecture, design decisions, paths
2026-03-20 15:35:59 +07:00
↓
2026-03-25 22:15:57 +07:00
OpenACP (bridge + session manager)
↓
AI Agent (Claude Code, Codex, Gemini, Cursor, ...)
↓
Your Codebase
2026-03-19 15:55:33 +07:00
```
2026-03-22 17:01:46 +07:00
< div align = "center" >
< table >
< tr >
< td align = "center" > < img src = "docs/images/menu.png" width = "250" / > < br / > < b > Control Panel< / b > < br / > Manage sessions, agents, and settings< / td >
< td align = "center" > < img src = "docs/images/agent-working.png" width = "250" / > < br / > < b > Agent at Work< / b > < br / > Plans, reads files, writes code< / td >
< / tr >
< tr >
< td align = "center" > < img src = "docs/images/tool-calls.png" width = "250" / > < br / > < b > Real-time Tool Calls< / b > < br / > See every action the agent takes< / td >
< td align = "center" > < img src = "docs/images/skills.png" width = "250" / > < br / > < b > Agent Skills< / b > < br / > Brainstorming, TDD, debugging & more< / td >
< / tr >
< / table >
< / div >
2026-03-25 22:15:57 +07:00
## Quick Start
2026-03-19 15:55:33 +07:00
2026-03-31 09:58:57 +07:00
```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Open-ACP/OpenACP/main/scripts/install.sh | bash
# Windows
powershell -c "irm https://raw.githubusercontent.com/Open-ACP/OpenACP/main/scripts/install.ps1 | iex"
```
Works on macOS, Linux & Windows. Installs Node.js (if needed) and everything else for you.
< details >
< summary > Or install via npm< / summary >
2026-03-19 15:55:33 +07:00
```bash
docs: refactor README into landing page + separate guide docs
README.md is now a concise landing page with badges, architecture,
highlights (linked titles), quick start, commands, roadmap, and
star history chart.
Detailed documentation moved to docs/guide/:
- getting-started.md: install, setup wizard, agent detection
- telegram-setup.md: bot setup, streaming, skill commands, topics
- usage.md: commands, sessions, workspaces, lazy resume
- configuration.md: full config reference, env vars, logging
- tunnel.md: providers, file/diff viewer, security, endpoints
- plugins.md: install/create channel adapters
- development.md: build, architecture, design decisions, paths
2026-03-20 15:35:59 +07:00
npm install -g @openacp/cli
2026-03-19 17:29:37 +07:00
openacp
```
2026-03-31 09:58:57 +07:00
< / details >
2026-03-25 22:15:57 +07:00
The interactive setup wizard walks you through everything:
2026-03-19 15:55:33 +07:00
2026-03-25 22:15:57 +07:00
1. Choose your platform (Telegram, Discord, Slack, or multiple)
2. Connect your bot (token validation + auto-detection)
3. Pick a workspace directory
4. Select your default AI agent
5. Choose run mode (foreground or daemon)
2026-03-21 23:05:32 +07:00
2026-03-25 22:15:57 +07:00
That's it. Send a message to your bot and start coding.
2026-03-21 23:05:32 +07:00
2026-03-26 10:03:37 +07:00
> **Need detailed setup for a specific platform?** See the [Platform Setup guides](https://openacp.gitbook.io/docs/platform-setup).
2026-03-21 23:05:32 +07:00
2026-03-25 22:15:57 +07:00
## Features
2026-03-20 17:13:48 +07:00
2026-03-25 22:15:57 +07:00
### Messaging Platforms
2026-03-20 17:13:48 +07:00
2026-03-25 22:15:57 +07:00
| Platform | Status | Highlights |
|----------|--------|------------|
| **Telegram** | Stable | Forum topics per session, streaming, permission buttons, voice |
| **Discord** | Stable | Thread-based sessions, slash commands, button interactions |
| **Slack** | Stable | Socket Mode, channel-based sessions, thread organization |
2026-03-20 17:13:48 +07:00
2026-03-25 22:15:57 +07:00
### Core
2026-03-20 17:13:48 +07:00
2026-03-25 22:15:57 +07:00
- **28+ AI agents** — Claude Code, Codex, Gemini, Cursor, Copilot, and [more ](#supported-agents )
- **Session management** — Each conversation gets its own thread/topic with auto-naming
- **Session persistence** — Sessions survive restarts, with configurable TTL
- **Permission control** — Approve or deny agent actions via buttons, with optional auto-approve
- **Real-time streaming** — See agent thinking, tool calls, and output as they happen
2026-03-30 18:43:24 +07:00
- **Agent switching** — Switch agents mid-conversation with `/switch` ; history carries over automatically
2026-03-20 17:13:48 +07:00
2026-03-25 22:15:57 +07:00
### Developer Tools
2026-03-21 23:05:32 +07:00
2026-03-25 22:15:57 +07:00
- **Tunnel & port forwarding** — Expose local ports to the internet (Cloudflare, ngrok, bore, Tailscale)
- **Built-in file viewer** — Monaco Editor with syntax highlighting, diffs, and markdown preview
- **Session transfer** — Move sessions between terminal and chat (`/handoff` )
2026-03-30 18:43:24 +07:00
- **Agent switch** — Change which AI agent handles your session mid-conversation (`/switch` )
2026-03-25 22:15:57 +07:00
- **Voice & speech** — Send voice messages, get spoken responses (Groq STT + Edge TTS)
- **Usage tracking** — Token counts, cost reports, optional monthly budget limits
- **Context resume** — Resume sessions with full conversation history
2026-03-23 14:19:38 +07:00
2026-03-25 22:15:57 +07:00
### Operations
2026-03-19 15:55:33 +07:00
2026-03-25 22:15:57 +07:00
- **Daemon mode** — Run as a background service with auto-start on boot
- **CLI API** — Full REST API for automation (`openacp api ...` )
- **Plugin system** — Install adapters as npm packages
- **Doctor diagnostics** — `openacp doctor` checks everything and suggests fixes
- **Structured logging** — Pino with rotation, per-session log files
2026-03-19 15:55:33 +07:00
2026-03-26 10:03:37 +07:00
> **Full feature documentation** — [Documentation](https://openacp.gitbook.io/docs)
2026-03-23 14:19:38 +07:00
2026-03-25 22:15:57 +07:00
## Supported Agents
2026-03-23 14:19:38 +07:00
2026-03-25 22:15:57 +07:00
OpenACP uses the [ACP Registry ](https://agentclientprotocol.com/get-started/registry ) — new agents are available as soon as they're registered.
2026-03-23 14:19:38 +07:00
2026-03-25 22:15:57 +07:00
| Agent | Type | Description |
|-------|------|-------------|
| [Claude Code ](https://github.com/anthropics/claude-code ) | npx | Anthropic's Claude coding agent |
| [Gemini CLI ](https://github.com/google-gemini/gemini-cli ) | npx | Google's Gemini CLI |
| [Codex CLI ](https://github.com/openai/codex ) | npx | OpenAI's coding assistant |
| [GitHub Copilot ](https://github.com/github/copilot-cli ) | npx | GitHub's AI pair programmer |
| [Cursor ](https://www.cursor.com/ ) | binary | Cursor's coding agent |
| [Cline ](https://github.com/cline/cline ) | npx | Autonomous coding agent |
| [goose ](https://github.com/block/goose ) | binary | Open source AI agent by Block |
| [Amp ](https://github.com/tao12345666333/amp-acp ) | binary | The frontier coding agent |
| [Auggie CLI ](https://www.augmentcode.com/ ) | npx | Augment Code's context engine |
| [Junie ](https://www.jetbrains.com/ ) | binary | AI coding agent by JetBrains |
| [Kilo ](https://github.com/kilocode/kilo ) | npx | Open source coding agent |
| [Qwen Code ](https://github.com/QwenLM/qwen-code ) | npx | Alibaba's Qwen assistant |
| ...and more | | [Full registry → ](https://agentclientprotocol.com/get-started/registry ) |
2026-03-21 23:05:32 +07:00
2026-03-25 22:15:57 +07:00
```bash
openacp agents # Browse all agents
openacp agents install < name > # Install from registry
```
2026-03-22 01:38:17 +07:00
2026-03-25 22:15:57 +07:00
## CLI Overview
2026-03-22 01:38:17 +07:00
```bash
2026-03-25 22:15:57 +07:00
# Server
openacp # Start (first run = setup wizard)
2026-03-31 15:52:48 +07:00
openacp start / stop / restart # Daemon management
openacp status # Check daemon status
2026-03-25 22:15:57 +07:00
openacp logs # Tail daemon logs
# Configuration
openacp config # Interactive config editor
openacp reset # Re-run setup wizard
openacp doctor # System diagnostics
# Sessions & API (requires running daemon)
openacp api new [agent] [workspace]
openacp api status
openacp api cancel < id >
# Tunnels
openacp tunnel add < port > [--label name]
openacp tunnel list
2026-03-22 01:38:17 +07:00
```
2026-03-26 10:03:37 +07:00
> **Full CLI reference** — [CLI Commands](https://openacp.gitbook.io/docs/api-reference/cli-commands)
2026-03-22 01:38:17 +07:00
2026-03-25 22:15:57 +07:00
## Documentation
2026-03-19 15:55:33 +07:00
2026-03-25 22:15:57 +07:00
| Section | Description |
|---------|-------------|
2026-03-26 10:03:37 +07:00
| [Getting Started ](https://openacp.gitbook.io/docs/getting-started ) | What is OpenACP, quickstart for users & developers |
| [Platform Setup ](https://openacp.gitbook.io/docs/platform-setup ) | Step-by-step guides for Telegram, Discord, Slack |
| [Using OpenACP ](https://openacp.gitbook.io/docs/using-openacp ) | Commands, sessions, agents, permissions, voice |
| [Self-Hosting ](https://openacp.gitbook.io/docs/self-hosting ) | Installation, configuration, daemon, security |
| [Features ](https://openacp.gitbook.io/docs/features ) | Tunnel, context resume, usage tracking, and more |
| [Extending ](https://openacp.gitbook.io/docs/extending ) | Plugin system, building adapters, contributing |
| [API Reference ](https://openacp.gitbook.io/docs/api-reference ) | CLI commands, REST API, config schema, env vars |
| [Troubleshooting ](https://openacp.gitbook.io/docs/troubleshooting ) | Common issues and FAQ |
2026-03-19 15:55:33 +07:00
docs: refactor README into landing page + separate guide docs
README.md is now a concise landing page with badges, architecture,
highlights (linked titles), quick start, commands, roadmap, and
star history chart.
Detailed documentation moved to docs/guide/:
- getting-started.md: install, setup wizard, agent detection
- telegram-setup.md: bot setup, streaming, skill commands, topics
- usage.md: commands, sessions, workspaces, lazy resume
- configuration.md: full config reference, env vars, logging
- tunnel.md: providers, file/diff viewer, security, endpoints
- plugins.md: install/create channel adapters
- development.md: build, architecture, design decisions, paths
2026-03-20 15:35:59 +07:00
## Star History
2026-03-19 17:29:37 +07:00
docs: refactor README into landing page + separate guide docs
README.md is now a concise landing page with badges, architecture,
highlights (linked titles), quick start, commands, roadmap, and
star history chart.
Detailed documentation moved to docs/guide/:
- getting-started.md: install, setup wizard, agent detection
- telegram-setup.md: bot setup, streaming, skill commands, topics
- usage.md: commands, sessions, workspaces, lazy resume
- configuration.md: full config reference, env vars, logging
- tunnel.md: providers, file/diff viewer, security, endpoints
- plugins.md: install/create channel adapters
- development.md: build, architecture, design decisions, paths
2026-03-20 15:35:59 +07:00
< a href = "https://star-history.com/ #Open -ACP/OpenACP&Date" >
< picture >
< source media = "(prefers-color-scheme: dark)" srcset = "https://api.star-history.com/svg?repos=Open-ACP/OpenACP&type=Date&theme=dark" / >
< source media = "(prefers-color-scheme: light)" srcset = "https://api.star-history.com/svg?repos=Open-ACP/OpenACP&type=Date" / >
< img alt = "Star History Chart" src = "https://api.star-history.com/svg?repos=Open-ACP/OpenACP&type=Date" / >
< / picture >
< / a >
2026-03-19 17:29:37 +07:00
docs: refactor README into landing page + separate guide docs
README.md is now a concise landing page with badges, architecture,
highlights (linked titles), quick start, commands, roadmap, and
star history chart.
Detailed documentation moved to docs/guide/:
- getting-started.md: install, setup wizard, agent detection
- telegram-setup.md: bot setup, streaming, skill commands, topics
- usage.md: commands, sessions, workspaces, lazy resume
- configuration.md: full config reference, env vars, logging
- tunnel.md: providers, file/diff viewer, security, endpoints
- plugins.md: install/create channel adapters
- development.md: build, architecture, design decisions, paths
2026-03-20 15:35:59 +07:00
## Contributing
2026-03-19 17:29:37 +07:00
2026-03-26 10:03:37 +07:00
We welcome contributions! See the [contributing guide ](https://openacp.gitbook.io/docs/extending/contributing ) for development setup, testing conventions, and PR process.
2026-03-19 17:29:37 +07:00
2026-03-22 21:53:18 +07:00
## Follow Us
2026-03-27 00:55:18 +07:00
[](https://x.com/openacp_ai)
2026-03-22 21:53:18 +07:00
2026-03-19 15:55:33 +07:00
## License
2026-03-22 16:01:55 +07:00
[MIT ](LICENSE )