symforge 7.11.1

SymForge — in-memory code intelligence MCP server for Claude Code, Codex, and Gemini CLI
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
# Provider CLI Runtime Architecture

Status: probable architecture  
Date: 2026-03-07

## Purpose

This document takes the verified integration research and turns it into a buildable architecture and source scaffold for SymForge.

This is not the final architecture.

It is the current **probable architecture**: the design that best fits the verified provider surfaces, the product direction, and the operational constraints we already know about.

## Product Position

SymForge should become:

- a local code-intelligence runtime
- a project and workspace registry
- a byte-exact retrieval system
- a local-first runtime with durable local state
- an MCP server
- a provider-adapter platform

In short:

**SymForge is not just a server process. It is the local code-intelligence substrate that provider CLIs consume.**

## Probable Architecture

### Layer 1: Core runtime

Core local daemon:

- `SymForged`

Responsibilities:

- project and workspace tracking
- local state lifecycle management
- snapshot and cache lifecycle management
- indexing orchestration
- file watching and change detection
- repo outline, symbol, and text query services
- prompt/resource generation support
- provider policy evaluation
- local telemetry and health

This daemon should be long-lived and warm.

It should not be recreated from scratch on every MCP stdio session if we want low-latency, consistent usage.

### Layer 2: Public transport surfaces

Primary transports:

- stdio MCP
- local RPC between adapters and daemon

Likely local RPC options:

- named pipe on Windows
- Unix domain socket on macOS/Linux
- optional localhost HTTP control API later if needed

Initial recommendation:

- implement local daemon control over named pipe / Unix socket
- keep the public AI-facing surface as MCP
- do not make provider adapters talk directly to storage internals

### Layer 3: Provider adapters

Provider-specific packages/config generators:

- Codex adapter
- Claude adapter
- Gemini adapter
- Copilot adapter
- Amazon Q adapter

Responsibilities:

- install MCP registration
- install provider-specific instruction/context files
- install hooks when supported
- install custom agents/subagents when supported
- install prompts/commands when supported
- point all integrations back to the same local SymForge runtime

### Layer 4: Repo-local integration assets

Generated or managed per project:

- `AGENTS.md`
- `CLAUDE.md`
- `GEMINI.md`
- `.claude/settings.json`
- `.claude/agents/*`
- `.gemini/settings.json`
- `.gemini/agents/*`
- `.github/copilot-instructions.md`
- `.github/agents/*`
- `.github/hooks/*`
- `.symforge/project.toml`

Important:

- only a small subset should be mandatory
- repo-local files should be additive and easy to remove
- large durable state must remain outside the repo

## Why a daemon is the probable answer

### Problem with pure stdio MCP

If SymForge lives only as a stdio MCP process:

- indexing state is cold too often
- project discovery repeats on every session
- background indexing is awkward
- provider-native hooks and commands have no stable local service to talk to
- "always on" behavior is weaker

### Problem with per-provider custom logic in the MCP process

If we stuff provider logic directly into the MCP binary:

- responsibilities blur
- provider-specific behavior leaks into core retrieval logic
- testability gets worse
- distribution becomes harder

### Why daemon plus adapters wins

- one warm runtime
- one authoritative project registry
- one place for index, snapshot, and adapter management
- multiple lightweight provider adapters
- easier to test and evolve

## Project Tracking Model

Project tracking is required.

### Core entities

#### Project

Logical codebase identity.

Fields:

- `project_id`
- `canonical_root`
- `git_remote_url`
- `default_branch`
- `provider_bindings`
- `created_at`
- `last_seen_at`

#### Workspace

Concrete local checkout or worktree.

Fields:

- `workspace_id`
- `project_id`
- `root_path`
- `kind` (`git_checkout`, `git_worktree`, `plain_folder`)
- `current_branch`
- `is_primary`
- `last_seen_at`

#### ClientBinding

Installed provider integration state.

Fields:

- `binding_id`
- `project_id`
- `provider`
- `scope` (`user`, `project`, `workspace`)
- `status`
- `config_path`
- `last_verified_at`

#### SessionLease

Active client/runtime association.

Fields:

- `session_id`
- `provider`
- `workspace_id`
- `started_at`
- `last_heartbeat_at`

### Resolution algorithm

When a provider launches SymForge:

1. use explicit project root if passed
2. else look for `.symforge/project.toml`
3. else walk upward for `.git`
4. else treat current directory as unmanaged workspace
5. map workspace to existing project if remote/root fingerprint matches
6. otherwise create a new project registration

### Important behavior

- one project can have many workspaces
- git worktrees should map to one logical project
- monorepo subtree pinning should be supported through `.symforge/project.toml`

## Provider Adapter Strategy

### Codex adapter

Current strategy:

- global MCP registration
- optional project-scoped `.codex/config.toml`
- repo `AGENTS.md` augmentation
- repository and user skill installation
- optional startup helper to verify SymForge runtime is reachable

Current limitation:

- public docs in this pass do not show a hook system equivalent to Claude or Gemini
- public docs in this pass do not show a packaged extension model equivalent to Gemini extensions

Therefore:

- Codex adapter is instruction-first, MCP-native, and skills-aware
- Codex should not be the source of truth for enforcement policy

Strategic deeper options:

- Codex SDK for internal orchestration workflows
- Codex app-server for future deep custom client integration if that becomes product-worthy

### Claude adapter

Current strategy:

- user or project MCP registration
- optional Claude plugin packaging for bundled distribution
- `.claude/settings.json` hook installation
- SymForge subagent definitions
- slash-command-oriented MCP prompts
- session-start and prompt-submit context injection

This is the strongest adapter for early implementation.

### Gemini adapter

Current strategy:

- official Gemini extension package
- bundled MCP registration
- bundled hooks
- bundled subagents
- bundled skills
- compatible `GEMINI.md` strategy

This is the cleanest packaging story.

### Copilot adapter

Current strategy:

- MCP registration
- `.github/copilot-instructions.md` and `AGENTS.md`
- `.github/agents/*`
- `.github/hooks/*`
- optional SymForge skill pack
- optional Copilot plugin package

This is a strong candidate after Claude and Gemini.

### Amazon Q adapter

Current strategy:

- MCP registration
- Q custom agent profile
- `agentSpawn` and `userPromptSubmit` hooks
- reusable local and MCP prompts

This is a reasonable later adapter.

## Behavioral Goal by Provider

### Baseline goal for all clients

When the model needs to:

- search code
- find symbols
- understand repo structure
- retrieve exact source spans

it should prefer SymForge over naive raw file scanning whenever SymForge is ready.

### Strong goal for hook-capable clients

Hook-capable clients should:

- inject repo/index context before the model plans
- bias the agent toward SymForge lookup
- optionally warn or steer when the model tries expensive naive grep/read flows first

### Non-goal

Do not try to force all file edits through SymForge.

The native file edit/write tools in each client should remain the primary mutation path.

## Installation and Deployment Shape

### User-facing binaries

- `SymForge`
- `SymForged`
- `symforge`

### Responsibilities

`SymForge`

- install
- integrate with provider CLIs
- init project
- doctor
- migrate
- runtime status

`SymForged`

- background runtime
- project registry
- local state manager
- snapshot manager
- indexing coordinator

`symforge`

- thin MCP transport shim
- forwards requests to `SymForged`

### Why split the binaries

- keeps MCP startup cheap
- gives hooks and adapters a stable local target
- avoids embedding provider logic into the daemon

## Probable Source Scaffold

This is the source scaffold most worth moving toward next.

```text
src/
  application/
    services/
      project_registry.rs
      workspace_resolution.rs
      runtime_health.rs
      integration_installer.rs
    use_cases/
      install_runtime.rs
      install_provider_adapter.rs
      init_project.rs
      doctor.rs
      migrate.rs
  control_plane/
    local_state/
      registry.rs
      snapshots.rs
      bootstrap.rs
  daemon/
    server.rs
    ipc.rs
    session.rs
    supervisor.rs
  domain/
    project.rs
    workspace.rs
    provider.rs
    binding.rs
    session.rs
    health.rs
  indexing/
    coordinator.rs
    watcher.rs
    discovery.rs
    hashing.rs
    checkpoints.rs
  integration/
    mod.rs
    codex/
      install.rs
      doctor.rs
      assets.rs
    claude/
      install.rs
      doctor.rs
      assets.rs
    gemini/
      install.rs
      doctor.rs
      assets.rs
    copilot/
      install.rs
      doctor.rs
      assets.rs
    amazon_q/
      install.rs
      doctor.rs
      assets.rs
  ipc/
    protocol.rs
    pipe.rs
  protocol/
    mcp/
      server.rs
      tools/
      resources/
      prompts/
  storage/
    cas/
    repositories/
  templates/
    codex/
      AGENTS.md
    claude/
      CLAUDE.md
      settings.json
      agents/
    gemini/
      GEMINI.md
      settings.json
      extension/
    copilot/
      copilot-instructions.md
      agents/
      hooks/
    amazon_q/
      agent.json
      prompts/
```

## Runtime Lifecycle

### Startup

1. provider client launches MCP shim or helper
2. shim resolves current workspace
3. shim connects to `SymForged`
4. if daemon is absent, start it
5. daemon verifies local runtime state and snapshots
6. daemon loads project and workspace context
7. daemon returns readiness and context summary
8. provider session continues with SymForge available

### Steady state

- daemon keeps project metadata warm
- background indexing updates state incrementally
- provider adapters consult the daemon, not raw repo scans

### Shutdown

- MCP shim exits with provider client
- daemon may remain running briefly with idle timeout
- durable state stays in local snapshots and caches

## Policy Model

SymForge should have a provider-agnostic policy engine.

Policy decisions:

- when SymForge is ready enough to be preferred
- whether stale index state should be served, degraded, or blocked
- whether hooks should warn vs block naive reads
- what context summary to inject at session start

This policy should live in SymForge, not in per-provider assets.

Provider assets should call back into SymForge for decisions whenever possible.

## Recommended First Implementation Sequence

### Phase 1

- document the adapter architecture
- add provider/domain models for project, workspace, provider binding, and session
- split `SymForged` from the MCP shim

### Phase 2

- implement project/workspace registry
- add local IPC
- move current health logic behind daemon services

### Phase 3

- implement Claude adapter first
- install MCP registration plus project/user hook assets
- validate session-start and prompt-submit flows

### Phase 4

- implement Codex adapter
- focus on MCP registration plus `AGENTS.md` strategy

### Phase 5

- implement Gemini extension package

### Phase 6

- add Copilot and Amazon Q adapters

## Open Questions

These questions should remain open until the next research or implementation pass:

- whether Codex exposes a public third-party skill packaging format beyond what is visible in current official docs
- how much provider-specific config SymForge should write automatically versus suggest for review
- whether repo-local generated integration assets should be opt-in or default
- how aggressively hook-capable clients should steer versus block non-SymForge lookups
- whether `SymForged` should be single-user and global, or one runtime per project root

## Working Decision

Unless new evidence contradicts it, the working decision should be:

**Build SymForge as a long-lived local runtime with MCP transport and provider-specific adapters.**

That is the most plausible architecture supported by the verified provider surfaces in this pass.