SwiftClaw

Warning This project is in early alpha. APIs, wire protocols, and package structure are subject to breaking changes. Use at your own risk.

A modular AI gateway written in Swift 6.0 for macOS, inspired from OpenClaw. SwiftClaw connects multiple LLM providers (Anthropic, OpenAI, Gemini, local models) to a unified WebSocket API, with pluggable agent backends, hybrid vector/keyword memory, session management, and a real-time web dashboard.

Architecture

┌─────────────────────────────────────────────────────────┐
│  Clients                                                │
│  ┌──────────────┐  ┌───────────┐  ┌──────────────────┐  │
│  │ Dashboard    │  │ CLI       │  │ TUI              │  │
│  │ Next.js 15   │  │ Argument- │  │ Terminal client  │  │
│  │ React 19     │  │ Parser    │  │                  │  │
│  └──────┬───────┘  └─────┬─────┘  └────────┬─────────┘  │
└─────────┼────────────────┼─────────────────┼────────────┘
          │ WebSocket      │ direct          │ direct
          │ JSON frames    │                 │
          ▼                ▼                 ▼
┌─────────────────────────────────────────────────────────┐
│  Gateway (Hummingbird HTTP/WS)                          │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐  │
│  │ RPC          │  │ EventBus     │  │ Channels      │  │
│  │ Dispatcher   │──│ pub/sub      │──│ Router        │  │
│  └──────┬───────┘  └──────────────┘  └───────────────┘  │
└─────────┼───────────────────────────────────────────────┘
          │ agent.run / session.*
          ▼
┌─────────────────────────────────────────────────────────┐
│  Agent Runtime                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │ Pluggable backends (5 engines)                   │   │
│  │ System prompt · Tool loop · Streaming            │   │
│  └───┬──────────────┬──────────────┬────────────┬───┘   │
└──────┼──────────────┼──────────────┼────────────┼───────┘
       │              │              │            │
       ▼              ▼              ▼            ▼
┌────────────┐ ┌────────────┐ ┌──────────┐ ┌──────────┐
│ Providers  │ │ Tools      │ │ Memory   │ │ Sessions │
│            │ │            │ │          │ │          │
│ Anthropic  │ │ Registry   │ │ Vector + │ │ JSONL    │
│ OpenAI     │ │ Policy     │ │ keyword  │ │ tran-    │
│ Gemini     │ │ engine     │ │ (SQLite) │ │ scripts  │
│ Local      │ │            │ │          │ │          │
└─────┬──────┘ └────────────┘ └──────────┘ └──────────┘
      │
      ▼
┌─────────────────────────────────────────────────────────┐
│  LLM APIs                                               │
│  Anthropic · OpenAI · Google AI · OpenAI-compatible     │
└─────────────────────────────────────────────────────────┘

All packages depend on SwiftClawCore (models, protocols, config).
Plugins extend the system via dynamic loading at runtime.
TestKit provides shared mocks and fixtures for testing.

Prerequisites

macOS 14+ (macOS 15+ for Gateway/CLI/Plugins)
Swift 6.0+ (Xcode 16+)
Node.js 18+ and npm (for the web dashboard)

Getting Started

1. Clone and build

git clone <repo-url> && cd SwiftClaw

# Build all Swift packages
swift build

# Run all Swift tests
swift test

2. Start the gateway

# Run the CLI to start the gateway server (default: 127.0.0.1:18789)
swift run swiftclaw-cli start

# Or with custom host/port
swift run swiftclaw-cli start --host 0.0.0.0 --port 9000

3. Run the web dashboard

cd Apps/swiftclaw-dashboard
npm install
npm run dev

Open http://localhost:3000. The dashboard connects to the gateway via WebSocket at ws://127.0.0.1:18789/ws.

To point the dashboard at a different gateway:

NEXT_PUBLIC_GATEWAY_HOST=0.0.0.0 NEXT_PUBLIC_GATEWAY_PORT=9000 npm run dev

4. Run the TUI client

swift run swiftclaw-tui

CLI Commands

swiftclaw-cli start     Start the gateway server
swiftclaw-cli stop      Stop the gateway
swiftclaw-cli status    Check gateway status
swiftclaw-cli config    View/edit configuration
swiftclaw-cli session   List and manage sessions
swiftclaw-cli onboard   Run the onboarding wizard

Development

Project structure

Directory	Contents
`Packages/SwiftClawCore`	Shared models, protocols, config
`Packages/SwiftClawProviders`	LLM provider implementations (Anthropic, OpenAI, Gemini, OpenAI-compatible)
`Packages/SwiftClawSessions`	JSONL transcript storage, session lifecycle
`Packages/SwiftClawMemory`	Hybrid vector/keyword search via SQLite (GRDB)
`Packages/SwiftClawAgent`	Pluggable agent runtime with 5 backend engines
`Packages/SwiftClawTools`	Tool registry and policy engine
`Packages/SwiftClawChannels`	Channel router for message distribution
`Packages/SwiftClawPlugins`	Dynamic plugin loading
`Packages/SwiftClawGateway`	Hummingbird HTTP/WebSocket server, RPC dispatcher, EventBus
`Packages/SwiftClawTestKit`	Shared test mocks and fixtures
`Apps/swiftclaw-cli`	Command-line interface
`Apps/swiftclaw-tui`	Terminal UI client
`Apps/swiftclaw-dashboard`	Next.js 15 + React 19 web dashboard

Building individual packages

cd Packages/SwiftClawCore
swift build
swift test

Dashboard E2E tests

The dashboard has Playwright E2E tests that use a mock WebSocket gateway:

cd Apps/swiftclaw-dashboard
npm run test:e2e          # Headless
npm run test:e2e:ui       # Interactive UI mode

Key configuration paths

Path	Purpose
`~/.swiftclaw/config.json`	Gateway configuration
`~/.swiftclaw/sessions/`	Session transcript storage

Wire Protocol

The gateway uses flat JSON frames over WebSocket:

// Client → Server (RPC request)
{"type": "request", "id": "req-1", "method": "session.list", "params": {}}

// Server → Client (RPC response)
{"type": "response", "id": "req-1", "success": true, "data": {"sessions": [...]}}

// Server → Client (event push)
{"type": "event", "event": "textDelta", "session_id": "...", "data": {"text": "Hello"}}

RPC methods: session.list, session.transcript, session.delete, agent.run, config.get, config.set, memory.search

License

MIT

antranapp/SwiftClaw

README