@foxden-app/foxclaw 0.2.0

package/docs/agent-assisted-install.md

@@ -0,0 +1,84 @@
+# Agent-Assisted Install
+
+If you already have a shell-capable coding agent on the target computer, use this path first. It is the fastest and least error-prone way to install FoxClaw.
+
+This works well with Codex, OpenClaw, QwenPaw, Hermes, OpenCode, Kimi CLI, or any agent that can inspect the machine, run shell commands, edit files, and report blockers.
+
+## What You Need To Provide
+
+Prepare these values before asking the agent:
+
+- `TG_BOT_TOKEN`: Telegram bot token from `@BotFather`
+- `TG_ALLOWED_USER_ID`: your numeric Telegram user id
+- `DEFAULT_CWD`: the folder where Codex should work
+
+Optional later:
+
+- `TG_ALLOWED_CHAT_ID`
+- `TG_ALLOWED_TOPIC_ID`
+
+Use private Telegram chat first. Configure groups/topics only after private chat works.
+
+## Copy-Paste Prompt
+
+Send this to your agent on the target computer:
+
+```text
+Install FoxClaw on this machine.
+
+Repository:
+https://github.com/foxden-app/foxclaw.git
+
+Use private Telegram chat first. Do not configure group/topic mode unless I explicitly provide TG_ALLOWED_CHAT_ID or TG_ALLOWED_TOPIC_ID.
+
+Here are the required values:
+TG_BOT_TOKEN=<paste token here>
+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.
+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.
+8. Only after the foreground test works, install the background service:
+   - Linux: npm run install-systemd
+   - macOS: ./scripts/launchd/install.sh
+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
+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.
+```
+
+## Migration Prompt For Old Installs
+
+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
+
+Please:
+1. Check git status before changing the repo. If there are uncommitted local changes, stop and report them.
+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.
+```
+
+## Safety Notes
+
+- Do not paste bot tokens into public issue trackers or public chat logs.
+- Do not commit `.env`.
+- When reporting results, redact `TG_BOT_TOKEN`.
+- Do not use `/` or your whole home directory as `DEFAULT_CWD` for a first install.
+- Do not install the background service before the foreground Telegram test works.

package/docs/install-for-beginners.md

@@ -0,0 +1,287 @@
+# Beginner Install Guide
+
+This guide is for a first FoxClaw install. It assumes you can open a terminal and paste commands, but it does not assume you already know Node.js, Telegram bots, or Codex CLI.
+
+FoxClaw runs on your own computer. Your phone talks to a Telegram bot, the bot talks to FoxClaw, and FoxClaw talks to local Codex. You do not need a public server.
+
+If you already have a shell-capable agent such as Codex, OpenClaw, QwenPaw, Hermes, OpenCode, or Kimi CLI on this computer, use [Agent-Assisted Install](./agent-assisted-install.md) first. It is the recommended path.
+
+Before you start:
+
+- Do not configure a Telegram group first. Use private chat first.
+- Do not send your bot token to anyone you do not trust.
+- Do not use `/`, `/Users`, `/home`, or your whole home directory as `DEFAULT_CWD` for the first install.
+- Do not install the background service until foreground mode replies to `/help` and `/status`.
+
+## 1. Prepare
+
+You need:
+
+- a macOS or Linux computer that can stay on while you use FoxClaw
+- a Telegram account
+- a Codex account
+- a folder where Codex can work, for example `~/Projects` or `~/Desktop`
+- about 10-20 minutes for the first setup
+
+Use private chat first. Group and topic setup can wait until the bot replies reliably.
+
+## 2. Install Node.js 24
+
+FoxClaw needs Node.js 24 because it uses the built-in SQLite runtime.
+
+If you already have Node 24, this should print `v24...`:
+
+```bash
+node -v
+```
+
+If not, install Node 24 with `nvm`:
+
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+nvm install 24
+nvm use 24
+node -v
+npm -v
+```
+
+If `node -v` still shows an old version, close the terminal, open a new one, and run:
+
+```bash
+nvm use 24
+```
+
+## 3. Install And Log In To Codex
+
+FoxClaw does not create a Codex account. It uses the Codex CLI already logged in on this computer.
+
+Install the Codex CLI if you do not already have it:
+
+```bash
+npm install -g @openai/codex
+```
+
+If this fails with `EACCES` or `permission denied`, stop and check [Troubleshooting](./troubleshooting.md). Do not keep retrying with random `sudo` commands.
+
+Log in:
+
+```bash
+codex login
+```
+
+Check the CLI exists:
+
+```bash
+codex --version
+```
+
+`codex --version` only proves the command exists. To verify Codex auth actually works, start Codex and run one tiny request:
+
+```bash
+codex
+```
+
+Ask it:
+
+```text
+Say ready and exit.
+```
+
+If your Codex CLI supports `codex login status`, you can also use it, but the real test is that Codex can answer a normal prompt without asking you to log in again.
+
+## 4. Create A Telegram Bot
+
+1. Open Telegram.
+2. Search for `@BotFather`.
+3. Send `/newbot`.
+4. Follow the prompts and choose a bot name.
+5. Copy the bot token. It looks like `123456789:AA...`.
+
+Keep this token private. Anyone with the token can control that Telegram bot.
+
+## 5. Get Your Numeric Telegram User ID
+
+FoxClaw only accepts messages from one configured Telegram user.
+
+The easiest path:
+
+1. Open Telegram.
+2. Search for `@userinfobot`.
+3. Send it any message or press Start.
+4. Copy the numeric `Id`.
+
+Use the number, not your `@username`.
+
+## 6. Download FoxClaw
+
+Choose a stable folder and clone the repo:
+
+```bash
+git clone https://github.com/foxden-app/foxclaw.git
+cd foxclaw
+npm install
+cp .env.example .env
+```
+
+## 7. Fill In `.env`
+
+Open `.env` in a simple editor:
+
+```bash
+nano .env
+```
+
+For a first private-chat install, fill only the important values:
+
+```dotenv
+TG_BOT_TOKEN=123456789:replace_with_your_bot_token
+TG_ALLOWED_USER_ID=123456789
+TG_ALLOWED_CHAT_ID=
+TG_ALLOWED_TOPIC_ID=
+DEFAULT_CWD=/absolute/path/to/a/folder
+DEFAULT_APPROVAL_POLICY=on-request
+DEFAULT_SANDBOX_MODE=workspace-write
+```
+
+Keep `TG_ALLOWED_CHAT_ID=` and `TG_ALLOWED_TOPIC_ID=` empty for the first install. Do not delete those lines; leaving them empty means private-chat mode.
+
+`DEFAULT_CWD` must be a real folder. Examples:
+
+```dotenv
+DEFAULT_CWD=/Users/alice/Desktop
+DEFAULT_CWD=/home/alice/projects
+```
+
+In `nano`, press `Ctrl+O`, Enter, then `Ctrl+X` to save and exit.
+
+## 8. Run The First Check
+
+Build and run doctor:
+
+```bash
+npm run build
+npm run doctor
+```
+
+You want to see:
+
+```text
+[OK] node >= 24
+[OK] codex cli available
+[OK] telegram bot token configured
+[OK] telegram allowed user configured
+[OK] default cwd exists
+```
+
+If you see `[FAIL]`, stop and check [Troubleshooting](./troubleshooting.md).
+
+## 9. Start In The Foreground First
+
+Run FoxClaw directly before installing it as a background service:
+
+```bash
+npm run serve
+```
+
+Leave this terminal open.
+
+Now open your Telegram bot and send:
+
+```text
+/help
+```
+
+If it replies, send:
+
+```text
+/status
+```
+
+Then try a normal request, for example:
+
+```text
+List the files in the current working directory.
+```
+
+Good first messages to try:
+
+```text
+/setup
+```
+
+```text
+List files in DEFAULT_CWD.
+```
+
+```text
+Create a short README-style summary of this folder.
+```
+
+```text
+/interrupt
+```
+
+Stop the foreground process with `Ctrl+C` after the bot works.
+
+## 10. Install As A Background Service
+
+Only do this after foreground mode works.
+
+On Linux with systemd:
+
+```bash
+npm run install-systemd
+systemctl --user status foxclaw.service
+journalctl --user -u foxclaw.service -f
+```
+
+The service starts again when your user session starts. If you need it to start after reboot before you log in, run:
+
+```bash
+loginctl enable-linger "$USER"
+```
+
+On macOS:
+
+```bash
+./scripts/launchd/install.sh
+```
+
+launchd starts FoxClaw when you log in.
+
+## 11. Day-To-Day Commands
+
+Check current status:
+
+```bash
+npm run status
+```
+
+Restart Linux service after changing `.env`:
+
+```bash
+systemctl --user restart foxclaw.service
+```
+
+Stop Linux service:
+
+```bash
+systemctl --user stop foxclaw.service
+```
+
+Uninstall Linux service:
+
+```bash
+npm run uninstall-systemd
+```
+
+Update FoxClaw later:
+
+```bash
+git pull
+npm install
+npm run build
+systemctl --user restart foxclaw.service
+```

package/docs/troubleshooting.md

@@ -0,0 +1,239 @@
+# Troubleshooting
+
+Start with these commands from the FoxClaw repo directory:
+
+```bash
+npm run doctor
+npm run status
+```
+
+If FoxClaw is installed as a Linux user service, also check:
+
+```bash
+systemctl --user status foxclaw.service
+journalctl --user -u foxclaw.service -f
+```
+
+## Doctor Failures
+
+| 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] 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`. |
+| `[FAIL] default cwd exists` | `DEFAULT_CWD` points to a folder that does not exist. | Create the folder or change `DEFAULT_CWD` to an existing absolute path. |
+
+## Node Or npm Is Missing
+
+If you see `node: command not found` or `npm: command not found`, install Node.js 24 with `nvm`:
+
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+nvm install 24
+nvm use 24
+node -v
+npm -v
+```
+
+If it still fails, close the terminal, open a new one, and run:
+
+```bash
+nvm use 24
+```
+
+## npm Permission Errors
+
+If `npm install -g @openai/codex` fails with `EACCES`, `EPERM`, or `permission denied`, your global npm directory is not writable by your user.
+
+Recommended fix: use Node through `nvm`, then install again:
+
+```bash
+nvm install 24
+nvm use 24
+npm install -g @openai/codex
+```
+
+Avoid `sudo npm install -g ...` unless you already understand how your Node installation is managed. Mixing `sudo`, system Node, and `nvm` is a common source of broken PATHs.
+
+If `codex` installs but FoxClaw still cannot find it, locate the binary:
+
+```bash
+command -v codex
+```
+
+Then put the absolute path in `.env`:
+
+```dotenv
+CODEX_CLI_BIN=/absolute/path/to/codex
+```
+
+## Bot Does Not Reply
+
+Check these in order:
+
+1. Make sure FoxClaw is running:
+
+   ```bash
+   npm run status
+   ```
+
+2. Try private chat first. Open your bot directly and send:
+
+   ```text
+   /help
+   ```
+
+3. Confirm `TG_ALLOWED_USER_ID` is your numeric Telegram id, not your `@username`.
+
+4. Confirm the bot token in `.env` belongs to the bot you are messaging.
+
+5. Restart after changing `.env`:
+
+   ```bash
+   systemctl --user restart foxclaw.service
+   ```
+
+   If running foreground mode, stop with `Ctrl+C` and run `npm run serve` again.
+
+## Group Messages Do Not Work
+
+Private chat is the easiest mode. For groups and topics:
+
+1. Add the bot to the group.
+2. Disable the bot's `privacy mode` in `@BotFather`.
+3. Promote the bot to administrator.
+4. Remove and re-add the bot if privacy mode was changed after it joined.
+5. Configure `TG_ALLOWED_CHAT_ID`, and optionally `TG_ALLOWED_TOPIC_ID`.
+
+Explicit commands such as `/status@botname` can work even when normal group messages are blocked by privacy mode, so verify with a plain natural-language message too.
+
+## Get Group Or Topic IDs
+
+1. Stop FoxClaw.
+2. Send a new message in the target group or topic.
+3. Open:
+
+   ```text
+   https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
+   ```
+
+4. Use `message.chat.id` as `TG_ALLOWED_CHAT_ID`.
+5. Use `message.message_thread_id` as `TG_ALLOWED_TOPIC_ID`.
+
+If FoxClaw is still running, it may consume the update before you inspect it.
+
+## Telegram Polling Conflict
+
+If Telegram reports conflicts or the same bot behaves strangely, two processes may be polling the same bot token.
+
+Check old and new services:
+
+```bash
+systemctl --user is-active foxclaw.service
+systemctl --user is-active telegram-codex-app-bridge.service 2>/dev/null || true
+```
+
+Stop the old service:
+
+```bash
+systemctl --user disable --now telegram-codex-app-bridge.service
+```
+
+Then restart FoxClaw:
+
+```bash
+systemctl --user restart foxclaw.service
+```
+
+## Codex Or App-Server Fails
+
+FoxClaw requires local Codex auth. Check:
+
+```bash
+codex --version
+```
+
+If Codex is not logged in:
+
+```bash
+codex login
+```
+
+`codex --version` only verifies the command exists. To verify auth, run:
+
+```bash
+codex
+```
+
+Then ask:
+
+```text
+Say ready and exit.
+```
+
+If your CLI supports `codex login status`, that is also useful, but a normal successful prompt is the most reliable check.
+
+FoxClaw app-server logs are stored here by default:
+
+```bash
+tail -f ~/.foxclaw/logs/codex-app-server.log
+```
+
+Bridge logs are stored here:
+
+```bash
+tail -f ~/.foxclaw/logs/service.log
+```
+
+## Service Starts With The Wrong Node Version
+
+The systemd installer captures the `node` binary from your current PATH. If you installed the service from a shell using Node 22 or older, reinstall it from a Node 24 shell:
+
+```bash
+nvm use 24
+npm run install-systemd
+systemctl --user status foxclaw.service
+```
+
+The status output should show a Node 24 path in `ExecStart`.
+
+## Does It Run After Reboot?
+
+Linux user systemd:
+
+```bash
+systemctl --user is-enabled foxclaw.service
+```
+
+`enabled` means it starts with your user session. To start after reboot before login:
+
+```bash
+loginctl enable-linger "$USER"
+```
+
+macOS launchd starts FoxClaw when you log in after running:
+
+```bash
+./scripts/launchd/install.sh
+```
+
+## Migrating From The Old Project Name
+
+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
+```
+
+If `git status --short` shows local changes before migration, stop and review those changes before pulling.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@foxden-app/foxclaw",
+  "version": "0.2.0",
+  "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
+  "type": "module",
+  "main": "dist/main.js",
+  "bin": {
+    "foxclaw": "dist/main.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "scripts",
+    "skills",
+    ".env.example",
+    "README.md",
+    "README_EN.md",
+    "LICENSE"
+  ],
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/foxden-app/foxclaw.git"
+  },
+  "homepage": "https://github.com/foxden-app/foxclaw#readme",
+  "bugs": {
+    "url": "https://github.com/foxden-app/foxclaw/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "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",
+    "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",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "node --test --import tsx \"src/**/*.test.ts\"",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "dotenv": "^16.6.1",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.0",
+    "@types/node": "^24.12.0",
+    "eslint": "^9.39.0",
+    "tsx": "^4.19.3",
+    "typescript": "5.9.3",
+    "typescript-eslint": "^8.58.0"
+  }
+}

package/scripts/doctor.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+node dist/main.js doctor