GhostPaw Telegram

@ghostpaw/telegram

Agent Telegram bots: every update mirrored into SQLite before your handler runs.

ghostpaw-telegram --help             # after installing the release binary

Telegram bot channel engine — fetch transport with zero runtime dependencies, SQLite message mirror with FTS5 full-text search, eager file BLOB storage, markdown rendering, and a structured LLM tool facade.

Every incoming update is mirrored into a local SQLite database before your handler runs, giving you a persistent, queryable record of everything the bot sees — including the raw bytes of every photo, document, voice message, and video, which are downloaded in the background after the update is stored and kept once per SHA-256 hash. A failed download leaves the file row without a checksum, so you can retry it with write.downloadFile. It ships as a single prebundled blob designed for two audiences at once: human developers building bot backends in code, and LLM agents operating through a structured tool facade.

MCP server

Every client below starts the same stdio server: ghostpaw-telegram mcp. For npm-based environments, use npx -y @ghostpaw/telegram mcp. Messages live in ~/.ghostpaw/telegram.db unless the GHOSTPAW_TELEGRAM_DB environment variable (absolute path) or --db says otherwise.

Claude Code

claude mcp add ghostpaw-telegram -- ghostpaw-telegram mcp

or as a plugin, which also installs the skill:

/plugin marketplace add GhostPawJS/telegram

/plugin install ghostpaw-telegram@ghostpaw-telegram

Codex CLI (~/.telegram/config.toml)

[mcp_servers.ghostpaw-telegram]

command = "ghostpaw-telegram" args = ["mcp"]

Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json) or a project .mcp.json:

{

"mcpServers": { "ghostpaw-telegram": { "command": "ghostpaw-telegram", "args": ["mcp"] } } }

Claude Desktop users can also install server.mcpb from the latest GitHub release. A Dockerfile is included for container hosts: docker build -t ghostpaw-telegram . && docker run -i --rm -v telegram:/data ghostpaw-telegram.

The server speaks MCP 2026-07-28 (stateless, server/discover) and the initialize-based revisions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.

Set TELEGRAM_BOT_TOKEN in the server environment to execute send and moderation actions. Without a token, these tools return plans; local reads and tool discovery work offline. The .mcp.json token placeholder must be supplied by the client environment. The server reads the mirror populated by your library transport; it does not poll for updates.

Noun-verb CLI

The 27 command paths derive from the 4 tool schemas:

bot stats | state <key> | chats

mirror message mirror messages | search mirror chat | chats | user | users mirror reactions mirror replies | edits message send | edit message delete | pin | unpin message typing | forward member ban | unban | restrict member promote | kick | show member list

Use help or --help for schema flags. Fields accept kebab-case flags, such as --can-send-messages true and --is-admin false. Objects accept JSON; arrays accept repeated flags or JSON. Values are literal, including a leading @; no flag reads a file. A single - reads stdin JSON; explicit flags override stdin fields. -- ends option parsing.

Global flags: --db , --json, --quiet, --compact, --help/-h, --version/-V/-v, --no-color. Piped output defaults to JSON; --quiet suppresses stdout. completions bash|zsh|fish prints completion setup and version prints the package version and installation variant.

Existing tools [--json], describe , call [JSON|-], flat tg_ --parameter value, mcp and skill forms keep their behavior. The noun-verb send and moderation commands always return plans, including when TELEGRAM_BOT_TOKEN is set. Execution remains available through createTelegramToolFacade({ client, execute: true }); the existing tool-level CLI and MCP forms execute when TELEGRAM_BOT_TOKEN is set. Local mirror reads and plans work offline without credentials. GHOSTPAW_TELEGRAM_DB sets the default database, otherwise ~/.ghostpaw/telegram.db is used; --db overrides both.

Offline examples:

ghostpaw-telegram mirror chats --db /tmp/telegram-port-example.db --json

ghostpaw-telegram message send 123 'Offline plan' --db /tmp/telegram-port-example.db --json ghostpaw-telegram mirror messages 123 --db /tmp/telegram-port-example.db --json

The empty mirror returns no chats or messages. The send returns an action descriptor without sending a Telegram message.

CLI

ghostpaw-telegram tools

ghostpaw-telegram call tg_read '{"subcommand":"list_chats"}' ghostpaw-telegram --db :memory: call tg_send '{"subcommand":"send_message","chatId":123,"text":"Hello"}'

The send example returns a plan unless TELEGRAM_BOT_TOKEN is set.

Use ghostpaw-telegram skill --short for the compact CLI cheat sheet, ghostpaw-telegram skill --list to list guides, and ghostpaw-telegram skill to read one.

On POSIX, CLI and MCP mirror databases are created with mode 0600, including new SQLite WAL/SHM files. Directories created for the database use mode 0700. Existing database and directory permissions are preserved. The mirror may contain private chat content and file blobs.

Agent Skill

SKILL.md and skills/telegram/ ship in the package. Print the skill with ghostpaw-telegram skill or copy skills/telegram/ into your skills folder.

Install

Release binary (default)

Each line downloads the latest release asset, checks it against the release's SHA256SUMS and installs it on the PATH (~/.local/bin on Linux/macOS; the Windows script adds its folder to the user PATH).

These lines never edit ~/.profile or other shell startup files: export PATH applies to the current shell only. To keep it in new shells, use the ~/.profile line below.

linux-x64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.sh | sh -s -- --target linux-x64 && export PATH="$HOME/.local/bin:$PATH"

linux-arm64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.sh | sh -s -- --target linux-arm64 && export PATH="$HOME/.local/bin:$PATH"

darwin-arm64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.sh | sh -s -- --target darwin-arm64 && export PATH="$HOME/.local/bin:$PATH"

darwin-x64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.sh | sh -s -- --target darwin-x64 && export PATH="$HOME/.local/bin:$PATH"

windows-x64 (PowerShell; persistently adds the install folder to the user PATH):

irm https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.ps1 | iex

To skip the persistent user PATH edit:

$env:GHOSTPAW_NO_MODIFY_PATH=1; irm https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.ps1 | iex

Pinned to a release:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.sh | sh -s -- --target linux-x64 --version 0.7.8 && export PATH="$HOME/.local/bin:$PATH"

Also adding ~/.local/bin to ~/.profile (edits ~/.profile once; skipped if it already mentions ~/.local/bin; zsh login shells read ~/.zprofile instead, so use that file name there):

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.sh | sh -s -- --target linux-x64 && { grep -qs '.local/bin' ~/.profile || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile; } && export PATH="$HOME/.local/bin:$PATH"

$ ghostpaw-telegram --version

telegram 0.7.8 (binary, linux-x64)

Scripts that compare versions should use --version --short or --version --json.

A session with the 0.7.1 linux-x64 binary against a fresh database, with no token set, so outbound commands only return the planned action and nothing is sent (output piped through jq to keep it short):

The same session as an animated GIF.

Other release installers:

mise use -g github:GhostPawJS/telegram

ubi --project GhostPawJS/telegram --exe ghostpaw-telegram --in ~/.local/bin eget GhostPawJS/telegram

For aqua, define a github_release package in aqua.yaml:

registries:

• name: telegram type: local path: telegram-registry.yaml

packages:

• name: GhostPawJS/telegram@v registry: telegram

telegram-registry.yaml:

packages:

• type: github_release repo_owner: GhostPawJS repo_name: telegram asset: ghostpaw-telegram-{{trimV .Version}}-{{.OS}}-{{.Arch}}.tar.gz format: tar.gz replacements: { amd64: x64 } overrides:
• goos: windows asset: ghostpaw-telegram-{{trimV .Version}}-windows-{{.Arch}}.zip format: zip files:
• name: ghostpaw-telegram

Install scripts verify SHA256SUMS. To verify a downloaded archive's build attestation:

gh attestation verify <archive> -R GhostPawJS/telegram

Set GHOSTPAW_VERIFY=attestation for attestation verification in install.sh. Binaries are unsigned; macOS binaries carry an ad-hoc signature. For a browser download on macOS, remove quarantine with xattr -d com.apple.quarantine /path/to/ghostpaw-telegram. Linux binaries require glibc 2.28+; use npx on Alpine. See the [binary build workflow](.github/wo