Gentleman.Dots

Important Notice (January 2026): Anthropic has blocked third-party tools (OpenCode, Crush, etc.) from using Claude Max subscriptions. OAuth tokens are now restricted to Claude Code only. This config now uses Claude Code as the primary AI assistant in Neovim, and OpenCode with API key as secondary option.

Description

This repository provides a complete, declarative development environment configuration using Nix Flakes and Home Manager. Everything is configured through local modules and automatically installs all dependencies.

🛠️ Development Tools & Languages

Languages: Node.js, Bun, Cargo/Rust, Go, GCC
Package Managers: Volta (Node.js), Cargo, Bun
Build Tools: Nil (Nix LSP), Nixd (Nix language server)
Utilities: jq, bash, fd, ripgrep, coreutils, unzip, bat, yazi

🐚 Shell Configurations

Fish Shell: Complete configuration with 400+ command completions
Nushell: Modern shell with custom config and environment setup
Zsh: Traditional shell with modern enhancements
Starship: Cross-shell prompt with custom configuration

🖥️ Terminal Emulators

Ghostty: Modern GPU-accelerated terminal with custom themes
WezTerm: Feature-rich terminal with Lua configuration
Tmux: Terminal multiplexer with custom key bindings
Zellij: Modern terminal workspace (optional - see customization)

⚡ Development Environment

Neovim: Fully configured IDE with LazyVim, AI assistants, and 40+ plugins
Zed: Modern code editor with custom themes and settings
Git & GitHub CLI: Pre-configured version control
Lazy Git: Terminal UI for Git operations

🤖 AI Integrations

Claude Code CLI: Primary AI coding assistant with 35 skills, SDD orchestrator workflow, Engram persistent memory, and custom Gentleman persona
OpenCode: Multi-model AI assistant with 12 agents (gentleman, sdd-orchestrator, dangerous-gentleman + 9 SDD sub-agents), same 35 skills, multi-provider support
Engram: Persistent memory system for cross-session context and SDD artifact storage
MCP Servers: Context7 (documentation), Notion (knowledge management)
Gemini CLI: Google's AI assistant (optional)

🔧 System Utilities

Television: Modern file navigator and system monitor
Zoxide: Smart directory jumping
Atuin: Enhanced shell history
Carapace: Universal shell completions
FZF: Fuzzy finder integration
Raycast Scripts: Custom automation scripts for display management

🪟 Window Management (macOS)

OmniWM (current Home Manager default): Apple Silicon, macOS 26+; migration and login setup
Yabai + Skhd + SketchyBar (legacy): kept for recovery, not imported or started by the default flake
Nehir / Aerospace: Alternative window managers (optional)

📝 Development Workflow

Oil.nvim: Custom file navigation scripts
Custom Scripts: Productivity-enhancing shell scripts
Nerd Fonts: Iosevka Term for consistent typography
Declarative Configuration: Everything version-controlled and reproducible

The flake automatically handles system-specific configurations, installs all dependencies, and sets up your complete development environment with a single command.

Features Overview

🎯 What You Get

Zero Configuration: Everything works out of the box
Declarative: Version-controlled, reproducible environment
Modern Toolchain: Latest development tools and utilities
AI-Enhanced: Multiple AI coding assistants integrated
Shell Agnostic: Fish, Nushell, and Zsh all configured
Terminal Flexibility: Multiple terminal emulators supported
macOS Optimized: Specifically tuned for macOS workflows

🔧 Technical Stack

Category	Tools
Package Manager	Nix with Flakes + Home Manager
Shells	Fish, Nushell, Zsh with Starship prompt
Terminals	Ghostty, WezTerm, Tmux, Zellij (optional)
Editor	Neovim (LazyVim) + Zed
Languages	Node.js, Rust, Go, with Volta management
AI Tools	Claude Code, OpenCode (12 agents), Engram, Herdr, Context7, Notion MCP
Navigation	Television, Yazi, Oil.nvim, Zoxide
Development	Git, GitHub CLI, Lazy Git
Window Manager	OmniWM (current); Yabai + Skhd + SketchyBar (legacy)
Automation	Raycast Scripts

📁 Project Structure

.
├── flake.nix              # Main Nix flake configuration
├── README.md              # This file
├── AGENTS.md              # AI agent instructions
│
├── # ─── Shell Configurations ───
├── fish.nix               # Fish shell configuration
├── fish/                  # Fish completions (400+ commands)
├── nushell.nix            # Nushell configuration
├── nushell/               # Nushell config and env files
├── zsh.nix                # Zsh configuration
├── starship.nix           # Starship prompt configuration
│
├── # ─── Terminal Emulators ───
├── ghostty.nix            # Ghostty terminal configuration
├── ghostty/               # Ghostty config, themes, and shaders
├── wezterm.nix            # WezTerm configuration
├── tmux.nix               # Tmux configuration
├── zellij.nix             # Zellij terminal workspace (optional)
├── zellij/                # Zellij plugins (zjstatus, forgot)
│
├── # ─── Editors ───
├── nvim.nix               # Neovim configuration
├── nvim/                  # Neovim plugins and settings (LazyVim)
├── nvim-oil-minimal/      # Minimal Neovim config for Oil.nvim
├── zed.nix                # Zed editor configuration
├── zed/                   # Zed themes, keymaps, tasks, prompts
│
├── # ─── AI Tools ───
├── claude.nix             # Claude Code CLI configuration
├── claude/                # Claude settings, 35 skills, themes, statusline, output styles
├── opencode.nix           # OpenCode AI configuration
├── opencode/              # OpenCode config, AGENTS.md, 35 skills, themes
├── engram.nix             # Engram persistent memory configuration
├── herdr.nix              # Herdr agent multiplexer configuration
├── gemini.nix             # Gemini CLI configuration (optional)
│
├── # ─── Window Management (macOS) ───
├── omniwm.nix             # OmniWM install check and legacy startup migration
├── nehir.nix              # Nehir config (optional, not imported)
├── nehir/                 # Nehir hotkeys, settings, workspaces (TOML)
├── yabai.nix              # Yabai window manager configuration (legacy, not imported)
├── yabai/                 # Yabai scripts and config
├── skhd.nix               # Skhd hotkey daemon configuration (legacy, not imported)
├── skhd/                  # Skhd keybindings (skhdrc)
├── sketchybar.nix         # SketchyBar status bar configuration (legacy, not imported)
├── sketchybar/            # SketchyBar plugins and config
├── simple-bar.nix         # simple-bar for Übersicht (disabled)
├── simple-bar/            # simple-bar themes (disabled)
├── aerospace/             # Aerospace window manager config (optional)
│
├── # ─── Utilities ───
├── television.nix         # Television file navigator
├── television/            # Television config and channels
├── oil-scripts.nix        # Custom Oil.nvim scripts
├── scripts/               # Custom utility scripts (ocd, oil)
├── raycast.nix            # Raycast scripts configuration
└── raycast/               # Raycast automation scripts

🐧 Linux Users: Important Configuration

If you're using Linux, you MUST disable macOS-specific modules before running the installation.

The following modules are macOS-only and will fail on Linux:

Module	Description	Why macOS-only
`omniwm.nix`	OmniWM and legacy startup migration	Requires Apple Silicon and macOS 26+
`yabai.nix`, `skhd.nix`, `sketchybar.nix`	Legacy window-management modules (not imported)	macOS-only
`simple-bar.nix`	Status bar widget	Requires Übersicht (macOS app)
`raycast.nix`	Automation scripts	Raycast is macOS-only

How to Disable macOS Modules

Edit flake.nix and comment out these lines in the modules array (around line 40-57):

modules = [
  ./nushell.nix
  ./ghostty.nix
  ./zed.nix
  ./television.nix
  ./wezterm.nix
  # ./zellij.nix  # Optional - uncomment if you want Zellij
  ./tmux.nix
  ./fish.nix
  ./starship.nix
  ./nvim.nix
  ./zsh.nix
  ./oil-scripts.nix
  ./opencode.nix
  ./claude.nix
  # ─── macOS ONLY - Comment these on Linux ───
  # ./omniwm.nix       # ← Comment this line
  # ./raycast.nix      # ← Comment this line
  {
    # ... rest of config

The default flake does not add the legacy window-manager packages to home.packages.

Additional Linux Changes

1. Set your username (around line 20):

# ─── User Configuration ───
# Change this to your Linux username
username = "YourUser";  # ← Replace with your username

2. Change home directory path (around line 67):

# Change from macOS path:
home.homeDirectory = "/Users/${username}";

# To Linux path:
home.homeDirectory = "/home/${username}";

3. Add Linux system support (around line 17):

# Change from:
supportedSystems = [ "x86_64-darwin" "aarch64-darwin" ];

# To (add your Linux architecture):
supportedSystems = [ "x86_64-darwin" "aarch64-darwin" "x86_64-linux" "aarch64-linux" ];

4. Add Linux home configuration (around line 140):

homeConfigurations = {
  # macOS system configurations
  "gentleman-macos-intel" = mkHomeConfiguration "x86_64-darwin";
  "gentleman-macos-arm" = mkHomeConfiguration "aarch64-darwin";
  
  # Linux system configurations (add these)
  "gentleman-linux" = mkHomeConfiguration "x86_64-linux";
  "gentleman-linux-arm" = mkHomeConfiguration "aarch64-linux";
  
  # Default to Apple Silicon
  "gentleman" = mkHomeConfiguration "aarch64-darwin";
};

5. Run installation with Linux config:

home-manager switch --flake .#gentleman-linux

Linux Alternatives

For window management on Linux, consider:

i3/Sway - Popular tiling window managers
Hyprland - Modern Wayland compositor
bspwm - Scriptable tiling window manager
Polybar/Waybar - Status bars (replace simple-bar)

Note: This configuration is primarily optimized for macOS. Linux support is possible but requires manual adjustment of these modules.

🪟 OmniWM Window Manager (macOS)

The default Home Manager flake uses OmniWM on Apple Silicon with macOS 26 or later. It preserves an existing app and GUI-managed settings; otherwise activation installs the Homebrew cask. Enable Start at Login yourself in OmniWM, then verify it in macOS Login Items. No additional launch agent is created.

See the migration guide for the legacy service cleanup, failure behavior, and tests. Nehir and the old yabai/skhd/SketchyBar modules remain in the repository but are not imported.

🖥️ SketchyBar Status Bar

Legacy — not imported or started by the default flake. Kept for users who explicitly return to yabai.

This configuration includes a fully customized SketchyBar setup with:

Workspace indicators with Yabai integration
System monitors (CPU, memory, battery)
Media controls and now playing info
Custom plugins for various system information

SketchyBar Plugins

Plugin	Description
`spaces.sh`	Workspace/space indicators with window counts
`front_app.sh`	Currently focused application
`media.sh`	Now playing media info
`battery.sh`	Battery status and percentage
`wifi.sh`	Network connection status
`clock.sh`	Date and time display

Starting SketchyBar

The default flake does not start SketchyBar. If you deliberately opt back into the legacy setup, these commands control it:

# Start
brew services start sketchybar

# Restart
brew services restart sketchybar

# Stop
brew services stop sketchybar

⚡ Raycast Scripts

Custom Raycast automation scripts for display and system management:

Script	Description
`set-4k.sh`	Set LG TV to 4K resolution with multi-monitor arrangement
`set-1080p.sh`	Set LG TV to 1080p resolution with multi-monitor arrangement
`reset-display-placement.sh`	Auto-detect resolution and reset display arrangement
`restart-sketchybar.sh`	Kill and restart SketchyBar

Setup

Open Raycast Settings → Extensions → Script Commands
Add ~/Raycast Scripts/ as a script directory
Scripts will be available in Raycast search

Requirements

displayplacer: brew install displayplacer

Note: Display scripts use hardcoded monitor IDs. Run displayplacer list to get your monitor IDs and update the scripts accordingly.

Installation Steps (for macOS)

1. Install the Nix Package Manager

sh <(curl -L https://nixos.org/nix/install)

2. Configure Nix to Use Extra Experimental Features

To enable the experimental features for flakes and the new nix-command (needed for our declarative setup), create/edit the configuration file:

# For daemon installation (default on macOS)
# The file may not exist, create it if needed
sudo mkdir -p /etc/nix
sudo nano /etc/nix/nix.conf
# Or: sudo vi /etc/nix/nix.conf

Add:

extra-experimental-features = flakes nix-command
build-users-group = nixbld

(This is necessary because support for flakes and the new Nix command is still experimental, but it allows us to have a fully declarative and reproducible configuration.)

3. Configure Your Username

The flake has Intel and Apple Silicon targets, but the default OmniWM module requires Apple Silicon and macOS 26+. Disable or replace that module before activating an Intel configuration.

You only need to update the username variable at the top of flake.nix (around line 20):

# ─── User Configuration ───
# Change this to your macOS username
username = "YourUser";  # ← Replace with your username

This single variable is used for both home.username and home.homeDirectory, so you only need to change it in one place.

4. Install Terminal Emulators (Optional)

Configurations are automatically applied. Choose your preferred terminal:

Ghostty (Recommended): https://ghostty.org/download
- Reload config with Shift + Cmd + ,
- Modern GPU-accelerated with custom themes
- Optimized for performance
- 50+ custom shaders included (CRT effects, cursor trails, matrix, etc.)
WezTerm: https://wezterm.org/installation.html
- Feature-rich with Lua configuration
- Cross-platform compatibility
- Advanced customization options

Ghostty Shaders

The configuration includes 50+ GLSL shaders for visual effects:

Category	Examples
CRT Effects	`crt.glsl`, `bettercrt.glsl`, `retro-terminal.glsl`
Cursor Trails	`cursor_blaze.glsl`, `cursor_smear.glsl`, `cursor_frozen.glsl`
Backgrounds	`starfield.glsl`, `matrix-hallway.glsl`, `galaxy.glsl`
Effects	`bloom.glsl`, `glitchy.glsl`, `underwater.glsl`

To enable a shader, edit ~/.config/ghostty/config and add:

custom-shader = ~/.config/ghostty/shaders/cursor_smear_gentleman.glsl

5. Window Management Options

Current default: OmniWM. See OmniWM Window Manager above. The Yabai/Skhd options below are legacy and no longer imported by flake.nix.

Option A: Yabai + Skhd (legacy)

The retained legacy modules can be re-imported explicitly, which also restores their startup hooks. They provide:

Yabai: Tiling window manager with BSP layout
Skhd: Hotkey daemon for keyboard shortcuts
SketchyBar: Status bar with workspace indicators

Key bindings (configured in skhd/skhdrc):

Shortcut	Action
`alt + h/j/k/l`	Focus window (vim-style)
`shift + alt + h/j/k/l`	Move window
`alt + 1-9`	Switch to space
`shift + alt + 1-9`	Move window to space
`alt + f`	Toggle fullscreen
`alt + t`	Toggle float

Note: Yabai requires accessibility permissions and SIP configuration. See yabai/README.md for details.

Option B: Aerospace (Alternative)

For a simpler setup without SIP changes, copy the Aerospace configuration:

cp ./aerospace/.aerospace.toml ~/

Aerospace provides:

Automatic window tiling
Workspace management
Keyboard-driven navigation
macOS-native integration (no SIP changes needed)

6. Install Home Manager

Before running the flake configuration, you need to set up Home Manager:

# Add home-manager channel
nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager

# Update channels
nix-channel --update

# Install home-manager
nix-shell '<home-manager>' -A install

7. Run the Installation

Once you have cloned the repository and are inside its directory, run the command for your system.

⚠️ Important: You must be in the root of this project directory for the command to work, as it uses . to find the flake.nix file.

For Apple Silicon with macOS 26 or later:

home-manager switch --flake .#gentleman

Alternative: Specific system configurations:

Apple Silicon Macs (M1/M2/M3/M4):

home-manager switch --flake .#gentleman-macos-arm

Intel Macs: the gentleman-macos-intel target requires disabling or replacing omniwm.nix before activation; OmniWM rejects Intel before the Home Manager write boundary.

(These commands apply the configuration defined in the flake, installing all dependencies and applying the necessary settings.)

8. Verify Installation

PATH is configured automatically on macOS!

9. Default Shell

Now run the following script to add Nushell, Fish or Zsh to your list of available shells and select it as the default one:

Fish (Recommended):

shellPath="$HOME/.local/state/nix/profiles/home-manager/home-path/bin/fish" && sudo sh -c "grep -Fxq '$shellPath' /etc/shells || echo '$shellPath' >> /etc/shells" && sudo chsh -s "$shellPath" "$USER"

Nushell:

shellPath="$HOME/.local/state/nix/profiles/home-manager/home-path/bin/nu" && sudo sh -c "grep -Fxq '$shellPath' /etc/shells || echo '$shellPath' >> /etc/shells" && sudo chsh -s "$shellPath" "$USER"

Zsh:

shellPath="$HOME/.local/state/nix/profiles/home-manager/home-path/bin/zsh" && sudo sh -c "grep -Fxq '$shellPath' /etc/shells || echo '$shellPath' >> /etc/shells" && sudo chsh -s "$shellPath" "$USER"

Configuration Details

🔧 How It Works

Declarative Setup: All configurations are defined in Nix modules
Automatic Deployment: Files are copied to correct macOS locations
Dependency Management: All tools and dependencies installed automatically
Version Pinning: Reproducible builds with locked versions
System Integration: Proper PATH configuration and shell integration

📍 File Locations

Configurations are automatically deployed to:

Tool	Location
Nushell	`~/Library/Application Support/nushell/`
Fish	`~/.config/fish/`
Ghostty	`~/.config/ghostty/`
WezTerm	`~/.wezterm.lua`
Neovim	`~/.config/nvim/`
Zed	`~/Library/Application Support/Zed/`
Starship	`~/.config/starship.toml`
Tmux	`~/.config/tmux/`
Zellij	`~/.config/zellij/` (optional)
Television	`~/.config/television/`
Claude Code	`~/.claude/`
OpenCode	`~/.config/opencode/`
Engram	`~/go/bin/engram` (managed by `engram.nix`)
OmniWM	`~/.config/omniwm/` (managed by the app)
Yabai	`~/.config/yabai/` (legacy)
Skhd	`~/.config/skhd/` (legacy)
SketchyBar	`~/.config/sketchybar/` (legacy)
Raycast	`~/Raycast Scripts/`

🚀 Performance Features

Shell Completions: 400+ Fish completions for better productivity
Smart History: Atuin for enhanced command history across shells
Fuzzy Finding: FZF integration for quick file/command finding
Directory Navigation: Zoxide for intelligent directory jumping
File Management: Yazi and Television for modern file browsing
Git Workflow: Lazy Git for streamlined version control

🤖 AI Development Features

Claude Code Integration: Native AI coding assistant with 35 skills and SDD orchestrator
OpenCode Multi-Agent: 12 agents spanning multiple AI providers for SDD workflow
Engram Memory: Persistent cross-session memory for context and artifact storage
MCP Servers: Context7 for live documentation, Notion for knowledge management
SDD Workflow: Full Spec-Driven Development pipeline (explore → propose → spec → design → tasks → apply → verify → archive)

🎨 Theming & Customization

Consistent Themes: Catppuccin and custom themes across all tools
Nerd Font Support: Iosevka Term for perfect icon rendering
GPU Acceleration: Modern terminals with hardware acceleration
Custom Key Bindings: Vim-like navigation across all tools

Troubleshooting

Common Issues

Command not found after installation:

hash -r  # Refresh command cache
source ~/.zshrc  # or ~/.bashrc

nix: command not found when running home-manager:

This happens when the Nix binaries aren't in your PATH. Source the Nix daemon profile first:

# Source Nix profile
source /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh

# Then run home-manager
home-manager switch --flake .#gentleman

Permission denied when copying configs (sketchybar, nvim, etc):

Some config files may be set as read-only. Fix permissions before running home-manager:

# For sketchybar:
chmod -R u+w ~/.config/sketchybar/

# For nvim:
chmod -R u+w ~/.config/nvim/

# Then re-run home-manager
home-manager switch --flake .#gentleman

Nix installation issues:

Ensure /etc/nix/nix.conf has experimental features enabled
Restart terminal after Nix installation
Check that you're in the project directory when running commands

Terminal not picking up themes:

For Ghostty: Use Shift + Cmd + , to reload config
For WezTerm: Restart the terminal
Verify config files are in correct locations

Customization

Adding your own configurations:

Edit the relevant .nix files
Run the installation command again
Changes are applied automatically

Managing versions:

Update flake.lock with: nix flake update
Pin specific package versions in the flake

Enabling Optional Configurations:

Some configurations are commented out by default. To enable them:

Zellij Terminal Workspace:

# Edit flake.nix and uncomment the Zellij line
sed -i '' 's|# ./zellij.nix|./zellij.nix|' flake.nix

# Re-run the installation
nix run github:nix-community/home-manager -- switch --flake .#gentleman-macos-arm -b backup

Features:

Modern terminal multiplexer alternative to tmux
Vim-like keybindings with custom themes
Plugin system with status bar and session management
Custom layouts and workspace management

Additional Configuration Required: After enabling Zellij, you need to update shell configurations to use Zellij instead of tmux:

Fish Shell (~/.config/fish/config.fish):

# Change line ~31 from:
if not set -q TMUX; and not set -q ZED_TERMINAL
    tmux

# To:
if not set -q ZELLIJ; and not set -q ZED_TERMINAL
    zellij

Zsh Shell (~/.zshrc):

# Change lines ~100-102 from:
WM_VAR="/$TMUX"
WM_CMD="tmux"

# To:
WM_VAR="/$ZELLIJ"
WM_CMD="zellij"

Nushell (~/.config/nushell/config.nu):

# Change lines ~1015-1016 from:
let MULTIPLEXER = "tmux"
let MULTIPLEXER_ENV_PREFIX = "TMUX"

# To:
let MULTIPLEXER = "zellij"
let MULTIPLEXER_ENV_PREFIX = "ZELLIJ"

Gemini CLI Integration:

# Edit flake.nix and add Gemini module
# Add './gemini.nix' to the modules list in flake.nix

# Re-run the installation
nix run github:nix-community/home-manager -- switch --flake .#gentleman-macos-arm -b backup

Features:

Google's AI assistant CLI tool
Integrated via Bun package manager
Direct access with gemini command
Perfect for AI-powered development workflows

🤖 Claude Code CLI Configuration

This configuration includes a complete Claude Code CLI setup with custom skills, themes, and output styles.

Claude Code Features

Feature	Description
CLAUDE.md	Custom system instructions and Gentleman persona
Skills	35 skills covering SDD workflow, frameworks, testing, and project patterns
Output Styles	Custom response formatting (Gentleman style)
Themes	Custom TweakCC theme for terminal
Statusline	Custom status bar script
MCP Servers	context7 (docs), engram (memory), notion (knowledge)

Included Skills

Both Claude Code and OpenCode share the exact same 35 skills, organized by category:

SDD Skills (9) — Spec-Driven Development workflow:

Skill	Description
`sdd-init`	Initialize SDD context in any project
`sdd-explore`	Explore and investigate ideas before committing
`sdd-propose`	Create a change proposal with intent and scope
`sdd-spec`	Write specifications with requirements and scenarios
`sdd-design`	Create technical design document
`sdd-tasks`	Break down a change into implementation tasks
`sdd-apply`	Implement tasks following specs and design
`sdd-verify`	Validate implementation matches specs
`sdd-archive`	Sync delta specs and archive completed changes

Framework Skills (10):

Skill	Trigger
`react-19`	React components, hooks, JSX (React Compiler)
`nextjs-15`	App Router, Server Components, Server Actions
`typescript`	Types, interfaces, generics (strict mode)
`tailwind-4`	Tailwind CSS 4 styling patterns
`zod-4`	Zod 4 schema validation
`zustand-5`	Zustand 5 state management
`ai-sdk-5`	Vercel AI SDK 5 chat features
`django-drf`	Django REST Framework ViewSets, Serializers
`dotnet`	.NET 9 / ASP.NET Core Minimal APIs
`scope-rule-architect-angular`	Angular 20+ Scope Rule architecture

Testing Skills (3):

Skill	Trigger
`playwright`	E2E tests, Page Objects, selectors
`pytest`	Python tests, fixtures, mocking
`go-testing`	Go tests, Bubbletea TUI testing

Workflow Skills (5):

Skill	Trigger
`skill-creator`	Creating new AI agent skills
`skill-registry`	Update skill registry for project
`pr-review`	Review GitHub PRs and issues
`technical-review`	Review candidate submissions
`homebrew-release`	Release workflow for Gentleman-Programming projects

Project Skills (7) — Gentleman.Dots specific:

Skill	Trigger
`gentleman-bubbletea`	Bubbletea TUI patterns in installer
`gentleman-installer`	Installation step patterns
`gentleman-system`	System detection and command execution
`gentleman-trainer`	Vim Trainer RPG system patterns
`gentleman-e2e`	Docker-based E2E testing
`jira-epic`	Create Jira epics (Prowler standard format)
`jira-task`	Create Jira tasks (Prowler standard format)

Creative (1):

Skill	Trigger
`stream-deck`	Slide-deck presentations for streams and courses

OpenCode Configuration

OpenCode shares all 35 skills with Claude Code and additionally includes:

12 agents defined in opencode.json:
- gentleman — primary coding agent with Gentleman persona (primary)
- sdd-orchestrator — SDD orchestration with delegation-only behavior (primary)
- dangerous-gentleman — all permissions enabled, for complex automation
- 9 hidden SDD sub-agents, each using a different model:
  - sdd-apply → claude-sonnet-4-6
  - sdd-archive → gpt-5.4
  - sdd-design → claude-opus-4-6
  - sdd-explore → claude-sonnet-4-6
  - sdd-init → claude-opus-4-6
  - sdd-propose → gemini-3.1-pro-preview
  - sdd-spec → gemini-3.1-pro-preview
  - sdd-tasks → gemini-3.1-pro-preview
  - sdd-verify → gpt-5.4
AGENTS.md — project-level agent instructions referenced by all agents via {file:./AGENTS.md}
MCP Servers: context7 (documentation), engram (persistent memory), notion (knowledge management)

AI Configuration for Neovim

This configuration includes support for the following AI tools:

Avante.nvim - AI-powered coding assistant
CopilotChat.nvim - GitHub Copilot chat interface
OpenCode.nvim - OpenCode AI integration
CodeCompanion.nvim - Multi-AI provider support
Claude Code.nvim - Claude AI integration (enabled by default)
Gemini.nvim - Google Gemini integration

How to Switch AI Plugins

Claude Code is already enabled by default. To switch to a different AI assistant:

Navigate to the disabled plugins file:

nvim ~/.config/nvim/lua/plugins/disabled.lua

Disable Claude Code by changing enabled = true to enabled = false:

{
  "greggh/claude-code.nvim",
  enabled = false,  -- Disable Claude Code
},

Enable your preferred AI assistant by changing enabled = false to enabled = true:

{
  "yetone/avante.nvim",
  enabled = true,  -- Change to true to enable
},

Save the file and restart Neovim.

Important Notes

Only enable ONE AI plugin at a time to avoid conflicts and keybinding issues
Required CLI tools are automatically installed by the script:
- Claude Code CLI (brew install --cask claude-code)
- OpenCode CLI (curl -fsSL https://opencode.ai/install | bash)
- Gemini CLI (brew install gemini-cli)
API keys may be required for some services - check each plugin's documentation
Node.js 18+ is required for most AI plugins (automatically handled by the configuration)

Switching Between AI Assistants

To switch from one AI assistant to another:

Set your current AI plugin to enabled = false
Set your desired AI plugin to enabled = true
Restart Neovim

Recommended AI Assistants

For beginners: Start with CodeCompanion.nvim - supports multiple AI providers
For Claude users: Use Claude Code.nvim with the Claude Code CLI
For GitHub Copilot users: Use CopilotChat.nvim
For Google Gemini users: Use Gemini.nvim with the Gemini CLI

OpenCode Configuration

Why Claude Code is the default: In January 2026, Anthropic restricted their OAuth tokens to only work with the official Claude Code CLI. Third-party tools like OpenCode, Crush, etc. were blocked from using Claude Max/Pro subscriptions.

Recommended: Use OpenCode with API Key

The safest way to use OpenCode is with an Anthropic API key:

{
  "provider": "anthropic",
  "model": "anthropic/claude-sonnet-4-20250514"
}

Then set your API key:

export ANTHROPIC_API_KEY="your-api-key-here"

Location: ~/.config/opencode/opencode.json

OpenCode SDD Orchestrator (Agent Teams)

This setup also includes an sdd-orchestrator agent with the same Gentleman personality as gentleman, plus delegate-only SDD orchestration behavior.

Recommended usage flow:

Start OpenCode in your project:
```
opencode .
```
Open the agent picker (Tab) and select sdd-orchestrator

Run SDD commands:

/sdd:init
/sdd:new <change-name>
/sdd:continue

Switch back to gentleman (Tab) for day-to-day coding.

Artifact store recommendation:

Use artifact_store.mode: engram (recommended) - https://github.com/gentleman-programming/engram
auto fallback order: user-requested files -> engram -> existing openspec -> none

⚠️

RISKY ALTERNATIVE: opencode-anthropic-auth plugin (click to expand)

There's a community plugin (opencode-anthropic-auth) that enables OAuth authentication with Claude Max/Pro subscriptions. However, this violates Anthropic's Terms of Service and can result in account suspension.

What the plugin does:

Spoofs the Claude Code CLI's OAuth client ID
Fakes the user-agent to impersonate Claude Code
Replaces "OpenCode" strings to evade server detection

From Anthropic's Usage Policy:

"Do Not Abuse our Platform: Intentionally bypass capabilities, restrictions, or guardrails established within our products without prior authorization from Anthropic"

Risks:

🚫 Account ban - Your Claude account can be suspended
⚠️ You can request an unban via X/Twitter, but it's not guaranteed
🔄 Anthropic could block this workaround at any time

If you still want to use it (at your own risk):

{
  "plugin": ["opencode-anthropic-auth"],
  "model": "anthropic/claude-sonnet-4-20250514"
}

We do NOT recommend this approach. Use Claude Code CLI or OpenCode with an API key instead.

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Test your changes thoroughly
Submit a pull request

For questions or issues, open a GitHub issue.

Contributors

Thanks to everyone who has contributed to Gentleman.Dots!

Happy coding! 🚀

— Gentleman Programming

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.windsurf/workflows		.windsurf/workflows
aerospace		aerospace
alacritty		alacritty
atuin/themes		atuin/themes
docs		docs
fish		fish
ghostty		ghostty
herdr		herdr
homebrew-tap/Formula		homebrew-tap/Formula
installer		installer
nehir		nehir
nushell		nushell
nvim-oil-minimal		nvim-oil-minimal
nvim		nvim
odd/tasks		odd/tasks
raycast		raycast
scripts		scripts
simple-bar		simple-bar
sketchybar		sketchybar
skhd		skhd
skills		skills
television		television
tmux-agents		tmux-agents
yabai		yabai
zed		zed
zellij		zellij
.gitignore		.gitignore
AGENTS.md		AGENTS.md
Dockerfile.test		Dockerfile.test
README.es.md		README.es.md
README.md		README.md
alacritty.nix		alacritty.nix
claude.nix		claude.nix
engram.nix		engram.nix
fish.nix		fish.nix
flake.lock		flake.lock
flake.nix		flake.nix
gemini.nix		gemini.nix
ghostty.nix		ghostty.nix
herdr.nix		herdr.nix
kitty.nix		kitty.nix
nehir.nix		nehir.nix
nushell.nix		nushell.nix
nvim.nix		nvim.nix
oil-scripts.nix		oil-scripts.nix
omniwm.nix		omniwm.nix
opencode.nix		opencode.nix
raycast.nix		raycast.nix
simple-bar.nix		simple-bar.nix
sketchybar.nix		sketchybar.nix
skhd.nix		skhd.nix
starship.nix		starship.nix
television.nix		television.nix
tmux-agents.nix		tmux-agents.nix
tmux.nix		tmux.nix
wezterm.nix		wezterm.nix
yabai.nix		yabai.nix
zed.nix		zed.nix
zellij.nix		zellij.nix
zsh.nix		zsh.nix

Latest commit

History

Folders and files

Repository files navigation

Gentleman.Dots

Description

🛠️ Development Tools & Languages

🐚 Shell Configurations

🖥️ Terminal Emulators

⚡ Development Environment

🤖 AI Integrations

🔧 System Utilities

🪟 Window Management (macOS)

📝 Development Workflow

Features Overview

🎯 What You Get

🔧 Technical Stack

📁 Project Structure

🐧 Linux Users: Important Configuration

How to Disable macOS Modules

Additional Linux Changes

Linux Alternatives

🪟 OmniWM Window Manager (macOS)

🖥️ SketchyBar Status Bar

SketchyBar Plugins

Starting SketchyBar

⚡ Raycast Scripts

Setup

Requirements

Installation Steps (for macOS)

1. Install the Nix Package Manager

2. Configure Nix to Use Extra Experimental Features

3. Configure Your Username

4. Install Terminal Emulators (Optional)

Ghostty Shaders

5. Window Management Options

Option A: Yabai + Skhd (legacy)

Option B: Aerospace (Alternative)

6. Install Home Manager

7. Run the Installation

8. Verify Installation

9. Default Shell

Configuration Details

🔧 How It Works

📍 File Locations

🚀 Performance Features

🤖 AI Development Features

🎨 Theming & Customization

Troubleshooting

Common Issues

Customization

🤖 Claude Code CLI Configuration

Claude Code Features

Included Skills

OpenCode Configuration

AI Configuration for Neovim

How to Switch AI Plugins

Important Notes

Switching Between AI Assistants

Recommended AI Assistants

OpenCode Configuration

OpenCode SDD Orchestrator (Agent Teams)

Contributing

Contributors

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages