Imported from zuhabul/ss-bridge (docs/AGENTS.md). Install upstream with npx skills add zuhabul/ss-bridge --skill docs. Copyright stays with the author.

Repository Guidelines

This document provides essential information for developers working on the SS Bridge project.

Project Overview

SS Bridge is a macOS menu bar application that captures screenshots locally, uploads them to AWS S3, and provides a shareable presigned URL for use with remote AI agents (Claude, Codex) over SSH.

Project Structure

ss-bridge/
├── Sources/SSBridge/
│   ├── App/                  # Application entry and controller
│   │   ├── SSBridgeApp.swift
│   │   └── AppController.swift
│   ├── Models/               # Data models
│   │   └── AppSettings.swift
│   ├── Services/             # Business logic services
│   │   ├── S3Service.swift
│   │   ├── ScreenshotService.swift
│   │   ├── KeychainStore.swift
│   │   ├── SettingsStore.swift
│   │   ├── ClipboardService.swift
│   │   ├── NotificationService.swift
│   │   ├── CommandBuilder.swift
│   │   └── LaunchAtLoginService.swift
│   ├── Views/               # SwiftUI views
│   │   ├── MenuBarContentView.swift
│   │   └── SettingsView.swift
│   └── Utilities/            # Utilities
│       └── GlobalHotKey.swift
├── scripts/                 # Build and utility scripts
│   ├── build-app.sh
│   ├── run-app.sh
│   ├── configure-app.sh
│   └── prototype.sh
├── Package.swift            # Swift package manifest
├── README.md                # User documentation
└── PLAN.md                  # Project plan

Build Commands

# Development build (faster, debug symbols)
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift build

# Release build
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift build -c release

# Build app bundle (produces .app in dist/)
./scripts/build-app.sh

# Launch the built app
./scripts/run-app.sh

Development Notes

Minimum macOS version: 13.0 (Ventura)
Swift version: 6.0
Frameworks: AppKit, SwiftUI, CryptoKit, Security, ServiceManagement, Carbon

Key Implementation Details

AWS S3 integration uses custom SigV4 signing (no AWS SDK dependency)
Credentials stored securely in macOS Keychain
Settings persisted via UserDefaults
Global hotkey registered via Carbon API (Shift+Cmd+S)
Launch-at-login uses ServiceManagement (macOS 13+)

Coding Style

Swift 6 with strict concurrency checking
Use @MainActor for UI-bound classes
Prefer async/await over completion handlers
4-space indentation
Follow Apple's Swift API Design Guidelines

Adding New Features

S3-related logic belongs in S3Service.swift
UI components go in Views/
Persistent settings should be added to AppSettings.swift
Use Logger.swift for debug logging (writes to ~/Library/Logs/ss-bridge/app.log)

Security

Never commit AWS credentials or secrets
Use KeychainStore for sensitive data
S3 objects should remain private; use presigned URLs for access

Testing

No formal test suite exists yet. Manual testing via:

./scripts/run-app.sh

Then use the menu bar interface to capture and upload screenshots.

Install docs and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

docs

About