diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..20ad9c0
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,72 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+This is a nixvim configuration repository that provides a standalone Neovim configuration using Nix flakes. The configuration is built using the nixvim framework, which allows declarative Neovim configuration through Nix expressions.
+
+## Development Commands
+
+### Testing Configuration
+```bash
+# Test the current configuration by running nixvim
+nix run .
+
+# Verify configuration is not broken
+nix flake check .
+```
+
+### Installation
+```bash
+# Install the configuration to user profile (first time)
+./install.sh
+# or manually:
+nix profile install .
+
+# Update existing installation
+./update.sh
+```
+
+### Git Workflow Scripts
+```bash
+# Switch to dev branch and pull latest changes
+./pull.sh
+
+# Commit changes with timestamp, merge to main, and push
+./push.sh
+```
+
+## Architecture
+
+### Core Structure
+- **flake.nix**: Main flake definition with nixpkgs, nixvim, and flake-parts inputs
+- **config/**: Contains all nixvim configuration modules
+  - **default.nix**: Main configuration file with plugins, options, and keymaps
+  - **bufferline.nix**: Example modular configuration for bufferline plugin
+- **flake.lock**: Dependency lockfile
+
+### Configuration System
+The configuration uses nixvim's module system:
+- Configurations are split into logical modules in the `config/` directory
+- Each module can be imported in `config/default.nix`
+- The main configuration includes essential plugins like Telescope, LSP support, Treesitter, and various productivity tools
+
+### Key Features Enabled
+- Nord colorscheme with line numbers and relative numbering
+- Comprehensive plugin suite including Telescope, nvim-tree, fugitive, lazygit
+- Auto-completion with cmp and all sources enabled
+- Custom keymap for hop (two-character jump) on 's' key
+- Tab width set to 2 spaces
+
+### Branch Strategy
+- **main**: Stable configuration
+- **dev**: Development branch for testing changes
+- Scripts automate switching and merging between branches
+
+## Adding New Configurations
+
+1. Create new `.nix` files in the `config/` directory for specific feature sets
+2. Import them in `config/default.nix` using the imports array
+3. Test with `nix run .` before committing
+4. Use the git workflow scripts to maintain the branch structure
\ No newline at end of file
diff --git a/update.sh b/update.sh
new file mode 100755
index 0000000..ecbd05e
--- /dev/null
+++ b/update.sh
@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+nix profile upgrade vim
\ No newline at end of file