admin-valentin/agent-ecosystem
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
agent-ecosystem/.planning/codebase/INTEGRATIONS.md
matt ae4833e310 feat(planning): add project planning documents and configuration for SSH multi-context workspaces 
- Introduced new planning files including PROJECT.md, REQUIREMENTS.md, ROADMAP.md, and STATE.md to outline the vision and requirements for SSH multi-context workspaces.
- Added ARCHITECTURE.md and CONCERNS.md to detail the codebase structure and address technical debt, known bugs, and security considerations.
- Created CONVENTIONS.md to establish coding standards and practices for the project.
- Updated .gitignore to exclude demo files and added configuration for planning tools.

This commit lays the groundwork for enhancing SSH functionality and user experience in managing multiple workspaces.
2026-02-12 09:37:58 +09:00

5.1 KiB
Raw Blame History

External Integrations

Analysis Date: 2026-02-12

APIs & External Services

SSH/SFTP:

  • ssh2 - Direct SSH client implementation for remote session access
    • SDK/Client: ssh2 package (Node.js native)
    • Auth: SSH agent, password, or private key authentication
    • Implementation: src/main/services/infrastructure/SshConnectionManager.ts
    • Config parsing: src/main/services/infrastructure/SshConfigParser.ts (reads ~/.ssh/config)
    • File system: src/main/services/infrastructure/SshFileSystemProvider.ts (SFTP-based)
    • Purpose: Read Claude Code session files from remote machines

GitHub Releases:

  • electron-updater - Auto-update via GitHub release assets
    • SDK/Client: electron-updater package
    • Configuration: electron-builder.yml publish section
    • Implementation: src/main/services/infrastructure/UpdaterService.ts
    • Update flow: Check → Download → Install (user-confirmed)
    • Purpose: Application auto-updates

Data Storage

Databases:

  • None - File-based storage only

File Storage:

  • Local filesystem only
  • Session data: ~/.claude/projects/{encoded-path}/*.jsonl (read-only)
  • App config: ~/.claude/claude-devtools-config.json (read-write)
  • Notifications: ~/.claude/claude-devtools-notifications.json (read-write)
  • Remote access: SFTP via ssh2 (optional)

Caching:

  • In-memory LRU cache - src/main/services/infrastructure/DataCache.ts
    • Max entries: 50 sessions
    • TTL: 10 minutes
    • Auto-cleanup: Every 5 minutes
    • Disable flag: CLAUDE_CONTEXT_DISABLE_CACHE=1

Authentication & Identity

Auth Provider:

  • SSH authentication (remote access only)
    • Methods: SSH agent, password, private key
    • Agent discovery: SSH_AUTH_SOCK env var, launchctl (macOS), known socket paths
    • 1Password SSH agent: Supported via ~/Library/Group Containers/2BUA8C4S2C.com.1password/agent.sock
    • Default keys: ~/.ssh/id_ed25519, ~/.ssh/id_rsa, ~/.ssh/id_ecdsa
    • Config: ~/.ssh/config parsing for host aliases, identity files

Git Identity:

  • Git identity resolution - src/main/services/parsing/GitIdentityResolver.ts
    • Reads .git/config for user.name/user.email
    • Purpose: Display commit author information in UI

Monitoring & Observability

Error Tracking:

  • None - Local logging only via @shared/utils/logger.ts

Logs:

  • Console output (main process)
  • Electron DevTools console (renderer process)
  • Log prefix format: [Domain:Service] (e.g., [Infrastructure:SshConnectionManager])

CI/CD & Deployment

Hosting:

  • GitHub - Source repository and release hosting

CI Pipeline:

  • GitHub Actions
    • Workflow: .github/workflows/ci.yml - Lint, typecheck, test, build
    • Workflow: .github/workflows/release.yml - Build and publish releases

Build Output:

  • Local: dist-electron/ (compiled code), out/ (packaged app)
  • Distribution: release/ directory
    • macOS: DMG, ZIP
    • Windows: NSIS installer
  • ASAR: Enabled (app code packaged into single archive)

Environment Configuration

Required env vars:

  • None for local mode

Optional env vars:

  • CLAUDE_CONTEXT_DISABLE_CACHE=1 - Disable in-memory cache
  • NODE_ENV=development - Development mode
  • APPLE_TEAM_ID - macOS code signing team ID (build-time only)
  • SSH_AUTH_SOCK - SSH agent socket path (runtime, optional)

Secrets location:

  • SSH keys: ~/.ssh/ directory
  • SSH agent: External (OS keychain, 1Password)
  • App config: ~/.claude/claude-devtools-config.json (user preferences, no secrets)

Webhooks & Callbacks

Incoming:

  • None - Desktop application with no server component

Outgoing:

  • None - No webhook emissions

IPC Communication

Electron IPC:

  • Pattern: Main ↔ Preload ↔ Renderer communication
  • Bridge: contextBridge in src/preload/index.ts exposes window.electronAPI
  • Channels: Defined in src/preload/constants/ipcChannels.ts
  • Domains:
    • Sessions: Project/session listing, search, detail views
    • Repository: Git worktree grouping
    • Validation: Path and mention validation
    • CLAUDE.md: Configuration file reading
    • Config: App settings management
    • Notifications: Error notifications and triggers
    • Utilities: Shell operations, file watching
    • SSH: Remote connection management
    • Updater: Update lifecycle events

Real-time Updates:

  • File watching: chokidar-based file system monitoring
    • Debounce: 100ms
    • Events: file-change, todo-change
    • Implementation: src/main/services/infrastructure/FileWatcher.ts
    • Supports both local and SSH file systems

External File Access

Session Files:

  • Location: ~/.claude/projects/{encoded-path}/*.jsonl
  • Format: JSONL (JSON Lines) with Claude Code conversation data
  • Access: Read-only
  • Parser: src/main/services/parsing/SessionParser.ts

Configuration Files:

  • ~/.claude/CLAUDE.md - Global Claude Code configuration
  • {project-root}/CLAUDE.md - Project-specific configuration
  • {directory}/CLAUDE.md - Directory-specific configuration
  • Reader: src/main/services/parsing/ClaudeMdReader.ts

Git Worktrees:

  • Reads .git/config for worktree detection
  • Grouper: src/main/services/discovery/WorktreeGrouper.ts

Integration audit: 2026-02-12