{"id":24108248,"url":"https://github.com/theherk/neovideproject","last_synced_at":"2026-05-04T18:34:49.257Z","repository":{"id":271627421,"uuid":"914057872","full_name":"theherk/NeovideProject","owner":"theherk","description":"A macOS application that manages Neovide instances per Git repository, providing a seamless project-based editing experience.","archived":false,"fork":false,"pushed_at":"2025-01-16T16:17:13.000Z","size":6078,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-16T17:43:55.924Z","etag":null,"topics":["git","neovide","neovim","nvim","project-management"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theherk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-08T21:38:16.000Z","updated_at":"2025-01-16T16:16:51.000Z","dependencies_parsed_at":"2025-01-16T17:43:45.392Z","dependency_job_id":null,"html_url":"https://github.com/theherk/NeovideProject","commit_stats":{"total_commits":17,"total_committers":1,"mean_commits":17.0,"dds":0.0,"last_synced_commit":"8136524e800324d515f7a4d640484fdb6ee4301f"},"previous_names":["theherk/neovideproject"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theherk%2FNeovideProject","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theherk%2FNeovideProject/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theherk%2FNeovideProject/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theherk%2FNeovideProject/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theherk","download_url":"https://codeload.github.com/theherk/NeovideProject/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241090615,"owners_count":19907984,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["git","neovide","neovim","nvim","project-management"],"created_at":"2025-01-10T23:26:43.675Z","updated_at":"2026-05-04T18:34:49.248Z","avatar_url":"https://github.com/theherk.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NeovideProject\n\nA macOS application that manages Neovide instances per Git repository, providing a seamless project-based editing experience.\n\n![Screencast of NeovideProject](./assets/NeovideProject.gif)\n\nAs you can see in the screencast included, this can be used in association with any of several [Raycast](https://www.raycast.com/) extensions, or any other workflow management tool that can call `open`. My favorite is in combination with [Zoxide Git Projects](https://www.raycast.com/theherk/zoxide-git-projects), with which you can easily fuzzy find from all previously opened git projects.\n\n🎥 View a longer [Introductory video in the wiki](https://github.com/theherk/NeovideProject/wiki/Usage).\n\n## Features\n\n- Single instance per Git repository\n- Seamless switching between instances\n- File/directory dropping support\n\n## Requirements\n\n- macOS 10.15 or later\n- Neovide\n- Neovim\n- Git\n\n## Installation\n\n1. Download the latest release from the Releases page.\n2. Move NeovideProject.app to your Applications folder.\n3. (Optional) Set as default application for opening directories.\n\n## Building from Source\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/theherk/NeovideProject\n   ```\n\n2. Run the build script:\n   ```bash\n   ./build.sh\n   ```\n\n3. The built application will be in `build/NeovideProject.app`\n\n## Usage\n\n- Drag and drop folders or files onto the application.\n- Use \"Open With\" in Finder.\n- Double-click Git repositories to open them in Neovide.\n\n## Detailed Behavior\n\n### Instance: Neovide or Neovim?\n\n- **In the script, \"instance\" refers to a Neovim process launched by Neovide,** with each instance associated with a unique socket (named by git repo root, home, or directory).\n- **Neovide** is the GUI frontend, but the script manages Neovim instances via sockets. Neovide connects to these Neovim instances.\n- **Multiple Neovim instances:** One can have multiple Neovim instances (each with its own socket) running under Neovide, but the script enforces one instance per git repo (or directory/home).\n- **RAM usage:** Heavy RAM usage typically comes from LSPs loaded by Neovim, not Neovide itself.\n\nThis can be a bit cumbersome with switching windows, since switching to the \"Application\" Neovide, does not switch consistently to the last selected instance and the window switcher list gets many instances. The former I actually just don't understand, and I think it is a MacOS peculiarity, but I'd love to find a way around it. The latter I simply do not worry about, because I always switch to precisely the project I seek directly.\n\n### \"Single instance per Git repository\", What does it mean?\n\n- **If you open a directory that is a git repo:**\n  The script finds the git root and creates a socket named for that repo. If no Neovim instance exists for that socket, it launches Neovide (which launches Neovim) with that repo as the working directory.\n- **If you open a file within that repo:**\n  The script will connect to the existing Neovim instance for that repo (via the socket) and open the file as a buffer/tab.\n- **If you open a subdirectory of the repo:**\n  - If the subdirectory is inside the git repo, the script will still resolve the git root and use the same socket.\n  - If the Neovim instance is already running, it will focus the existing Neovide window and (if you opened a directory) send a `:cd` command to change the working directory, or (if you opened a file) open the file.\n\n### What does NeovideProject actually do with directories, git repos, and Neovide?\n\n- **Project boundary detection:**\n  Uses git root as the boundary for a \"project.\" If no git repo, falls back to directory or home.\n- **Instance management:**\n  Ensures only one Neovim instance per project boundary (git repo, directory, or home).\n- **Socket management:**\n  Names sockets by project boundary, so opening anything within the same boundary connects to the same instance.\n- **No Session restoration:**\n  The script itself does **not** manage sessions or workspaces. It only launches/focuses Neovide/Neovim instances.\n  **If you use a sessions plugin in Neovim, it will still work as expected**—the script does not interfere with session restoration.\n\n### Relevance of zoxide, raycast, fzf, etc.\n\n- These are just examples of good UX for quickly opening projects/files.\n- **They are not dependencies** of NeovideProject.\n- You can use them alongside NeovideProject for navigation, but NeovideProject itself is agnostic to these tools.\n\n### Summary\n\n| Action                    | What NeovideProject Does                     | What It Does NOT Do                     |\n| ------------------------- | -------------------------------------------- | --------------------------------------- |\n| Open git repo dir         | Launch/focus Neovide/Neovim for that repo    | Restore sessions/workspaces             |\n| Open file in git repo     | Open file in existing instance for that repo | Manage buffers/tabs beyond opening file |\n| Open subdir in git repo   | Focus instance, send `:cd` to subdir         | Open netrw or do nothing                |\n| Open dir outside git repo | Launch/focus instance for that dir           | Session management                      |\n| Use session plugin        | Unaffected—plugin manages session restore    |                                         |\n| Use zoxide/raycast/fzf    | Unaffected—can use for navigation            |                                         |\n\n### Instance Management Flow\n\n```mermaid\nflowchart TD\n    A[User opens file or directory] --\u003e B{Is it inside a Git repo?}\n    B -- Yes --\u003e C[Find Git root]\n    B -- No --\u003e D{Is it $HOME?}\n    C --\u003e E[Set socket name: neovide-git-root-md5]\n    D -- Yes --\u003e F[Set socket name: neovide-home]\n    D -- No --\u003e G[Set socket name: neovide-dir-md5]\n    E --\u003e H{Does socket exist?}\n    F --\u003e H\n    G --\u003e H\n    H -- Yes --\u003e I{Is target a file?}\n    H -- No --\u003e J[Launch Neovide with working dir]\n    I -- Yes --\u003e K[Open file in existing instance]\n    I -- No --\u003e L[Send :cd to directory in existing instance]\n```\n\n## License\n\nMIT License - See LICENSE file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheherk%2Fneovideproject","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheherk%2Fneovideproject","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheherk%2Fneovideproject/lists"}