feat: add plugin caching with environment variable expansion

- Add cache system that copies plugins per construct instance
- Support ${VAR} and ${VAR:-default} syntax in configs
- Expand env vars in .mcp.json, agent frontmatter, skill frontmatter
- Add CLAUDE_PLUGIN_ROOT expansion to cached plugin path
- Add --clear-cache CLI flag for cleanup after crashes
- Support HTTP MCP servers in translation
- Auto-cleanup cache on process exit (including SIGINT/SIGTERM)

Author: scaryrawr

CLAUDE.md

@@ -17,6 +17,9 @@ bun run index.ts --load tmux@scaryrawr-plugins -- --continue
 
 # Run with saved config
 bun run index.ts
+
+# Clear plugin caches (after crashes/interrupts)
+bun run index.ts --clear-cache
 ```
 
 ### Project Structure
@@ -158,6 +161,20 @@ const mergedEnv = {
 };
 ```
 
+### Variable Expansion
+Environment variables are automatically expanded during plugin loading:
+- **Syntax**: `${VAR}` or `${VAR:-default}` 
+- **Scope**: MCP configs, agent frontmatter, and skill frontmatter
+- **Special Variable**: `${CLAUDE_PLUGIN_ROOT}` expands to the cached plugin directory path
+- See `variable-expansion.md` for complete syntax and behavior details
+
+### Plugin Cache System
+Plugins are cached per construct instance for reliable environment variable expansion:
+- **Cache Location**: `~/.cache/construct/plugins/<instance-id>/<marketplace>/<plugin>/`
+- **Lifecycle**: Auto-created on startup, auto-deleted on exit (normal or signal-based)
+- **Purpose**: Enables environment variable expansion in plugin files without modifying originals
+- **Isolation**: Each construct instance has isolated cache, enabling parallel runs
+
 ## Testing Strategies
 
 ### Unit Testing

README.md

@@ -58,21 +58,69 @@ construct -- "fix the failing tests"
 construct operator
 construct operator -- --continue
 
+# Clear plugin caches (removes all cached instances, useful after crashes)
+construct --clear-cache
+
 # Type-check the codebase
 bun run typecheck
 ```
 
 `construct operator` launches an interactive `fzf` multi-select for plugins, saves your selection to `.construct.json`, and then runs Copilot with those plugins enabled.
 
+## Environment Variables
+
+Construct supports automatic environment variable expansion in plugin configurations:
+
+### Supported Syntax
+
+- `${VAR}` - Basic expansion (uses value if set, otherwise unchanged)
+- `${VAR:-default}` - Expansion with default value (uses default if VAR is unset or empty)
+
+### Examples
+
+```json
+{
+  "chrome-devtools": {
+    "command": "npx",
+    "args": [
+      "chrome-devtools-mcp@latest",
+      "--browser-url=http://${DEVTOOLS_BASE_URL:-127.0.0.1}:${DEVTOOLS_PORT:-9222}"
+    ]
+  },
+  "greptile": {
+    "type": "http",
+    "url": "https://api.greptile.com/mcp",
+    "headers": {
+      "Authorization": "Bearer ${GREPTILE_API_KEY}"
+    }
+  }
+}
+```
+
+### Special Variables
+
+**`${CLAUDE_PLUGIN_ROOT}`** - Automatically expands to the cached plugin directory path. Useful for referencing plugin-relative paths in configurations.
+
+### Expansion Scope
+
+Environment variable expansion applies to:
+- MCP server configurations (`.mcp.json`)
+- Agent file frontmatter (YAML headers in `agents/*.md`)
+- Skill file frontmatter (YAML headers in `skills/*/SKILL.md`)
+
+Note: Plugin file bodies (markdown content) are not expanded, only metadata/frontmatter.
+
 ## How It Works
 
 1. **Scans** `~/.claude/plugins/installed_plugins.json` for installed Claude Code plugins
 2. **Discovers** skills, MCP servers, and agents in each plugin
-3. **Translates** Claude Code formats to Copilot CLI equivalents:
+3. **Caches** plugins per construct instance for reliable environment variable expansion
+4. **Translates** Claude Code formats to Copilot CLI equivalents:
    - Skills → `COPILOT_SKILLS_DIRS` environment variable
-   - MCP configs → `--additional-mcp-config` JSON argument
+   - MCP configs → `--additional-mcp-config` JSON argument (supports both local and HTTP servers)
    - Agents → `.github/agents/<plugin>-<agent>.md` files with translated tool references
-4. **Spawns** `copilot` with the translated configuration
+   - Environment variables → Automatically expanded in configurations
+5. **Spawns** `copilot` with the translated configuration
 
 ### Agent Translation
 

index.ts

@@ -5,6 +5,7 @@ import { loadConfig, saveConfig, mergeCliWithConfig } from "./src/config";
 import { translatePlugins } from "./src/translator";
 import { executeCopilot } from "./src/executor";
 import { runOperator } from "./src/operator";
+import { clearAllCaches } from "./src/cache";
 
 async function main(): Promise<void> {
   const args = parseCliArgs(process.argv);
@@ -14,6 +15,13 @@ async function main(): Promise<void> {
     process.exit(exitCode);
   }
 
+  // Handle --clear-cache
+  if (args.clearCache) {
+    await clearAllCaches();
+    console.log("Cache cleared.");
+    process.exit(0);
+  }
+
   // Handle --list
   if (args.listAvailablePlugins) {
     const plugins = await listAvailablePlugins();

src/agent-translator.ts

@@ -183,16 +183,22 @@ export async function writeAgentFile(
  * @param component - Agent component to translate
  * @param pluginInfo - Plugin information
  * @param mcpServers - List of available MCP server names
+ * @param cachedPath - Path to cached plugin directory with expanded frontmatter
  * @returns TranslatedAgent or null if translation fails
  */
 export async function translateSingleAgent(
   component: { type: string; path: string; name: string },
   pluginInfo: PluginInfo,
-  mcpServers: string[]
+  mcpServers: string[],
+  cachedPath: string
 ): Promise<TranslatedAgent | null> {
   try {
-    // Read agent file
-    const file = Bun.file(component.path);
+    // Compute relative path from plugin's install path and read from cached path
+    const relativePath = component.path.replace(pluginInfo.installPath, '').replace(/^\//, '');
+    const cachedFilePath = join(cachedPath, relativePath);
+    
+    // Read agent file from cached path
+    const file = Bun.file(cachedFilePath);
     const content = await file.text();
 
     // Parse frontmatter
@@ -269,23 +275,33 @@ export async function translateSingleAgent(
  *
  * @param plugins - Array of enabled plugins
  * @param mcpServers - List of available MCP server names
+ * @param cachedPaths - Map of plugin name to cached path
  * @returns Array of translated agents for cleanup tracking
  */
 export async function translateAgents(
   plugins: PluginInfo[],
-  mcpServers: string[]
+  mcpServers: string[],
+  cachedPaths: Map<string, string>
 ): Promise<TranslatedAgent[]> {
   const translatedAgents: TranslatedAgent[] = [];
 
   for (const plugin of plugins) {
+    // Look up cached path for this plugin
+    const cachedPath = cachedPaths.get(plugin.name);
+    if (!cachedPath) {
+      console.warn(`Skipping plugin ${plugin.name}: no cached path found`);
+      continue;
+    }
+    
     // Find agent components
     const agentComponents = plugin.components.filter(c => c.type === 'agent');
 
     for (const component of agentComponents) {
       const translated = await translateSingleAgent(
         component,
         plugin,
-        mcpServers
+        mcpServers,
+        cachedPath
       );
 
       if (translated) {