Add user scripts feature with multi-path and directory support (#41)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: gricha

docs/docs/configuration/ai-agents.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # AI Agents

docs/docs/configuration/github.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # GitHub Integration

docs/docs/configuration/overview.md

@@ -50,7 +50,11 @@ Location: `~/.config/perry/config.json`
     "workspaces": {}
   },
   "scripts": {
-    "post_start": "~/.config/perry/scripts/post-start.sh"
+    "post_start": [
+      "~/.perry/userscripts",
+      "~/scripts/setup.sh"
+    ],
+    "fail_on_error": false
   },
   "allowHostAccess": true
 }
@@ -103,6 +107,7 @@ perry config worker myserver.tail1234.ts.net
 
 - [Environment Variables](./environment.md) - Inject env vars into workspaces
 - [Files](./files.md) - Copy files into workspaces
+- [Scripts](./scripts.md) - Run scripts after workspace starts
 - [GitHub](./github.md) - GitHub token and SSH key setup
 - [AI Agents](./ai-agents.md) - Claude Code, OpenCode, Codex CLI
 - [Tailscale](./tailscale.md) - Remote access via Tailscale

docs/docs/configuration/scripts.md

@@ -0,0 +1,214 @@
+---
+sidebar_position: 4
+---
+
+# Scripts
+
+Run custom scripts after workspace starts. Scripts execute after file sync, so they can reference synced resources.
+
+## Configuration
+
+### Via config.json
+
+```json
+{
+  "scripts": {
+    "post_start": [
+      "~/.perry/userscripts",
+      "~/scripts/setup.sh"
+    ],
+    "fail_on_error": false
+  }
+}
+```
+
+### Via Web UI
+
+1. Open http://localhost:7391
+2. Go to Settings > Scripts
+3. Add script paths or directories
+4. Toggle "Stop on script error" if needed
+5. Save
+
+## Default Configuration
+
+New installations include:
+
+```json
+{
+  "scripts": {
+    "post_start": ["~/.perry/userscripts"],
+    "fail_on_error": false
+  }
+}
+```
+
+Create `~/.perry/userscripts/` directory on your host to add startup scripts.
+
+## Script Types
+
+### Single Scripts
+
+Point to a shell script file:
+
+```json
+{
+  "scripts": {
+    "post_start": ["~/scripts/setup.sh"]
+  }
+}
+```
+
+The script must be executable (`chmod +x`).
+
+### Script Directories
+
+Point to a directory containing `.sh` files:
+
+```json
+{
+  "scripts": {
+    "post_start": ["~/.perry/userscripts"]
+  }
+}
+```
+
+All `.sh` files in the directory execute in **sorted order** (alphabetical). Use numeric prefixes to control order:
+
+```
+~/.perry/userscripts/
+  01-install-tools.sh
+  02-configure-git.sh
+  10-setup-project.sh
+```
+
+Non-`.sh` files are ignored.
+
+## Multiple Sources
+
+Combine scripts and directories:
+
+```json
+{
+  "scripts": {
+    "post_start": [
+      "~/.perry/userscripts",
+      "~/work/company-setup.sh",
+      "~/projects/tools"
+    ]
+  }
+}
+```
+
+Scripts execute in array order.
+
+## Error Handling
+
+### Default: Continue on Error
+
+```json
+{
+  "scripts": {
+    "post_start": ["~/scripts/setup.sh"],
+    "fail_on_error": false
+  }
+}
+```
+
+If a script fails, Perry logs a warning and continues with remaining scripts. Workspace starts normally.
+
+### Strict Mode
+
+```json
+{
+  "scripts": {
+    "post_start": ["~/scripts/setup.sh"],
+    "fail_on_error": true
+  }
+}
+```
+
+If any script exits with non-zero status, workspace startup fails.
+
+## Execution Environment
+
+Scripts run:
+- As the `workspace` user
+- In the container's home directory (`/home/workspace`)
+- After file sync completes (synced files are available)
+- With access to configured environment variables
+
+## Common Use Cases
+
+### Install Project Tools
+
+```bash
+#!/bin/bash
+# ~/.perry/userscripts/01-install-tools.sh
+
+# Install global npm packages
+npm install -g typescript tsx
+
+# Install rust tools
+cargo install just
+```
+
+### Configure Git
+
+```bash
+#!/bin/bash
+# ~/.perry/userscripts/02-git-config.sh
+
+# Set up git aliases not in .gitconfig
+git config --global alias.st status
+git config --global alias.co checkout
+```
+
+### Create Symlinks
+
+```bash
+#!/bin/bash
+# ~/.perry/userscripts/03-symlinks.sh
+
+# Link synced config directories
+ln -sf ~/.synced-nvim ~/.config/nvim
+ln -sf ~/.synced-tmux/.tmux.conf ~/.tmux.conf
+```
+
+### Start Background Services
+
+```bash
+#!/bin/bash
+# ~/.perry/userscripts/99-services.sh
+
+# Start any background services needed
+# (Note: prefer using Docker services when possible)
+```
+
+## Path Expansion
+
+- `~` expands to home directory on host
+- Scripts are copied to container and executed there
+- Absolute paths work as-is
+
+## Apply Changes
+
+Scripts run:
+- When creating new workspaces
+- When starting stopped workspaces
+
+Scripts do **not** run when syncing (`perry sync`) - only file sync occurs.
+
+## Debugging
+
+Check script output in workspace logs:
+
+```bash
+perry logs myworkspace
+```
+
+Or connect to the workspace and check manually:
+
+```bash
+perry ssh myworkspace
+```

docs/docs/configuration/tailscale.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 # Tailscale Integration

src/agent/router.ts

@@ -61,7 +61,8 @@ const CredentialsSchema = z.object({
 });
 
 const ScriptsSchema = z.object({
-  post_start: z.string().optional(),
+  post_start: z.array(z.string()).optional(),
+  fail_on_error: z.boolean().optional(),
 });
 
 const CodingAgentsSchema = z.object({

src/config/loader.ts

@@ -19,7 +19,10 @@ export function createDefaultAgentConfig(): AgentConfig {
       env: {},
       files: {},
     },
-    scripts: {},
+    scripts: {
+      post_start: ['~/.perry/userscripts'],
+      fail_on_error: false,
+    },
     agents: {},
     allowHostAccess: true,
     ssh: {
@@ -33,6 +36,19 @@ export function createDefaultAgentConfig(): AgentConfig {
   };
 }
 
+function migratePostStart(value: unknown): string[] {
+  if (!value) {
+    return ['~/.perry/userscripts'];
+  }
+  if (typeof value === 'string') {
+    return [value, '~/.perry/userscripts'];
+  }
+  if (Array.isArray(value)) {
+    return value.length > 0 ? value : ['~/.perry/userscripts'];
+  }
+  return ['~/.perry/userscripts'];
+}
+
 export async function loadAgentConfig(configDir?: string): Promise<AgentConfig> {
   const dir = getConfigDir(configDir);
   const configPath = path.join(dir, CONFIG_FILE);
@@ -46,7 +62,10 @@ export async function loadAgentConfig(configDir?: string): Promise<AgentConfig>
         env: config.credentials?.env || {},
         files: config.credentials?.files || {},
       },
-      scripts: config.scripts || {},
+      scripts: {
+        post_start: migratePostStart(config.scripts?.post_start),
+        fail_on_error: config.scripts?.fail_on_error ?? false,
+      },
       agents: config.agents || {},
       allowHostAccess: config.allowHostAccess ?? true,
       ssh: {

src/index.ts

@@ -437,8 +437,15 @@ configCmd
     for (const [dest, src] of Object.entries(config.credentials.files)) {
       console.log(`    - ${dest} <- ${src}`);
     }
-    if (config.scripts.post_start) {
-      console.log(`  Post-start Script: ${config.scripts.post_start}`);
+    const scripts = config.scripts.post_start;
+    if (scripts && scripts.length > 0) {
+      console.log(`  Post-start Scripts: ${scripts.length}`);
+      for (const script of scripts) {
+        console.log(`    - ${script}`);
+      }
+    }
+    if (config.scripts.fail_on_error) {
+      console.log(`  Scripts Fail on Error: enabled`);
     }
   });
 

src/shared/client-types.ts

@@ -36,7 +36,8 @@ export interface Credentials {
 }
 
 export interface Scripts {
-  post_start?: string;
+  post_start?: string[];
+  fail_on_error?: boolean;
 }
 
 export interface CodingAgents {

src/shared/types.ts

@@ -11,7 +11,8 @@ export interface WorkspaceCredentials {
 }
 
 export interface WorkspaceScripts {
-  post_start?: string;
+  post_start?: string[];
+  fail_on_error?: boolean;
 }
 
 export interface CodingAgents {