fuse-agents AGENTS.md

Project Overview

This is a cross-shell plugin (Bash & Zsh) that automatically fuses AI assistant configuration files (CLAUDE.md, GEMINI.md) into a unified AGENTS.md file with intelligent symlink management. The plugin provides automatic detection, smart merging, and different handling for different AI assistants.

Key Architecture

Shell Compatibility Layer

The plugin detects the current shell (Bash/Zsh/unknown) and adapts behavior:

• SHELL_TYPE variable determines shell-specific features
• array_join() function handles cross-shell array operations
• Different hook mechanisms: Zsh uses chpwd, Bash uses PROMPT_COMMAND

Core Processing Pipeline

1. Detection: _fuse_auto_detect() triggers on directory changes
2. Processing: _fuse-agents() handles individual directories
3. File Handling: _handle_ai_file() manages individual AI assistant files
4. Conflict Resolution: Interactive prompts using gum (if available) or fallback text prompts

Critical Design Decisions

• CLAUDE.md: Always symlinked to AGENTS.md (Claude requires symlink)
• GEMINI.md: Always symlinked to AGENTS.md (same as CLAUDE.md)
• Auto-detection: Triggers for both CLAUDE.md and GEMINI.md files
• Merge Strategy: Creates timestamped backups and structured merges
• Conditional Symlinks: Symlinks are only created for files that existed originally

Common Development Tasks

Testing Plugin Functionality

# Test basic fusing
mkdir -p /tmp/test-fuse
cd /tmp/test-fuse
echo "# Claude instructions" > CLAUDE.md
echo "# Gemini instructions" > GEMINI.md
source /path/to/fuse-agents.plugin.sh
fuse-agents-auto

# Test recursive processing
mkdir -p ~/test-projects/{proj1,proj2}
echo "# Claude proj1" > ~/test-projects/proj1/CLAUDE.md
echo "# Gemini proj2" > ~/test-projects/proj2/GEMINI.md
fuse-agents-recursive ~/test-projects

Installation Testing

# Test installer script
./install.sh

# Verify installation
type fuse-agents
fuse-agents --help

# Test auto-hooks by changing directories
cd ~/project-with-CLAUDE.md