help

name	help
description	Show the telegram-topics plugin help — list all commands and the typical setup flow. Use when the user asks what they can do with telegram-topics, wants a command list, or doesn't know where to start.
user-invocable	true
allowed-tools	[]

/telegram-topics:help — Plugin Help

Arguments passed: $ARGUMENTS

---

Show the user the following help text (you can tailor it slightly if the user's question is narrower, but default to showing everything):

telegram-topics — Claude Code channel plugin with Forum Topics

Each project directory gets its own Telegram Forum Topic. Messages in
each topic reach only the Claude Code instance running in that project.

====================================================================
ONE-TIME SETUP  (per machine / Telegram account)
====================================================================

 1. Create a bot
      - DM @BotFather, run /newbot, copy the token.

 2. Create the supergroup
      - New group → convert to supergroup → Edit group → turn on Topics.
      - Add the bot as admin with "Manage Topics" + "Post Messages".

 3. Get the chat ID
      - Forward any message from the group to @userinfobot.
      - It returns a negative integer, e.g. -1001234567890.

 4. Save token + chat (in Claude Code, any directory)
      /telegram-topics:configure <token>
      /telegram-topics:configure chat <chat_id>

 5. Start Claude Code in any project so a topic exists
      cd ~/some/project
      claude --dangerously-load-development-channels \
             plugin:telegram-topics@wilfoa-plugins

 6. Pair your Telegram account  (ONE TIME per account)
      - In Telegram, open the new topic and send "hi".
      - Bot replies with a 6-char pairing code.
      - In Claude Code:
          /telegram-topics:pair <code>
          /telegram-topics:access policy allowlist

    Future projects reuse the same allowlist — no re-pairing.

====================================================================
PER-PROJECT SETUP  (each new project directory)
====================================================================

 1. (Optional) Set a custom topic name, BEFORE first session
      cd ~/Development/my-project
      /telegram-topics:configure topic "My Project"
      - Default is the directory basename. Skip this to accept it.

 2. Restart Claude Code in the project directory
      cd ~/Development/my-project
      claude --dangerously-load-development-channels \
             plugin:telegram-topics@wilfoa-plugins
      - Daemon creates/renames the Forum Topic on first connect.

 3. Talk to it
      - Messages in that topic route only to the Claude Code running
        in that directory. Reactions, attachments, and permission
        prompts all thread back to the same topic.

====================================================================
RUNNING MULTIPLE CLAUDE CODE SESSIONS IN THE SAME PROJECT
====================================================================

The default is auto-suffix: the first session in a directory gets
the primary topic, the second is auto-routed to "<cwd>#2" with a
topic named "<baseLabel> (#2)", the third to "(#3)", etc. No eviction
required, no env var required. Freed slots are reused before new
integers are allocated.

For a stable, human-chosen name instead of an integer, set
TELEGRAM_TOPICS_INSTANCE on launch:

    TELEGRAM_TOPICS_INSTANCE=exp claude \
      --dangerously-load-development-channels \
      plugin:telegram-topics@wilfoa-plugins

Registers as "<baseLabel> (exp)" under "<cwd>#exp". Named instances
don't participate in integer numbering — two unnamed sessions plus a
"#exp" session still land on slots 1, 2, and exp (not 1, 2, 3).

Run /telegram-topics:configure instance <name> for the launch recipe,
or /telegram-topics:configure instance (no name) to list named +
integer instances currently in topics.json for the cwd.

Eviction only fires if you EXPLICITLY collide on the same named or
integer-suffixed instance (e.g. two shells both setting
TELEGRAM_TOPICS_INSTANCE=exp). "Explicit wins over auto."

====================================================================
REMOVING A TOPIC
====================================================================

Two-step, token-confirmed:

    /telegram-topics:project remove <name-or-path>
    # → prints a 6-char token (5 min TTL)
    /telegram-topics:project remove-confirm <token>

Deletes the topic from Telegram and clears its entry from
topics.json. Any Claude Code session still attached is evicted.

====================================================================
COMMANDS
====================================================================

Setup:
  /telegram-topics:configure <token>          Save the bot token
  /telegram-topics:configure chat <chat_id>   Set the supergroup chat ID
  /telegram-topics:configure topic "<name>" [--instance <inst>]
                                              Rename the topic live (no
                                              session restart needed).
                                              --instance targets a named
                                              instance topic.
  /telegram-topics:configure instance [name]  Launch recipe for a second
                                              Claude Code session in the same
                                              project with its own topic.
                                              No name → list instance topics.
  /telegram-topics:configure clear            Remove the stored token
  /telegram-topics:configure                  Show full status

Pairing / access:
  /telegram-topics:pair <code>                Approve a pairing code
  /telegram-topics:access pair <code>         Same, via the access skill
  /telegram-topics:access deny <code>         Reject a pending code
  /telegram-topics:access allow <senderId>    Manually allowlist a user
  /telegram-topics:access remove <senderId>   Remove a user
  /telegram-topics:access policy <mode>       pairing | allowlist | disabled

Projects:
  /telegram-topics:project list               Show all registered topics
  /telegram-topics:project remove <name|path> Request deletion. Prints a
                                              confirmation token (5 min TTL).
  /telegram-topics:project remove-confirm <token>
                                              Complete the deletion.

Daemon:
  /telegram-topics:daemon status              PID, uptime, version
  /telegram-topics:daemon stop                Kill the daemon
  /telegram-topics:daemon restart             Stop; next session respawns
  /telegram-topics:daemon log                 Tail the daemon log

Repo: https://github.com/wilfoa/claude-telegram-topics

After showing this, ask: "What do you want to do?" — or, if the user's original message indicated a specific need (e.g. "how do I rename a topic?"), point them directly to the relevant command.