{"slug":"tg-agent","title":"tg-agent","summary":"Full-spectrum Telegram actions via the tg-agent CLI — channels, collection, search, chats and messages (send, edit, delete, forward, media, participants, admins), content pipelines, analytics. Use when the user asks to do anything in Telegram, manage Telegram channels/chats/conte","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-10-16T16:28:26.016334Z","repo":{"url":"https://github.com/axisrow/tg_content_factory","stars":33,"forks":7,"license":"MIT","updatedAt":"2026-10-16T14:14:09Z"},"bodyHtml":"<hr>\n<h2>name: tg-agent\ndescription: Full-spectrum Telegram actions via the tg-agent CLI — channels, collection, search, chats and messages (send, edit, delete, forward, media, participants, admins), content pipelines, analytics. Use when the user asks to do anything in Telegram, manage Telegram channels/chats/content, or mentions tg-agent.\nallowed-tools: Bash(tg-agent *)</h2>\n<h1>tg-agent — Telegram actions for coding agents</h1>\n<p><code>tg-agent</code> is a personal Telegram automation CLI. Once installed and authorized, it lets you\nact on the user's Telegram for them: read and send messages, manage channels and chats,\ndownload media, run LLM content pipelines, and inspect analytics. Full command catalog:\n<a href=\"reference.md\">reference.md</a>.</p>\n<h2>Setup check (run once per session)</h2>\n<pre><code>tg-agent --version\n</code></pre>\n<ul>\n<li>If missing: <code>pip install tg-agent</code>, then the user must provide Telegram API credentials\n(<code>TG_API_ID</code>, <code>TG_API_HASH</code> from my.telegram.org) in <code>.env</code> in the working directory.</li>\n<li>Check an account is authorized: <code>tg-agent account list</code>. If none, first authorization is\n<strong>interactive</strong> — the user must run <code>tg-agent account add</code> themselves (they receive a\nTelegram login code). Never try to automate the code entry.</li>\n<li><code>.env</code> from the current directory is picked up automatically.</li>\n<li>If Telegram connections time out (MTProto IPs blocked on this network), set\n<code>TG_PROXY=socks5://user:pass@host:port</code> (no-auth <code>socks5://host:port</code>, or\n<code>http://host:port</code>) in <code>.env</code>. Unset/empty = direct connection.</li>\n</ul>\n<h2>How to run commands</h2>\n<pre><code>tg-agent &lt;group&gt; &lt;command&gt; [args]\n</code></pre>\n<p>Use <code>tg-agent &lt;group&gt; --help</code> and <code>tg-agent &lt;group&gt; &lt;command&gt; --help</code> liberally — flags are\nnot repeated here. Many commands support <code>--format json</code> for parseable output.</p>\n<p>Task → group (details in <a href=\"reference.md\">reference.md</a>):</p>\n<table>\n<thead>\n<tr>\n<th>Task</th>\n<th>Group</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>Read message history</td>\n<td><code>messages read &lt;id&gt; [--query TEXT --date-from D --date-to D --topic-id ID --limit N --format json]</code></td>\n</tr>\n<tr>\n<td>Search collected history</td>\n<td><code>search \"query\" [--limit N --mode local|tg|ai]</code></td>\n</tr>\n<tr>\n<td>Search-discovered channel candidates (premium search cache)</td>\n<td><code>channel candidates [--json]</code></td>\n</tr>\n<tr>\n<td>Channels: list, add, collect, stats, import</td>\n<td><code>channel</code>, <code>filter</code></td>\n</tr>\n<tr>\n<td>Chats: read, send, edit, forward, media, participants, admins — real actions, see Safety</td>\n<td><code>dialogs</code></td>\n</tr>\n<tr>\n<td>Incoming-DM reply drafts: prepare → owner approves → worker sends (queue, no double-send)</td>\n<td><code>dm drafts</code></td>\n</tr>\n<tr>\n<td>Content factory (LLM pipelines, images)</td>\n<td><code>pipeline</code>, <code>photo-loader</code></td>\n</tr>\n<tr>\n<td>Analytics, notifications, scheduling, accounts, settings</td>\n<td><code>analytics</code>, <code>notification</code>, <code>scheduler</code>, <code>account</code>, <code>settings</code></td>\n</tr>\n</tbody>\n</table>\n<h2>Safety — this is the user's real Telegram</h2>\n<p><code>dialogs *</code> commands perform <strong>real actions</strong> from the user's account to real chats.\nSending a wrong message or kicking a wrong member is not reversible by you.</p>\n<ul>\n<li><strong>Read-only</strong> (<code>dialogs list/read/topics/participants</code>, <code>channel *</code>, <code>search</code>, <code>messages read</code>,\n<code>analytics</code>): run freely.</li>\n<li><strong>Visible actions</strong> (<code>send</code>, <code>forward</code>, <code>edit-message</code>, <code>delete-message</code>, <code>react</code>,\n<code>pin-message</code>, <code>download-media</code>): only when the user explicitly asked for this action.\nConfirm target chat + content before first send in a task.</li>\n<li><strong>Destructive / hard to undo</strong> (<code>kick</code>, <code>leave</code>, <code>edit-admin</code>, <code>edit-permissions</code>,\n<code>create-channel</code>, <code>create-group</code>, <code>channel delete</code>, <code>filter purge*</code>/<code>hard-delete</code>): always ask\nan explicit yes/no confirmation naming the exact target before running, even if the user\ndescribed the intent.</li>\n<li><strong>No bulk messaging</strong> (broadcast to many chats) unless the user spelled out the exact\nrecipient list and content.</li>\n<li>On <code>FloodWait</code> errors: stop and wait the reported seconds (or tell the user); do not retry\nin a loop.</li>\n</ul>\n<h2>Background collection</h2>\n<p>One-off: <code>tg-agent channel collect --channel-id &lt;id&gt;</code> runs a collection synchronously and\nexits. Continuous/scheduled collection needs the long-lived daemon: <code>tg-agent restart</code>\nstops any previous daemon and starts the worker runtime — no web panel, no WEB_PASS\nrequired, managed via a PID file (<code>tg-agent stop</code> halts it). Check scheduler state with\n<code>tg-agent scheduler status</code>.</p>\n<p>While the daemon runs, most <code>dialogs</code> actions (<code>send</code>, <code>forward</code>, <code>react</code>, <code>refresh</code>, …)\nand <code>channel collect</code> are handed off to the worker automatically — the CLI queues them\ninstead of connecting directly. Commands that must open their own connection and have no\nqueue equivalent (<code>messages read --live</code>, <code>dialogs read</code>, <code>dialogs download-media</code>)\nare <strong>refused</strong> after a short wait (<code>SessionLockError ... held by PID N</code>): Telegram\nkills sessions seen from two connections at once. Stop the daemon (<code>tg-agent stop</code>) for\nthose. Details: <a href=\"reference.md\">reference.md</a> → \"Session lock\".</p>\n<h2>Legacy surfaces — do not use for integration</h2>\n<p>The web panel, TUI, embedded agent chat (<code>tg-agent agent chat</code>) and MCP server still work,\nbut their development is paused indefinitely (bug fixes only). For coding agents the CLI\nabove is the only supported interface.</p>\n","files":[{"path":"reference.md","sizeBytes":9345,"isText":true},{"path":"SKILL.md","sizeBytes":4996,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"notes-only","suspicious":0,"notes":7,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-16T16:28:31.778436Z","sha256":"4055FB7C83C6A1E9EFEAB05A2E2344FFAD02EB024E0AA323D539F59AF0B47FD3","sizeBytes":6740},"review":null,"source":{"repositoryUrl":"https://github.com/axisrow/tg_content_factory","path":"skills/tg-agent","license":"MIT","commit":"958486282753e1ea1cefdd1dad0835390bd6dbbc","subtreeSha":"2860F040D5843A65166DB4EADE18BF02474CBA271AF3B397A33145658A0C3602","lastSyncedAt":"2026-10-16T16:28:25.811113Z"},"reviewedAt":"2026-10-16T16:29:23.252118Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/axisrow/tg_content_factory/tree/main/skills/tg-agent"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install axisrow-tg-content-factory@llmmart"},{"target":"git","command":"git clone https://github.com/axisrow/tg_content_factory.git"}]}