Simplify env setup: use .env.local with Bun native loading

Refactor environment variable management to leverage Bun native .env loading:

- Replace .infisical-cache with .env.local as the secrets file
- Use .env.development.local for worktree port overrides (highest precedence)
- Simplify .bin/bun wrapper: sync Infisical to .env.local, let Bun load natively
- Add create_env_symlinks() for subdirectory .env.local access
- Simplify CONTRIBUTING.md: manual .env.local setup as default path
- Move Infisical to optional team setup in INFISICAL_SETUP_GUIDE.md
- Add "bun run setup" script for quick .env.local creation
- Update knowledge.md with correct env file hierarchy
- Fix Next.js dev server: use PORT env var instead of shell expansion
- Fix init-worktree.ts to set PORT to webPort for Next.js

Author: brandonkachen

.bin/bun

@@ -2,11 +2,10 @@
 .idea/
 .vercel
 
+# Environment files (secrets) - Bun loads .env.* files natively
 .env
 .env.*
 !.env.example
-.env.worktree
-.worktree-env.sh
 
 # ctags
 tags
@@ -29,7 +28,5 @@ debug/
 .nx/cache
 .nx/workspace-data
 
-# Infisical cache (contains secrets, should not be committed)
-.infisical-cache
-.infisical-cache.tmp
+# Infisical config (user-specific)
 .infisical.json

.gitignore

@@ -9,74 +9,46 @@ Hey there! 👋 Thanks for wanting to contribute to Codebuff. Whether you're squ
 Before you begin, you'll need to install a few tools:
 
 1. **Bun** (our primary package manager): Follow the [Bun installation guide](https://bun.sh/docs/installation)
-2. **direnv**: This manages environment variables automatically
-   - macOS: `brew install direnv`
-   - Ubuntu/Debian: `sudo apt install direnv`
-   - Other systems: See [direnv installation guide](https://direnv.net/docs/installation.html)
-3. **Docker**: Required for the web server database
-4. **Infisical CLI**: For secrets management
-   ```bash
-   npm install -g @infisical/cli
-   ```
+2. **Docker**: Required for the web server database
 
 ### Setting Up Your Development Environment
 
-1. **Hook direnv into your shell** (one-time setup):
-
-   - For zsh: `echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && source ~/.zshrc`
-   - For bash: `echo 'eval "$(direnv hook bash)"' >> ~/.bashrc && source ~/.bashrc`
-   - For fish: `echo 'direnv hook fish | source' >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish`
-
-2. **Restart your shell**: Run `exec $SHELL` or restart your terminal
-
-3. **Clone the repository**:
+1. **Clone the repository**:
 
    ```bash
    git clone https://github.com/CodebuffAI/codebuff.git
    cd codebuff
    ```
 
-4. **Set up secrets management**:
+2. **Set up environment variables**:
 
    ```bash
-   npm install -g @infisical/cli
-   infisical init
-   infisical login
-   # Select "US" region when prompted
+   # Copy the example file
+   cp .env.example .env.local
+   
+   # Edit .env.local and update DATABASE_URL to match Docker:
+   # DATABASE_URL=postgresql://manicode_user_local:secretpassword_local@localhost:5432/manicode_db_local
    ```
 
-   Follow the [Infisical Setup Guide](./INFISICAL_SETUP_GUIDE.md) for detailed setup instructions.
-
-   Load all environment variables at once:
-
-   ```bash
-   infisical secrets set --file .env.example
-   infisical secrets set DATABASE_URL=postgresql://manicode_user_local:secretpassword_local@localhost:5432/manicode_db_local
-   ```
-
-5. **Configure environment**:
-
-   ```bash
-   direnv allow
-   ```
+   > **Team members**: For shared secrets management, see the [Infisical Setup Guide](./INFISICAL_SETUP_GUIDE.md).
 
-6. **Install dependencies**:
+3. **Install dependencies**:
 
    ```bash
    bun install
    ```
 
-7. **Setup a Github OAuth app**
+4. **Setup a Github OAuth app**
 
    1. Follow these instructions to set up a [Github OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app)
-   2. Find your app's Github client ID and secret access key and set them in Infisical:
+   2. Add your Github client ID and secret to `.env.local`:
 
    ```bash
-   infisical secrets set CODEBUFF_GITHUB_ID=<your-github-app-id-here>
-   infisical secrets set CODEBUFF_GITHUB_SECRET=<your-github-app-secret-here>
+   CODEBUFF_GITHUB_ID=<your-github-app-id-here>
+   CODEBUFF_GITHUB_SECRET=<your-github-app-secret-here>
    ```
 
-8. **Start development services**:
+5. **Start development services**:
 
    **Option A: All-in-one (recommended)**
    ```bash
@@ -99,7 +71,7 @@ Before you begin, you'll need to install a few tools:
 
    **Note**: CLI requires both backend and web server running for authentication.
 
-9. **Giving yourself credits**:
+6. **Giving yourself credits**:
 
    1. Log into Codebuff at [http://localhost:3000/login](http://localhost:3000/login)
 
@@ -115,7 +87,7 @@ Before you begin, you'll need to install a few tools:
 
    Now, you should be able to run the CLI commands locally from within the `codebuff` directory.
 
-10. **Running in other directories**:
+7. **Running in other directories**:
 
 In order to run the CLI from other directories, you need to first publish the agents to the database.
 
@@ -271,14 +243,12 @@ Level up the web interface in `web/` with better agent management, project templ
 
 **Setup issues?**
 
-- **direnv problems?** Make sure it's hooked into your shell, run `direnv allow`, and restart your terminal
 - **Script errors?** Double-check you're using bun for all commands
-- **Infisical issues?** See our [Infisical Setup Guide](./INFISICAL_SETUP_GUIDE.md) for step-by-step instructions
 - **Database connection errors?** If you see `password authentication failed for user "postgres"` errors:
-  1. Ensure DATABASE_URL uses the correct credentials: `postgresql://manicode_user_local:secretpassword_local@localhost:5432/manicode_db_local`
-  2. Update both your local `.env` file and Infisical secret: `infisical secrets set DATABASE_URL=postgresql://manicode_user_local:secretpassword_local@localhost:5432/manicode_db_local`
-  3. Run the database migration: `infisical run -- bun run db:migrate`
-  4. Restart your development services
+  1. Ensure DATABASE_URL in `.env.local` uses the correct credentials: `postgresql://manicode_user_local:secretpassword_local@localhost:5432/manicode_db_local`
+  2. Run the database migration: `bun run db:migrate`
+  3. Restart your development services
+- **Using Infisical?** See the [Infisical Setup Guide](./INFISICAL_SETUP_GUIDE.md) for team secrets management
 - **Empty Agent Store in dev mode?** This is expected behavior - agents from `.agents/` directory need to be published to the database to appear in the marketplace
 
 **Questions?** Jump into our [Discord community](https://codebuff.com/discord) - we're friendly and always happy to help!

CONTRIBUTING.md

@@ -1,51 +1,80 @@
-# Simple Infisical Setup for Codebuff
+# Infisical Setup Guide
 
-Quick 5-step setup to get Codebuff running with Infisical secrets.
+This guide is for **team/advanced secrets management** using [Infisical](https://infisical.com/).
+
+> **Personal development?** Just copy `.env.example` to `.env.local` and fill in your values. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full setup guide.
+
+## Why Infisical?
+
+- **Team sync**: Share secrets securely across team members
+- **Auto-refresh**: The `.bin/bun` wrapper automatically syncs secrets to `.env.local`
+- **No manual copying**: Secrets stay up-to-date with a 15-minute cache
+
+## Prerequisites
+
+- **direnv**: Required for the bun wrapper to work
+  - macOS: `brew install direnv`
+  - Ubuntu/Debian: `sudo apt install direnv`
+  - [Hook it into your shell](https://direnv.net/docs/hook.html)
 
 ## Setup Steps
 
-### 1. Install & Setup
+### 1. Enable the bun wrapper
+```bash
+direnv allow
+```
+This adds `.bin/` to your PATH so the Infisical sync wrapper runs automatically.
+
+### 2. Install & Login
 ```bash
 npm install -g @infisical/cli
 infisical init
 infisical login
 # Select "US" region when prompted
-infisical secrets  # Verify setup works
 ```
 
-### 2. Browser Login
+### 3. Browser Login
 - Browser opens automatically to https://app.infisical.com
-- Login with **any email** (Gmail, etc.)
-- Fill in any **name** and **organization name** when asked
+- Login with your email
+- Select or create your organization and project
 - Copy the token from browser and paste in terminal
 
-### 3. Select Project  
-- Use arrow keys to choose your organization
-- Select or create a Codebuff project
-
-### 4. Load Environment Variables
+### 4. Load Initial Secrets
 ```bash
-# Load all variables at once
+# Load all variables from .env.example as a starting point
 infisical secrets set --file .env.example
 
-# IMPORTANT: Fix the database password separately
+# Fix the database password to match Docker
 infisical secrets set DATABASE_URL=postgresql://manicode_user_local:secretpassword_local@localhost:5432/manicode_db_local
 ```
 
-### 5. Done! Run Codebuff
+### 5. Run Codebuff
 ```bash
-bun run dev  # Starts everything automatically
+bun run dev  # Secrets auto-sync to .env.local
 ```
 
-## Common Issues & Quick Fixes
+## How It Works
 
-**Token won't paste?** → Right-click → paste  
-**Database error?** → Run the DATABASE_URL command above  
-**Can't navigate menus?** → Use arrow keys ↓ ↑  
+1. The `.bin/bun` wrapper checks if `.env.local` needs refreshing
+2. If stale (>15 min) or missing, it syncs from Infisical
+3. Bun then loads `.env.local` automatically
 
-## That's It!
+## Common Issues
 
-The `.env.example` file contains all the dummy values needed for development. Only the database password needs to be fixed to match Docker's password.
+| Problem | Solution |
+|---------|----------|
+| Token won't paste | Right-click → paste |
+| Session expired | Run `infisical login` again |
+| Can't navigate menus | Use arrow keys ↓ ↑ |
+| Infisical not working | Fall back to manual `.env.local` |
 
-You will need to populate all the secrets in the Infisical UI at https://app.infisical.com. You can provide dummy values for the secrets if you get an error about missing secrets, but you will need to update them with real values in order to use the associated feature.
+## Updating Secrets
 
+```bash
+# Set a single secret
+infisical secrets set MY_API_KEY=abc123
+
+# Delete the local cache to force refresh
+rm .env.local
+bun run dev  # Re-syncs from Infisical
+```

INFISICAL_SETUP_GUIDE.md

@@ -366,33 +366,52 @@ Important constants are centralized in `common/src/constants.ts`:
 
 ## Environment Variables
 
-This project uses [Infisical](https://infisical.com/) for secret management. All secrets are injected at runtime.
+This project uses standard `.env.*` files for environment configuration. Bun natively loads these files automatically.
 
-### Release Process
+### File Hierarchy
 
-The release mechanism uses the `CODEBUFF_GITHUB_TOKEN` environment variable directly. The old complex GitHub App token generation system has been removed in favor of using a simple personal access token or the infisical-managed token.
+Bun loads `.env` files in this order (highest precedence last):
 
-Environment variables are defined and validated in `packages/internal/src/env.ts`. This module provides type-safe `env` objects for use throughout the monorepo.
+1. `.env.local` - Main secrets file synced from Infisical (gitignored)
+2. `.env.development.local` - Worktree-specific overrides like ports (gitignored, highest precedence)
+
+**Note**: Bun also supports `.env` and `.env.development`, but this project only uses `.env.local` and `.env.development.local`.
+
+### Infisical Integration
+
+Infisical is used as a background sync mechanism to populate `.env.local`:
 
-### Bun Wrapper Script
+- The `.bin/bun` wrapper syncs secrets from Infisical to `.env.local`
+- Caching: 15-minute TTL (configurable via `INFISICAL_CACHE_TTL`)
+- Cache invalidates when `.infisical.json` is modified or TTL expires
+- If Infisical is not set up, existing `.env.local` is used directly
 
-The `.bin/bun` script automatically wraps bun commands with infisical when secrets are needed. It prevents nested infisical calls by checking for `NEXT_PUBLIC_INFISICAL_UP` environment variable, ensuring infisical runs only once at the top level while nested bun commands inherit the environment variables.
+**Setup Options**:
+1. **With Infisical**: Run `infisical login`, secrets auto-sync to `.env.local`
+2. **Without Infisical**: Copy `.env.example` to `.env.local` and fill in values
 
-**Worktree Support**: The wrapper automatically detects and loads `.env.worktree` files when present, allowing worktrees to override Infisical environment variables (like ports) for local development. This enables multiple worktrees to run simultaneously on different ports without conflicts.
+### Worktree Support
 
-The wrapper also loads environment variables in the correct precedence order:
+For git worktrees running on different ports:
 
-1. Infisical secrets are loaded first (if needed)
-2. `.env.worktree` is loaded second to override any conflicting variables
-3. This ensures worktree-specific overrides (like custom ports) always take precedence over cached Infisical defaults
+- Create `.env.development.local` in the worktree with port overrides
+- Bun loads `.env.development.local` with highest precedence, so it overrides ports from `.env.local`
+- The `scripts/init-worktree.ts` script creates this file automatically
 
-The wrapper looks for `.env.worktree` in the project root directory, making it work consistently regardless of the current working directory when bun commands are executed.
+### Bun Wrapper Script (`.bin/bun`)
 
-**Performance Optimizations**: The wrapper uses `--silent` flag with Infisical to reduce CLI output overhead and sets `INFISICAL_DISABLE_UPDATE_CHECK=true` to skip version checks for faster startup times.
+The wrapper's role is simple: ensure `.env.local` is synced from Infisical before running bun.
 
-**Infisical Caching**: The wrapper implements robust caching of environment variables in `.infisical-cache` with a 15-minute TTL (configurable via `INFISICAL_CACHE_TTL`). This reduces startup time from ~1.2s to ~0.16s (87% improvement). The cache uses `infisical export` which outputs secrets directly in `KEY='value'` format, ensuring ONLY Infisical-managed secrets are cached (no system environment variables). Multi-line secrets like RSA private keys are handled correctly using `source` command. Cache automatically invalidates when `.infisical.json` is modified or after TTL expires. Uses subshell execution to avoid changing the main shell's working directory.
+- Checks `NEXT_PUBLIC_INFISICAL_UP` to prevent nested syncs
+- Uses `INFISICAL_DISABLE_UPDATE_CHECK=true` for faster startup
+- 10-second timeout on Infisical commands to prevent hangs
+- Falls back gracefully if Infisical is not available
 
-**Session Validation**: The wrapper detects expired Infisical sessions using `infisical export` with a robust 10-second timeout implementation that works cross-platform (macOS and Linux). Uses background processes with polling to prevent hanging on interactive prompts. Valid sessions output environment variables in `KEY='value'` format, while expired sessions either output interactive prompts or timeout. Provides clear error messages directing users to run `infisical login`.
+### Release Process
+
+The release mechanism uses the `CODEBUFF_GITHUB_TOKEN` environment variable directly.
+
+Environment variables are defined and validated in `packages/internal/src/env.ts`. This module provides type-safe `env` objects for use throughout the monorepo.
 
 ## Python Package
 

knowledge.md

@@ -16,7 +16,7 @@ All environment variables are defined and validated in `env.ts`:
 
 - Server variables: API keys, database URLs, service credentials
 - Client variables: Public configuration values
-- Uses Infisical for secret management in development
+- Loaded from `.env.local` (manually created or synced from Infisical)
 
 ## Current Integrations
 

packages/internal/src/knowledge.md

@@ -29,6 +29,13 @@ cleanup_worktree() {
     fi
 
     # Clean up any worktree-specific files that might be left behind
+    if [ -f "$WORKTREE_PATH/.env.development.local" ]; then
+        rm -f "$WORKTREE_PATH/.env.development.local" 2>/dev/null || true
+    fi
+    # Also clean up legacy .env.development and .env.worktree if present
+    if [ -f "$WORKTREE_PATH/.env.development" ]; then
+        rm -f "$WORKTREE_PATH/.env.development" 2>/dev/null || true
+    fi
     if [ -f "$WORKTREE_PATH/.env.worktree" ]; then
         rm -f "$WORKTREE_PATH/.env.worktree" 2>/dev/null || true
     fi

scripts/cleanup-worktree.sh

@@ -206,17 +206,22 @@ async function checkGitBranchExists(branchName: string): Promise<boolean> {
   }
 }
 
-function createEnvWorktreeFile(worktreePath: string, args: WorktreeArgs): void {
+function createEnvDevelopmentLocalFile(
+  worktreePath: string,
+  args: WorktreeArgs,
+): void {
   const envContent = `# Worktree-specific port overrides
 # Generated by init-worktree.ts for worktree: ${args.name}
-PORT=${args.backendPort}
+# This file has highest precedence in Bun's .env loading order, overriding .env.local
+# PORT is used by Next.js dev server
+PORT=${args.webPort}
 NEXT_PUBLIC_CODEBUFF_BACKEND_URL=localhost:${args.backendPort}
 NEXT_PUBLIC_WEB_PORT=${args.webPort}
 NEXT_PUBLIC_CODEBUFF_APP_URL=http://localhost:${args.webPort}
 `
 
-  writeFileSync(join(worktreePath, '.env.worktree'), envContent)
-  console.log('Created .env.worktree with port configurations')
+  writeFileSync(join(worktreePath, '.env.development.local'), envContent)
+  console.log('Created .env.development.local with port configurations')
 }
 
 function copyInfisicalConfig(worktreePath: string): void {
@@ -308,9 +313,9 @@ async function main(): Promise<void> {
     console.log(`Web port: ${args.webPort}`)
 
     // Create configuration files
-    createEnvWorktreeFile(worktreePath, args)
+    createEnvDevelopmentLocalFile(worktreePath, args)
     copyInfisicalConfig(worktreePath)
-    // Note: .bin/bun wrapper now automatically loads .env.worktree
+    // Note: Bun loads .env.development.local with highest precedence, overriding .env.local
 
     // Run direnv allow
     await runDirenvAllow(worktreePath)

scripts/init-worktree.ts

@@ -10,7 +10,7 @@
     }
   },
   "scripts": {
-    "dev": "next dev -p ${NEXT_PUBLIC_WEB_PORT:-3000}",
+    "dev": "next dev",
     "build": "next build 2>&1 | sed '/Contentlayer esbuild warnings:/,/^]/d' && bun run scripts/prebuild-agents-cache.ts",
     "start": "next start",
     "preview": "bun run build && bun run start",