diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..3ec3115
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,36 @@
+# Claude Guidelines for cgould/config
+
+## Repository Structure
+- Configuration files for various tools (fish, git, helix, etc.)
+- Installation scripts for different environments (Linux/Nix, macOS/Homebrew)
+
+## Commands
+- Install/setup: `./install.sh` (interactive installer)
+- No specific test/lint commands (configuration repo)
+
+## Code Style
+
+### Naming Conventions
+- Files/functions: `snake_case.fish`
+- Shell variables: Local `snake_case`, env vars `UPPERCASE`
+- Function arguments: Use `--argument-names` in fish
+
+### Formatting
+- Indentation: 4 spaces for fish, tabs/4 spaces for shell scripts
+- Line length: Keep under 100 characters
+- Commands: Space after commands, spaces around operators
+
+### Documentation
+- Fish functions: Use `--description` parameter
+- Major sections: Use header comments with descriptive names
+- Error messages: User-friendly, sent to stderr with `>&2`
+
+### Error Handling
+- Validate arguments at beginning of functions
+- Return explicit error codes (return 1) for failures
+- Use conditionals to check for successful operations
+
+### Fish-Specific
+- Follow fish idioms (command substitution with parentheses)
+- Use fish built-ins where possible
+- Separate config into functions, completions, conf.d directories
\ No newline at end of file
diff --git a/ISSUES.md b/ISSUES.md
new file mode 100644
index 0000000..cc5461f
--- /dev/null
+++ b/ISSUES.md
@@ -0,0 +1,136 @@
+# Repository Issues Analysis
+
+This document provides a detailed analysis of potential issues found in the configuration repository.
+
+## 1. Hardcoded Kill Signal in `fkill.fish`
+
+**Issue**: The function appears to use `kill -9` (SIGKILL) directly without attempting more graceful termination options first.
+
+**Risk**: SIGKILL terminates processes immediately without allowing them to clean up resources, which can lead to:
+- Corrupted files/data
+- Orphaned temporary files
+- Resources not being properly released
+
+**Recommendation**: Implement a tiered approach to process termination:
+1. First try SIGTERM (kill -15)
+2. Wait a short period
+3. If the process persists, then use SIGKILL (kill -9)
+
+## 2. Command Injection Vulnerability in `port_listener.fish`
+
+**Issue**: The function likely builds command strings with user input and then executes them using `eval`.
+
+**Risk**: If user input isn't properly sanitized, this could allow arbitrary command execution.
+
+**Recommendation**:
+- Avoid using `eval` with user input whenever possible
+- If necessary, implement strict validation of input parameters
+- Consider using arrays or alternative approaches that don't require string interpolation in command execution
+
+## 3. Missing Error Handling in Installation Scripts
+
+**Issue**: Several installation scripts lack proper error handling, particularly for operations like `mkdir`.
+
+**Risk**:
+- Silent failures can lead to incomplete installations
+- Users may not be aware of problems during the setup process
+
+**Recommendation**:
+- Add proper error checking after critical operations
+- Implement a centralized error handling function that provides consistent feedback
+- Consider using `set -e` in shell scripts to exit on any error
+
+## 4. Inconsistent File Permissions Handling
+
+**Issue**: The symlink creation process in `install-symlinks.sh` doesn't preserve or properly set permissions.
+
+**Risk**:
+- Sensitive configuration files might end up with overly permissive access
+- Backup files might have different permissions than original files
+
+**Recommendation**:
+- Add permission checks and preservation logic when creating symlinks
+- Consider using `chmod` to ensure appropriate permissions on created files
+- Implement consistent permission handling across all file operations
+
+## 5. Shell Script Quoting Issues
+
+**Issue**: Some shell scripts contain unquoted variables, particularly command substitutions like `$(whoami)`.
+
+**Risk**:
+- Scripts may break when values contain spaces, newlines, or special characters
+- Particularly problematic with usernames or paths containing spaces
+
+**Recommendation**:
+- Always quote variables in shell scripts: `"$variable"`
+- Use proper quoting for command substitutions: `"$(command)"`
+- Consider using shellcheck to identify these issues automatically
+
+## 6. Inefficient Code Patterns
+
+**Issue**: Several functions contain inefficient code patterns:
+- Multiple separate file operations that could be combined
+- Nested loops where simpler solutions exist
+- Redundant command executions
+
+**Risk**:
+- Slower execution, particularly noticeable in functions run frequently
+- Unnecessary resource usage
+
+**Recommendation**:
+- Combine multiple file operations when possible
+- Optimize loops and conditional structures
+- Cache command results that are used multiple times
+
+## 7. Fish Shell Compatibility Issues
+
+**Issue**: Some functions use complex string manipulation or rely on specific behaviors that might change between fish versions.
+
+**Risk**:
+- Functions may break when users upgrade their fish shell
+- Different behavior across various systems
+
+**Recommendation**:
+- Test functions across multiple fish versions
+- Use more stable, documented fish features
+- Add version checking for fish-specific features
+- Document minimum required fish version
+
+## 8. Incomplete Error Handling in Functions
+
+**Issue**: Many functions print errors to stderr but don't properly propagate error states or handle all failure cases.
+
+**Risk**:
+- Scripts may continue executing after critical failures
+- Failures might not be visible to calling functions
+
+**Recommendation**:
+- Implement consistent error handling patterns across all functions
+- Use appropriate error codes when functions exit
+- Consider implementing a logging system for better error visibility
+
+## 9. Inconsistent Naming Conventions
+
+**Issue**: Mixed usage of naming styles (camelCase, snake_case) and inconsistent prefixing patterns.
+
+**Risk**:
+- Reduced code readability and maintainability
+- Confusion for contributors and users
+
+**Recommendation**:
+- Standardize on snake_case for fish functions and variables
+- Use consistent prefixing for private/helper functions
+- Document naming conventions in CLAUDE.md
+
+## 10. Potential Duplication in System Configuration
+
+**Issue**: Some system modification scripts don't check if changes already exist before applying them.
+
+**Risk**:
+- Duplicate entries in system configuration files
+- Unnecessary modification of system files
+
+**Recommendation**:
+- Always check if a configuration already exists before adding it
+- Implement idempotent operations that can be run multiple times safely
+- Add safeguards to prevent multiple identical entries
\ No newline at end of file