@foxden-app/foxclaw 0.2.0 → 0.2.2

package/.env.example

@@ -29,7 +29,7 @@ TELEGRAM_PREVIEW_THROTTLE_MS=800
 THREAD_LIST_LIMIT=10
 CODEX_CLI_BIN=/absolute/path/to/codex
 
-# Weixin (iLink): run `npm run weixin-login` once, then enable:
+# Weixin (iLink): run `foxclaw weixin-login` once, then enable:
 # WX_ENABLED=true
 # Comma-separated iLink user ids allowed to chat (see account JSON linkedIlinkUserId)
 # WX_ALLOWED_ILINK_USER_IDS=

package/README.md

@@ -31,17 +31,24 @@ FoxClaw 是 Foxden agents 的本地执行爪。
 - 来自 `@BotFather` 的 Telegram bot token
 - 你的 Telegram 数字用户 ID
 
-## 快速设置
+## npm 快速设置
 
 ```bash
-git clone https://github.com/foxden-app/foxclaw.git
-cd foxclaw
-npm install
-cp .env.example .env
-$EDITOR .env
-npm run build
-npm run doctor
-npm run serve
+npm install -g @foxden-app/foxclaw
+foxclaw init
+$EDITOR ~/.foxclaw/.env
+foxclaw doctor
+foxclaw serve
+```
+
+pnpm 用户可以使用：
+
+```bash
+pnpm add -g @foxden-app/foxclaw
+foxclaw init
+$EDITOR ~/.foxclaw/.env
+foxclaw doctor
+foxclaw serve
 ```
 
 运行 `doctor` 或 `serve` 前先编辑 `.env`。私聊模式的最小配置：
@@ -54,6 +61,8 @@ DEFAULT_APPROVAL_POLICY=on-request
 DEFAULT_SANDBOX_MODE=workspace-write
 ```
 
+默认配置文件是 `~/.foxclaw/.env`。如果你想把配置放在别处，可以设置 `FOXCLAW_ENV=/path/to/.env`。
+
 FoxClaw 只接受来自 `TG_ALLOWED_USER_ID` 的消息。把机器人放进群组并不会让每个群成员都能使用它。
 
 <details>
@@ -79,7 +88,7 @@ FoxClaw 只接受来自 `TG_ALLOWED_USER_ID` 的消息。把机器人放进群
 Linux 用户级 systemd：
 
 ```bash
-npm run install-systemd
+foxclaw install-systemd
 systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
@@ -87,7 +96,7 @@ journalctl --user -u foxclaw.service -f
 macOS launchd：
 
 ```bash
-./scripts/launchd/install.sh
+foxclaw install-launchd
 ```
 
 默认运行时文件存储在 `~/.foxclaw`：
@@ -109,14 +118,14 @@ FoxClaw 最初 fork 自 `Gan-Xing/telegram-codex-app-bridge`，并继续以 MIT
 ```bash
 systemctl --user disable --now telegram-codex-app-bridge.service 2>/dev/null || true
 test -e ~/.foxclaw || cp -a ~/.telegram-codex-app-bridge ~/.foxclaw
-npm run install-systemd
+foxclaw install-systemd
 ```
 
 如果使用 launchd 安装，先卸载旧 plist（如存在）：
 
 ```bash
 launchctl unload ~/Library/LaunchAgents/com.ganxing.telegram-codex-app-bridge.plist 2>/dev/null || true
-./scripts/launchd/install.sh
+foxclaw install-launchd
 ```
 
 旧运行时目录不会被自动读取。如果你想保留现有绑定、缓存线程列表、审批和状态数据，请手动复制一次。
@@ -125,7 +134,7 @@ launchctl unload ~/Library/LaunchAgents/com.ganxing.telegram-codex-app-bridge.pl
 
 1. 使用 `@BotFather` 创建机器人，并把 token 填入 `TG_BOT_TOKEN`。
 2. 获取你的 Telegram 数字用户 ID，并填入 `TG_ALLOWED_USER_ID`。
-3. 使用 `npm run serve` 或服务安装器启动 FoxClaw。
+3. 使用 `foxclaw serve` 或服务安装器启动 FoxClaw。
 4. 打开与机器人的私聊并发送 `/help`。
 
 可选的群组/话题配置：
@@ -216,7 +225,7 @@ WX_ALLOWED_ILINK_USER_IDS=
 构建后运行一次二维码登录助手：
 
 ```bash
-npm run weixin-login
+foxclaw weixin-login
 ```
 
 微信运行时文件默认存储在 `~/.foxclaw/weixin`。
@@ -232,11 +241,10 @@ npm run weixin-login
 ## 运维命令
 
 ```bash
-npm run build
-npm run doctor
-npm run status
-npm run install-systemd
-npm run uninstall-systemd
+foxclaw doctor
+foxclaw status
+foxclaw install-systemd
+foxclaw uninstall-systemd
 ```
 
 ## 贡献

package/README_EN.md

@@ -31,17 +31,24 @@ The minimum install needs only a Telegram bot token, your numeric Telegram user
 - A Telegram bot token from `@BotFather`
 - Your Telegram numeric user id
 
-## Quick Setup
+## npm Quick Setup
 
 ```bash
-git clone https://github.com/foxden-app/foxclaw.git
-cd foxclaw
-npm install
-cp .env.example .env
-$EDITOR .env
-npm run build
-npm run doctor
-npm run serve
+npm install -g @foxden-app/foxclaw
+foxclaw init
+$EDITOR ~/.foxclaw/.env
+foxclaw doctor
+foxclaw serve
+```
+
+pnpm users can use:
+
+```bash
+pnpm add -g @foxden-app/foxclaw
+foxclaw init
+$EDITOR ~/.foxclaw/.env
+foxclaw doctor
+foxclaw serve
 ```
 
 Edit `.env` before running `doctor` or `serve`. Minimum private-chat config:
@@ -54,6 +61,8 @@ DEFAULT_APPROVAL_POLICY=on-request
 DEFAULT_SANDBOX_MODE=workspace-write
 ```
 
+The default config file is `~/.foxclaw/.env`. Set `FOXCLAW_ENV=/path/to/.env` if you want to keep it somewhere else.
+
 FoxClaw accepts messages only from `TG_ALLOWED_USER_ID`. Putting the bot in a group does not make it available to every group member.
 
 <details>
@@ -79,7 +88,7 @@ FoxClaw accepts messages only from `TG_ALLOWED_USER_ID`. Putting the bot in a gr
 Linux user systemd:
 
 ```bash
-npm run install-systemd
+foxclaw install-systemd
 systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
@@ -87,7 +96,7 @@ journalctl --user -u foxclaw.service -f
 macOS launchd:
 
 ```bash
-./scripts/launchd/install.sh
+foxclaw install-launchd
 ```
 
 Default runtime files are stored under `~/.foxclaw`:
@@ -109,14 +118,14 @@ When upgrading an existing local install:
 ```bash
 systemctl --user disable --now telegram-codex-app-bridge.service 2>/dev/null || true
 test -e ~/.foxclaw || cp -a ~/.telegram-codex-app-bridge ~/.foxclaw
-npm run install-systemd
+foxclaw install-systemd
 ```
 
 For launchd installs, unload the old plist if present:
 
 ```bash
 launchctl unload ~/Library/LaunchAgents/com.ganxing.telegram-codex-app-bridge.plist 2>/dev/null || true
-./scripts/launchd/install.sh
+foxclaw install-launchd
 ```
 
 The old runtime directory is not read automatically. Copy it once if you want to keep existing bindings, cached thread lists, approvals, and status data.
@@ -125,7 +134,7 @@ The old runtime directory is not read automatically. Copy it once if you want to
 
 1. Create a bot with `@BotFather` and copy the token into `TG_BOT_TOKEN`.
 2. Get your Telegram numeric user id and place it into `TG_ALLOWED_USER_ID`.
-3. Start FoxClaw with `npm run serve` or the service installer.
+3. Start FoxClaw with `foxclaw serve` or the service installer.
 4. Open a private chat with the bot and send `/help`.
 
 Optional group/topic config:
@@ -216,7 +225,7 @@ WX_ALLOWED_ILINK_USER_IDS=
 Run the QR login helper once after building:
 
 ```bash
-npm run weixin-login
+foxclaw weixin-login
 ```
 
 Weixin runtime files default to `~/.foxclaw/weixin`.
@@ -232,11 +241,10 @@ See [Troubleshooting](./docs/troubleshooting.md) for `doctor` failures, Telegram
 ## Operations
 
 ```bash
-npm run build
-npm run doctor
-npm run status
-npm run install-systemd
-npm run uninstall-systemd
+foxclaw doctor
+foxclaw status
+foxclaw install-systemd
+foxclaw uninstall-systemd
 ```
 
 ## Contributing

package/dist/config.d.ts

@@ -7,6 +7,8 @@ export declare const DEFAULT_LOG_PATH: string;
 export declare const DEFAULT_LOCK_PATH: string;
 export declare const DEFAULT_CODEX_APP_SERVER_STATE_PATH: string;
 export declare const DEFAULT_CODEX_APP_SERVER_LOG_PATH: string;
+export declare const DEFAULT_ENV_PATH: string;
+export declare function loadEnv(): void;
 export interface AppConfig {
     tgBotToken: string;
     tgAllowedUserId: string;

package/dist/config.js

@@ -3,15 +3,33 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import dotenv from 'dotenv';
-export const APP_HOME = path.join(os.homedir(), '.foxclaw');
+export const APP_HOME = path.join(process.env.HOME || os.homedir(), '.foxclaw');
 export const DEFAULT_STORE_PATH = path.join(APP_HOME, 'data', 'bridge.sqlite');
 export const DEFAULT_STATUS_PATH = path.join(APP_HOME, 'runtime', 'status.json');
 export const DEFAULT_LOG_PATH = path.join(APP_HOME, 'logs', 'service.log');
 export const DEFAULT_LOCK_PATH = path.join(APP_HOME, 'runtime', 'bridge.lock');
 export const DEFAULT_CODEX_APP_SERVER_STATE_PATH = path.join(APP_HOME, 'runtime', 'codex-app-server.json');
 export const DEFAULT_CODEX_APP_SERVER_LOG_PATH = path.join(APP_HOME, 'logs', 'codex-app-server.log');
+export const DEFAULT_ENV_PATH = path.join(APP_HOME, '.env');
+let envLoaded = false;
+export function loadEnv() {
+    if (envLoaded)
+        return;
+    envLoaded = true;
+    const explicitPath = process.env.FOXCLAW_ENV?.trim();
+    if (explicitPath) {
+        dotenv.config({ path: explicitPath });
+        return;
+    }
+    const cwdEnvPath = path.join(process.cwd(), '.env');
+    if (fs.existsSync(cwdEnvPath)) {
+        dotenv.config({ path: cwdEnvPath });
+        return;
+    }
+    dotenv.config({ path: DEFAULT_ENV_PATH });
+}
 export function loadConfig() {
-    dotenv.config();
+    loadEnv();
     const config = {
         tgBotToken: required('TG_BOT_TOKEN'),
         tgAllowedUserId: required('TG_ALLOWED_USER_ID'),

package/dist/main.js

@@ -3,26 +3,33 @@ import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { spawnSync } from 'node:child_process';
-import dotenv from 'dotenv';
-import { APP_HOME, DEFAULT_LOG_PATH, DEFAULT_STATUS_PATH, loadConfig } from './config.js';
-import { BridgeMessagingRouter } from './channels/bridge_messaging_router.js';
-import { TelegramMessagingPort } from './channels/telegram/telegram_messaging_port.js';
-import { WeixinChannelAdapter } from './channels/weixin/weixin_channel_adapter.js';
-import { WeixinMessagingPort } from './channels/weixin/weixin_messaging_port.js';
-import { attachIlinkRuntimeFromBridgeLogger } from './channels/weixin/ilink/runtime_attach.js';
-import { startWeixinLoginWithQr, waitForWeixinLogin } from './channels/weixin/ilink/login_qr.js';
-import { accountFilePath, loadWeixinAccount, saveWeixinAccount } from './channels/weixin/account_store.js';
-import { Logger } from './logger.js';
-import { BridgeStore } from './store/database.js';
-import { TelegramGateway } from './telegram/gateway.js';
-import { CodexAppClient } from './codex_app/client.js';
-import { BridgeSessionCore } from './controller/controller.js';
-import { TelegramChannelAdapter } from './channels/telegram/telegram_channel_adapter.js';
+import { fileURLToPath } from 'node:url';
+import { APP_HOME, DEFAULT_ENV_PATH, DEFAULT_LOG_PATH, DEFAULT_STATUS_PATH, loadConfig, loadEnv, } from './config.js';
 import { acquireProcessLock, LockHeldError } from './lock.js';
 import { readRuntimeStatus, writeRuntimeStatus } from './runtime.js';
 const command = process.argv[2] || 'serve';
-dotenv.config();
+loadEnv();
+const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const entryPoint = fileURLToPath(import.meta.url);
 async function main() {
+    if (command === 'init') {
+        initConfig();
+        return;
+    }
+    if (command === 'install-systemd') {
+        requireNode24(command);
+        installSystemd();
+        return;
+    }
+    if (command === 'uninstall-systemd') {
+        uninstallSystemd();
+        return;
+    }
+    if (command === 'install-launchd') {
+        requireNode24(command);
+        installLaunchd();
+        return;
+    }
     if (command === 'status') {
         const status = readRuntimeStatus(process.env.STATUS_PATH || DEFAULT_STATUS_PATH);
         if (!status) {
@@ -73,9 +80,28 @@ async function main() {
         process.exit(failed ? 1 : 0);
     }
     if (command === 'weixin-login') {
+        requireNode24(command);
         await runWeixinLoginCli();
         return;
     }
+    requireNode24(command);
+    await runServeCli();
+}
+async function runServeCli() {
+    const [{ BridgeMessagingRouter }, { TelegramMessagingPort }, { WeixinChannelAdapter }, { WeixinMessagingPort }, { attachIlinkRuntimeFromBridgeLogger }, { loadWeixinAccount }, { Logger }, { BridgeStore }, { TelegramGateway }, { CodexAppClient }, { BridgeSessionCore }, { TelegramChannelAdapter },] = await Promise.all([
+        import('./channels/bridge_messaging_router.js'),
+        import('./channels/telegram/telegram_messaging_port.js'),
+        import('./channels/weixin/weixin_channel_adapter.js'),
+        import('./channels/weixin/weixin_messaging_port.js'),
+        import('./channels/weixin/ilink/runtime_attach.js'),
+        import('./channels/weixin/account_store.js'),
+        import('./logger.js'),
+        import('./store/database.js'),
+        import('./telegram/gateway.js'),
+        import('./codex_app/client.js'),
+        import('./controller/controller.js'),
+        import('./channels/telegram/telegram_channel_adapter.js'),
+    ]);
     const config = loadConfig();
     const logger = new Logger(config.logLevel, config.logPath);
     attachIlinkRuntimeFromBridgeLogger(logger, config.wxIlinkRouteTag);
@@ -139,7 +165,177 @@ async function main() {
         throw error;
     }
 }
+function initConfig() {
+    const envPath = process.env.FOXCLAW_ENV?.trim() || DEFAULT_ENV_PATH;
+    fs.mkdirSync(path.dirname(envPath), { recursive: true });
+    if (fs.existsSync(envPath)) {
+        console.log(`Config already exists: ${envPath}`);
+        return;
+    }
+    const examplePath = path.join(packageRoot, '.env.example');
+    fs.copyFileSync(examplePath, envPath);
+    console.log(`Created ${envPath}`);
+    console.log('Edit it, then run: foxclaw doctor');
+}
+function installSystemd() {
+    if (!hasCommand('systemctl')) {
+        console.error('systemctl not found (need systemd)');
+        process.exit(1);
+    }
+    const unitName = 'foxclaw.service';
+    const userSystemdDir = path.join(process.env.XDG_CONFIG_HOME || path.join(process.env.HOME || '', '.config'), 'systemd', 'user');
+    const unitPath = path.join(userSystemdDir, unitName);
+    const configDir = path.dirname(process.env.FOXCLAW_ENV?.trim() || DEFAULT_ENV_PATH);
+    const nodeBin = process.execPath;
+    const nodeDir = path.dirname(nodeBin);
+    const pathValue = buildServicePath(nodeDir);
+    fs.mkdirSync(userSystemdDir, { recursive: true });
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.mkdirSync(path.join(APP_HOME, 'logs'), { recursive: true });
+    const foxclawEnvLine = process.env.FOXCLAW_ENV?.trim()
+        ? `Environment=FOXCLAW_ENV=${systemdEscape(process.env.FOXCLAW_ENV.trim())}\n`
+        : '';
+    fs.writeFileSync(unitPath, `[Unit]
+Description=FoxClaw local Codex execution bridge
+Documentation=https://github.com/foxden-app/foxclaw
+After=network-online.target
+Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
+
+[Service]
+Type=simple
+WorkingDirectory=${systemdEscape(configDir)}
+Environment=HOME=${systemdEscape(process.env.HOME || '')}
+Environment=USER=${systemdEscape(process.env.USER || '')}
+Environment=LOGNAME=${systemdEscape(process.env.LOGNAME || process.env.USER || '')}
+Environment=PATH=${systemdEscape(pathValue)}
+${foxclawEnvLine}ExecStart=${systemdEscape(nodeBin)} ${systemdEscape(entryPoint)} serve
+Restart=always
+RestartSec=10
+TimeoutStopSec=45
+KillMode=process
+
+[Install]
+WantedBy=default.target
+`);
+    spawnChecked('systemctl', ['--user', 'daemon-reload']);
+    spawnChecked('systemctl', ['--user', 'enable', unitName]);
+    const restarted = spawnSync('systemctl', ['--user', 'restart', unitName], { stdio: 'inherit' });
+    if (restarted.status !== 0) {
+        spawnChecked('systemctl', ['--user', 'start', unitName]);
+    }
+    console.log(`Installed ${unitPath}`);
+    console.log(`Status: systemctl --user status ${unitName}`);
+    console.log(`Logs:   journalctl --user -u ${unitName} -f`);
+}
+function uninstallSystemd() {
+    if (!hasCommand('systemctl')) {
+        console.error('systemctl not found');
+        process.exit(1);
+    }
+    const unitName = 'foxclaw.service';
+    const userSystemdDir = path.join(process.env.XDG_CONFIG_HOME || path.join(process.env.HOME || '', '.config'), 'systemd', 'user');
+    const unitPath = path.join(userSystemdDir, unitName);
+    spawnSync('systemctl', ['--user', 'disable', '--now', unitName], { stdio: 'inherit' });
+    fs.rmSync(unitPath, { force: true });
+    spawnChecked('systemctl', ['--user', 'daemon-reload']);
+    console.log(`Removed ${unitPath}`);
+}
+function installLaunchd() {
+    if (process.platform !== 'darwin') {
+        console.error('launchd install is only available on macOS');
+        process.exit(1);
+    }
+    const home = process.env.HOME || '';
+    const plist = path.join(home, 'Library', 'LaunchAgents', 'app.foxden.foxclaw.plist');
+    const configDir = path.dirname(process.env.FOXCLAW_ENV?.trim() || DEFAULT_ENV_PATH);
+    fs.mkdirSync(path.dirname(plist), { recursive: true });
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.mkdirSync(path.join(APP_HOME, 'logs'), { recursive: true });
+    const foxclawEnvXml = process.env.FOXCLAW_ENV?.trim()
+        ? `    <key>FOXCLAW_ENV</key>
+    <string>${xmlEscape(process.env.FOXCLAW_ENV.trim())}</string>
+`
+        : '';
+    fs.writeFileSync(plist, `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>app.foxden.foxclaw</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(process.execPath)}</string>
+    <string>${xmlEscape(entryPoint)}</string>
+    <string>serve</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(configDir)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xmlEscape(process.env.PATH || '')}</string>
+    <key>HOME</key>
+    <string>${xmlEscape(home)}</string>
+    <key>USER</key>
+    <string>${xmlEscape(process.env.USER || '')}</string>
+    <key>LOGNAME</key>
+    <string>${xmlEscape(process.env.LOGNAME || process.env.USER || '')}</string>
+${foxclawEnvXml}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(path.join(APP_HOME, 'logs', 'launchd.out.log'))}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(path.join(APP_HOME, 'logs', 'launchd.err.log'))}</string>
+</dict>
+</plist>
+`);
+    spawnSync('launchctl', ['unload', plist], { stdio: 'ignore' });
+    spawnChecked('launchctl', ['load', plist]);
+    console.log(`Installed ${plist}`);
+}
+function buildServicePath(nodeDir) {
+    const parts = [
+        path.join(process.env.HOME || '', '.local', 'bin'),
+        nodeDir,
+        '/usr/local/sbin',
+        '/usr/local/bin',
+        '/usr/sbin',
+        '/usr/bin',
+        '/sbin',
+        '/bin',
+    ];
+    return parts.filter((part, index) => part && parts.indexOf(part) === index).join(':');
+}
+function spawnChecked(commandName, args) {
+    const result = spawnSync(commandName, args, { stdio: 'inherit' });
+    if (result.status !== 0) {
+        process.exit(result.status || 1);
+    }
+}
+function systemdEscape(value) {
+    return value.replace(/\\/g, '\\\\').replace(/ /g, '\\x20');
+}
+function xmlEscape(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
 async function runWeixinLoginCli() {
+    const [{ attachIlinkRuntimeFromBridgeLogger }, { startWeixinLoginWithQr, waitForWeixinLogin }, { accountFilePath, saveWeixinAccount }, { Logger },] = await Promise.all([
+        import('./channels/weixin/ilink/runtime_attach.js'),
+        import('./channels/weixin/ilink/login_qr.js'),
+        import('./channels/weixin/account_store.js'),
+        import('./logger.js'),
+    ]);
     const logPath = process.env.LOG_PATH || DEFAULT_LOG_PATH;
     const level = process.env.LOG_LEVEL === 'debug' || process.env.LOG_LEVEL === 'warn' || process.env.LOG_LEVEL === 'error'
         ? process.env.LOG_LEVEL
@@ -228,6 +424,15 @@ function hasConfiguredCodexBin(binPath) {
         return false;
     }
 }
+function requireNode24(commandName) {
+    if (Number(process.versions.node.split('.')[0]) >= 24)
+        return;
+    console.error(`FoxClaw ${commandName} requires Node.js 24+. Current Node.js is ${process.version}.`);
+    console.error('Install or activate Node 24, then reinstall/re-run FoxClaw:');
+    console.error('  nvm install 24 && nvm use 24');
+    console.error('  npm install -g @foxden-app/foxclaw@latest');
+    process.exit(1);
+}
 function serializeError(error) {
     if (error instanceof Error) {
         return { message: error.message, stack: error.stack };

package/docs/agent-assisted-install.md

@@ -27,7 +27,8 @@ Send this to your agent on the target computer:
 Install FoxClaw on this machine.
 
 Repository:
-https://github.com/foxden-app/foxclaw.git
+Published package:
+@foxden-app/foxclaw
 
 Use private Telegram chat first. Do not configure group/topic mode unless I explicitly provide TG_ALLOWED_CHAT_ID or TG_ALLOWED_TOPIC_ID.
 
@@ -37,20 +38,20 @@ TG_ALLOWED_USER_ID=<paste numeric Telegram user id here>
 DEFAULT_CWD=<paste absolute working directory here>
 
 Tasks:
-1. Inspect the machine first. Do not overwrite local changes if a FoxClaw or old telegram-codex-app-bridge repo already exists.
+1. Inspect the machine first. If a FoxClaw or old telegram-codex-app-bridge service already exists, report it before changing services.
 2. Ensure Node.js 24+ is available. If not, install or activate Node 24 with nvm.
 3. Ensure the Codex CLI exists and is logged in. If login is required, stop and tell me exactly what I need to do.
-4. Clone or update https://github.com/foxden-app/foxclaw.git.
-5. Write a local .env. Never commit .env.
-6. Run npm install, npm run build, and npm run doctor.
-7. Start FoxClaw in the foreground first and ask me to send /help and /status to the Telegram bot.
+4. Install or update FoxClaw with npm install -g @foxden-app/foxclaw@latest.
+5. Run foxclaw init, then write ~/.foxclaw/.env. Never print or commit the bot token.
+6. Run foxclaw doctor.
+7. Start FoxClaw in the foreground with foxclaw serve and ask me to send /help and /status to the Telegram bot.
 8. Only after the foreground test works, install the background service:
-   - Linux: npm run install-systemd
-   - macOS: ./scripts/launchd/install.sh
+   - Linux: foxclaw install-systemd
+   - macOS: foxclaw install-launchd
 9. Verify the final state:
    - foxclaw.service is active/enabled on Linux
    - old telegram-codex-app-bridge.service is inactive/disabled if present
-   - npm run status works
+   - foxclaw status works
 10. Report the commands used, the final status, and the log command I should use if something stops working. Redact TG_BOT_TOKEN and never print the full token or full .env content.
 ```
 
@@ -61,18 +62,19 @@ Use this when the target computer is still running `telegram-codex-app-bridge`:
 ```text
 Migrate this machine from telegram-codex-app-bridge to FoxClaw.
 
-New repository:
-https://github.com/foxden-app/foxclaw.git
+New package:
+@foxden-app/foxclaw
 
 Please:
-1. Check git status before changing the repo. If there are uncommitted local changes, stop and report them.
+1. Inspect the current install method, service file, and runtime directory before changing anything.
 2. Stop and disable telegram-codex-app-bridge.service if it exists.
 3. If ~/.foxclaw does not exist and ~/.telegram-codex-app-bridge exists, copy ~/.telegram-codex-app-bridge to ~/.foxclaw.
-4. Update the source repo to https://github.com/foxden-app/foxclaw.git and pull main.
-5. Run npm install, npm run build, npm run doctor.
-6. Install and start foxclaw.service with npm run install-systemd.
-7. Verify foxclaw.service is active and telegram-codex-app-bridge.service is inactive/disabled.
-8. Report final status and any blockers. Redact TG_BOT_TOKEN and never print the full token or full .env content.
+4. Install or update FoxClaw with npm install -g @foxden-app/foxclaw@latest.
+5. Run foxclaw init if ~/.foxclaw/.env does not exist, then verify ~/.foxclaw/.env.
+6. Run foxclaw doctor.
+7. Install and start foxclaw.service with foxclaw install-systemd.
+8. Verify foxclaw.service is active and telegram-codex-app-bridge.service is inactive/disabled.
+9. Report final status and any blockers. Redact TG_BOT_TOKEN and never print the full token or full .env content.
 ```
 
 ## Safety Notes

package/docs/install-for-beginners.md

@@ -114,15 +114,22 @@ The easiest path:
 
 Use the number, not your `@username`.
 
-## 6. Download FoxClaw
+## 6. Install FoxClaw
 
-Choose a stable folder and clone the repo:
+Install the published npm package:
 
 ```bash
-git clone https://github.com/foxden-app/foxclaw.git
-cd foxclaw
-npm install
-cp .env.example .env
+npm install -g @foxden-app/foxclaw
+foxclaw init
+```
+
+This creates the config file at `~/.foxclaw/.env`.
+
+If you prefer pnpm:
+
+```bash
+pnpm add -g @foxden-app/foxclaw
+foxclaw init
 ```
 
 ## 7. Fill In `.env`
@@ -130,7 +137,7 @@ cp .env.example .env
 Open `.env` in a simple editor:
 
 ```bash
-nano .env
+nano ~/.foxclaw/.env
 ```
 
 For a first private-chat install, fill only the important values:
@@ -158,11 +165,10 @@ In `nano`, press `Ctrl+O`, Enter, then `Ctrl+X` to save and exit.
 
 ## 8. Run The First Check
 
-Build and run doctor:
+Run doctor:
 
 ```bash
-npm run build
-npm run doctor
+foxclaw doctor
 ```
 
 You want to see:
@@ -182,7 +188,7 @@ If you see `[FAIL]`, stop and check [Troubleshooting](./troubleshooting.md).
 Run FoxClaw directly before installing it as a background service:
 
 ```bash
-npm run serve
+foxclaw serve
 ```
 
 Leave this terminal open.
@@ -232,7 +238,7 @@ Only do this after foreground mode works.
 On Linux with systemd:
 
 ```bash
-npm run install-systemd
+foxclaw install-systemd
 systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
@@ -246,7 +252,7 @@ loginctl enable-linger "$USER"
 On macOS:
 
 ```bash
-./scripts/launchd/install.sh
+foxclaw install-launchd
 ```
 
 launchd starts FoxClaw when you log in.
@@ -256,7 +262,7 @@ launchd starts FoxClaw when you log in.
 Check current status:
 
 ```bash
-npm run status
+foxclaw status
 ```
 
 Restart Linux service after changing `.env`:
@@ -274,14 +280,12 @@ systemctl --user stop foxclaw.service
 Uninstall Linux service:
 
 ```bash
-npm run uninstall-systemd
+foxclaw uninstall-systemd
 ```
 
 Update FoxClaw later:
 
 ```bash
-git pull
-npm install
-npm run build
+npm install -g @foxden-app/foxclaw@latest
 systemctl --user restart foxclaw.service
 ```

package/docs/troubleshooting.md

@@ -1,10 +1,10 @@
 # Troubleshooting
 
-Start with these commands from the FoxClaw repo directory:
+Start with these commands:
 
 ```bash
-npm run doctor
-npm run status
+foxclaw doctor
+foxclaw status
 ```
 
 If FoxClaw is installed as a Linux user service, also check:
@@ -18,7 +18,7 @@ journalctl --user -u foxclaw.service -f
 
 | Symptom | Meaning | Fix |
 | --- | --- | --- |
-| `[FAIL] node >= 24` | Your current shell is using an older Node.js. | Run `nvm install 24 && nvm use 24`, then rerun `npm run doctor`. If the service uses old Node, reinstall it from a Node 24 shell with `npm run install-systemd`. |
+| `[FAIL] node >= 24` | Your current shell is using an older Node.js. | Run `nvm install 24 && nvm use 24`, then rerun `foxclaw doctor`. If the service uses old Node, reinstall it from a Node 24 shell with `foxclaw install-systemd`. |
 | `[FAIL] codex cli available` | The `codex` command is not in PATH. | Install Codex CLI or fix PATH, then confirm `codex --version` works. |
 | `[FAIL] telegram bot token configured` | `TG_BOT_TOKEN` is missing from `.env`. | Copy the token from `@BotFather` into `.env`. |
 | `[FAIL] telegram allowed user configured` | `TG_ALLOWED_USER_ID` is missing from `.env`. | Get your numeric id from `@userinfobot` and add it to `.env`. |
@@ -77,7 +77,7 @@ Check these in order:
 1. Make sure FoxClaw is running:
 
    ```bash
-   npm run status
+   foxclaw status
    ```
 
 2. Try private chat first. Open your bot directly and send:
@@ -96,7 +96,7 @@ Check these in order:
    systemctl --user restart foxclaw.service
    ```
 
-   If running foreground mode, stop with `Ctrl+C` and run `npm run serve` again.
+   If running foreground mode, stop with `Ctrl+C` and run `foxclaw serve` again.
 
 ## Group Messages Do Not Work
 
@@ -194,7 +194,7 @@ The systemd installer captures the `node` binary from your current PATH. If you
 
 ```bash
 nvm use 24
-npm run install-systemd
+foxclaw install-systemd
 systemctl --user status foxclaw.service
 ```
 
@@ -217,7 +217,7 @@ loginctl enable-linger "$USER"
 macOS launchd starts FoxClaw when you log in after running:
 
 ```bash
-./scripts/launchd/install.sh
+foxclaw install-launchd
 ```
 
 ## Migrating From The Old Project Name
@@ -227,13 +227,10 @@ If this machine still runs `telegram-codex-app-bridge`, migrate once:
 ```bash
 systemctl --user disable --now telegram-codex-app-bridge.service 2>/dev/null || true
 test -e ~/.foxclaw || cp -a ~/.telegram-codex-app-bridge ~/.foxclaw
-git remote set-url origin https://github.com/foxden-app/foxclaw.git
-git fetch origin main
-git checkout main
-git pull --ff-only origin main
-npm install
-npm run build
-npm run install-systemd
+npm install -g @foxden-app/foxclaw@latest
+foxclaw init
+foxclaw doctor
+foxclaw install-systemd
 ```
 
-If `git status --short` shows local changes before migration, stop and review those changes before pulling.
+If `~/.foxclaw/.env` already exists, `foxclaw init` leaves it untouched.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",
@@ -8,13 +8,13 @@
     "foxclaw": "dist/main.js"
   },
   "files": [
-    "dist",
-    "docs",
-    "scripts",
+    "dist",
+    "docs",
+    "scripts",
     "skills",
     ".env.example",
-    "README.md",
-    "README_EN.md",
+    "README.md",
+    "README_EN.md",
     "LICENSE"
   ],
   "private": false,
@@ -32,21 +32,23 @@
   "engines": {
     "node": ">=24"
   },
-  "scripts": {
-    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "npm run clean && tsc -p tsconfig.build.json",
-    "dev": "tsx src/main.ts serve",
-    "serve": "node dist/main.js serve",
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "dev": "tsx src/main.ts serve",
+    "serve": "node dist/main.js serve",
     "weixin-login": "node dist/main.js weixin-login",
     "status": "node dist/main.js status",
     "doctor": "node dist/main.js doctor",
-    "install-systemd": "bash scripts/systemd/install.sh",
-    "uninstall-systemd": "bash scripts/systemd/uninstall.sh",
+    "init": "node dist/main.js init",
+    "install-systemd": "node dist/main.js install-systemd",
+    "uninstall-systemd": "node dist/main.js uninstall-systemd",
+    "install-launchd": "node dist/main.js install-launchd",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
-    "test": "node --test --import tsx \"src/**/*.test.ts\"",
-    "prepack": "npm run build"
-  },
+    "test": "node --test --import tsx \"src/**/*.test.ts\"",
+    "prepack": "npm run build"
+  },
   "dependencies": {
     "dotenv": "^16.6.1",
     "qrcode-terminal": "^0.12.0"

package/scripts/doctor.sh

@@ -1,3 +1,4 @@
 #!/usr/bin/env bash
 set -euo pipefail
-node dist/main.js doctor
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+node "$ROOT_DIR/dist/main.js" doctor

package/scripts/launchd/install.sh

@@ -1,54 +1,4 @@
 #!/usr/bin/env bash
 set -euo pipefail
-ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
-PLIST="$HOME/Library/LaunchAgents/app.foxden.foxclaw.plist"
-NODE_BIN="$(command -v node)"
-PATH_VALUE="$PATH"
-HOME_VALUE="$HOME"
-USER_VALUE="${USER:-}"
-LOGNAME_VALUE="${LOGNAME:-$USER_VALUE}"
-if [[ -z "$NODE_BIN" ]]; then
-  echo "node not found in PATH" >&2
-  exit 1
-fi
-mkdir -p "$HOME/Library/LaunchAgents" "$HOME/.foxclaw/logs"
-cat > "$PLIST" <<PLIST
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key>
-  <string>app.foxden.foxclaw</string>
-  <key>ProgramArguments</key>
-  <array>
-    <string>$NODE_BIN</string>
-    <string>$ROOT_DIR/dist/main.js</string>
-    <string>serve</string>
-  </array>
-  <key>WorkingDirectory</key>
-  <string>$ROOT_DIR</string>
-  <key>EnvironmentVariables</key>
-  <dict>
-    <key>PATH</key>
-    <string>$PATH_VALUE</string>
-    <key>HOME</key>
-    <string>$HOME_VALUE</string>
-    <key>USER</key>
-    <string>$USER_VALUE</string>
-    <key>LOGNAME</key>
-    <string>$LOGNAME_VALUE</string>
-  </dict>
-  <key>RunAtLoad</key>
-  <true/>
-  <key>KeepAlive</key>
-  <true/>
-  <key>StandardOutPath</key>
-  <string>$HOME/.foxclaw/logs/launchd.out.log</string>
-  <key>StandardErrorPath</key>
-  <string>$HOME/.foxclaw/logs/launchd.err.log</string>
-</dict>
-</plist>
-PLIST
-launchctl unload "$PLIST" >/dev/null 2>&1 || true
-launchctl load "$PLIST"
-echo "Installed $PLIST"
+ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+node "$ROOT_DIR/dist/main.js" install-launchd

package/scripts/status.sh

@@ -1,3 +1,4 @@
 #!/usr/bin/env bash
 set -euo pipefail
-node dist/main.js status
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+node "$ROOT_DIR/dist/main.js" status

package/scripts/systemd/install.sh

@@ -1,83 +1,4 @@
 #!/usr/bin/env bash
 set -euo pipefail
 ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
-UNIT_NAME="foxclaw.service"
-USER_SYSTEMD_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user"
-UNIT_PATH="$USER_SYSTEMD_DIR/$UNIT_NAME"
-NODE_BIN="$(command -v node)"
-# Do not embed full interactive $PATH: WSL often includes /mnt/c/Program Files/... which breaks
-# systemd's unquoted Environment=PATH=... (spaces split the assignment). Use a small Linux PATH.
-NODE_DIR="$(dirname "$NODE_BIN")"
-PATH_VALUE="${NODE_DIR}:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
-if [[ -d "${HOME}/.local/bin" ]]; then
-  PATH_VALUE="${HOME}/.local/bin:${PATH_VALUE}"
-fi
-HOME_VALUE="${HOME:?}"
-USER_VALUE="${USER:-}"
-LOGNAME_VALUE="${LOGNAME:-$USER_VALUE}"
-
-if [[ -z "$NODE_BIN" ]]; then
-  echo "node not found in PATH" >&2
-  exit 1
-fi
-
-if ! command -v systemctl >/dev/null 2>&1; then
-  echo "systemctl not found (need systemd)" >&2
-  exit 1
-fi
-
-NO_BUILD=0
-NO_START=0
-for arg in "$@"; do
-  case "$arg" in
-    --no-build) NO_BUILD=1 ;;
-    --no-start) NO_START=1 ;;
-  esac
-done
-
-if [[ "$NO_BUILD" -eq 0 ]]; then
-  (cd "$ROOT_DIR" && npm run build)
-fi
-
-mkdir -p "$USER_SYSTEMD_DIR" "$HOME/.foxclaw/logs"
-
-cat >"$UNIT_PATH" <<UNIT
-[Unit]
-Description=FoxClaw local Codex execution bridge
-Documentation=https://github.com/foxden-app/foxclaw
-After=network-online.target
-Wants=network-online.target
-StartLimitIntervalSec=300
-StartLimitBurst=5
-
-[Service]
-Type=simple
-WorkingDirectory=$ROOT_DIR
-Environment=HOME=$HOME_VALUE
-Environment=USER=$USER_VALUE
-Environment=LOGNAME=$LOGNAME_VALUE
-Environment=PATH=$PATH_VALUE
-ExecStart=$NODE_BIN dist/main.js serve
-Restart=always
-RestartSec=10
-TimeoutStopSec=45
-KillMode=process
-
-[Install]
-WantedBy=default.target
-UNIT
-
-systemctl --user daemon-reload
-systemctl --user enable "$UNIT_NAME"
-if [[ "$NO_START" -eq 0 ]]; then
-  systemctl --user restart "$UNIT_NAME" || systemctl --user start "$UNIT_NAME"
-fi
-
-echo "Installed $UNIT_PATH"
-echo "Status: systemctl --user status $UNIT_NAME"
-echo "Logs:   journalctl --user -u $UNIT_NAME -f"
-if [[ "$(loginctl show-user "$USER" -p Linger --value 2>/dev/null || true)" != "yes" ]]; then
-  echo ""
-  echo "Tip: for this service to start at boot without an interactive login, run once:"
-  echo "  loginctl enable-linger $USER"
-fi
+node "$ROOT_DIR/dist/main.js" install-systemd

package/scripts/systemd/uninstall.sh

@@ -1,15 +1,4 @@
 #!/usr/bin/env bash
 set -euo pipefail
-UNIT_NAME="foxclaw.service"
-USER_SYSTEMD_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user"
-UNIT_PATH="$USER_SYSTEMD_DIR/$UNIT_NAME"
-
-if ! command -v systemctl >/dev/null 2>&1; then
-  echo "systemctl not found" >&2
-  exit 1
-fi
-
-systemctl --user disable --now "$UNIT_NAME" 2>/dev/null || true
-rm -f "$UNIT_PATH"
-systemctl --user daemon-reload
-echo "Removed $UNIT_PATH"
+ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+node "$ROOT_DIR/dist/main.js" uninstall-systemd