0xmrpeter fa071dc5c4 fix: address code review findings — resolve critical, high, and medium issues
- C1: resolveWorkspace() now allows absolute/tilde paths under baseDir; rejects paths outside baseDir; update tests to match new semantics and add coverage for allowed cases
- C2: revert bore.ts to use --secret CLI flag instead of BORE_SECRET env var (bore does not support env var)
- H1: revert openacp.ts to use --token CLI flag instead of TUNNEL_TOKEN env var (cloudflared env var support unreliable)
- H2: add sessions:dangerous scope to KNOWN_SCOPES in roles.ts; not granted to any named role (admin-only via wildcard)
- H3: expand DEFAULT_ENV_WHITELIST with GIT_*, SSH_AUTH_SOCK/PID, terminal rendering vars; add comments documenting envWhitelist/allowedPaths config wiring as follow-up
- H4: revert tunnel viewer routes to auth: false — content is already gated by random UUIDs
- M1: readTextFile PathGuard rejection now throws Error instead of returning access-denied string as content
- M2: apply sanitizeHtml() to file-viewer fallback path (non-marked rendering) to prevent XSS
- M3: envWhitelist/allowedPaths documented as follow-up in agent-instance.ts comments
- M4: validateTarContents uses segment-based check for .. traversal to avoid false positives on filenames like setup..sh
2026-04-03 13:14:02 +07:00
2026-04-01 13:56:46 +07:00

OpenACP

Control AI coding agents from Telegram, Discord & Slack

Send a message. The agent writes code. You see everything — in real time.

License: MIT Node.js >= 20 ACP Protocol npm Twitter Follow

Documentation · Quick Start · Features · Agents · Contributing


What is OpenACP?

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.

Built on the open Agent Client Protocol (ACP). Your machine, your keys, your data.

You (Telegram / Discord / Slack)
  ↓
OpenACP (bridge + session manager)
  ↓
AI Agent (Claude Code, Codex, Gemini, Cursor, ...)
  ↓
Your Codebase

Control Panel
Manage sessions, agents, and settings

Agent at Work
Plans, reads files, writes code

Real-time Tool Calls
See every action the agent takes

Agent Skills
Brainstorming, TDD, debugging & more

Installation

Requirements: Node.js 20+ (the installer handles this for you)

macOS

curl -fsSL https://raw.githubusercontent.com/Open-ACP/OpenACP/main/scripts/install.sh | bash

Linux

curl -fsSL https://raw.githubusercontent.com/Open-ACP/OpenACP/main/scripts/install.sh | bash

Works on Debian/Ubuntu, Fedora/RHEL, Arch, and other distros. Also supports WSL (Windows Subsystem for Linux).

Windows

Open PowerShell and run:

powershell -c "irm https://raw.githubusercontent.com/Open-ACP/OpenACP/main/scripts/install.ps1 | iex"

Requires PowerShell 5.1+ (built into Windows 10/11).

Manual install via npm

If you already have Node.js 20+ installed:

npm install -g @openacp/cli
openacp

After installation, the interactive setup wizard walks you through everything:

  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)

That's it. Send a message to your bot and start coding.

Need detailed setup for a specific platform? See the Platform Setup guides.

Features

Messaging Platforms

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

Core

  • 28+ AI agents — Claude Code, Codex, Gemini, Cursor, Copilot, and more
  • 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
  • Agent switching — Switch agents mid-conversation with /switch; history carries over automatically

Developer Tools

  • 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)
  • Agent switch — Change which AI agent handles your session mid-conversation (/switch)
  • 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

Operations

  • 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

Full feature documentation — Documentation

Supported Agents

OpenACP uses the ACP Registry — new agents are available as soon as they're registered.

Agent Type Description
Claude Code npx Anthropic's Claude coding agent
Gemini CLI npx Google's Gemini CLI
Codex CLI npx OpenAI's coding assistant
GitHub Copilot npx GitHub's AI pair programmer
Cursor binary Cursor's coding agent
Cline npx Autonomous coding agent
goose binary Open source AI agent by Block
Amp binary The frontier coding agent
Auggie CLI npx Augment Code's context engine
Junie binary AI coding agent by JetBrains
Kilo npx Open source coding agent
Qwen Code npx Alibaba's Qwen assistant
...and more Full registry →
openacp agents                     # Browse all agents
openacp agents install <name>      # Install from registry

CLI Overview

# Server
openacp                            # Start (first run = setup wizard)
openacp start / stop / restart     # Daemon management
openacp status                     # Check daemon status
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

Full CLI reference — CLI Commands

Documentation

Section Description
Getting Started What is OpenACP, quickstart for users & developers
Platform Setup Step-by-step guides for Telegram, Discord, Slack
Using OpenACP Commands, sessions, agents, permissions, voice
Self-Hosting Installation, configuration, daemon, security
Features Tunnel, context resume, usage tracking, and more
Extending Plugin system, building adapters, contributing
API Reference CLI commands, REST API, config schema, env vars
Troubleshooting Common issues and FAQ

Star History

Star History Chart

Contributing

We welcome contributions! See the contributing guide for development setup, testing conventions, and PR process.

Follow Us

Twitter Follow

License

MIT

Description
Self-hosted bridge that lets you interact with AI coding agents (Claude Code, Codex, etc.) from messaging platforms (Telegram, Discord, etc.) via the Agent Client Protocol (ACP).
Readme MIT 7.5 MiB
Languages
TypeScript 96.8%
Shell 1.6%
JavaScript 1%
PowerShell 0.6%