OpenACP/docs/gitbook/features/assistant-mode.md
0xmrpeter 7007ed3cec docs(gitbook): write all 8 content sections — complete documentation
Sections written:
- Getting Started (what-is-openacp, for-users, for-developers, for-contributors)
- Platform Setup (Telegram, Discord, Slack)
- Using OpenACP (commands, sessions, agents, permissions, voice, files)
- Self-Hosting (installation, configuration, daemon, security, logging, updating)
- Features (tunnel, context-resume, usage, persistence, handoff, doctor, assistant)
- Extending (plugin-system, building-adapters, adapter-reference, contributing)
- API Reference (CLI commands, REST API, config schema, env vars)
- Troubleshooting (Telegram, Discord, Slack, agent issues, FAQ)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 18:00:11 +07:00

2.6 KiB

Assistant Mode

What it is

Assistant mode is a dedicated agent session that runs in a special "Assistant" topic inside your Telegram forum group. Unlike regular coding sessions — where each topic is a direct line to a specific agent working on a specific project — the Assistant topic is a management interface. It understands your OpenACP setup and can create sessions, check status, cancel stuck sessions, manage configuration, install agents, and troubleshoot issues, all through natural language.


The Assistant topic

When OpenACP starts with the Telegram adapter, it automatically creates (or finds an existing) "Assistant" forum topic. This happens before any user sessions are created.

On startup, the Assistant sends a welcome message summarizing the current state:

  • Number of active and total sessions
  • Installed agents and which is the default
  • Any sessions in error state

A dedicated agent session is spawned for the Assistant topic using the configured defaultAgent. A system prompt is injected that gives the agent full awareness of OpenACP's current state: active session count, topic status breakdown, installed agents, available agents in the ACP Registry, workspace base directory, and STT configuration.


Difference from regular sessions

Regular session Assistant topic
Purpose Work on a coding task Manage OpenACP itself
Workspace A specific project directory OpenACP's workspace base directory
Auto-naming Yes, after first prompt Fixed name: "Assistant"
Commands available Agent-specific Full openacp api ... command set
One per user No, unlimited Yes, one global Assistant

The Assistant runs openacp api ... commands silently and presents results as natural language. Users never see raw CLI output unless they ask for it.


What you can ask the Assistant

  • "Create a new session for my React app in ~/code/my-app"
  • "What sessions are currently running?"
  • "Cancel the stuck session"
  • "Clean up all finished topics"
  • "Install the Gemini agent"
  • "Set my monthly budget to $30"
  • "Enable voice transcription with Groq"
  • "Why is session X in error state?"
  • "Restart the daemon"

Configuration

The Assistant uses the defaultAgent from your config. No special configuration is needed. If you want to change which agent powers the Assistant, update defaultAgent in ~/.openacp/config.json:

{
  "defaultAgent": "claude"
}

The Assistant topic is created with initialName: "Assistant" to prevent the auto-naming system from renaming it based on the first message content.