fix: add global .env file support for client configuration #40

This fix eliminates the need to manually create .env files in every
cloned repository by introducing a two-tier environment variable
configuration system.

Changes:
- Modified Config class to support loadGlobal() method
- Added Config.loadGlobal() call in index.ts before repository-specific load
- Created examples/global-env.example with setup instructions
- Updated client/README.md with configuration documentation
- Updated CLAUDE.md with environment variable configuration section

Configuration priority:
1. Global config: ~/.config/agent-manager/.env (shared across all repos)
2. Repository-specific config: .env in repo root (overrides global)

Benefits:
- No need to duplicate GOGS_* variables in every repository
- Backward compatible with existing repository .env files
- Secure credentials storage with restricted permissions
- Flexible per-repository overrides when needed

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -662,6 +662,41 @@ The client automatically discovers available tools from all configured MCP serve
 
 **Example**: If you configure a custom MCP server named "github" with tools "create_pr" and "list_repos", they will automatically be available as `mcp__github__create_pr` and `mcp__github__list_repos`.
 
+### Environment Variable Configuration
+
+The client supports a two-tier environment variable configuration system to eliminate the need for duplicating `.env` files in every cloned repository:
+
+**Configuration Priority**:
+1. **Global configuration**: `~/.config/agent-manager/.env` (shared across all repositories)
+2. **Repository-specific configuration**: `.env` in repository root (overrides global)
+
+**How It Works**:
+1. When the client starts, it first loads `Config.loadGlobal()` to read `~/.config/agent-manager/.env`
+2. Then it loads `Config.load(repoPath)` to read the repository-specific `.env` (if it exists)
+3. Repository-specific values override global values
+4. If a repository doesn't have a `.env` file, it uses only global values
+
+**Required Environment Variables**:
+- `GOGS_ACCESS_TOKEN` or `GOGS_TOKEN` - Gogs API authentication token
+- `GOGS_BASE_URL` - Gogs server URL (e.g., `https://git.smartbotics.ai`)
+- `GOGS_MCP_PATH` - Path to gogs-mcp server (defaults to `/data/gogs-mcp/dist/index.js`)
+
+**Setup Global Configuration**:
+```bash
+mkdir -p ~/.config/agent-manager
+cp examples/global-env.example ~/.config/agent-manager/.env
+chmod 600 ~/.config/agent-manager/.env
+# Edit the file and add your actual values
+```
+
+**Benefits**:
+- **No duplication** - Set `GOGS_ACCESS_TOKEN` once in global config instead of in every repository
+- **Flexibility** - Repositories can override global values when needed
+- **Backward compatible** - Existing repository `.env` files continue to work
+- **Secure** - Credentials stored in `~/.config/agent-manager/` with restricted permissions
+
+See `examples/global-env.example` for a complete example configuration file.
+
 ## Code Modification Guidelines
 
 **Main Server (src/)**:

client/README.md

@@ -170,20 +170,51 @@ The client is called directly from `commands.json` for issue and issue_comment e
 
 ### Environment Variables
 
-The client reads configuration from the repository's `.env` file:
+The client loads environment variables from **two locations** (in priority order):
 
-```env
-# Required: Path to gogs-mcp server
-GOGS_MCP_PATH=/data/gogs-mcp/dist/index.js
+1. **Global configuration**: `~/.config/agent-manager/.env` (shared across all repositories)
+2. **Repository-specific configuration**: `.env` in repository root (overrides global)
+
+This allows you to set common values (like `GOGS_ACCESS_TOKEN`) once in the global file, eliminating the need to duplicate them in every cloned repository.
+
+#### Global Configuration (`~/.config/agent-manager/.env`)
+
+Create this file to set global defaults for all repositories:
 
-# Required: Gogs API authentication
+```env
+# Required: Gogs API authentication (applies to all repositories)
 GOGS_ACCESS_TOKEN=your-token-here
 GOGS_BASE_URL=https://git.smartbotics.ai
 
-# Optional: Home directory override
-HOME=/home/claude
+# Optional: Path to gogs-mcp server
+GOGS_MCP_PATH=/data/gogs-mcp/dist/index.js
 ```
 
+**Setup**:
+```bash
+mkdir -p ~/.config/agent-manager
+cp /path/to/agent-manager/examples/global-env.example ~/.config/agent-manager/.env
+chmod 600 ~/.config/agent-manager/.env
+# Edit the file and add your values
+```
+
+#### Repository-Specific Configuration (`.env` in repository)
+
+Optional. Use this to override global values for specific repositories:
+
+```env
+# Example: Use a different Gogs token for this specific repository
+GOGS_ACCESS_TOKEN=repo-specific-token
+
+# Example: Custom home directory for this repository
+HOME=/custom/home/path
+```
+
+**Notes**:
+- Repository-specific values **override** global values
+- If a repository doesn't have a `.env` file, it uses only global values
+- You no longer need to manually create `.env` files in every cloned repository
+
 ### Webhook Variables
 
 When called from `commands.json`, the client receives these variables from webhooks:

client/src/config.ts

@@ -11,11 +11,10 @@ export class Config {
   private static envVars: Map<string, string> = new Map();
 
   /**
-   * Load environment variables from .env file
+   * Load environment variables from a .env file
+   * Private helper method used by loadGlobal() and load()
    */
-  static load(repoPath: string): void {
-    const envPath = join(repoPath, '.env');
-
+  private static loadEnvFile(envPath: string, source: string): void {
     if (!existsSync(envPath)) {
       return;
     }
@@ -44,11 +43,31 @@ export class Config {
           }
         }
       }
+      console.log(`Loaded ${source}: ${envPath}`);
     } catch (error) {
-      console.error(`Warning: Failed to load .env file: ${error}`);
+      console.error(`Warning: Failed to load ${source} from ${envPath}: ${error}`);
     }
   }
 
+  /**
+   * Load global environment variables from ~/.config/agent-manager/.env
+   * This should be called before load() to set global defaults
+   */
+  static loadGlobal(): void {
+    const home = process.env.HOME || process.env.USERPROFILE || '/root';
+    const globalEnvPath = join(home, '.config', 'agent-manager', '.env');
+    this.loadEnvFile(globalEnvPath, 'global .env');
+  }
+
+  /**
+   * Load environment variables from repository-specific .env file
+   * Repository-specific values override global values
+   */
+  static load(repoPath: string): void {
+    const envPath = join(repoPath, '.env');
+    this.loadEnvFile(envPath, 'repository .env');
+  }
+
   /**
    * Get environment variable value
    */

client/src/index.ts

@@ -96,8 +96,10 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   process.chdir(repoPath);
   console.log(`Working directory: ${process.cwd()}`);
 
-  // Load configuration
-  Config.load(repoPath);
+  // Load configuration: global first, then repository-specific
+  console.log('Loading configuration...');
+  Config.loadGlobal();  // Load global .env from ~/.config/agent-manager/.env
+  Config.load(repoPath);  // Load repository-specific .env (overrides global)
 
   // Generate MCP configuration for this repository
   const mcpConfig = Config.generateMcpConfig(repoPath, owner, repo);

commands.json

@@ -38,3 +38,4 @@
     "global": []
   }
 }
+

examples/global-env.example

@@ -0,0 +1,18 @@
+# Global .env file for agent-manager client
+# Location: ~/.config/agent-manager/.env
+#
+# This file provides global environment variables that apply to all cloned repositories.
+# Repository-specific .env files can override these values.
+#
+# Required for Gogs API access (used by gogs-helper.ts before MCP initialization)
+GOGS_ACCESS_TOKEN=your-gogs-access-token-here
+GOGS_BASE_URL=https://git.smartbotics.ai
+
+# Optional: Path to gogs-mcp server (defaults to /data/gogs-mcp/dist/index.js)
+GOGS_MCP_PATH=/data/gogs-mcp/dist/index.js
+
+# Notes:
+# 1. Create this file at: ~/.config/agent-manager/.env
+# 2. Copy this example and fill in your actual values
+# 3. Ensure proper permissions: chmod 600 ~/.config/agent-manager/.env
+# 4. Repository-specific .env files (in each cloned repo) can override these values