How To Use The Bot From Telegram

How To Use The Bot From Telegram#

This guide shows the main command flow for day-to-day usage.

1. Start working (implicit session)#

Send a normal prompt. If the chat has no active session, the bot creates one automatically in the default workspace.

Example:

Please review the latest commit and suggest a fix.

You can also attach images/documents; the bot forwards them to ACP prompt input.

2. Start or switch sessions with /new#

Create a session in the default workspace:

/new

Create a session in a specific workspace:

/new /home/user/project

The bot will reply with the ACP session_id and workspace path.

Use /new when you want a different session/workspace than the current one.

3. Resume an existing ACP session#

List resumable sessions and pick one from buttons:

/resume

Resume by list index (0-based, where 0 is the most recent):

/resume 0

List resumable sessions for a specific workspace:

/resume /home/user/project

This resumes the most recent session in that workspace.

When you tap a button, the bot calls ACP session/load and switches the active conversation for that chat.

/resume accepts either an index or a workspace path (not both in the same command).

If your agent does not support ACP session/list, /resume will report it.

4. Inspect current session#

/session

Shows the active session workspace.

5. Cancel, stop, and clear#

Cancel current in-flight operation:

/cancel

Stop current session process:

/stop

Clear current session:

/clear

6. Switch activity mode#

Show the current mode:

/mode

Set the mode explicitly:

/mode normal
/mode compact
/mode verbose

The available modes are:

  • normal: separate activity messages, no streaming edits.

  • compact: one in-progress status message that becomes the final answer.

  • verbose: in-place append-only streaming for reply text and active tool output.

7. Busy-state handling#

When you send a message while the agent is already processing a previous prompt, the bot:

  • Queues your message automatically.

  • Replies to that queued message with the busy notice.

  • Shows a temporary Send now inline button.

Send now#

Pressing Send now immediately cancels the current in-flight operation and processes your queued message. The queued notice is updated to ✅ Sent. so chat state matches what happened.

If the current task finishes naturally before you press the button, your queued message runs automatically and the button is removed (pressing it after that shows “Already sent.” with no side effects).

8. Inspect and cancel scheduled follow-ups#

When the agent schedules a deferred follow-up, you can inspect the pending work directly from Telegram:

/scheduled

The bot replies with a compact summary of the scheduled tasks for the current chat. Pending tasks are shown with inline Cancel buttons, so you do not have to copy or type task ids manually.

A typical interaction looks like this:

/scheduled

Scheduled tasks for this chat:

Pending:
1. prompt_agent | 2026-03-30 22:10:00 UTC
  Check the PR again and report any new comments.
2. notify | 2026-03-30 22:30:00 UTC
  Remind me to restart the bot.

From there you can tap Cancel 1, Cancel 2, and so on, or use Cancel all pending if you want to clear the queue for that chat.

For this first version, cancellation is intentionally limited to tasks that are still pending. Tasks that are already running are visible for inspection, but they are not turned into interruptible jobs by this command.

9. Restart bot process (dev workflow)#

/restart

With an active session, the bot replies with:

Restart requested. Re-launching process...
Session restarted: <session_id> in <workspace>

Then it exits polling and re-execs the process (or uses ACP_RESTART_COMMAND if configured).

If there is no active session, it replies:

No active session. Use /new first.

Resume a specific saved session in-process with the restart command:

/restart 0

You can combine index and workspace filter:

/restart 2 /home/user/project

That path replies with:

Session resumed: <session_id> in <workspace>

Notes#

  • Session scope is per Telegram chat.

  • The first prompt creates a session implicitly when none is active (including after /restart).

  • /new replaces the active session for that chat and is intended for explicitly switching to another workspace/session.

  • /resume is ACP-native (session/list + session/load) and depends on agent capabilities.

  • /mode is stored per Telegram chat, so different chats can use different activity modes.

Logging and traceability#

Every application log line includes contextual identifiers:

  • chat_id: Telegram chat id.

  • session_id: ACP session id (when a session is active).

  • prompt_cycle_id: per-prompt cycle/task id generated for each incoming user prompt.

This lets you trace:

  • all activity from one ACP session (session_id),

  • all logs tied to a single prompt execution (including queued prompts) via prompt_cycle_id.

Use ACP_LOG_FORMAT=json to emit structured logs for log aggregators.

By default, the bot also emits compact text previews for prompts and replies:

  • Prompt received: ...

  • Reply sent: ...

The human-oriented text log format uses rich output in the terminal to highlight the logger, chat/session/cycle ids, and the message preview.

To keep logs focused on auditability, verbose transport/framework logs (for example httpx Telegram API request lines) are downgraded to warning level by default.