0
# Daemon Mode
1

2
Rome's daemon mode provides a persistent server process that significantly improves performance for repeated operations by avoiding startup costs and maintaining parsed state between commands.
3

4
## Capabilities
5

6
### Daemon Management
7

8
Control Rome's background server process for improved performance.
9

10
```bash { .api }
11
/**
12
 * Start the Rome daemon server process
13
 * 
14
 * Usage: rome start
15
 * 
16
 * Starts a background server process that other Rome commands can connect to
17
 */
18
rome start
19

20
/**
21
 * Stop the Rome daemon server process
22
 * 
23
 * Usage: rome stop
24
 * 
25
 * Stops the running background server process
26
 */
27
rome stop
28

29
/**
30
 * Language Server Protocol over stdin/stdout
31
 * 
32
 * Usage: rome lsp-proxy
33
 * 
34
 * Acts as a server for the Language Server Protocol, typically used by editors
35
 */
36
rome lsp-proxy
37
```
38

39
### Using Daemon Mode
40

41
Connect to the running daemon for faster command execution.
42

43
```bash { .api }
44
/**
45
 * Connect to running daemon instance
46
 * 
47
 * Add --use-server to any Rome command to use the daemon
48
 */
49
rome check src/ --use-server
50
rome format src/ --use-server  
51
rome ci src/ --use-server
52
```
53

54
## Performance Benefits
55

56
### Startup Time Reduction
57

58
The daemon eliminates the overhead of starting the Rust process for each command:
59

60
```bash
61
# Without daemon (cold start each time)
62
rome check src/        # ~200ms startup
63
rome format src/       # ~200ms startup  
64
rome ci src/           # ~200ms startup
65

66
# With daemon (amortized startup cost)
67
rome start            # ~200ms startup once
68
rome check src/ --use-server    # ~20ms
69
rome format src/ --use-server   # ~20ms
70
rome ci src/ --use-server       # ~20ms
71
```
72

73
### State Persistence
74

75
The daemon maintains parsed state between operations:
76

77
- **File system cache**: Avoids re-reading unchanged files
78
- **Parse cache**: Reuses parsed ASTs for unchanged files
79
- **Configuration cache**: Avoids re-parsing rome.json
80
- **Rule cache**: Maintains compiled rule state
81

82
## Usage Examples
83

84
### Basic Daemon Usage
85

86
```bash
87
# Start daemon
88
rome start
89

90
# Use daemon for commands (faster execution)
91
rome check src/ --use-server
92
rome format src/ --write --use-server
93
rome ci src/ --use-server
94

95
# Stop daemon when done
96
rome stop
97
```
98

99
### Development Workflow
100

101
```bash
102
# Start daemon at beginning of work session
103
rome start
104

105
# Fast feedback during development
106
rome check src/components/Button.tsx --use-server
107
rome format src/components/Button.tsx --write --use-server
108

109
# Stop daemon at end of session
110
rome stop
111
```
112

113
### CI/CD Integration
114

115
```bash
116
# Start daemon for build pipeline
117
rome start
118

119
# Run multiple checks efficiently
120
rome check src/ --use-server
121
rome format src/ --use-server  
122
rome ci tests/ --use-server
123

124
# Daemon automatically stops when process ends
125
```
126

127
## Daemon Status
128

129
### Check Daemon Status
130

131
```bash { .api }
132
# Commands will indicate if daemon is not running
133
rome check src/ --use-server
134
# Error: ServerNotRunning - start daemon with 'rome start'
135

136
# Check if daemon is running (implicit)
137
rome start  # Will report if already running
138
```
139

140
### Socket Information
141

142
```bash { .api }
143
/**
144
 * Print socket information (internal command)
145
 * 
146
 * Usage: rome __print_socket
147
 * 
148
 * Internal command that prints daemon socket information for debugging
149
 */
150
rome __print_socket
151
```
152

153
## Editor Integration
154

155
### Language Server Protocol
156

157
Rome provides LSP support through the daemon:
158

159
```bash { .api }
160
rome lsp-proxy
161
```
162

163
This enables:
164
- **Real-time diagnostics**: Live linting and error reporting
165
- **Format on save**: Automatic formatting in editors
166
- **Code actions**: Quick fixes and refactoring suggestions
167
- **Hover information**: Type and documentation information
168

169
### Editor Configuration
170

171
#### VS Code
172

173
```json
174
{
175
  "rome.lspBin": "rome",
176
  "rome.requireConfiguration": true,
177
  "editor.formatOnSave": true,
178
  "editor.codeActionsOnSave": {
179
    "quickfix.rome": true
180
  }
181
}
182
```
183

184
#### Neovim
185

186
```lua
187
require('lspconfig').rome.setup({
188
  cmd = { 'rome', 'lsp-proxy' },
189
  filetypes = { 'javascript', 'typescript', 'json' }
190
})
191
```
192

193
## Advanced Usage
194

195
### Internal Server Command
196

197
```bash { .api }
198
/**
199
 * Run server process (internal command)
200
 * 
201
 * Usage: rome __run_server
202
 * 
203
 * Internal command used by 'rome start' to run the actual server process
204
 */
205
rome __run_server
206
```
207

208
### Daemon Process Management
209

210
The daemon process:
211

212
- **Auto-discovery**: Commands automatically find running daemon
213
- **Socket communication**: Uses Unix sockets (Linux/macOS) or named pipes (Windows)
214
- **Process isolation**: Daemon runs as separate process
215
- **Resource management**: Automatically cleans up resources
216

217
### Error Handling
218

219
```bash { .api }
220
# Daemon not running
221
rome check src/ --use-server
222
# Error: ServerNotRunning
223

224
# Daemon connection failed
225
rome check src/ --use-server
226
# Falls back to direct execution
227

228
# Multiple daemon instances
229
rome start
230
# Reports if daemon already running
231
```
232

233
## Performance Considerations
234

235
### When to Use Daemon Mode
236

237
**Recommended for:**
238
- **Development workflows**: Frequent format/check cycles
239
- **CI/CD pipelines**: Multiple Rome commands in sequence
240
- **Editor integration**: Real-time feedback
241
- **Large codebases**: Significant startup overhead
242

243
**Not necessary for:**
244
- **Single-shot commands**: One-time formatting or checking
245
- **Small projects**: Minimal startup overhead
246
- **Memory-constrained environments**: Daemon uses additional memory
247

248
### Memory Usage
249

250
The daemon maintains caches that use memory:
251

252
```bash
253
# Monitor daemon memory usage
254
ps aux | grep rome
255

256
# Restart daemon to clear caches if needed
257
rome stop
258
rome start
259
```
260

261
### File System Watching
262

263
The daemon can watch for file changes:
264

265
- **Automatic invalidation**: Clears cache for changed files
266
- **Smart rebuilding**: Only re-processes affected files
267
- **Configuration changes**: Automatically reloads rome.json
268

269
## Troubleshooting
270

271
### Common Issues
272

273
```bash
274
# Daemon won't start
275
rome start
276
# Check if port/socket is already in use
277

278
# Commands hang with --use-server
279
# Daemon may be unresponsive, restart it:
280
rome stop
281
rome start
282

283
# Stale cache issues
284
# Restart daemon to clear all caches:
285
rome stop
286
rome start
287
```
288

289
### Debugging
290

291
```bash
292
# Enable verbose output
293
rome start --verbose
294

295
# Check socket information
296
rome __print_socket
297

298
# Test daemon connectivity
299
rome check --version --use-server
300
```
301

302
### Platform-Specific Considerations
303

304
#### Linux/macOS
305
- Uses Unix domain sockets
306
- Socket files created in temp directory
307
- Automatic cleanup on daemon exit
308

309
#### Windows
310
- Uses named pipes
311
- Pipe names follow Windows conventions
312
- Similar cleanup behavior
313

314
## Integration Patterns
315

316
### Build Scripts
317

318
```json
319
{
320
  "scripts": {
321
    "start-rome": "rome start",
322
    "stop-rome": "rome stop", 
323
    "dev": "rome start && npm run dev:watch && rome stop",
324
    "lint": "rome check src/ --use-server",
325
    "format": "rome format src/ --write --use-server"
326
  }
327
}
328
```
329

330
### Git Hooks
331

332
```bash
333
#!/bin/sh
334
# pre-commit hook
335
rome start 2>/dev/null || true
336
rome check --staged --use-server || exit 1
337
rome format --staged --write --use-server || exit 1
338
```
339

340
### Docker Integration
341

342
```dockerfile
343
# Start daemon in container
344
RUN rome start
345

346
# Use daemon for build steps
347
RUN rome check src/ --use-server
348
RUN rome format src/ --use-server
349

350
# Daemon automatically stops when container exits
351
```