How ir-interactive-studios/syncforge works
SyncForge coordinates developers working in isolated Git worktrees: developers create workspaces, observers report Git-derived activity to a coordinator, and the coordinator exposes presence, tasks, focus, and overlap warnings. The broader product adds checkpoints and guarded integration, local hunk/symbol analysis, remote collaboration, optional Docker execution and consent-gated AI conflict advice, plus diagnostics. The coordinator is the main orchestration layer. Some subsystem links reflect README capabilities because their implementations were not excerpted; those links are dashed where runtime wiring is unverified.
Main entry points: server.ts Coordinator service · store.ts SQLite project state · observer.ts Workspace observer · git.ts Git operations
Components 23
Developer workflow
- CLI commands
apps/cli/src/index.ts - Workspace observer
packages/agent/src/observer.ts
Coordination
- Coordinator service
apps/coordinator/src/server.ts - Command protocol
packages/protocol/src/index.ts
Git collaboration
- Worktree management
packages/git/src/workspaces.ts - Git operations
packages/git/src/git.ts - Checkpoints
packages/core/src/checkpoints.ts - Integration workflow
packages/core/src/integration.ts
Change analysis
- Conflict classification
packages/core/src/conflicts.ts - Hunk analysis
packages/core/src/hunks.ts - Symbol analysis
packages/core/src/symbols.ts - AI conflict advice
packages/ai/src/advisor.ts - Candidate context
packages/ai/src/context.ts - AI provider
packages/ai/src/provider.ts
Runtime and state
- Docker workspace runtime
packages/runtime/src/workspace-runtime.ts - SQLite project state
packages/storage/src/store.ts - Path safety
packages/core/src/paths.ts - Project setup
packages/core/src/project.ts - Structured logging
packages/core/src/logger.ts
Other components
- Developer
- Shared Git remote
- Docker engine
- AI endpoint
Connections 41
- Developer → CLI commands: runs commands
README.md - CLI commands → Worktree management: creates worktrees
apps/cli/src/index.ts - CLI commands → Workspace observer: starts observer
apps/cli/src/index.ts - Workspace observer → Git operations: reads Git activity
packages/agent/src/observer.ts - Workspace observer → Coordinator service: reports activity
README.md - Workspace observer → SQLite project state: updates activity
packages/agent/src/observer.ts - Workspace observer → Command protocol: validates messages
packages/agent/src/observer.ts - Coordinator service → Command protocol: handles commands
apps/coordinator/src/server.ts - Coordinator service → Worktree management: adds workspaces
apps/coordinator/src/server.ts - Coordinator service → Checkpoints: creates checkpoints
apps/coordinator/src/server.ts - Coordinator service → Integration workflow: orchestrates integration
apps/coordinator/src/server.ts - Coordinator service → Hunk analysis: requests analysis
apps/coordinator/src/server.ts - Coordinator service → Symbol analysis: requests analysis
apps/coordinator/src/server.ts - Coordinator service → Conflict classification: classifies overlap
apps/coordinator/src/server.ts - Coordinator service → Docker workspace runtime: manages runtime
apps/coordinator/src/server.ts - Coordinator service → SQLite project state: reads and writes
apps/coordinator/src/server.ts - Worktree management → Git operations: creates worktrees
packages/git/src/workspaces.ts - Worktree management → SQLite project state: registers workspace
packages/git/src/workspaces.ts - Checkpoints → Git operations: records commits
packages/core/src/checkpoints.ts - Checkpoints → SQLite project state: stores history
packages/core/src/checkpoints.ts - Integration workflow → Git operations: merges candidates
packages/core/src/integration.ts - Integration workflow → SQLite project state: stores operations
packages/core/src/integration.ts - Hunk analysis → Git operations: reads diffs
packages/core/src/hunks.ts - Hunk analysis → Symbol analysis: provides hunk results
packages/core/src/symbols.ts - Coordinator service → AI conflict advice: requests advice
apps/coordinator/src/server.ts - AI conflict advice → Candidate context: builds context
packages/ai/src/advisor.ts - AI conflict advice → AI provider: requests completion
packages/ai/src/advisor.ts - Candidate context → Git operations: checks candidate
packages/ai/src/context.ts - Candidate context → SQLite project state: reads operation
packages/ai/src/context.ts - AI provider → AI endpoint: sends request
packages/ai/src/provider.ts - Docker workspace runtime → Docker engine: runs containers
packages/runtime/src/workspace-runtime.ts - Docker workspace runtime → SQLite project state: uses workspace state
packages/runtime/src/workspace-runtime.ts - CLI commands → Project setup: initializes project
apps/cli/src/index.ts - Project setup → Git operations: inspects repository
packages/core/src/project.ts - Project setup → SQLite project state: initializes state
packages/core/src/project.ts - CLI commands → Shared Git remote: pairs remote clone
README.md - Coordinator service → Shared Git remote: supports remote collaboration
README.md - Coordinator service → Structured logging: writes structured logs
apps/coordinator/src/server.ts - Workspace observer → Path safety: normalizes activity paths
packages/agent/src/observer.ts - Hunk analysis → Path safety: validates paths
packages/core/src/hunks.ts - Candidate context → Path safety: restricts source paths
packages/ai/src/context.ts