tpmjs/apps/omega-mac

Omega Mac

Native macOS chat app powered by the TPMJS tool registry — 1M+ AI-ready tools at your fingertips.

Omega Mac is the desktop counterpart to the web-based Omega agent. It connects directly to the OpenAI API and the TPMJS registry to search, discover, and execute tools in a secure remote sandbox — all from a native SwiftUI interface.

Requirements

• macOS 15 (Sequoia) or later
• Xcode 16+
• An OpenAI API key

Getting Started

1. Open Package.swift in Xcode
2. Wait for Swift Package Manager to resolve dependencies
3. Build and run (Cmd+R)
4. Open Settings (Cmd+,) and enter your OpenAI API key
5. Press Cmd+N to start a new conversation

How It Works

Omega Mac implements a full agentic tool-use loop:

User message
    → Auto-discover relevant tools (BM25 search against tpmjs.com)
    → Build tool list (registrySearch + registryExecute + discovered tools)
    → Stream OpenAI response
    → If tool calls returned:
        → Execute tools via remote sandbox (executor.tpmjs.com)
        → Feed results back to OpenAI
        → Loop (up to 10 iterations)
    → Display final response

Two Core Tools

Every conversation has access to two meta-tools that unlock the entire registry:

• registrySearch — Search 1M+ tools by keyword. Returns tool IDs and metadata.
• registryExecute — Execute any tool by its ID. Runs in a secure remote sandbox.

When you send a message, Omega also auto-discovers relevant tools via BM25 search and injects them as directly-callable functions — so the AI can call them without going through registryExecute.

Architecture

OmegaMac/
├── Models/              SwiftData persistence
│   ├── Conversation     Chat sessions with token tracking
│   ├── Message          User/assistant/tool messages with JSON tool call data
│   ├── ToolCallRecord   Individual tool execution records
│   ├── EnvVar           Environment variable metadata (values in Keychain)
│   └── UserSettings     Model selection, system prompt, pinned tools
├── Services/            Actor-based networking
│   ├── OpenAIService    Streaming chat completions via SSE
│   ├── StreamParser     Server-Sent Events line parser
│   ├── TPMJSRegistry    Tool search + remote execution
│   ├── KeychainService  Secure storage for API keys and env vars
│   └── ChatOrchestrator @Observable coordinator for the agentic loop
├── Views/               SwiftUI interface
│   ├── Sidebar/         Conversation list with @Query
│   ├── Chat/            Messages, input bar, streaming indicator
│   ├── Tools/           Tool call cards with collapsible JSON
│   ├── Settings/        API key, env vars, system prompt, model picker
│   └── Shared/          Markdown rendering, empty state
└── Utilities/           Tool name sanitization, system prompt builder

Key Design Decisions

• SwiftData for local persistence — no server, no auth, everything on-device
• Keychain for secrets — API keys and env var values are encrypted at rest
• Actors for networking — OpenAIService and TPMJSRegistryService are actors for safe concurrent access
• @Observable — ChatOrchestrator drives all UI state with zero Combine boilerplate
• Dark theme by default — matches the web Omega aesthetic

Settings

API Key (required)

Your OpenAI API key is stored in the macOS Keychain. Omega Mac calls the OpenAI API directly — no proxy server.

Model Selection

Choose from: gpt-4.1-mini (default), gpt-4.1, gpt-4.1-nano, gpt-4o, gpt-4o-mini, o4-mini.

Environment Variables

Many tools in the TPMJS registry require API keys (e.g., WEATHER_API_KEY, GITHUB_TOKEN). Add them in Settings → Environment. Values are stored in Keychain; only key names and last-4-char hints are visible in the app.

All stored env vars are automatically passed to every tool execution.

Custom System Prompt

Append custom instructions to Omega's default system prompt. Useful for constraining behavior, adding domain context, or specifying preferred tools.

Keyboard Shortcuts

Shortcut	Action
Cmd+N	New conversation
Cmd+,	Open settings
Enter	Send message
Shift+Enter	New line in input

Dependencies

• MarkdownUI — GitHub-flavored markdown rendering
• Everything else uses Apple frameworks (SwiftUI, SwiftData, Security, Foundation)

Relationship to Web Omega

This app ports the core logic from the web implementation at apps/web/src/app/api/omega/. The agentic loop, system prompt, tool name sanitization, and search/execute flow are all faithful Swift translations of the TypeScript originals. The key difference is that web Omega uses server-side auth and a database, while Omega Mac stores everything locally with SwiftData and Keychain.