Claude Workspace Tools

A comprehensive workspace setup for Claude Code with command extensions, multi-AI integration, and synchronized development workflows.

🚀 Quick Start

Clone and setup:

git clone <this-repo>
cd claude-workspace-tools
chmod +x setup-ai-tools.sh
./setup-ai-tools.sh

Reload your shell:

source ~/.zshrc  # or ~/.bashrc, ~/.config/fish/config.fish

Start working:

ai          # Launch synchronized AI workflow
claude      # Use Claude with enhanced commands
/gemini     # Analyze large codebases

🏗️ System Architecture

Extension Framework

The setup uses a scalable extension system for Claude Code commands:

claude-workspace-tools/
├── extensions/                    # Command extension repositories
│   ├── SuperClaude/              # Professional development framework (submodule)
│   ├── claude-sessions/          # Session management system (submodule)  
│   └── custom-commands/          # Workflow-specific commands
├── config/
│   ├── extensions.yaml           # Extension registry and metadata
│   └── enabled.yaml              # User's active extensions
└── setup-ai-tools.sh            # Enhanced installation script

Available Extensions

Extension	Commands	Description
SuperClaude	18+	Professional development framework with specialized commands
claude-sessions	6	Advanced session management with persistence and context
custom-commands	2	Workflow tools for Gemini and visualization
agents	3	Specialized AI agents for deep research and code analysis

📦 What the Setup Script Does

The enhanced setup-ai-tools.sh script provides:

Core AI Tools Installation

✅ AI CLI Tools: Claude, Gemini, Codex (with detection of existing installations)
🔑 API Key Configuration: Secure environment variable setup
🐚 Shell Integration: Auto-detects zsh/bash/fish and configures appropriately
📺 Tmux Workflows: Synchronized multi-AI sessions with custom keybindings

Extension Framework

🔧 Extension Management: Modular installation of command packages
📊 Status Detection: Intelligent detection of existing installations
🎯 Selective Installation: Choose which extensions to install
🔄 Configuration Sync: Automatic enabled.yaml management

Git Workflow Integration

🌳 Worktree Scripts: Advanced parallel development workflows
🔀 PR-Only Workflow: Enforced pull request development process

🔑 Required API Keys

Service	CLI Tool	API Key Variable	Get API Key From
Anthropic Claude	`claude`	`ANTHROPIC_API_KEY`	console.anthropic.com
Google Gemini	`gemini`	`GOOGLE_AI_API_KEY`	aistudio.google.com/app/apikey
OpenAI Codex	`codex`	`OPENAI_API_KEY`	platform.openai.com/api-keys
Background Tasks	`claude`	`ENABLE_BACKGROUND_TASKS`	Set to `1` to enable enhanced processing

🔐 GitHub CLI Authentication & Rate Limits

The GitHub CLI (gh) is used by Claude Code for creating pull requests and other GitHub operations. It has different rate limits based on authentication:

Without authentication: 60 requests/hour (very restrictive)
With Personal Access Token (PAT): 5,000 requests/hour (recommended)

Setting up GitHub CLI with PAT

Create a Personal Access Token:
- Go to github.com/settings/tokens
- Click "Generate new token (classic)"
- Select scopes: repo (full control of private repositories)
- Copy the generated token

Authenticate GitHub CLI:

# Authenticate using PAT (recommended for higher rate limits)
echo "$YOUR_PAT" | gh auth login --hostname github.com --with-token

# Or set as environment variable
export GH_TOKEN="your_personal_access_token_here"

Verify authentication:
```
gh auth status
```

Rate Limit Monitoring

Check your current rate limit status:

# View current rate limits
gh api rate_limit

# Check remaining requests
gh api rate_limit | jq '.rate.remaining'

⚠️ Important: Without proper authentication, you may encounter rate limiting errors when using commands like gh pr create in automated workflows.

🔧 Background Tasks

The setup script automatically configures ENABLE_BACKGROUND_TASKS=1 for enhanced Claude capabilities:

✅ Adds to shell config (bash/zsh/fish agnostic) for global availability
✅ Prevents duplicates if already configured

🛠️ Available Commands

CLI Aliases

claude - Enhanced Claude CLI with extensions
gemini - Gemini CLI for large codebase analysis
codex - OpenAI Codex CLI for AI-powered development
cursor-agent - Cursor Agent for advanced GPT-5 analysis
yolo - Claude with dangerous permissions enabled
cursor - Cursor Agent with high reasoning and full access

Claude Code Extensions

SuperClaude Commands (18+)

Development framework with specialized commands:

/build - Universal project builder with stack templates
/review - AI-powered code review with evidence-based recommendations
/deploy - Application deployment with rollback capabilities
/analyze - Multi-dimensional analysis (code, architecture, performance, security)
/test - Comprehensive testing framework (e2e, integration, unit, visual, performance)
/troubleshoot - Professional debugging with systematic approaches
/improve - Enhancement & optimization with measurable outcomes
And 11+ more specialized commands...

Session Management Commands (6)

Advanced session tracking and persistence:

/project:session-start [name] - Start new development session
/project:session-update [notes] - Add timestamped progress updates
/project:session-end - End session with comprehensive summary
/project:session-current - Show current session status
/project:session-list - List all past sessions
/project:session-help - Display help information

Custom Workflow Commands (2)

Specialized workflow tools:

/gemini - Large codebase analysis using Gemini's massive context window
/mermaid - Generate Mermaid diagrams and visualizations

AI Agents (3)

Specialized agents for advanced analysis:

agent-expert - Creates specialized Claude Code agents with proper domain expertise
gpt-5 - Deep research and complex problem-solving using GPT-5 via Cursor Agent
cursor-agent - Advanced code analysis with high reasoning effort and full model capabilities

Tmux Workflow Sessions

Multi-AI synchronized sessions:

ai - Start synchronized session with Claude + Gemini + Terminal
reai - Reconnect to the AI session
ai-yolo - Start session with two Claude instances in "yolo" mode + Terminal
reai-yolo - Reconnect to the yolo session
ai-trinity - Start trinity session with Claude + Gemini + Codex
reai-trinity - Reconnect to the trinity session
ai-quad - Start quad session with Claude + Gemini + Codex + Cursor Agent
reai-quad - Reconnect to the quad session

Tmux Session Controls

Within synchronized tmux sessions:

Ctrl+s or Option+s - Toggle input synchronization
Ctrl+a s - Toggle sync using prefix key
Ctrl+a k - Kill the current session
Mouse support - Click to switch between panes
Visual indicator - Red "SYNC ON" appears when panes are synchronized

🔧 Extension Management

Adding New Extensions

Add to extensions.yaml:

extensions:
  your-extension:
    repo: "https://github.com/user/claude-extension.git"
    description: "Description of your extension"
    installer: "install.sh"
    commands: 5
    categories: ["category1", "category2"]

Add as submodule:

git submodule add https://github.com/user/claude-extension.git extensions/your-extension

Update setup script: Add installation function and detection logic to setup-ai-tools.sh

Extension Structure

Each extension should provide:

Command files (.md format for Claude Code)
Installation script or manual setup instructions
Clear documentation of provided commands
Dependency information

🌟 Advanced Workflows

Large Codebase Analysis with Gemini

# Analyze entire project structure
/gemini --all_files -p "Analyze project architecture and dependencies"

# Feature verification across multiple directories  
/gemini -p "@src/ @tests/ Check test coverage for authentication features"

# Security audit across codebase
/gemini -p "@src/ @api/ @middleware/ Identify potential security vulnerabilities"

Advanced AI Agent Usage

# Deep research with GPT-5
Task agent-expert agent # Create specialized agents
Task gpt-5 agent # Leverage GPT-5 for complex analysis
Task cursor-agent agent # Use Cursor Agent with high reasoning

# Direct cursor-agent usage
cursor-agent -m gpt-5 -c model_reasoning_effort="high" -p "!t Analyze architectural patterns"

🎯 Conductor.build - Recommended Worktree Manager (macOS)

What is Conductor?

Conductor is a powerful macOS application that provides:

Visual Worktree Management: Create, switch, and manage git worktrees with a beautiful UI
Multiple Claude Sessions: Run multiple Claude Code agents simultaneously in different worktrees
Project Organization: Keep your development organized with visual project management
Quick Switching: Instantly switch between different feature branches and experiments

Installation

Download Conductor: Visit https://conductor.build/
Install the macOS app: Drag to Applications folder
Connect your repositories: Add your projects to Conductor

Why Use Conductor?

Conductor replaces the command-line worktree workflow with a superior visual experience:

✅ Visual Interface: See all your worktrees at a glance
✅ Multiple Agents: Run different Claude Code sessions per worktree
✅ Fast Switching: Click to switch between branches instantly
✅ Resource Efficient: Optimized for macOS with native performance
✅ Git Integration: Full git support with visual diff and history

Workflow with Conductor

Create a worktree in Conductor's UI for your feature
Open Claude Code directly from Conductor in that worktree
Work on your feature with isolated dependencies
Switch between worktrees instantly via Conductor
Clean up completed worktrees with one click

Session-Driven Development

# Start tracked development session
/project:session-start "implement-user-auth"

# Update progress throughout development
/project:session-update "Completed user model and authentication logic"

# End with comprehensive summary
/project:session-end

🧠 Planning with o3

Enhance your development workflow with advanced AI planning capabilities using the Zen MCP Server.

What is Zen MCP Server?

The Zen MCP Server provides access to multiple AI models through Claude Code, including o3 for sophisticated planning and analysis tasks.

Quick Setup

Clone the Zen MCP Server:

cd /Users/gwi/01-projects/04-ai/
git clone https://github.com/BeehiveInnovations/zen-mcp-server.git
cd zen-mcp-server
./run-server.sh

Configure API Keys (Required):

# Copy example configuration
cp .env.example .env

# Edit .env with your API keys (at least one required):
nano .env

Add your API keys to the .env file:

GEMINI_API_KEY=your_gemini_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
OPENROUTER_API_KEY=your_openrouter_api_key_here
DEFAULT_MODEL=auto

Connect to Claude Code:

# Generate configuration
./run-server.sh -c

# Add to Claude Code
claude mcp add zen -s user -- /Users/gwi/01-projects/04-ai/zen-mcp-server/.zen_venv/bin/python /Users/gwi/01-projects/04-ai/zen-mcp-server/server.py

Available Planning Tools

Once connected, you'll have access to advanced planning capabilities:

/zen:planner - Interactive step-by-step planning with deep thinking modes
/zen:consensus - Multi-model consensus for complex decisions
/zen:thinkdeep - Comprehensive investigation and reasoning
/zen:chat - Access to o3 and other advanced models for analysis

API Key Sources

Service	API Key Location
OpenAI (o3, GPT-4)	platform.openai.com/api-keys
Google AI (Gemini)	aistudio.google.com/app/apikey
OpenRouter (Multiple Models)	openrouter.ai/keys

Example Usage

# Start Claude Code and use planning tools
claude

# Interactive planning session
/zen:planner "Plan a microservices migration for our monolith application"

# Multi-model consensus
/zen:consensus "Should we use GraphQL or REST for our new API?"

# Deep analysis with o3
/zen:chat "Analyze the architectural implications of this database schema change"

📋 Installation Options

Full Installation (Recommended)

./setup-ai-tools.sh
# Select all extensions when prompted

Selective Installation

./setup-ai-tools.sh
# Choose specific extensions:
# - SuperClaude: Professional development commands
# - claude-sessions: Session management  
# - custom-commands: Workflow tools

Manual Installation

# Install CLI tools only
npm install -g @anthropic-ai/claude-code @google/gemini-cli

# Install specific extensions
cd extensions/SuperClaude && ./install.sh
cd extensions/claude-sessions && # manual setup

🚨 Troubleshooting

Command not found after installation

# Restart terminal or reload shell
source ~/.zshrc

# Check npm global path
npm config get prefix
echo $PATH | grep npm

API key issues

# Verify keys are set
echo $ANTHROPIC_API_KEY
echo $GOOGLE_AI_API_KEY

# Re-run setup to update keys
./setup-ai-tools.sh

Extension installation failures

# Check submodule status
git submodule status

# Update submodules
git submodule update --init --recursive

# Verify extension detection
ls -la ~/.claude/commands/

Tmux session issues

# Install tmux if missing
brew install tmux        # macOS
sudo apt install tmux   # Ubuntu/Debian

# Kill stuck sessions
tmux kill-session -t ai
tmux list-sessions

YAML configuration corruption

# The setup script automatically fixes enabled.yaml corruption
# If manual fix needed:
cat > config/enabled.yaml << 'EOF'
enabled:
  - SuperClaude
  - claude-sessions
  - custom-commands
EOF

🔄 Updates and Maintenance

Updating Extensions

# Update all submodules
git submodule update --remote

# Update specific extension
cd extensions/SuperClaude
git pull origin main
cd ../..

Adding Custom Commands

Place .md files in extensions/custom-commands/commands/
Re-run setup script to install
Commands become available as /your-command

🎯 Best Practices

Development Workflow

Start with large codebase analysis: Use /gemini to understand architecture
Create isolated worktrees: Use /worktree-start for feature development
Track progress: Use session management for complex features
Review systematically: Use /review for code quality checks
Deploy safely: Use /deploy with rollback capabilities

Multi-AI Collaboration

Use synchronized sessions: ai command for parallel AI consultation
Compare approaches: Ask same question to Claude and Gemini simultaneously
Leverage strengths: Gemini for analysis, Claude for implementation
Document decisions: Session management tracks reasoning and outcomes

Extension Management

Regular updates: Keep extensions current with git submodule update
Selective enabling: Only enable extensions you actively use
Custom extensions: Create project-specific command extensions
Share improvements: Contribute back to extension repositories

📖 Further Reading

🙏 Credits & Acknowledgments

This project integrates and builds upon several excellent open-source projects:

Core Extensions

SuperClaude by NomenAK
- Professional development framework with 18+ specialized commands
- Advanced Claude Code configuration and command system
- Evidence-based development methodology
Claude Sessions by Ian Nuttall
- Advanced session management for Claude Code
- Development progress tracking and context preservation
- Session-driven development workflows

Workflow Tools

Git Worktree Scripts by tomups
- Advanced git worktree management and automation
- Parallel development workflow support
- PR-only development process enforcement

Additional Resources

Mermaid Command by Peter Steinberger
- Diagram generation command for Claude Code
- Part of the agent-rules project for AI development

AI CLI Tools

Special Thanks

The Claude Code team at Anthropic for creating an extensible AI development platform
The open-source community for developing the tools and workflows this project builds upon
Contributors to tmux, git, and other foundational tools that make these workflows possible

License: MIT | Contributions: Welcome | Issues: GitHub Issues

Repository: claude-workspace-tools - A comprehensive Claude Code workspace with extensions and multi-AI integration

Name		Name	Last commit message	Last commit date
config		config
docs		docs
extensions		extensions
.gitignore		.gitignore
.gitmodules		.gitmodules
.tmux.conf		.tmux.conf
README.md		README.md
setup-ai-tools.sh		setup-ai-tools.sh

Latest commit

History

Folders and files

Repository files navigation

Claude Workspace Tools

🚀 Quick Start

🏗️ System Architecture

Extension Framework

Available Extensions

📦 What the Setup Script Does

Core AI Tools Installation

Extension Framework

Git Workflow Integration

🔑 Required API Keys

🔐 GitHub CLI Authentication & Rate Limits

Setting up GitHub CLI with PAT

Rate Limit Monitoring

🔧 Background Tasks

🛠️ Available Commands

CLI Aliases

Claude Code Extensions

SuperClaude Commands (18+)

Session Management Commands (6)

Custom Workflow Commands (2)

AI Agents (3)

Tmux Workflow Sessions

Tmux Session Controls

🔧 Extension Management

Adding New Extensions

Extension Structure

🌟 Advanced Workflows

Large Codebase Analysis with Gemini

Advanced AI Agent Usage

🎯 Conductor.build - Recommended Worktree Manager (macOS)

What is Conductor?

Installation

Why Use Conductor?

Workflow with Conductor

Session-Driven Development

🧠 Planning with o3

What is Zen MCP Server?

Quick Setup

Available Planning Tools

API Key Sources

Example Usage

📋 Installation Options

Full Installation (Recommended)

Selective Installation

Manual Installation

🚨 Troubleshooting

Command not found after installation

API key issues

Extension installation failures

Tmux session issues

YAML configuration corruption

🔄 Updates and Maintenance

Updating Extensions

Adding Custom Commands

🎯 Best Practices

Development Workflow

Multi-AI Collaboration

Extension Management

📖 Further Reading

🙏 Credits & Acknowledgments

Core Extensions

Workflow Tools

Additional Resources

AI CLI Tools

Special Thanks

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages