icho | A bespoke neovim workspace. Powered by nixvim.
- 🌿 AI-Powered Assistance: Code completion, chat, and context-aware prompts.
- 🦥 Enhanced Editing: Code refactoring tools, etc.
- 🏃 Navigation: LSP navigation and bookmark management.
- 🎨 Customizable UI: Zen mode, refined UI elements, and improved notifications
- 🔧 Quality of Life: Auto session management, file saving with elevated privileges, and streamlined Git workflows.
- 🛠️ Language Support: Support for a wide range of programming languages and tools, ensuring a tailored experience for developers.
- 🧩 Modular Configuration: Files for each plugin.
- 💻 Automatic Updates: The project flake updates the plugins nightly.
- 🔑 Intuitive Keybindings: Comprehensive set of keybindings for efficient workflow. See the Keybinding Cheatsheet for details.
Welcome to my Neovim configuration crafted for Nix. Feel free to use it as is or extract pieces to help construct your own unique setup.
Important
This repo is provided as-is and is primarily developed for my own workflows. As such, I offer no guarantees of regular updates or support. Bug fixes and feature enhancements will be implemented at my discretion, and only if they align with my personal use-cases. Feel free to fork the project and customize it to your needs, but please understand my involvement in further development will be intermittent.
Before using icho, ensure your system meets the following requirements:
- Operating Systems:
- Linux: x86_64 and aarch64 architectures
- macOS: x86_64 (Intel) and aarch64 (Apple Silicon)
- Windows: Supported via WSL2 (Windows Subsystem for Linux)
- Recommended: NixOS or any modern Linux distribution
- WSL Installation Guide
- Nix: Using the Nix package manager with flakes enabled
- Nix version: 2.4 or higher (with flakes feature)
- Install Nix
- Enable flakes
- Nix installation on WSL
- Ensure your
nix.confhas experimental features enabled:experimental-features = nix-command flakes
- Git (for cloning the repository)
- Internet connection (for initial setup and updates)
{
inputs.icho.url = "github:simonwjackson/icho";
}
To utilize this configuration, clone the repo and run the following command from the directory:
nix run
or remote:
nix run github:simonwjackson/icho
Here are solutions to common issues you might encounter when using icho:
Q: I get "error: flake 'github:simonwjackson/icho' does not exist" A: This usually indicates connectivity issues or GitHub being unreachable. Check your internet connection and try again. If GitHub is down, wait until service is restored.
Q: I get "error: experimental feature 'flakes' is disabled"
A: You need to enable the flakes feature in Nix. Add the following to your ~/.config/nix/nix.conf file:
experimental-features = nix-command flakes
Then restart the nix-daemon or your terminal session.
Q: The installation fails with "Unable to find package" errors A: This could be due to a corrupt Nix cache. Try:
nix-store --verify --check-contents --repair
Then retry the installation.
Q: I get "warning: unknown warning: EXPERIMENTAL" A: This is a normal warning and can be safely ignored. It's just reminding you that you're using experimental features in Nix.
Q: I see "cannot substitute, path is not valid" errors A: This is usually a permission issue. Make sure you have the appropriate permissions for the Nix store. You may need to run:
sudo chown -R $(whoami):nixbld /nix
Q: Updates fail with "error: path ... is not valid" A: This can happen if your flake.lock file is corrupted. Try:
rm flake.lock
nix flake update
Q: AI plugins are not working/responding A: AI features require external API keys to be set up. Check that you have configured the necessary environment variables. See the AI plugin documentation for specific requirements.
Q: LSP server for my language doesn't work A: Some language servers require additional dependencies. Make sure the corresponding language toolchain is installed on your system outside of icho.
Q: Plugins keep disappearing after system updates A: This can happen if Nix garbage collection removes dependencies. Try adding your icho flake to the nix registry to prevent garbage collection:
nix registry add icho github:simonwjackson/icho
Q: Neovim is slow to start up A: This could be due to multiple factors:
- Too many plugins loading at startup - consider using lazy loading
- Large language servers initializing - configure them to start on demand
- Cold cache - subsequent starts should be faster
Q: High CPU usage during editing A: This is often caused by aggressive LSP or treesitter parsing. Try:
- Disable real-time diagnostics for large files
- Add file size limits to LSP configurations
- Reduce the frequency of certain operations like linting
Q: Memory usage grows over time A: Some plugins might have memory leaks. Identify the problematic plugin by starting with minimal config and adding plugins one by one to isolate the issue.
Q: Some keybindings don't work on my system A: Certain key combinations might be intercepted by your OS or terminal emulator. Check for conflicts in your terminal settings or OS keyboard shortcuts.
Q: AI-powered features give inconsistent results A: AI features depend on external services and can vary in quality based on model versions and internet connectivity. This is a limitation of current AI technology.
Q: Why doesn't icho include plugin X? A: icho is maintained as a personal configuration. If a plugin isn't included, it's likely because it doesn't align with the maintainer's workflow. You can always fork the repository and add the plugins you need.
Q: File-specific settings don't persist between sessions A: This is by design - icho prioritizes reproducible configurations via Nix, rather than session-specific settings. Use project-specific configuration files for persistent settings.
This configuration includes a variety of plugins:
- supermaven-nvim: AI code completion with customizable keymaps and conditions.
- avante: AI-powered plugin (specific functionality not detailed in the config).
- better-escape: Improved escape key mappings with customizable timeout and mappings.
- kulala: HTTP client with debug options, environment scoping, and custom icons.
- rest: REST client for Neovim.
- otter< 8000 /strong>: UI plugin (specific functionality not detailed in the config).
- dressing: Enhanced UI for input and select dialogs.
- zen-mode: Distraction-free writing mode with customizable window settings.
- noice: Improved UI for notifications, messages, and popup menus.
- vim-suda: Allows saving files with sudo privileges.
- vim-matchup: Enhanced match-up functionality with Treesitter support.
- repeat: Repeat plugin commands with
..
- todo-comments: Highlight and manage TODO comments.
- typescript-tools: TypeScript language support.
- tailwind-tools: Tailwind CSS utilities.
- scope: Scope management for syntax highlighting.
- smear-cursor: Smooth cursor animations.
- refactoring: Code refactoring tools with Telescope integration.
- qmk: QMK firmware configuration support.
- lspsaga: Enhanced LSP UI.
- nvim-surround: Surround text with brackets, quotes, etc.
- marks: Manage and navigate marks.
- navbuddy: Navigation sidebar with LSP integration.
- lazydev: Lazy development tools with custom runtime settings.
- helpview: Enhanced help viewer.
- direnv: Environment variable management.
- git-worktree: Git worktree management.
- glance: Quick navigation and preview.
- improved-search: Enhanced search functionality.
- auto-session: Automatic session management.
- comment: Comment toggling and management.
- firenvim: Embed Neovim in the browser.
- grug-far: Search and replace functionality.
nix flake updateThe repository is organized into a modular structure for managing Neovim configurations using Nix. Key components include:
- config/: Contains modular configuration files for Neovim plugins, LSP, UI, and utilities. Each file is dedicated to a specific plugin or feature, making it easy to customize or extend.
- flake.nix: The main Nix flake configuration, defining the Neovim environment and its dependencies.
- flake.lock: Ensures reproducible builds by locking dependency versions.
- README.md: Documentation for the repository, including setup instructions and plugin details.
- keybinding-cheatsheet.md: Comprehensive reference for all keybindings organized by category.
This structure is designed for flexibility, allowing users to pick and choose components for their own Neovim setups.
The repo includes support for the following programming languages and tools:
- Frontend: HTML, CSS, JavaScript, TypeScript, React (TSX), Vue, Svelte
- Backend: Python, Ruby, PHP, Java
- Data: SQL, GraphQL
- Styling: SCSS, CSS
- Languages: C, C++, Rust, Zig
- Build Tools: Make, Just
- Shell: Bash, Fish
- Containers: Dockerfile
- Package Management: Nix
- Data Formats: JSON, YAML, TOML, XML, Protocol Buffers
- Markup: Markdown, LaTeX, Typst
- API Docs: Vimdoc
- Regular Expressions: Regex support for pattern matching
- Pure FP: Haskell, Elm
- Actor Model: Erlang, Elixir
This project is co-authored by Claude, who has provided assistance with documentation, configuration improvements, and troubleshooting solutions.
The files and scripts in this repository are licensed under the MIT License, which is a very permissive license allowing you to use, modify, copy, distribute, sell, give away, etc. the software. In other words, do what you want with it. The only requirement with the MIT License is that the license and copyright notice must be provided with the software.