poke-gate 0.1.9 → 0.2.1

package/clients/Poke macOS Gate/Poke macOS Gate/SetupView.swift

@@ -0,0 +1,157 @@
+import SwiftUI
+
+struct SetupView: View {
+    @ObservedObject var service: GateService
+    @State private var selectedMode: GateService.PermissionMode
+    @State private var step: Step = .accessMode
+
+    enum Step { case accessMode, permissions }
+
+    init(service: GateService) {
+        self.service = service
+        _selectedMode = State(initialValue: service.permissionMode)
+    }
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 0) {
+            stepIndicator
+                .padding(.horizontal, 16)
+                .padding(.top, 16)
+                .padding(.bottom, 12)
+
+            Divider()
+
+            switch step {
+            case .accessMode: accessModeStep
+            case .permissions: permissionsStep
+            }
+        }
+        .frame(width: 380)
+        .onAppear { service.startPermissionPolling() }
+        .onDisappear { service.stopPermissionPolling() }
+    }
+
+    private var stepIndicator: some View {
+        HStack(spacing: 6) {
+            ForEach(Array(Step.allCases.enumerated()), id: \.offset) { index, s in
+                HStack(spacing: 4) {
+                    Circle()
+                        .fill(s == step ? MacVisualStyle.chipActiveFill : (isCompleted(s) ? Color.accentColor.opacity(0.5) : MacVisualStyle.chipInactiveFill))
+                        .frame(width: 6, height: 6)
+                    Text(s.label)
+                        .font(.caption2)
+                        .foregroundStyle(s == step ? .primary : .secondary)
+                }
+                if index < Step.allCases.count - 1 {
+                    Rectangle()
+                        .fill(MacVisualStyle.progressTrackColor)
+                        .frame(height: 1)
+                        .frame(maxWidth: .infinity)
+                }
+            }
+        }
+    }
+
+    private var accessModeStep: some View {
+        VStack(alignment: .leading, spacing: 16) {
+            VStack(alignment: .leading, spacing: 4) {
+                Text("Choose access mode")
+                    .font(.headline)
+                Text("Controls which tools Poke can use on this machine.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+
+            VStack(spacing: 8) {
+                ForEach(GateService.PermissionMode.allCases) { mode in
+                    modeRow(mode)
+                }
+            }
+
+            HStack {
+                Spacer()
+                Button("Continue") { step = .permissions }
+                    .keyboardShortcut(.defaultAction)
+            }
+        }
+        .padding(16)
+    }
+
+    private var permissionsStep: some View {
+        VStack(alignment: .leading, spacing: 16) {
+            VStack(alignment: .leading, spacing: 4) {
+                Text("Grant permissions")
+                    .font(.headline)
+                Text("These allow Poke to control your Mac. You can grant them now or later from the menu bar.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+
+            VStack(spacing: 10) {
+                ForEach(GateService.SystemPermission.allCases) { permission in
+                    let status = service.systemPermissionStatuses.first(where: { $0.permission == permission })
+                    PermissionRowView(
+                        permission: permission,
+                        isGranted: status?.isGranted ?? false,
+                        onGrant: { service.openSystemPermission(permission) }
+                    )
+                }
+            }
+
+            HStack {
+                Button("Back") { step = .accessMode }
+                    .buttonStyle(.plain)
+                    .foregroundStyle(.secondary)
+
+                Spacer()
+
+                Button("Finish Setup") {
+                    service.completeFirstRunSetup(selectedMode: selectedMode, requestPermissions: false)
+                }
+                .keyboardShortcut(.defaultAction)
+            }
+        }
+        .padding(16)
+    }
+
+    private func modeRow(_ mode: GateService.PermissionMode) -> some View {
+        Button { selectedMode = mode } label: {
+            HStack(alignment: .top, spacing: 10) {
+                Image(systemName: selectedMode == mode ? "checkmark.circle.fill" : "circle")
+                    .foregroundStyle(selectedMode == mode ? Color.accentColor : Color.secondary)
+
+                VStack(alignment: .leading, spacing: 2) {
+                    Text(mode.title)
+                        .font(.subheadline)
+                        .foregroundStyle(.primary)
+                    Text(mode.subtitle)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+
+                Spacer()
+            }
+            .padding(10)
+            .macPanelStyle(selectedMode == mode ? .selected : .neutral)
+        }
+        .buttonStyle(.plain)
+    }
+
+    private func isCompleted(_ s: Step) -> Bool {
+        switch s {
+        case .accessMode: return step == .permissions
+        case .permissions: return false
+        }
+    }
+}
+
+extension SetupView.Step: CaseIterable {
+    static var allCases: [SetupView.Step] { [.accessMode, .permissions] }
+
+    var label: String {
+        switch self {
+        case .accessMode: return "Access Mode"
+        case .permissions: return "Permissions"
+        }
+    }
+}

package/clients/Poke macOS Gate/Poke macOS Gate.xcodeproj/project.pbxproj

@@ -10,9 +10,22 @@
 		442DE4462F71DCD9009BF9EF /* Poke macOS Gate.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = "Poke macOS Gate.app"; sourceTree = BUILT_PRODUCTS_DIR; };
 /* End PBXFileReference section */
 
+/* Begin PBXFileSystemSynchronizedBuildFileExceptionSet section */
+		114D3ACF2F74597400C9F8B9 /* Exceptions for "Poke macOS Gate" folder in "Poke macOS Gate" target */ = {
+			isa = PBXFileSystemSynchronizedBuildFileExceptionSet;
+			membershipExceptions = (
+				Info.plist,
+			);
+			target = 442DE4452F71DCD9009BF9EF /* Poke macOS Gate */;
+		};
+/* End PBXFileSystemSynchronizedBuildFileExceptionSet section */
+
 /* Begin PBXFileSystemSynchronizedRootGroup section */
 		442DE4482F71DCD9009BF9EF /* Poke macOS Gate */ = {
 			isa = PBXFileSystemSynchronizedRootGroup;
+			exceptions = (
+				114D3ACF2F74597400C9F8B9 /* Exceptions for "Poke macOS Gate" folder in "Poke macOS Gate" target */,
+			);
 			path = "Poke macOS Gate";
 			sourceTree = "<group>";
 		};
@@ -78,7 +91,7 @@
 			attributes = {
 				BuildIndependentTargetsInParallel = 1;
 				LastSwiftUpdateCheck = 2620;
-				LastUpgradeCheck = 2620;
+				LastUpgradeCheck = 2630;
 				TargetAttributes = {
 					442DE4452F71DCD9009BF9EF = {
 						CreatedOnToolsVersion = 26.2;
@@ -159,8 +172,9 @@
 				CLANG_WARN_UNREACHABLE_CODE = YES;
 				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
 				COPY_PHASE_STRIP = NO;
+				DEAD_CODE_STRIPPING = YES;
 				DEBUG_INFORMATION_FORMAT = dwarf;
-				DEVELOPMENT_TEAM = RJA7656U34;
+				DEVELOPMENT_TEAM = "";
 				ENABLE_STRICT_OBJC_MSGSEND = YES;
 				ENABLE_TESTABILITY = YES;
 				ENABLE_USER_SCRIPT_SANDBOXING = YES;
@@ -179,11 +193,12 @@
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
 				LOCALIZATION_PREFERS_STRING_CATALOGS = YES;
-				MACOSX_DEPLOYMENT_TARGET = 26.2;
+				MACOSX_DEPLOYMENT_TARGET = 15.0;
 				MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
 				MTL_FAST_MATH = YES;
 				ONLY_ACTIVE_ARCH = YES;
 				SDKROOT = macosx;
+				STRING_CATALOG_GENERATE_SYMBOLS = YES;
 				SWIFT_ACTIVE_COMPILATION_CONDITIONS = "DEBUG $(inherited)";
 				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
 			};
@@ -223,8 +238,9 @@
 				CLANG_WARN_UNREACHABLE_CODE = YES;
 				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
 				COPY_PHASE_STRIP = NO;
+				DEAD_CODE_STRIPPING = YES;
 				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
-				DEVELOPMENT_TEAM = RJA7656U34;
+				DEVELOPMENT_TEAM = "";
 				ENABLE_NS_ASSERTIONS = NO;
 				ENABLE_STRICT_OBJC_MSGSEND = YES;
 				ENABLE_USER_SCRIPT_SANDBOXING = YES;
@@ -237,10 +253,11 @@
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
 				LOCALIZATION_PREFERS_STRING_CATALOGS = YES;
-				MACOSX_DEPLOYMENT_TARGET = 26.2;
+				MACOSX_DEPLOYMENT_TARGET = 15.0;
 				MTL_ENABLE_DEBUG_INFO = NO;
 				MTL_FAST_MATH = YES;
 				SDKROOT = macosx;
+				STRING_CATALOG_GENERATE_SYMBOLS = YES;
 				SWIFT_COMPILATION_MODE = wholemodule;
 			};
 			name = Release;
@@ -250,10 +267,12 @@
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
 				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
+				"CODE_SIGN_IDENTITY[sdk=macosx*]" = "-";
 				CODE_SIGN_STYLE = Automatic;
 				COMBINE_HIDPI_IMAGES = YES;
 				CURRENT_PROJECT_VERSION = 1;
-				DEVELOPMENT_TEAM = RJA7656U34;
+				DEAD_CODE_STRIPPING = YES;
+				DEVELOPMENT_TEAM = "";
 				ENABLE_APP_SANDBOX = NO;
 				ENABLE_HARDENED_RUNTIME = NO;
 				ENABLE_PREVIEWS = YES;
@@ -266,8 +285,8 @@
 					"$(inherited)",
 					"@executable_path/../Frameworks",
 				);
-				MACOSX_DEPLOYMENT_TARGET = 26.0;
-				MARKETING_VERSION = 0.1.7;
+				MACOSX_DEPLOYMENT_TARGET = 15.0;
+				MARKETING_VERSION = 0.2.0;
 				PRODUCT_BUNDLE_IDENTIFIER = "dev.fka.Poke-macOS-Gate";
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				REGISTER_APP_GROUPS = YES;
@@ -285,10 +304,11 @@
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
 				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
+				"CODE_SIGN_IDENTITY[sdk=macosx*]" = "-";
 				CODE_SIGN_STYLE = Automatic;
 				COMBINE_HIDPI_IMAGES = YES;
 				CURRENT_PROJECT_VERSION = 1;
-				DEVELOPMENT_TEAM = RJA7656U34;
+				DEAD_CODE_STRIPPING = YES;
 				ENABLE_APP_SANDBOX = NO;
 				ENABLE_HARDENED_RUNTIME = NO;
 				ENABLE_PREVIEWS = YES;
@@ -301,8 +321,8 @@
 					"$(inherited)",
 					"@executable_path/../Frameworks",
 				);
-				MACOSX_DEPLOYMENT_TARGET = 26.0;
-				MARKETING_VERSION = 0.1.7;
+				MACOSX_DEPLOYMENT_TARGET = 15.0;
+				MARKETING_VERSION = 0.2.0;
 				PRODUCT_BUNDLE_IDENTIFIER = "dev.fka.Poke-macOS-Gate";
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				REGISTER_APP_GROUPS = YES;

package/docs/cli.md

@@ -8,6 +8,23 @@ npx poke-gate
 
 Starts the MCP server, connects the tunnel, and begins the agent scheduler. On first run, if you're not signed in, opens Poke OAuth in your browser.
 
+### Access mode
+
+```bash
+npx poke-gate --mode limited
+npx poke-gate --mode sandbox
+```
+
+Controls which tools your Poke agent can use. Defaults to `full` if not specified.
+
+| Mode | Description |
+|------|-------------|
+| `full` | All tools available, subject to chat approval for risky actions |
+| `limited` | Safe tools and a curated set of read-only commands only |
+| `sandbox` | Broader command support, but writes are restricted by macOS `sandbox-exec` policies |
+
+You can also set the mode via the `POKE_GATE_PERMISSION_MODE` environment variable. The `--mode` flag takes precedence.
+
 ### Verbose mode
 
 ```bash
@@ -92,6 +109,8 @@ Fetching agent "beeper" from GitHub...
 
 | Variable | Description |
 |----------|-------------|
+| `POKE_GATE_PERMISSION_MODE` | Access mode: `full` (default), `limited`, or `sandbox` |
+| `POKE_GATE_HMAC_SECRET` | Fixed HMAC secret for approval tokens (random per session by default) |
 | `POKE_API_KEY` | Override the API key (skips OAuth) |
 | `POKE_API` | Override the Poke API base URL |
 | `POKE_FRONTEND` | Override the Poke frontend URL |

package/docs/getting-started.md

@@ -28,14 +28,17 @@ If you don't need the macOS app:
 npx poke-gate
 ```
 
-## Sign in
+Poke Gate needs **Accessibility** permission on your Mac to automate keyboard/mouse and take screenshots.
 
+### 1. Sign in
 Poke Gate uses Poke OAuth to authenticate. On first launch:
 
-1. Open Poke Gate from your menu bar
-2. The app starts and connects automatically
-3. If you're not signed in, a browser window opens for Poke OAuth
-4. After signing in, the connection is established
+1. Open Poke Gate from your menu bar.
+2. The **Setup View** will appear to guide you through:
+   - Selecting an access mode (Full, Limited, or Sandbox)
+   - Granting the required macOS Accessibility permissions
+3. If you're not signed in, a browser window opens for Poke OAuth.
+4. After signing in, the connection is established.
 
 You can also sign in manually:
 
@@ -47,7 +50,7 @@ npx poke login
 
 Once connected, you'll see a green dot in the menu bar. The popover shows:
 
-> ● Connected to your Poke, [your name]
+> ● Connected to your Poke, your name
 
 Now open iMessage or Telegram and message your Poke:
 

package/docs/index.md

@@ -17,24 +17,29 @@ hero:
       link: https://github.com/f/poke-gate
 
 features:
-  - icon: 🖥️
-    title: Full Shell Access
-    details: Run any terminal command on your machine — ls, git, brew, python, curl, and more.
-  - icon: 📁
-    title: File Operations
-    details: Read, write, and list files and directories. Your Poke agent sees your filesystem.
-  - icon: 📸
-    title: Screenshots
-    details: Capture your screen remotely. Poke can see what you see.
-  - icon: 🤖
-    title: Agents
-    details: Scheduled scripts that run in the background — automate message digests, backups, health checks.
-  - icon: 🌴
-    title: macOS Menu Bar App
-    details: Native SwiftUI app that lives in your menu bar. Auto-connects, auto-restarts, shows real-time status.
-  - icon: ⚡
-    title: MCP Tunnel
-    details: Secure WebSocket tunnel powered by the Poke SDK. Only your authenticated agent can reach your machine.
+- icon: 🖥️
+  title: Full Shell Access
+  details: Run any terminal command on your machine — ls, git, brew, python,
+    curl, and more.
+- icon: 📁
+  title: File Operations
+  details: Read, write, and list files and directories. Your Poke agent sees
+    your filesystem.
+- icon: 📸
+  title: Screenshots
+  details: Capture your screen remotely. Poke can see what you see.
+- icon: 🤖
+  title: Agents
+  details: Scheduled scripts that run in the background — automate message
+    digests, backups, health checks.
+- icon: 🌴
+  title: macOS Menu Bar App
+  details: Native SwiftUI app that lives in your menu bar. Auto-connects,
+    auto-restarts, shows real-time status.
+- icon: ⚡
+  title: MCP Tunnel
+  details: Secure WebSocket tunnel powered by the Poke SDK. Only your
+    authenticated agent can reach your machine.
 ---
 
 ## Quick install

package/docs/macos-app.md

@@ -1,16 +1,26 @@
 # macOS App
 
-Poke Gate includes a native SwiftUI menu bar app for macOS.
+Poke Gate includes a native SwiftUI menu bar app for macOS 15+ (Sequoia).
+
+## First-run setup
+
+On first launch, a **Setup View** guides you through two steps:
+
+1. **Choose access mode** — select Full, Limited, or Sandbox (see [Access modes](#access-modes) below)
+2. **Grant permissions** — the app checks for Accessibility permission and walks you through enabling it in System Settings
+
+The setup view only appears once. You can change the access mode anytime from Settings.
 
 ## Menu bar
 
 The app runs in the menu bar only — no Dock icon. Click the door icon to see the popover:
 
 - **Status** — green dot when connected, yellow when connecting, red on error
-- **Personalized** — shows "Connected to your Poke, [name]"
+- **Personalized** — shows "Connected to your Poke, name"
 - **Recent activity** — last few log entries
 - **Action buttons** — Logs, Agents, Settings, Restart/Start, Quit
-- **About** — version, GitHub link
+- **About** — dynamic version pulled from the app bundle (no hardcoded strings)
+- **Access mode chip** — shows the current mode with quick-switch buttons
 
 ### Status icons
 
@@ -20,6 +30,28 @@ The app runs in the menu bar only — no Dock icon. Click the door icon to see t
 | 🚪 (closed) | Stopped or connecting |
 | ⚠️ | Error |
 
+## Access modes
+
+The macOS app lets you choose an access mode from Settings or the popover. Changing the mode restarts poke-gate automatically.
+
+| Mode | What it allows |
+|------|---------------|
+| **Full System Access** | All tools available, subject to chat approval for risky actions |
+| **Limited Permissions** | Safe tools and curated command families only (`ls`, `cat`, `grep`, `curl`, etc.) |
+| **Run in Sandbox** | Broader command support, but writes restricted by macOS `sandbox-exec` to `~/Downloads` and `/tmp` |
+
+When **Full** mode is selected, the app shows an Accessibility permission prompt — this permission is required for keyboard/mouse automation and AppleScript tasks.
+
+## Accessibility permission
+
+The app uses an **Accessibility-first** permission model. Instead of requesting Full Disk Access, the app checks for Accessibility permission using the native `AXIsProcessTrusted()` API.
+
+- A dedicated **AccessibilityPermissionView** shows the current status with a button to open System Settings
+- Permission state refreshes automatically whenever the app regains focus
+- The view updates live — no need to restart the app after granting permission
+
+When Full mode is active, this view appears in both the Settings window and the popover to ensure you don't miss it.
+
 ## Settings
 
 Open Settings from the popover. The settings window shows:
@@ -27,6 +59,8 @@ Open Settings from the popover. The settings window shows:
 - **Authentication status** — whether you're signed in via Poke OAuth
 - **Sign in button** — runs `npx poke login` and opens a browser window
 - **Connection status** — current state with a Reconnect button
+- **Access mode** — radio buttons for Full, Limited, and Sandbox with descriptions
+- **Accessibility status** — permission check with a direct link to System Settings (in Full mode)
 
 ## Logs
 
@@ -34,6 +68,7 @@ The Logs window shows real-time activity:
 
 - Tool calls are highlighted
 - Errors appear in red
+- Sandbox status shown for each command (`sandbox=os` or `sandbox=none`)
 - Copy all logs to clipboard
 - Clear logs
 
@@ -58,7 +93,7 @@ The app connects automatically on launch if you've previously signed in. If the
 
 ## Building from source
 
-Requires macOS 15+ and Xcode 26+.
+Requires macOS 15+ and Xcode 16+.
 
 ```bash
 git clone https://github.com/f/poke-gate.git

package/docs/security.md

@@ -1,34 +1,78 @@
 # Security
 
 ::: danger Full shell access
-Poke Gate grants **full shell access** to your Poke agent. Understand the implications before running it.
+In **full** mode, Poke Gate grants **full shell access** to your Poke agent. Understand the implications before running it — or choose a more restrictive mode.
 :::
 
-## What the agent can do
+## Access modes
 
-When Poke Gate is running, your Poke agent can:
+Poke Gate supports three access modes that control what tools your agent can use:
 
-- **Run any command** with your user's permissions (`run_command`)
-- **Read any file** your user can access (`read_file`, `read_image`)
-- **Write any file** your user can access (`write_file`)
-- **List any directory** (`list_directory`)
-- **Take screenshots** of your screen (`take_screenshot`)
-- **See system info** — hostname, memory, uptime (`system_info`)
+### Full (default)
+
+All tools are available. Risky actions (`run_command`, `write_file`, `take_screenshot`) require **chat approval** — the agent must ask you in chat before executing, and you approve with a signed token.
+
+### Limited
+
+Only safe, read-only tools are available:
+
+- `read_file`, `read_image`, `list_directory`, `system_info`, `network_speed` work normally
+- `run_command` is restricted to a curated allowlist: `ls`, `pwd`, `cat`, `grep`, `find`, `head`, `tail`, `wc`, `sed`, `awk`, `curl`, `jq`, `diff`, and others
+- `write_file` and `take_screenshot` are **disabled**
+- Dangerous patterns (`sudo`, `rm -rf`, etc.) are always blocked
+
+### Sandbox
+
+Broader command support than Limited, plus commands like `brew`, `node`, `python`, `ffmpeg`, `mkdir`, `cp`, `mv`:
+
+- `run_command` uses macOS `sandbox-exec` to restrict file writes to `~/Downloads` and `/tmp`
+- `write_file` and `take_screenshot` are **disabled**
+- Dangerous patterns are always blocked
+
+### Setting the mode
+
+**CLI:**
+
+```bash
+npx poke-gate --mode limited
+npx poke-gate --mode sandbox
+```
+
+**Environment variable:**
+
+```bash
+POKE_GATE_PERMISSION_MODE=sandbox npx poke-gate
+```
+
+**macOS app:** Open Settings and select the access mode. The app restarts automatically when you change it.
+
+## Tool approval flow
+
+In **full** mode, risky tools (`run_command`, `write_file`, `take_screenshot`) use an HMAC-signed approval flow:
+
+1. The agent calls the tool — Poke Gate returns `AWAITING_APPROVAL` with a signed token
+2. The agent asks you in chat to approve
+3. You approve — the agent re-calls the tool with the approval token
+4. Optionally, you can `remember_in_session` (same command) or `remember_all_risky` (all risky tools for the session)
 
 ## What protects you
 
-- **Authentication** — only your Poke agent (authenticated via your Poke OAuth session) can reach the tunnel. No one else can send tool calls.
-- **Tunnel isolation** — the MCP server only listens on `127.0.0.1` (localhost). It's not exposed to the network. The tunnel is the only way to reach it.
-- **No persistent access** — when you quit Poke Gate (Ctrl-C or Quit from menu bar), the tunnel closes and the connection is deleted. Your machine is no longer reachable.
-- **Connection cleanup** — old connections are deleted before new ones are created, preventing stale tunnels.
+- **Authentication** — only your Poke agent (authenticated via Poke OAuth) can reach the tunnel
+- **Tunnel isolation** — the MCP server only listens on `127.0.0.1` (localhost), not exposed to the network
+- **Chat approval** — risky tools require explicit approval before execution (in full mode)
+- **Access policies** — limited and sandbox modes enforce strict command allowlists
+- **Loop guard** — duplicate or recently-failed commands are suppressed to prevent runaway retries
+- **No persistent access** — quitting Poke Gate closes the tunnel and deletes the connection
+- **Connection cleanup** — old connections are deleted before new ones are created
 
 ## Best practices
 
-1. **Only run on trusted machines** — don't run Poke Gate on shared or public computers.
-2. **Quit when not needed** — close the app when you don't need remote access.
-3. **Review agent scripts** — before installing a community agent, read the code. Agents run with your full user permissions.
-4. **Keep env files secure** — `.env` files in `~/.config/poke-gate/agents/` may contain API tokens. Don't commit them to git.
-5. **Use verbose mode** — run with `--verbose` to see what tools are being called in real time.
+1. **Choose the right access mode** — use `limited` or `sandbox` if you don't need full shell access.
+2. **Only run on trusted machines** — don't run Poke Gate on shared or public computers.
+3. **Quit when not needed** — close the app when you don't need remote access.
+4. **Review agent scripts** — before installing a community agent, read the code. Agents run with your user permissions.
+5. **Keep env files secure** — `.env` files in `~/.config/poke-gate/agents/` may contain API tokens. Don't commit them to git.
+6. **Use verbose mode** — run with `--verbose` to see what tools are being called in real time.
 
 ## Reporting issues
 

package/examples/agents/battery.30m.js

@@ -8,7 +8,7 @@
 
 import { Poke, getToken } from "poke";
 import { execSync } from "node:child_process";
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 

package/examples/agents/screentime.24h.js

@@ -17,10 +17,10 @@ if (!token) {
 
 function getScreenTime() {
   try {
-    const result = execSync(
-      `defaults read com.apple.ScreenTimeAgent 2>/dev/null || echo "{}"`,
-      { encoding: "utf-8", timeout: 10000 }
-    ).trim();
+    execSync(`defaults read com.apple.ScreenTimeAgent 2>/dev/null || echo "{}"`, {
+      encoding: "utf-8",
+      timeout: 10000,
+    }).trim();
 
     // Fallback: use process list to estimate active apps
     const ps = execSync(
@@ -42,11 +42,10 @@ function getActiveApps() {
       end tell
       return appList as text
     `;
-    const result = execSync(`osascript -e '${script}'`, {
+    return execSync(`osascript -e '${script}'`, {
       encoding: "utf-8",
       timeout: 10000,
     }).trim();
-    return result.split(", ");
   } catch {
     return [];
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poke-gate",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "description": "Expose your machine to your Poke AI assistant via MCP tunnel",
   "type": "module",
   "bin": {
@@ -8,6 +8,8 @@
   },
   "scripts": {
     "start": "node src/app.js",
+    "test": "node --test",
+    "test:watch": "node --test --watch",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "lint:md": "remark . --quiet --frail",