Kiri Friends
Your CLI tools, now on your wrist.
A bidirectional watchOS companion for Claude / OpenCode / Codex CLI.
Features . Quick Start . Architecture . Docs . Roadmap
Kiri Friends is an Apple Watch companion that brings your CLI AI tools to your wrist. It answers four questions at a glance:
- Which CLI tool is active?
- What is the current task or conversation status?
- Are there notifications or alerts from your CLI session?
- Can I send a quick command or prompt without pulling out my phone?
Daily actions stay on your wrist. Advanced features remain discoverable through the iPhone companion app when needed.
| Area | What Kiri Friends provides |
|---|---|
| Native watchOS app | SwiftUI interface built for Apple Watch with complications, notifications, and native controls. |
| Bidirectional communication | View CLI status on your wrist and send quick commands or prompts back to your tools. |
| iPhone companion | Bridge app that manages watch sync, notifications, and relay connection state. |
| Mac Buddy | SwiftUI macOS desktop pet (AGPL-3.0) that ingests CLI hook events, drives an animated overlay, shows approval bubbles, and uplinks to the Cloud Relay. See docs/interfaces/mac-buddy.md. |
| Cloud Relay | Remote relay for device pairing, presence, request routing, and downlink delivery to the Mac bridge. |
| Multi-CLI support | Works with Claude Code, Codex CLI, Copilot CLI, Gemini CLI, Cursor Agent, CodeBuddy, Kiro CLI, Kimi CLI, OpenCode, Pi, OpenClaw, and Hermes Agent through a unified plugin envelope. |
| Complications | Watch face complications show active CLI status at a glance. |
| Conversation history | Browse recent CLI interactions and responses directly on your watch. |
The v1 SwiftUI layout is being finalized. The current interface structure is documented in docs/interfaces/watchos-swiftui-interface.md.
- watchOS 11 or later
- iOS 18 or later (for iPhone companion)
- Xcode 16+ with the Swift 6.0 toolchain
- A paired Apple Watch for testing
git clone https://github.com/your-org/kiri-friends.git
cd kiri-friends
# Build all targets
make swift-build
# Run watchOS app on simulator
make run-watch
# Or run tests
make testWatch App iPhone Companion Cloud Relay Mac Host
| | | |
| WatchConnectivity | HTTPS / WebSocket | Downlink queue |
| WCSession | Relay API | CLIBridge |
v v v v
+-----------+ +---------------+ +--------------+ +-------------+
| watchOS | | iOS Bridge | | Kiri Relay | | Mac Bridge |
| SwiftUI | <---> | Notifications | <---> | Server |<-->| CLI Plugins |
+-----------+ +---------------+ +--------------+ +-------------+
|
v
Claude / OpenCode / Codex
apps/apple/ SwiftPM workspace for Apple clients and Mac bridge
Sources/
KiriFriendsWatchApp/ watchOS SwiftUI app shell
KiriFriendsWatchKit/ Shared watch components and extensions
KiriFriendsCore/ Shared domain models and protocol types
KiriFriendsBridge/ iPhone companion support code
KiriFriendsCLI/ Mac bridge entry point
server/ TypeScript Cloud Relay
plugins/ TypeScript CLI integrations
fixtures/ Shared golden JSON contracts
| Domain | Description |
|---|---|
| Product | Product scope, daily workflow, and information architecture. |
| Interfaces | watchOS SwiftUI UI, complications, notifications, and iPhone companion surfaces. |
| Core | Shared domain, CLIBridge protocol, state management, and CLI communication. |
| Server | Cloud Relay routing, API contracts, deployment, and operational behavior. |
| Operations | App bundle integration, TestFlight distribution, and release management. |
| Quality | Testing strategy, verification commands, and manual QA checklist. |
| Roadmap | Feature roadmap and milestone tracking. |
| Standards | Implementation standards for watchOS UI and communication patterns. |
| Decisions | Architecture decisions and topology rationale. |
| Research | Reference project findings that inform Kiri Friends design. |
| Command | Description |
|---|---|
make dev |
Show available dev targets |
make dev-iphone |
Build, install, and launch the iPhone companion in Simulator |
make dev-watch |
Build, install, and launch the Watch app in Watch Simulator |
make dev-mac |
Build and launch the Mac Buddy macOS app |
make dev-relay |
Run the Cloud Relay HTTP server on 127.0.0.1:8585 |
make dev-server |
Start Cloud Relay TypeScript watch mode |
make dev-plugin |
Start CLI plugin TypeScript watch mode |
make generate |
Generate KiriFriends.xcodeproj with XcodeGen |
make swift-build |
Build Apple Swift targets |
make run-watch |
Build and run watchOS app on simulator |
make test |
Run Apple, server, and plugin tests |
make test-apple |
Run Swift tests in apps/apple/ |
make test-mac |
Run Mac Buddy SwiftPM tests |
make test-server |
Run Cloud Relay tests in server/ |
make test-plugins |
Run CLI plugin tests in plugins/ |
make clean |
Clean build artifacts |
make dev-iphone and make dev-watch generate KiriFriends.xcodeproj with XcodeGen when needed, then use xcodebuild and simctl to launch Simulator apps. They require the matching iOS/watchOS Simulator runtimes from Xcode > Settings > Components. SwiftPM executable targets run on macOS and are only used for package-level build and test workflows.
For an end-to-end iPhone session against a real relay, run make dev-relay first (binds 127.0.0.1:8585). The iPhone companion (BridgeRuntime) polls /v1/events, folds them into a StateSnapshot, syncs to the watch via WatchConnectivity, and writes a ComplicationSnapshot to the shared App Group group.com.kirifriends.shared so the WidgetKit complication updates without restarting Xcode.
When communicating with CLI tools, Kiri Friends uses a JSON envelope:
{
"ok": true,
"data": { ... },
"error": null
}See docs/core/cli-bridge.md for the full protocol specification.
See docs/roadmap/README.md for the full roadmap.
- Read AGENTS.md before making changes.
- Update relevant
docs/files in the same change set as implementation. - Follow the docs/standards/README.md guidelines.
- Add tests for new domain behavior in
Tests/KiriFriendsCoreTests/.
Kiri Friends ships under two licenses:
- MIT for the shared domain library
KiriFriendsCore, the legacyKiriFriendsCLIscaffold, the Cloud Relay server, CLI plugins, fixtures, and documentation. See LICENSE. - AGPL-3.0 for every Apple-platform binary — the watchOS app, iPhone companion, WidgetKit complication, supporting libraries (
KiriFriendsWatchKit,KiriFriendsBridge), the Mac Buddy executable, and its supporting libraryKiriFriendsMacBuddyKit. These bundles carry assets and runtime semantics ported from Clawd on Desk. See NOTICE.md and docs/operations/license-boundaries.md.
Distribution is self-build and internal TestFlight only. Public App Store and external TestFlight are intentionally out of scope under the current license layout; see docs/operations/app-store-distribution.md for the full distribution playbook and the re-licensing path if you want to fork this project for App Store submission.