A plugin for central tracking of open nvim listen sockets
Add example configuration and usage examples to README
+116
-2
+2
-2
.beads/issues.jsonl
+2
-2
.beads/issues.jsonl
···
1
1
{"id":"nvim-registry-10s","title":"Create help documentation (doc/)","description":"Create comprehensive help documentation in doc/ directory. Generate doc/registry-nvim.txt with proper Vim help format. Document all commands, configuration options, and usage examples.","status":"closed","priority":3,"issue_type":"task","created_at":"2026-01-08T18:25:48.694899845-05:00","created_by":"rektide","updated_at":"2026-01-08T18:38:14.516605718-05:00","closed_at":"2026-01-08T18:38:14.516605718-05:00","close_reason":"Closed via update"}
2
2
{"id":"nvim-registry-3r0","title":"Implement init.lua - Plugin initialization","description":"Create init.lua as the main entry point. Implement setup() function for lazy.nvim configuration. Load and initialize all modules. Set up autocmds and commands.","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-08T18:25:49.453508485-05:00","created_by":"rektide","updated_at":"2026-01-08T18:36:47.806184235-05:00","closed_at":"2026-01-08T18:36:47.806184235-05:00","close_reason":"Closed via update"}
3
-
{"id":"nvim-registry-59v","title":"Create CLI script to send stdin to all registry sessions","description":"Create a CLI script that reads from stdin and sends the content to all Neovim sessions listed in the listen registry. The script should:\n\n- Read content from stdin\n- Connect to each listen socket in the registry\n- Send content to set a vim register in each session\n- Accept command line flags:\n - `--register` or `-r`: Specify which vim register to write to (default: clipboard register `\"*`)\n - `--env-guard` or `-e`: Environment variable check in format NAME=VALUE. Only run if environment variable exists and matches the specified value. Example: CLIPBOARD_STATE=data\n- Handle connection errors gracefully (skip invalid sockets)\n- Report which sessions were successfully updated\n\nThis enables external tools to sync clipboard content across all Neovim instances via the registry.\n\nTechnical details:\n- Use netcat or similar to connect to Unix sockets\n- Use nvim channel API to set registers remotely\n- Handle async communication with all sockets\n- Parse CLI flags with proper validation","status":"in_progress","priority":3,"issue_type":"feature","created_at":"2026-01-08T18:30:47.273970453-05:00","created_by":"rektide","updated_at":"2026-01-08T18:38:16.976972735-05:00","dependencies":[{"issue_id":"nvim-registry-59v","depends_on_id":"nvim-registry-iwa","type":"parent-child","created_at":"2026-01-08T18:30:50.239945982-05:00","created_by":"rektide"}]}
3
+
{"id":"nvim-registry-59v","title":"Create CLI script to send stdin to all registry sessions","description":"Create a CLI script that reads from stdin and sends the content to all Neovim sessions listed in the listen registry. The script should:\n\n- Read content from stdin\n- Connect to each listen socket in the registry\n- Send content to set a vim register in each session\n- Accept command line flags:\n - `--register` or `-r`: Specify which vim register to write to (default: clipboard register `\"*`)\n - `--env-guard` or `-e`: Environment variable check in format NAME=VALUE. Only run if environment variable exists and matches the specified value. Example: CLIPBOARD_STATE=data\n- Handle connection errors gracefully (skip invalid sockets)\n- Report which sessions were successfully updated\n\nThis enables external tools to sync clipboard content across all Neovim instances via the registry.\n\nTechnical details:\n- Use netcat or similar to connect to Unix sockets\n- Use nvim channel API to set registers remotely\n- Handle async communication with all sockets\n- Parse CLI flags with proper validation","status":"closed","priority":3,"issue_type":"feature","created_at":"2026-01-08T18:30:47.273970453-05:00","created_by":"rektide","updated_at":"2026-01-08T18:39:16.550292794-05:00","closed_at":"2026-01-08T18:39:16.550292794-05:00","close_reason":"Closed via update","dependencies":[{"issue_id":"nvim-registry-59v","depends_on_id":"nvim-registry-iwa","type":"parent-child","created_at":"2026-01-08T18:30:50.239945982-05:00","created_by":"rektide"}]}
4
4
{"id":"nvim-registry-5aj","title":"Implement registry.lua - Main registry module","description":"Create the main registry module that coordinates all functionality. Export public API for plugin usage. Manage the overall state and orchestrate between other modules.","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-08T18:25:45.045869094-05:00","created_by":"rektide","updated_at":"2026-01-08T18:35:35.73023499-05:00","closed_at":"2026-01-08T18:35:35.73023499-05:00","close_reason":"Closed via update"}
5
5
{"id":"nvim-registry-atn","title":"Implement cleanup.lua - Async socket validation","description":"Create cleanup.lua with async functionality using plenary.nvim. Check stats for all sockets in listen-registery using async operations. Perform batch update to remove invalid sockets after all stats are gathered. Expose :RegistryCleanup command.","status":"closed","priority":2,"issue_type":"feature","created_at":"2026-01-08T18:25:46.936796595-05:00","created_by":"rektide","updated_at":"2026-01-08T18:36:32.278258028-05:00","closed_at":"2026-01-08T18:36:32.278258028-05:00","close_reason":"Closed via update"}
6
6
{"id":"nvim-registry-cst","title":"Implement health.lua - Neovim healthcheck","description":"Create health.lua that provides healthcheck diagnostics. Check neoconf availability, plenary availability, and registry status. Report on any issues or misconfigurations.","status":"closed","priority":3,"issue_type":"task","created_at":"2026-01-08T18:25:47.889265985-05:00","created_by":"rektide","updated_at":"2026-01-08T18:37:31.359142755-05:00","closed_at":"2026-01-08T18:37:31.359142755-05:00","close_reason":"Closed via update"}
7
-
{"id":"nvim-registry-gxz","title":"Create example configuration and usage examples","description":"Add example configuration to README. Create usage examples in documentation. Show how to use the plugin manually and in automated workflows. Document the expected behavior.","status":"open","priority":4,"issue_type":"chore","created_at":"2026-01-08T18:25:56.569158454-05:00","created_by":"rektide","updated_at":"2026-01-08T18:25:56.569158454-05:00"}
7
+
{"id":"nvim-registry-gxz","title":"Create example configuration and usage examples","description":"Add example configuration to README. Create usage examples in documentation. Show how to use the plugin manually and in automated workflows. Document the expected behavior.","status":"in_progress","priority":4,"issue_type":"chore","created_at":"2026-01-08T18:25:56.569158454-05:00","created_by":"rektide","updated_at":"2026-01-08T18:39:22.140747623-05:00"}
8
8
{"id":"nvim-registry-iwa","title":"Extra Features for registry-nvim","description":"Epic for additional features beyond the core functionality. Includes CLI tools, integration utilities, and enhanced workflow capabilities.","status":"open","priority":4,"issue_type":"epic","created_at":"2026-01-08T18:30:35.840964917-05:00","created_by":"rektide","updated_at":"2026-01-08T18:30:35.840964917-05:00"}
9
9
{"id":"nvim-registry-x9n","title":"Implement config.lua - Configuration management","description":"Create config.lua module to handle neoconf integration. Manage the listen-registery property in global settings. Provide functions to get and update the registry list.","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-08T18:25:44.226867025-05:00","created_by":"rektide","updated_at":"2026-01-08T18:34:59.326163455-05:00","closed_at":"2026-01-08T18:34:59.326163455-05:00","close_reason":"Closed via update"}
10
10
{"id":"nvim-registry-yjo","title":"Add tests for core functionality","description":"Create tests for registry, config, monitor, and cleanup modules. Use plenary's test framework or vitest. Test async operations and neoconf integration.","status":"open","priority":4,"issue_type":"task","created_at":"2026-01-08T18:25:50.169339092-05:00","created_by":"rektide","updated_at":"2026-01-08T18:25:50.169339092-05:00"}
+114
README.md
+114
README.md
···
19
19
20
20
- `:RegistryCleanup` - Clean up stale listen sockets from the registry
21
21
22
+
### Programmatic Usage
23
+
24
+
```lua
25
+
local registry = require("registry-nvim")
26
+
27
+
-- Get all registered sockets
28
+
local sockets = registry.get_all()
29
+
30
+
-- Add a socket manually
31
+
registry.add("/tmp/nvim.sock")
32
+
33
+
-- Remove a socket manually
34
+
registry.remove("/tmp/nvim.sock")
35
+
36
+
-- Check if a socket is registered
37
+
if registry.contains("/tmp/nvim.sock") then
38
+
print("Socket is registered")
39
+
end
40
+
41
+
-- Get count of registered sockets
42
+
local count = registry.count()
43
+
44
+
-- Clear all sockets
45
+
registry.clear()
46
+
47
+
-- Manually trigger cleanup
48
+
registry.cleanup()
49
+
```
50
+
51
+
### Advanced Workflows
52
+
53
+
**Sync clipboard from terminal:**
54
+
55
+
```bash
56
+
# Copy to all Neovim instances
57
+
pbpaste | ./scripts/registry-send
58
+
59
+
# Or with xclip on Linux
60
+
xclip -o | ./scripts/registry-send
61
+
```
62
+
63
+
**Automated cleanup:**
64
+
65
+
```lua
66
+
-- Add periodic cleanup to your config
67
+
vim.api.nvim_create_autocmd("User", {
68
+
pattern = "RegistryCleanup",
69
+
callback = function()
70
+
require("registry-nvim").cleanup()
71
+
end,
72
+
})
73
+
74
+
-- Manually trigger via:
75
+
:RegistryCleanup
76
+
```
77
+
78
+
**Custom monitoring control:**
79
+
80
+
```lua
81
+
-- Stop monitoring temporarily
82
+
require("registry-nvim").stop_monitor()
83
+
84
+
-- Do some work...
85
+
86
+
-- Restart monitoring
87
+
require("registry-nvim").start_monitor()
88
+
```
89
+
22
90
## Configuration
23
91
24
92
The plugin uses `neoconf` for configuration. The listen registry is stored in global settings:
···
31
99
}
32
100
```
33
101
102
+
### Lazy.nvim Configuration Example
103
+
104
+
```lua
105
+
{
106
+
'yourusername/registry-nvim',
107
+
dependencies = {
108
+
'folke/neoconf.nvim',
109
+
'nvim-lua/plenary.nvim',
110
+
},
111
+
config = function()
112
+
local registry = require('registry-nvim')
113
+
114
+
-- Basic setup
115
+
registry.setup()
116
+
117
+
-- Or with manual control of monitoring
118
+
registry.setup()
119
+
-- Later in your config:
120
+
registry.start_monitor()
121
+
end,
122
+
}
123
+
```
124
+
34
125
## Requirements
35
126
36
127
- Neovim >= 0.9.0
···
66
157
- `init.lua` - Plugin initialization
67
158
68
159
## Development
160
+
161
+
### CLI Tool
162
+
163
+
The `scripts/registry-send` script allows you to send content to all registered Neovim instances:
164
+
165
+
```bash
166
+
# Send text to all sessions' clipboard
167
+
echo "Hello from terminal" | ./scripts/registry-send
168
+
169
+
# Send to a specific register
170
+
echo "Important text" | ./scripts/registry-send -r +
171
+
172
+
# Only send if an environment guard matches
173
+
export CLIPBOARD_STATE=enabled
174
+
echo "Sensitive data" | ./scripts/registry-send -e CLIPBOARD_STATE=enabled
175
+
176
+
# Use in shell scripts for clipboard synchronization
177
+
cat file.txt | ./scripts/registry-send
178
+
```
179
+
180
+
**CLI Dependencies:**
181
+
- `jq` - For parsing neoconf JSON
182
+
- `nvim` - For server communication
69
183
70
184
### Healthcheck
71
185