@sarkar-ai/deskmate 0.2.0 → 0.3.0

package/.env.example

@@ -4,24 +4,22 @@
 # Run `deskmate init` for interactive setup, or copy this file to .env and edit.
 # Alternative: ./install.sh
 
-# Telegram Bot Token (get from @BotFather)
-# https://t.me/BotFather → /newbot → copy token
-TELEGRAM_BOT_TOKEN=your_bot_token_here
-
-# Your Telegram User ID (get from @userinfobot)
-# https://t.me/userinfobot → send any message → copy Id
-# Only this user can interact with the bot
-ALLOWED_USER_ID=your_user_id_here
-
-# Multi-client allowed users (for gateway mode)
+# Allowed users (required)
 # Format: clientType:userId, comma-separated
 # Example: telegram:123456,discord:987654321,slack:U12345
 ALLOWED_USERS=telegram:your_user_id_here
 
+# Telegram Bot Token (get from @BotFather)
+# https://t.me/BotFather -> /newbot -> copy token
+TELEGRAM_BOT_TOKEN=your_bot_token_here
+
 # Anthropic API Key
 # https://console.anthropic.com/
 ANTHROPIC_API_KEY=your_anthropic_key_here
 
+# Legacy single-user Telegram ID (still supported, converted to telegram:<id> internally)
+# ALLOWED_USER_ID=your_user_id_here
+
 # ===========================================
 # Optional Configuration
 # ===========================================

package/README.md

@@ -8,7 +8,7 @@ Control your Local Machine from anywhere using natural language.
   <a href="#requirements"><img src="https://img.shields.io/badge/node-%3E%3D18-green.svg?style=for-the-badge" alt="Node"></a>
 </p>
 
-Deskmate is a personal AI assistant that runs on your personal machine and talks to you on the channels you already use. Send a Telegram message from your phone, and it executes on your machine. Powered by the [Claude Agent SDK](https://docs.anthropic.com/en/docs/claude-code/agent-sdk) with full local tool access — no sandboxed command set, no artificial limits.
+Deskmate is a local execution agent that lets you control your personal machine using natural language and talks to you on the channels you already use. Deskmate focuses on execution, not autonomy or orchestration. Send a Telegram message from your phone, and it executes on your machine. Powered by the [Claude Agent SDK](https://docs.anthropic.com/en/docs/claude-code/agent-sdk) with full local tool access — no sandboxed command set, no artificial limits.
 
 A passion project developed, born from a simple goal: staying in creative and developer flow even when I'm not sitting at my desk. Inspired by [gen-shell](https://github.com/sarkarsaurabh27/gen-shell).
 
@@ -18,6 +18,10 @@ A passion project developed, born from a simple goal: staying in creative and de
 
 ## Demo
 
+<p align="center">
+  <img src="assets/deskmate-screenshot.jpeg" alt="Deskmate Screenshot" width="500">
+</p>
+
 | Telegram Conversation | Installation |
 |:---:|:---:|
 | ![Telegram Demo](assets/deskmate-tg.gif) | ![Installation Demo](assets/deskmate-install.gif) |
@@ -47,6 +51,17 @@ Telegram / Discord* / Slack* / ...
 
 The Gateway is the control plane. Each messaging platform is a thin I/O adapter. The agent has unrestricted access to your machine (approve-by-default), with optional approval gating for protected folders.
 
+## Responsibility Boundary
+
+Deskmate’s responsibility is **execution**.
+
+- It turns intent into concrete system actions
+- It does not coordinate other agents
+- It does not monitor agent health or resource usage
+
+If you want visibility into what agents are doing on your machine,
+see **Riva**, the local observability layer.
+
 ## Highlights
 
 - **Full local access** — the agent can run any command, read/write any file, take screenshots. No artificial 6-tool sandbox.
@@ -87,25 +102,34 @@ The installer guides you through these (macOS only). You can also configure them
 
 ## Quick Start
 
-### Install from npm (recommended for users)
+### Option A: Install from npm (recommended)
 
 ```bash
-npm install -g deskmate
+npm install -g @sarkar-ai/deskmate
 deskmate init
 ```
 
 The wizard walks you through everything: API keys, Telegram credentials,
-platform permissions, and background service setup.
+platform permissions, and background service setup. Config is stored in
+`~/.config/deskmate/.env`.
 
-### Install from source (for contributors)
+After setup, run manually with `deskmate` or let the background service handle it.
+
+### Option B: Install from source (for contributors)
 
 ```bash
 git clone https://github.com/sarkar-ai-taken/deskmate.git
 cd deskmate
 npm install --legacy-peer-deps
-cp .env.example .env  # edit with your credentials
 npm run build
-./install.sh          # or: npx deskmate init
+./install.sh          # interactive: configures .env, service, permissions
+```
+
+Or use the TypeScript wizard instead of the shell installer:
+
+```bash
+cp .env.example .env  # edit with your credentials
+npx deskmate init     # or: npm link && deskmate init
 ```
 
 To reconfigure later: `deskmate init`
@@ -114,30 +138,26 @@ To reconfigure later: `deskmate init`
 
 | Mode | Command | Description |
 |------|---------|-------------|
-| Telegram | `deskmate telegram` | Standalone Telegram bot (legacy) |
-| Gateway | `deskmate gateway` | Multi-client gateway (recommended for new setups) |
+| Gateway | `deskmate` | Multi-client gateway (default) |
 | MCP | `deskmate mcp` | MCP server for Claude Desktop |
-| Both | `deskmate both` | Telegram + MCP simultaneously |
+| Both | `deskmate both` | Gateway + MCP simultaneously |
+
+> **Note:** `deskmate telegram` still works but is a deprecated alias that starts the gateway.
 
 ## Gateway Mode
 
-The gateway is the recommended way to run Deskmate. It separates platform I/O from agent logic, so adding a new messaging client doesn't require touching auth, sessions, or the agent layer.
+The gateway is the default way to run Deskmate. It separates platform I/O from agent logic, so adding a new messaging client doesn't require touching auth, sessions, or the agent layer.
 
 ```bash
 # Configure multi-client auth
 ALLOWED_USERS=telegram:123456,discord:987654321
 
 # Start
-deskmate gateway
+deskmate
 ```
 
 The gateway auto-registers clients based on available env vars. If `TELEGRAM_BOT_TOKEN` is set, Telegram is active. Future clients (Discord, Slack) follow the same pattern.
 
-### Gateway vs Telegram mode
-
-- **`deskmate telegram`** — original standalone bot. Simple, self-contained, no gateway overhead. Good for single-user Telegram-only setups.
-- **`deskmate gateway`** — centralized architecture. Auth, sessions, and agent orchestration are shared. Required for multi-client setups and recommended for new installations.
-
 ## Bot Commands
 
 | Command | Description |
@@ -187,32 +207,77 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 Restart Claude Desktop. You can now ask Claude to interact with your local machine.
 
-### Combined Mode (MCP + Telegram)
+### Combined Mode (Gateway + MCP)
+
+Run both with `deskmate both`. MCP handles Claude Desktop requests; the gateway handles Telegram (and future clients), sending approval notifications to your phone so you can approve sensitive operations from anywhere.
 
-Run both with `deskmate both`. MCP handles Claude Desktop requests; Telegram sends approval notifications to your phone so you can approve sensitive operations from anywhere.
+### Observability
+
+Deskmate focuses on executing actions safely.
+
+For monitoring agent behavior, resource usage, and failures across
+multiple local agents, see **Riva** (local-first agent observability).
 
 ## Security
 
 > **Important**: The agent can execute arbitrary commands on your machine. This is by design — the strategy is approve-by-default for read-only operations, with approval gating for protected folders and write operations.
 
-**Built-in protections:**
+### Built-in protections
 
 | Layer | What it does |
 |-------|-------------|
-| **User authentication** | Only allowlisted user IDs can interact (per-client) |
-| **Folder protection** | Desktop, Documents, Downloads, etc. require explicit approval |
-| **No sudo by default** | The agent won't use sudo unless you explicitly ask |
-| **No open ports** | The bot polls Telegram's servers, doesn't expose any ports |
-| **Structured logging** | All actions are logged with timestamps for audit |
-| **Session isolation** | Gateway sessions are keyed by `clientType:channelId` |
-
-**Recommendations:**
+| **User authentication** | Allowlist-based access control via `SecurityManager`. Only users in `ALLOWED_USERS` can interact. Supports per-client auth (`telegram:123`, `discord:456`) and wildcards (`*:*`). |
+| **Action approval** | `ApprovalManager` gates sensitive operations. Write commands, file writes, and folder access require explicit human approval with configurable timeouts (default 5 min). |
+| **Protected folders** | OS-aware folder protection. Desktop, Documents, Downloads, Pictures, Movies/Videos, Music, and iCloud (macOS) require approval. Session-based caching avoids repeated prompts. |
+| **Safe command auto-approval** | Read-only commands (`ls`, `cat`, `git status`, `docker ps`, `node -v`, etc.) auto-approve. Full list in `src/core/approval.ts`. |
+| **Command execution limits** | 2-minute timeout and 10 MB output buffer per command. Prevents runaway processes and memory exhaustion. |
+| **Session isolation** | Sessions keyed by `clientType:channelId`. 30-minute idle timeout with automatic pruning. Optional disk persistence survives restarts. |
+| **Input validation** | MCP tools use Zod schema validation. Telegram callbacks validated via regex patterns. |
+| **No open ports** | The bot polls Telegram's servers — no inbound ports exposed. |
+| **No sudo by default** | The agent won't use sudo unless you explicitly ask. |
+| **Structured logging** | All actions logged with timestamps, context hierarchy, and configurable log levels for audit trails. |
+| **Stale message protection** | Telegram client drops pending updates on startup (`drop_pending_updates: true`), preventing replay of messages received while offline. |
+
+### Approval workflow
+
+1. User sends a message that triggers a sensitive operation (e.g., writing to `~/Documents`)
+2. `ApprovalManager` checks if the action matches a safe auto-approve pattern
+3. If not safe, a pending approval is created with a timeout countdown
+4. Approval request is broadcast to all clients with recent activity (last 30 min)
+5. User taps Approve/Reject via inline buttons (Telegram) or equivalent
+6. Action executes on approval, or is cancelled on rejection/timeout
+
+Set `REQUIRE_APPROVAL_FOR_ALL=true` to gate every operation, including reads.
+
+### Recommendations
+
 - Set `WORKING_DIR` to limit default command scope
-- Use `ALLOWED_USERS` (gateway mode) for multi-client allowlisting
+- Use `ALLOWED_USERS` for multi-client allowlisting
+- Use `ALLOWED_FOLDERS` to pre-approve specific directories
 - Review logs regularly (`logs/stdout.log`)
 - Keep `.env` secure and never commit it
 - Use `REQUIRE_APPROVAL_FOR_ALL=true` if you want to approve every operation
 
+### Execution Philosophy
+
+Deskmate follows an **approve-by-default, visible-by-design** model.
+
+- Read-only operations are auto-approved
+- Sensitive operations require explicit confirmation
+- All actions are logged locally
+
+The goal is speed without hidden behavior.
+
+## Non-goals
+
+Deskmate is intentionally not:
+- A multi-agent orchestration framework
+- A cloud-hosted control plane
+- A long-running autonomous system
+- A monitoring or observability tool
+
+These constraints are deliberate.
+
 ## Architecture
 
 ```
@@ -233,8 +298,6 @@ src/
 │   └── session.ts                # Session manager (composite keys, idle pruning)
 ├── clients/
 │   └── telegram.ts               # Telegram adapter (grammY)
-├── telegram/
-│   └── bot.ts                    # Legacy standalone Telegram bot
 └── mcp/
     └── server.ts                 # MCP server
 ```
@@ -312,7 +375,7 @@ systemctl --user status deskmate.service
 
 **Bot not responding?**
 1. Check logs: `tail -f logs/stderr.log`
-2. Verify your `ALLOWED_USER_ID` matches your Telegram ID
+2. Verify your `ALLOWED_USERS` includes your Telegram ID (e.g. `telegram:123456`)
 3. Ensure Claude Code CLI is installed: `which claude`
 
 **Commands timing out?**

package/dist/cli/init.js

@@ -2,10 +2,16 @@
 /**
  * Interactive Setup Wizard
  *
- * Self-contained setup: writes .env, optionally installs a background service
- * (launchd on macOS, systemd on Linux), and guides through macOS permissions.
+ * Supports two install paths:
+ *   1. npm global: `npm install -g @sarkar-ai/deskmate && deskmate init`
+ *      — config stored in ~/.config/deskmate/.env
+ *      — service uses the global `deskmate` binary
  *
- * For an alternative shell-based installer, see ./install.sh.
+ *   2. Source clone: `git clone ... && cd deskmate && deskmate init`  (or ./install.sh)
+ *      — config stored in project root .env
+ *      — service uses `node <projectDir>/dist/index.js`
+ *
+ * For an alternative shell-based installer (source path only), see ./install.sh.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -89,6 +95,67 @@ function detectPlatform() {
             return "unsupported";
     }
 }
+function resolveInstallPaths() {
+    // dist/cli/init.js -> go up two levels to get package root
+    const packageDir = path.resolve(__dirname, "..", "..");
+    const isGlobal = __dirname.includes("node_modules");
+    if (isGlobal) {
+        const configDir = path.join(os.homedir(), ".config", "deskmate");
+        // Use the global deskmate binary (which is in PATH)
+        const deskmateCmd = process.argv[1] || "deskmate";
+        // Resolve to an absolute path so the service always finds it
+        let deskmateBin;
+        try {
+            deskmateBin = (0, child_process_1.execSync)("which deskmate", { encoding: "utf-8" }).trim();
+        }
+        catch {
+            deskmateBin = deskmateCmd;
+        }
+        return {
+            isGlobalInstall: true,
+            packageDir,
+            configDir,
+            execStart: (runMode) => `${deskmateBin} ${runMode}`,
+        };
+    }
+    // Source install — configDir is the project root
+    return {
+        isGlobalInstall: false,
+        packageDir,
+        configDir: packageDir,
+        execStart: (runMode) => `${process.execPath} ${packageDir}/dist/index.js ${runMode}`,
+    };
+}
+// ---------------------------------------------------------------------------
+// .env reader
+// ---------------------------------------------------------------------------
+async function loadExistingEnv(envPath) {
+    const existing = {};
+    try {
+        const content = await fs.readFile(envPath, "utf-8");
+        for (const line of content.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const eqIdx = trimmed.indexOf("=");
+            if (eqIdx > 0) {
+                const key = trimmed.slice(0, eqIdx).trim();
+                const value = trimmed.slice(eqIdx + 1).trim();
+                if (value)
+                    existing[key] = value;
+            }
+        }
+    }
+    catch {
+        // file doesn't exist — fine
+    }
+    return existing;
+}
+function mask(value) {
+    if (value.length <= 8)
+        return "****";
+    return value.slice(0, 4) + "..." + value.slice(-4);
+}
 // ---------------------------------------------------------------------------
 // Service installation helpers
 // ---------------------------------------------------------------------------
@@ -102,7 +169,10 @@ function systemdDir() {
 function systemdPath() {
     return path.join(systemdDir(), "deskmate.service");
 }
-function buildPlist(nodePath, projectDir, logsDir, runMode) {
+function buildPlist(execStart, workingDir, logsDir) {
+    // Split the execStart into program + arguments for ProgramArguments array
+    const parts = execStart.split(" ");
+    const argsXml = parts.map((p) => `        <string>${p}</string>`).join("\n");
     return `<?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">
@@ -112,13 +182,11 @@ function buildPlist(nodePath, projectDir, logsDir, runMode) {
 
     <key>ProgramArguments</key>
     <array>
-        <string>${nodePath}</string>
-        <string>${projectDir}/dist/index.js</string>
-        <string>${runMode}</string>
+${argsXml}
     </array>
 
     <key>WorkingDirectory</key>
-    <string>${projectDir}</string>
+    <string>${workingDir}</string>
 
     <key>EnvironmentVariables</key>
     <dict>
@@ -140,7 +208,7 @@ function buildPlist(nodePath, projectDir, logsDir, runMode) {
 </dict>
 </plist>`;
 }
-function buildSystemdUnit(nodePath, projectDir, logsDir, runMode) {
+function buildSystemdUnit(execStart, workingDir, logsDir) {
     return `[Unit]
 Description=Deskmate - Local Machine Assistant
 After=network-online.target
@@ -148,8 +216,8 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-ExecStart=${nodePath} ${projectDir}/dist/index.js ${runMode}
-WorkingDirectory=${projectDir}
+ExecStart=${execStart}
+WorkingDirectory=${workingDir}
 Environment=PATH=/usr/local/bin:/usr/bin:/bin:${os.homedir()}/.local/bin
 Restart=always
 RestartSec=5
@@ -162,8 +230,7 @@ StandardError=append:${logsDir}/stderr.log
 [Install]
 WantedBy=default.target`;
 }
-async function installMacosService(projectDir, logsDir, runMode) {
-    const nodePath = process.execPath;
+async function installMacosService(execStart, workingDir, logsDir) {
     const dest = plistPath();
     // Unload existing
     try {
@@ -177,13 +244,12 @@ async function installMacosService(projectDir, logsDir, runMode) {
     }
     await fs.mkdir(path.dirname(dest), { recursive: true });
     await fs.mkdir(logsDir, { recursive: true });
-    await fs.writeFile(dest, buildPlist(nodePath, projectDir, logsDir, runMode), "utf-8");
+    await fs.writeFile(dest, buildPlist(execStart, workingDir, logsDir), "utf-8");
     (0, child_process_1.execSync)(`launchctl load "${dest}"`);
     console.log("\n  Service installed and started via launchd.");
     console.log(`  Plist: ${dest}`);
 }
-async function installLinuxService(projectDir, logsDir, runMode) {
-    const nodePath = process.execPath;
+async function installLinuxService(execStart, workingDir, logsDir) {
     const dest = systemdPath();
     // Stop existing
     try {
@@ -194,7 +260,7 @@ async function installLinuxService(projectDir, logsDir, runMode) {
     }
     await fs.mkdir(systemdDir(), { recursive: true });
     await fs.mkdir(logsDir, { recursive: true });
-    await fs.writeFile(dest, buildSystemdUnit(nodePath, projectDir, logsDir, runMode), "utf-8");
+    await fs.writeFile(dest, buildSystemdUnit(execStart, workingDir, logsDir), "utf-8");
     (0, child_process_1.execSync)("systemctl --user daemon-reload");
     (0, child_process_1.execSync)("systemctl --user enable deskmate.service");
     (0, child_process_1.execSync)("systemctl --user start deskmate.service");
@@ -286,33 +352,89 @@ async function runInitWizard() {
         console.log("Install it from: https://docs.anthropic.com/en/docs/claude-code");
         console.log("");
     }
+    // Detect install type and resolve paths
+    const paths = resolveInstallPaths();
+    if (paths.isGlobalInstall) {
+        console.log(`Install type: npm global`);
+        console.log(`Config directory: ${paths.configDir}\n`);
+    }
+    else {
+        console.log(`Install type: source`);
+        console.log(`Project directory: ${paths.packageDir}\n`);
+    }
+    // Ensure config directory exists
+    await fs.mkdir(paths.configDir, { recursive: true });
     // ----- Step 1: .env wizard -----
+    const envPath = path.join(paths.configDir, ".env");
+    const existing = await loadExistingEnv(envPath);
+    const hasExisting = Object.keys(existing).length > 0;
+    if (hasExisting) {
+        console.log("Found existing .env — values shown below. Press Enter to keep current value.\n");
+    }
     const env = {};
-    env.AGENT_PROVIDER = "claude-code";
-    const apiKey = await ask(rl, "Anthropic API Key (for Claude Code): ");
-    if (apiKey)
-        env.ANTHROPIC_API_KEY = apiKey;
+    env.AGENT_PROVIDER = existing.AGENT_PROVIDER || "claude-code";
+    // Anthropic API Key
+    if (existing.ANTHROPIC_API_KEY) {
+        const apiKey = await ask(rl, `Anthropic API Key [${mask(existing.ANTHROPIC_API_KEY)}]: `);
+        env.ANTHROPIC_API_KEY = apiKey || existing.ANTHROPIC_API_KEY;
+    }
+    else {
+        const apiKey = await ask(rl, "Anthropic API Key (for Claude Code): ");
+        if (apiKey)
+            env.ANTHROPIC_API_KEY = apiKey;
+    }
+    // Telegram
     console.log("\n--- Telegram Configuration ---\n");
-    console.log("  Bot token → message @BotFather on Telegram, send /newbot");
-    console.log("  User ID   → message @userinfobot on Telegram, copy the number");
-    console.log("");
-    const token = await ask(rl, "Telegram Bot Token (from @BotFather): ");
-    if (token)
-        env.TELEGRAM_BOT_TOKEN = token;
-    const userId = await ask(rl, "Your Telegram User ID (from @userinfobot): ");
-    if (userId) {
-        env.ALLOWED_USER_ID = userId;
-        env.ALLOWED_USERS = `telegram:${userId}`;
+    if (!existing.TELEGRAM_BOT_TOKEN) {
+        console.log("  Bot token → message @BotFather on Telegram, send /newbot");
+        console.log("  User ID   → message @userinfobot on Telegram, copy the number");
+        console.log("");
+    }
+    if (existing.TELEGRAM_BOT_TOKEN) {
+        const token = await ask(rl, `Telegram Bot Token [${mask(existing.TELEGRAM_BOT_TOKEN)}]: `);
+        env.TELEGRAM_BOT_TOKEN = token || existing.TELEGRAM_BOT_TOKEN;
+    }
+    else {
+        const token = await ask(rl, "Telegram Bot Token (from @BotFather): ");
+        if (token)
+            env.TELEGRAM_BOT_TOKEN = token;
+    }
+    // User ID / Allowed Users
+    const existingUsers = existing.ALLOWED_USERS;
+    const existingUserId = existing.ALLOWED_USER_ID;
+    if (existingUsers) {
+        const users = await ask(rl, `Allowed users [${existingUsers}]: `);
+        env.ALLOWED_USERS = users || existingUsers;
+    }
+    else if (existingUserId) {
+        const userId = await ask(rl, `Telegram User ID [${existingUserId}]: `);
+        const id = userId || existingUserId;
+        env.ALLOWED_USER_ID = id;
+        env.ALLOWED_USERS = `telegram:${id}`;
     }
+    else {
+        const userId = await ask(rl, "Your Telegram User ID (from @userinfobot): ");
+        if (userId) {
+            env.ALLOWED_USER_ID = userId;
+            env.ALLOWED_USERS = `telegram:${userId}`;
+        }
+    }
+    // General config
     console.log("\n--- General Configuration ---\n");
-    const workingDir = await ask(rl, `Working directory (default: ${os.homedir()}): `);
-    if (workingDir)
-        env.WORKING_DIR = workingDir;
-    const botName = await ask(rl, "Bot name (default: Deskmate): ");
-    if (botName)
-        env.BOT_NAME = botName;
+    const defaultWorkingDir = existing.WORKING_DIR || os.homedir();
+    const workingDir = await ask(rl, `Working directory [${defaultWorkingDir}]: `);
+    env.WORKING_DIR = workingDir || defaultWorkingDir;
+    const defaultBotName = existing.BOT_NAME || "Deskmate";
+    const botName = await ask(rl, `Bot name [${defaultBotName}]: `);
+    env.BOT_NAME = botName || defaultBotName;
+    // Carry over other existing values that we don't prompt for
+    if (existing.LOG_LEVEL)
+        env.LOG_LEVEL = existing.LOG_LEVEL;
+    if (existing.REQUIRE_APPROVAL_FOR_ALL)
+        env.REQUIRE_APPROVAL_FOR_ALL = existing.REQUIRE_APPROVAL_FOR_ALL;
+    if (existing.ALLOWED_FOLDERS)
+        env.ALLOWED_FOLDERS = existing.ALLOWED_FOLDERS;
     // ----- Step 2: Write .env -----
-    const envPath = path.join(process.cwd(), ".env");
     let envContent = "# Deskmate Configuration (generated by deskmate init)\n\n";
     for (const [key, value] of Object.entries(env)) {
         envContent += `${key}=${value}\n`;
@@ -322,20 +444,18 @@ async function runInitWizard() {
     if (!env.REQUIRE_APPROVAL_FOR_ALL)
         envContent += "REQUIRE_APPROVAL_FOR_ALL=false\n";
     try {
-        let envExists = false;
-        try {
-            await fs.access(envPath);
-            envExists = true;
-        }
-        catch {
-            // does not exist
-        }
-        if (envExists) {
-            console.log(`\nWARNING: .env file already exists at ${envPath}`);
-            const newPath = envPath + ".new";
-            await fs.writeFile(newPath, envContent, "utf-8");
-            console.log(`Configuration saved to ${newPath}`);
-            console.log("Review and rename it to .env when ready.");
+        if (hasExisting) {
+            const overwrite = await askYesNo(rl, "\nOverwrite existing .env with new values?");
+            if (overwrite) {
+                await fs.writeFile(envPath, envContent, "utf-8");
+                console.log(`Configuration saved to ${envPath}`);
+            }
+            else {
+                const newPath = envPath + ".new";
+                await fs.writeFile(newPath, envContent, "utf-8");
+                console.log(`Configuration saved to ${newPath}`);
+                console.log("Review and rename it to .env when ready.");
+            }
         }
         else {
             await fs.writeFile(envPath, envContent, "utf-8");
@@ -352,16 +472,15 @@ async function runInitWizard() {
         console.log("");
         const installService = await askYesNo(rl, "Install as background service?");
         if (installService) {
-            // Determine project root (where package.json lives)
-            const projectDir = path.resolve(__dirname, "..");
-            const logsDir = path.join(projectDir, "logs");
+            const logsDir = path.join(paths.configDir, "logs");
             const runMode = "gateway";
+            const execStart = paths.execStart(runMode);
             try {
                 if (platform === "macos") {
-                    await installMacosService(projectDir, logsDir, runMode);
+                    await installMacosService(execStart, paths.configDir, logsDir);
                 }
                 else {
-                    await installLinuxService(projectDir, logsDir, runMode);
+                    await installLinuxService(execStart, paths.configDir, logsDir);
                 }
             }
             catch (err) {
@@ -383,5 +502,9 @@ async function runInitWizard() {
     }
     rl.close();
     console.log("\nSetup complete! Your bot is ready.");
+    if (paths.isGlobalInstall) {
+        console.log(`\nRun "deskmate" to start, or the background service is already running.`);
+        console.log(`Config: ${paths.configDir}/.env`);
+    }
     console.log("");
 }