feat: persist telegram skill and mcp state

Author: MackDing

.env.example

@@ -1,6 +1,7 @@
 BOT_TOKEN=123456789:telegram-token-from-botfather
 ALLOWED_USER_IDS=123456789,987654321
 PROACTIVE_USER_IDS=123456789
+STATE_FILE=.codex-telegram-claws-state.json
 
 CODEX_COMMAND=codex
 CODEX_ARGS=

.gitignore

@@ -2,3 +2,4 @@ node_modules/
 .env
 .DS_Store
 npm-debug.log*
+.codex-telegram-claws-state.json

README.md

@@ -47,6 +47,7 @@ Minimum required:
 ```bash
 BOT_TOKEN=123456789:telegram-token
 ALLOWED_USER_IDS=123456789
+STATE_FILE=.codex-telegram-claws-state.json
 WORKSPACE_ROOT=.
 CODEX_WORKDIR=.
 ```
@@ -201,6 +202,7 @@ Required:
 ```bash
 BOT_TOKEN=...
 ALLOWED_USER_IDS=123456789,987654321
+STATE_FILE=.codex-telegram-claws-state.json
 WORKSPACE_ROOT=.
 CODEX_WORKDIR=.
 ```
@@ -211,6 +213,7 @@ Common options:
 CODEX_COMMAND=codex
 CODEX_ARGS=
 WORKSPACE_ROOT=/Users/yourname/projects
+STATE_FILE=/path/to/codex-telegram-claws-state.json
 SHELL_ENABLED=false
 SHELL_READ_ONLY=true
 SHELL_ALLOWED_COMMANDS=["pwd","ls","git status","git diff --stat","npm test","npm run check"]
@@ -274,6 +277,7 @@ Telegram can manage runtime usage of Bot-side MCP and skills, but not install ar
 - MCP servers are process-level runtime resources: list, inspect, reconnect, enable, disable
 - Skills are chat-level routing switches: each chat can enable or disable `github` and `mcp` independently
 - Codex's own MCP remains separate and is not managed through these bot commands
+- Runtime state is persisted to `STATE_FILE`, so `/mcp enable|disable` and `/skill on|off` survive bot restarts
 
 ## Troubleshooting
 

src/config.js

@@ -64,6 +64,17 @@ function resolveDirectory(value, name, fallback = process.cwd()) {
   return resolvedFallback;
 }
 
+function resolveFile(value, fallback) {
+  const candidate = path.resolve(value || fallback);
+  const directory = path.dirname(candidate);
+
+  if (!fs.existsSync(directory)) {
+    fs.mkdirSync(directory, { recursive: true });
+  }
+
+  return candidate;
+}
+
 function normalizeMcpServer(raw, index) {
   if (!raw || typeof raw !== "object") return null;
   if (!raw.name || !raw.command) {
@@ -113,7 +124,11 @@ export function loadConfig() {
 
   return {
     app: {
-      name: "codex-telegram-claws"
+      name: "codex-telegram-claws",
+      stateFile: resolveFile(
+        process.env.STATE_FILE,
+        path.join(process.cwd(), ".codex-telegram-claws-state.json")
+      )
     },
     workspace: {
       root: workspaceRoot

src/index.js

@@ -1,5 +1,6 @@
 import { Telegraf } from "telegraf";
 import { loadConfig } from "./config.js";
+import { RuntimeStateStore } from "./runtimeStateStore.js";
 import { createAuthMiddleware } from "./bot/middleware.js";
 import { registerHandlers } from "./bot/handlers.js";
 import { Router } from "./orchestrator/router.js";
@@ -15,10 +16,25 @@ const config = loadConfig();
 const bot = new Telegraf(config.telegram.botToken, {
   handlerTimeout: 120000
 });
+const stateStore = new RuntimeStateStore({ config });
+let mcpClient;
+let skillRegistry;
+
+async function saveRuntimeState() {
+  if (!mcpClient || !skillRegistry) return;
+  await stateStore.save({
+    mcp: mcpClient.exportState(),
+    skills: skillRegistry.exportState()
+  });
+}
 
 bot.use(createAuthMiddleware(config));
 
-const mcpClient = new McpClient(config);
+const runtimeState = await stateStore.load();
+mcpClient = new McpClient(config, {
+  onChange: () => void saveRuntimeState()
+});
+mcpClient.restoreState(runtimeState.mcp);
 await mcpClient.connectAll().catch((error) => {
   console.error("[mcp] connect failed:", error.message);
 });
@@ -29,7 +45,10 @@ const skills = {
   github: githubSkill,
   mcp: mcpSkill
 };
-const skillRegistry = new SkillRegistry(skills);
+skillRegistry = new SkillRegistry(skills, {
+  onChange: () => void saveRuntimeState()
+});
+skillRegistry.restoreState(runtimeState.skills);
 
 const router = new Router({
   skills,

src/orchestrator/mcpClient.js

@@ -25,10 +25,11 @@ function normalizeToolContent(result) {
 }
 
 export class McpClient {
-  constructor(config) {
+  constructor(config, { onChange } = {}) {
     this.config = config;
     this.connections = new Map();
     this.disabledServers = new Set();
+    this.onChange = onChange;
   }
 
   hasServers() {
@@ -147,6 +148,7 @@ export class McpClient {
 
     this.disabledServers.add(serverName);
     await this.disconnectServer(serverName);
+    this.onChange?.(this.exportState());
     return this.listServers().find((server) => server.name === serverName) || null;
   }
 
@@ -157,9 +159,24 @@ export class McpClient {
 
     this.disabledServers.delete(serverName);
     await this.connectServerByName(serverName);
+    this.onChange?.(this.exportState());
     return this.listServers().find((server) => server.name === serverName) || null;
   }
 
+  exportState() {
+    return {
+      disabledServers: [...this.disabledServers].sort()
+    };
+  }
+
+  restoreState(snapshot = {}) {
+    const disabledServers = Array.isArray(snapshot?.disabledServers)
+      ? snapshot.disabledServers.filter((serverName) => this.hasServer(serverName))
+      : [];
+
+    this.disabledServers = new Set(disabledServers);
+  }
+
   async listTools(serverName) {
     const conn = this.connections.get(serverName);
     if (!conn) throw new Error(`MCP server not connected: ${serverName}`);

src/orchestrator/skillRegistry.js

@@ -1,7 +1,8 @@
 export class SkillRegistry {
-  constructor(skills = {}) {
+  constructor(skills = {}, { onChange } = {}) {
     this.skillNames = Object.keys(skills).sort();
     this.chatStates = new Map();
+    this.onChange = onChange;
   }
 
   normalizeSkillName(name) {
@@ -47,13 +48,47 @@ export class SkillRegistry {
     const normalized = this.ensureKnownSkill(name);
     const state = this.ensureChatState(chatId);
     state.enabledSkills.add(normalized);
+    this.onChange?.(this.exportState());
     return this.list(chatId);
   }
 
   disable(chatId, name) {
     const normalized = this.ensureKnownSkill(name);
     const state = this.ensureChatState(chatId);
     state.enabledSkills.delete(normalized);
+    this.onChange?.(this.exportState());
     return this.list(chatId);
   }
+
+  exportState() {
+    const chats = {};
+    for (const [chatId, state] of this.chatStates.entries()) {
+      chats[chatId] = {
+        enabledSkills: [...state.enabledSkills].sort()
+      };
+    }
+
+    return {
+      chats
+    };
+  }
+
+  restoreState(snapshot = {}) {
+    const chats = snapshot?.chats;
+    if (!chats || typeof chats !== "object") return;
+
+    this.chatStates.clear();
+
+    for (const [chatId, state] of Object.entries(chats)) {
+      const enabledSkills = Array.isArray(state?.enabledSkills)
+        ? state.enabledSkills
+            .map((skill) => this.normalizeSkillName(skill))
+            .filter((skill) => this.skillNames.includes(skill))
+        : this.skillNames;
+
+      this.chatStates.set(String(chatId), {
+        enabledSkills: new Set(enabledSkills)
+      });
+    }
+  }
 }

src/runtimeStateStore.js

@@ -0,0 +1,70 @@
+import fs from "node:fs/promises";
+
+function defaultState() {
+  return {
+    version: 1,
+    mcp: {
+      disabledServers: []
+    },
+    skills: {
+      chats: {}
+    }
+  };
+}
+
+export class RuntimeStateStore {
+  constructor({ config }) {
+    this.file = config.app.stateFile;
+    this.writeQueue = Promise.resolve();
+  }
+
+  async load() {
+    try {
+      const raw = await fs.readFile(this.file, "utf8");
+      const parsed = JSON.parse(raw);
+      return {
+        ...defaultState(),
+        ...parsed,
+        mcp: {
+          ...defaultState().mcp,
+          ...(parsed?.mcp || {})
+        },
+        skills: {
+          ...defaultState().skills,
+          ...(parsed?.skills || {})
+        }
+      };
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        return defaultState();
+      }
+
+      console.warn(`[state] failed to load runtime state: ${error.message}`);
+      return defaultState();
+    }
+  }
+
+  async save(snapshot) {
+    const payload = JSON.stringify(
+      {
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        ...snapshot
+      },
+      null,
+      2
+    );
+
+    this.writeQueue = this.writeQueue
+      .then(async () => {
+        const tempFile = `${this.file}.tmp`;
+        await fs.writeFile(tempFile, payload, "utf8");
+        await fs.rename(tempFile, this.file);
+      })
+      .catch((error) => {
+        console.warn(`[state] failed to save runtime state: ${error.message}`);
+      });
+
+    return this.writeQueue;
+  }
+}

tests/config.test.js

@@ -1,11 +1,14 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
 import { loadConfig } from "../src/config.js";
 
 const ENV_KEYS = [
   "BOT_TOKEN",
   "ALLOWED_USER_IDS",
   "PROACTIVE_USER_IDS",
+  "STATE_FILE",
   "CODEX_COMMAND",
   "CODEX_ARGS",
   "CODEX_WORKDIR",
@@ -63,11 +66,13 @@ function withMutedWarnings(fn) {
 }
 
 test("loadConfig parses env values into runtime config", () => {
+  const stateFile = path.join(os.tmpdir(), "codex-telegram-claws-runtime-state.json");
   const config = withEnv(
     {
       BOT_TOKEN: "telegram-token",
       ALLOWED_USER_IDS: "1, 2",
       PROACTIVE_USER_IDS: "2",
+      STATE_FILE: stateFile,
       CODEX_COMMAND: "codex",
       CODEX_ARGS: "--approval-mode auto \"--model gpt-5\"",
       CODEX_WORKDIR: ".",
@@ -94,6 +99,7 @@ test("loadConfig parses env values into runtime config", () => {
   );
 
   assert.equal(config.telegram.botToken, "telegram-token");
+  assert.equal(config.app.stateFile, stateFile);
   assert.deepEqual(config.telegram.allowedUserIds, ["1", "2"]);
   assert.deepEqual(config.telegram.proactiveUserIds, ["2"]);
   assert.equal(config.runner.command, "codex");

tests/mcpClient.test.js

@@ -92,3 +92,16 @@ test("mcp client reconnect refreshes a known enabled server", async () => {
   assert.deepEqual(closes, ["context7"]);
   assert.equal(connectCalls, 1);
 });
+
+test("mcp client exports and restores disabled server state", () => {
+  const client = createClient();
+  client.restoreState({
+    disabledServers: ["sequential-thinking"]
+  });
+
+  assert.deepEqual(client.exportState(), {
+    disabledServers: ["sequential-thinking"]
+  });
+  assert.equal(client.isServerEnabled("sequential-thinking"), false);
+  assert.equal(client.isServerEnabled("context7"), true);
+});