🔀 Janus

Directory-aware OpenCode configuration switcher

Named after the Roman god of transitions—seamlessly transform your configuration as you navigate between projects

Features • Quick Start • Configuration • How It Works

✨ Features

🎯 Smart Path Matching

Automatically detects your working directory and applies the right configuration

⚡ Zero Overhead

Lightweight shell integration with instant switching

🔒 Process Isolation

Each OpenCode instance runs with its own isolated configuration

🎨 Flexible Patterns

Full glob pattern support with longest-prefix priority

🚀 Quick Start

Installation

npm install -g opencode-janus

git clone https://github.com/kuitos/janus.git
cd janus
bun install && bun run build
npm install -g .

Setup in 3 steps

# 1. Create your configuration file
mkdir -p ~/.config/janus
nano ~/.config/janus/config.json

# 2. Install shell hook (auto-detects zsh/bash)
janus install

# 3. Reload your shell
source ~/.zshrc  # or ~/.bashrc

That's it! 🎉 Your opencode command now adapts to each directory.

⚙️ Configuration

Create ~/.config/janus/config.json with your mapping rules:

{
  "defaultConfigDir": "/Users/yourname/.config/opencode-default", // Optional: Fallback config for unmatched paths
  "mappings": [
    {
      "match": ["/Users/yourname/work/**"],        // Company projects
      "configDir": "/Users/yourname/.config/opencode-work"
    },
    {
      "match": ["/Users/yourname/projects/oss/**"], // Open source
      "configDir": "/Users/yourname/.config/opencode-oss"
    },
    {
      "match": ["/Users/yourname/personal/**"],     // Personal projects
      "configDir": "/Users/yourname/.config/opencode-personal"
    }
  ]
}

Configuration Structure

Each configDir should contain:

~/.config/opencode-work/
├── opencode.json           # OpenCode settings
└── oh-my-opencode.json     # oh-my-opencode plugins

| Field | Type | Required | Description | |-------|------|----------|-------------| | defaultConfigDir | string | No | Fallback configuration directory when no mappings match | | mappings | Array | Yes | List of directory-to-config mapping rules | | match | string[] | Yes | Path patterns to match (supports ** glob) | | configDir | string | Yes | Absolute path to configuration directory |

Pattern Matching:

• Supports glob patterns: **, *, ?
• Supports tilde (~) expansion for home directory
• Multiple patterns per mapping
• Longest (most specific) match wins
• Falls back to defaultConfigDir if configured and no match found

Path Examples:

{
  "defaultConfigDir": "~/.config/opencode-default",  // ✅ Optional fallback
  "mappings": [
    {
      "match": ["~/work/**"],           // ✅ Tilde expanded to home directory
      "configDir": "~/.config/work"     // ✅ Also supports tilde
    },
    {
      "match": ["/absolute/path/**"],   // ✅ Absolute path
      "configDir": "/absolute/config"
    }
  ]
}

Default Configuration Behavior:

• When a directory doesn't match any pattern in mappings, defaultConfigDir is used (if configured)
• If defaultConfigDir is not set, unmatched directories will not use any configuration (backward compatible)
• Useful for providing a general-purpose configuration for casual projects

💡 How It Works

graph LR
    A[cd ~/work/project] --> B{janus hook}
    B --> C[Match path patterns]
    C --> D[Find longest match]
    D --> E[Set OPENCODE_CONFIG_DIR]
    E --> F[opencode uses custom config]

1. Shell Integration – Hook runs on directory change
2. Path Resolution – Matches current path against patterns
3. Priority Selection – Longest (most specific) pattern wins
4. Environment Setup – Sets OPENCODE_CONFIG_DIR for the session
5. Isolated Execution – Each process gets the right configuration

🛠️ Commands

janus install    # Install shell hook (auto-detects shell)
janus uninstall  # Remove shell hook
janus --version  # Show version
janus --help     # Show help

🧪 Development

# Run tests
bun test

# Coverage report
bun test --coverage

# Type checking
bun run typecheck

# Build for production
bun run build

📦 Project Structure

src/
├── cli.ts              # CLI entry point
├── config.ts           # Configuration loading & validation
├── resolver.ts         # Path matching engine
├── install.ts          # Shell hook installer
├── shell-hook.ts       # Hook generation logic
├── types.ts            # TypeScript definitions
└── *.test.ts           # Comprehensive test suite

🤝 Contributing

Contributions are welcome! Feel free to:

• 🐛 Report bugs
• 💡 Suggest features
• 🔧 Submit pull requests

📄 License

MIT © kuitos

🙏 Acknowledgments

Built with ❤️ using:

• Bun – Fast all-in-one JavaScript runtime
• Zod – TypeScript-first schema validation

Inspired by:

• direnv – Environment switcher for the shell
• projj – Project management tool