@foxden-app/foxclaw 0.2.0

package/scripts/launchd/install.sh

@@ -0,0 +1,54 @@
+#!/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"

package/scripts/status.sh

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

package/scripts/systemd/install.sh

@@ -0,0 +1,83 @@
+#!/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

package/scripts/systemd/uninstall.sh

@@ -0,0 +1,15 @@
+#!/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"

package/skills/foxclaw/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: foxclaw
+description: Deploy, configure, and validate FoxClaw on macOS, locally or over SSH. Use when Codex needs to clone or update the FoxClaw repo, collect Telegram bot and chat/topic values, write `.env`, enable a launchd service, and guide the user through the first Telegram message test. Trigger on requests about trusted chat interfaces controlling local Codex, copying FoxClaw to another Mac, remote FoxClaw deployment, or turning this repo into an installable Codex skill.
+---
+
+# FoxClaw
+
+Deploy FoxClaw to a Mac with as little manual setup as possible. The bundled scripts install user-scoped Node.js and Codex CLI when missing, clone or update the FoxClaw repo, write `.env`, build the project, run doctor checks, and optionally install the launchd service.
+
+This skill is not finished when the repo is merely installed. Treat a bridge setup as complete only after:
+
+1. the repo exists at the target path
+2. `.env` contains the correct Telegram values
+3. the bridge passes `doctor` and can report `status`
+4. the user has been told exactly where to send the first Telegram message
+5. the setup has been smoke-tested or clearly blocked by missing Telegram-side values
+
+## Mandatory Workflow
+
+Follow this order every time:
+
+1. Decide whether this is a local Mac install or a remote Mac over SSH.
+2. Confirm where the bridge repo should live. If the repo is not already present, clone it or let bootstrap clone it.
+3. Decide the Telegram mode before writing `.env`:
+   - private chat only
+   - one allowed group
+   - one allowed topic inside one group
+4. Collect the Telegram values and filesystem paths listed below.
+5. Run the correct bootstrap script with explicit arguments.
+6. Run post-install validation.
+7. Tell the user to send a first Telegram message and explain exactly where to send it.
+8. If the bridge does not answer, inspect `status`, logs, and Telegram configuration instead of declaring success.
+
+Do not stop after "install completed" if the user asked for a working bot.
+
+## Required Inputs
+
+Collect these values before running bootstrap:
+
+- `TG_BOT_TOKEN`
+- `TG_ALLOWED_USER_ID`
+- `DEFAULT_CWD`
+
+Collect these values when group/topic mode is used:
+
+- `TG_ALLOWED_CHAT_ID`
+- `TG_ALLOWED_TOPIC_ID`
+
+Collect these deployment values on every run:
+
+- install directory
+- SSH host when deploying remotely
+
+Defaults:
+
+- repo URL: `https://github.com/foxden-app/foxclaw.git`
+- repo ref: `main`
+- install directory: `~/foxclaw`
+- `DEFAULT_APPROVAL_POLICY`: `on-request`
+- `DEFAULT_SANDBOX_MODE`: `workspace-write`
+
+Telegram behavior:
+
+- private chat with `TG_ALLOWED_USER_ID` remains available even when `TG_ALLOWED_CHAT_ID` or `TG_ALLOWED_TOPIC_ID` is set
+- `TG_ALLOWED_CHAT_ID` and `TG_ALLOWED_TOPIC_ID` choose the default group or topic scope; they do not disable private chat
+
+If `TG_ALLOWED_CHAT_ID` or `TG_ALLOWED_TOPIC_ID` is missing, read [references/telegram-setup.md](./references/telegram-setup.md) and explicitly guide the user through collecting it.
+
+## Deployment Rules
+
+1. If the user is deploying to a second Mac, prefer one bot per device.
+2. If no unique bot token has been provided for the second Mac, bootstrap with `--no-start`.
+3. If group or topic mode is involved, read [references/telegram-setup.md](./references/telegram-setup.md) before continuing.
+4. Always explain to the user which values will be written into `.env` before starting bootstrap.
+5. After bootstrap, check `codex login status`. If authentication is missing, tell the user to run `codex login` or open `codex app` on that Mac.
+6. If the user only says "set it up" and has not given all required values, ask for the missing values directly instead of guessing Telegram IDs.
+7. If the user wants a fully usable setup, continue until first-message validation is done or clearly blocked by Telegram-side prerequisites.
+
+## What To Ask The User
+
+Use short direct questions when values are missing. The minimum useful checklist is:
+
+1. Where should the repo live on the target Mac?
+2. Which directory should be the bridge's default working directory?
+3. What is the Telegram bot token?
+4. What is the Telegram numeric user id allowed to control the bridge?
+5. Are we using private chat only, a group, or a specific topic?
+6. If group/topic mode: what are the `TG_ALLOWED_CHAT_ID` and `TG_ALLOWED_TOPIC_ID` values?
+
+If the user does not know the Telegram ids, point them to the exact `getUpdates` method in [references/telegram-setup.md](./references/telegram-setup.md).
+
+## Local Bootstrap
+
+Run:
+
+```bash
+python3 "$CODEX_HOME/skills/foxclaw/scripts/bootstrap_host.py" \
+  --tg-bot-token "<BOT_TOKEN>" \
+  --tg-allowed-user-id "<USER_ID>" \
+  --default-cwd "<ABSOLUTE_CWD>" \
+  --tg-allowed-chat-id "<CHAT_ID>" \
+  --tg-allowed-topic-id "<TOPIC_ID>" \
+  --default-sandbox-mode "workspace-write"
+```
+
+Omit `--tg-allowed-chat-id` and `--tg-allowed-topic-id` when using private chat only.
+
+Use `--no-start` when you only want the host prepared but do not want the bridge service to start yet.
+
+When the repo is not already present on disk, this bootstrap path counts as the repo download step because it clones the bridge automatically.
+
+## Remote Bootstrap Over SSH
+
+Run:
+
+```bash
+python3 "$CODEX_HOME/skills/foxclaw/scripts/bootstrap_remote.py" \
+  --ssh-host "<USER@HOST>" \
+  --install-dir "<REMOTE_INSTALL_DIR>" \
+  --tg-bot-token "<BOT_TOKEN>" \
+  --tg-allowed-user-id "<USER_ID>" \
+  --default-cwd "<REMOTE_ABSOLUTE_CWD>" \
+  --tg-allowed-chat-id "<CHAT_ID>" \
+  --tg-allowed-topic-id "<TOPIC_ID>" \
+  --default-sandbox-mode "workspace-write"
+```
+
+Use `--no-start` by default when preparing a second Mac before a unique bot token is ready.
+
+## Validation
+
+After either bootstrap path:
+
+1. Run `node dist/main.js doctor` in the installed bridge repo.
+2. If launchd was installed, run `node dist/main.js status`.
+3. Check `codex login status`. If authentication is missing, stop and tell the user exactly how to log in.
+4. If the bridge is expected to answer in a Telegram group, confirm:
+   - `privacy mode` is disabled
+   - the bot is an admin in the group
+   - the configured `TG_ALLOWED_CHAT_ID` and `TG_ALLOWED_TOPIC_ID` match the target group/topic
+5. If group or topic mode is enabled, also verify that private chat still responds for the configured `TG_ALLOWED_USER_ID`.
+
+## First Telegram Message Check
+
+Do this whenever the bridge has been started:
+
+1. Tell the user exactly where to send the first test message:
+   - private chat mode: send `/help` to the bot in private chat
+   - group mode: send `/help@botname` or `/help` in the configured default scope
+   - topic mode: send `/help` inside the configured topic, then send one plain-language message
+2. After the user sends that message, verify the bridge is listening:
+   - `node dist/main.js status`
+   - launchd or service log if there is no reply
+3. If the bot still does not answer, debug the Telegram side before changing the bridge:
+   - wrong bot token
+   - wrong user id
+   - wrong chat/topic ids
+   - privacy mode still on
+   - bot not admin in group
+
+Do not describe the setup as "done" until this smoke test has either passed or been blocked by missing Telegram-side access.
+
+## Resources
+
+- [references/telegram-setup.md](./references/telegram-setup.md): Telegram-side checklist and ID discovery
+- `scripts/bootstrap_host.py`: install and configure the bridge on the current Mac
+- `scripts/bootstrap_remote.py`: run the same bootstrap on another Mac over SSH

package/skills/foxclaw/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "FoxClaw"
+  short_description: "Install, configure, and validate Telegram Codex bridges"
+  default_prompt: "Use $foxclaw to clone the FoxClaw repo, collect Telegram values, write .env, start the service, and verify it with a first Telegram message."

package/skills/foxclaw/references/telegram-setup.md

@@ -0,0 +1,93 @@
+# Telegram Bridge Checklist
+
+Use this checklist whenever the bridge is configured for a Telegram group or topic.
+
+## Mode Selection
+
+Pick one mode before writing `.env`:
+
+- private chat only
+- one allowed group
+- one allowed topic inside one allowed group
+
+Rules:
+
+- private chat remains available even when group/topic ids are configured
+- if multiple bots share one group, prefer one topic per bot
+- if a user only wants the bot in private chat, leave both `TG_ALLOWED_CHAT_ID` and `TG_ALLOWED_TOPIC_ID` empty
+
+## Required Values
+
+- `TG_BOT_TOKEN`
+- `TG_ALLOWED_USER_ID`
+- `DEFAULT_CWD`
+
+Optional values:
+
+- `TG_ALLOWED_CHAT_ID`
+- `TG_ALLOWED_TOPIC_ID`
+
+Behavior:
+
+- No `TG_ALLOWED_CHAT_ID`: private-chat mode
+- `TG_ALLOWED_CHAT_ID` only: the whole group becomes the default scope
+- `TG_ALLOWED_CHAT_ID` + `TG_ALLOWED_TOPIC_ID`: that topic becomes the default scope
+- Private chat with `TG_ALLOWED_USER_ID` still works in every mode above
+
+If multiple bots share one group, keep the same `TG_ALLOWED_CHAT_ID` and give each bot a different `TG_ALLOWED_TOPIC_ID`.
+
+## Path Guidance
+
+Best practice:
+
+- keep the FoxClaw repo in a stable path such as `~/foxclaw`
+- point `DEFAULT_CWD` at a directory the user actually wants Codex to work inside, such as `~/workspace`, `~/Documents`, or `~/Dev`
+- do not use an ambiguous or disposable path unless the user explicitly wants that
+
+## Group Requirements
+
+Before testing natural-language chat in a group:
+
+1. Add the bot to the target group.
+2. Disable the bot's `privacy mode` in `@BotFather`.
+3. Promote the bot to administrator.
+4. If natural-language messages still do not arrive after the privacy change, remove the bot and add it back.
+
+`/status@botname` can work even when normal group text still does not. Do not treat command success as proof that group natural-language mode is ready.
+
+## Finding Chat And Topic IDs
+
+1. Stop the bridge.
+2. Send a message in the target group or topic.
+3. Open `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`.
+4. Read:
+   - `message.chat.id` -> `TG_ALLOWED_CHAT_ID`
+   - `message.message_thread_id` -> `TG_ALLOWED_TOPIC_ID`
+
+If the bridge is still polling, it may consume the update before you inspect it.
+
+## First Message Smoke Test
+
+After the bridge is started:
+
+1. Private chat mode:
+   - send `/help` to the bot in private chat
+   - send one plain-language message such as `show /status`
+2. Group mode:
+   - send `/help` in the configured group or default topic
+   - if multiple bots are present, use `@botname`
+3. Topic mode:
+   - send `/help` inside the configured topic
+   - then send one plain-language message inside that same topic
+
+If the bot does not answer:
+
+1. run `node dist/main.js status`
+2. inspect the bridge log
+3. re-check:
+   - bot token
+   - allowed user id
+   - chat id
+   - topic id
+   - privacy mode
+   - admin status