tg_cursor_pocket

Telegram bot that drives the Cursor SDK locally: forum topics, per-topic workspace cwd, whitelist, session active_profile_id, and secrets merged from a shared directory (AGENT_SHARED_SECRETS_DIR → sorted *.env) plus optional overlay TG_AGENT_ROOT/profiles/<id>.env.

User-facing docs: docs/userguide-eng/ and docs/userguide-rus/.

Quick start

cd tg_cursor_pocket
cp .env.example .env
# fill .env — use absolute paths where required
npm install
npm run dev

In a forum supergroup: send /start — the bot replies with chat.id and message_thread_id for your allowlist.

Environment

Variable	Purpose
TELEGRAM_BOT_TOKEN	from @BotFather
TELEGRAM_ALLOWED_CHAT_IDS	optional, comma-separated
TELEGRAM_ALLOWED_USER_IDS	optional
CURSOR_API_KEY	bot .env or shared *.env
CURSOR_MODEL	default model id (e.g. composer-2)
TG_AGENT_ROOT	bot data: profiles/, workspaces/, bot.sqlite
AGENT_SHARED_SECRETS_DIR	directory: all *.env merged (sorted)
DEFAULT_PROFILE_ID	loads TG_AGENT_ROOT/profiles/<id>.env when present

Variable names without values

• In repo: shared_secrets.example/env.keys.example — human template.
• Script: npm run profile:keys -- /path/to/a.env /path/to/b.env — prints sorted key names from real files.

The bot builds the “shared secrets name catalog” for the agent from the same parsing logic (no extra MCP for that).

Commands

Command	Behaviour
/start	chat.id, topic, profile
/profile <id>	Switch profile → reload shared + profiles/<id>.env, reset Cursor agent for that chat/topic
/workspaces	Button menu: entries under TG_AGENT_ROOT/workspaces/catalog/ + topic folder
/newsession	New agent session, same cwd (change folder via /workspaces)

Cursor SDK

• Any plain text message (not starting with /) → Agent.resume / Agent.create, stream to Telegram (~3800 chars per chunk in Markdown mode).
• A second message in the same chat/topic while a run is active → “busy” reply (no queue yet).
• Full stream + user payload is appended to <cwd>/logs/<runId>.log (topic workspace); on success, a short message with the log path.
• Default cwd: per-topic workspace under workspaces/catalog/...; after /workspaces — absolute path to a catalog subfolder.
• SQLite: TG_AGENT_ROOT/bot.sqlite stores agent_id per (chat_id, thread_id).
• Optional HTTP MCP after bootstrap: Tavily (TAVILY_API_KEY), Supabase (SUPABASE_ACCESS_TOKEN + SUPABASE_MCP_PROJECT_REF).
• Bundled stdio MCP pocket_agent: shell, grep/glob, topic files, etc. (see code and user guides).

Status

Working bot: Composer (Cursor) SDK, /workspaces, General menu, profiles, shared secrets, pocket_agent MCP, Telegram HTML/Markdown safeguards. Further work as needed (queueing, richer diagnostics).