{"id":50114964,"url":"https://github.com/erkutyavuzer/pixel-agent","last_synced_at":"2026-05-29T02:00:54.834Z","repository":{"id":359552147,"uuid":"1245685584","full_name":"ErkutYavuzer/pixel-agent","owner":"ErkutYavuzer","description":"Personal AI agent for macOS — chat with Claude/Codex/Gemini side by side, dispatch subagents, see your screen via Set-of-Mark, control everything from iPhone. Native Swift, MCP server included.","archived":false,"fork":false,"pushed_at":"2026-05-26T18:57:51.000Z","size":2992,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T20:24:20.796Z","etag":null,"topics":["ai-agent","anthropic","claude-code","computer-use","ios","llm","macos","mcp","subagent","swift"],"latest_commit_sha":null,"homepage":"https://erkutyavuzer.github.io/pixel-agent","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ErkutYavuzer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T13:06:25.000Z","updated_at":"2026-05-26T18:58:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"8af90e11-5a82-4680-b03c-19e6f320fcf5","html_url":"https://github.com/ErkutYavuzer/pixel-agent","commit_stats":null,"previous_names":["erkutyavuzer/pixel-agent"],"tags_count":73,"template":false,"template_full_name":null,"purl":"pkg:github/ErkutYavuzer/pixel-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ErkutYavuzer%2Fpixel-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ErkutYavuzer%2Fpixel-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ErkutYavuzer%2Fpixel-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ErkutYavuzer%2Fpixel-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ErkutYavuzer","download_url":"https://codeload.github.com/ErkutYavuzer/pixel-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ErkutYavuzer%2Fpixel-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33633468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","anthropic","claude-code","computer-use","ios","llm","macos","mcp","subagent","swift"],"created_at":"2026-05-23T14:01:26.340Z","updated_at":"2026-05-29T02:00:54.828Z","avatar_url":"https://github.com/ErkutYavuzer.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pixel-agent\n\n\u003e Pixel-art mascot kılığında, macOS için kişisel bir AI ajanı — sohbet eder, iPhone'la eşleşir, kendi tool'larını başka LLM client'larına MCP ile sunar.\n\n![version](https://img.shields.io/badge/version-0.2.21-blue)\n![tests](https://img.shields.io/badge/tests-420%20passing-brightgreen)\n![swift](https://img.shields.io/badge/swift-6.0-orange)\n![platform](https://img.shields.io/badge/platform-macOS%2014%2B-blue)\n![iOS](https://img.shields.io/badge/iOS-17%2B-blue)\n![license](https://img.shields.io/badge/license-MIT-blue)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/hero-mac-chat.png\" alt=\"pixel-agent Mac uygulaması — chat görünümü, mor mascot köşede, Claude CLI üzerinden cevap\" width=\"700\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eTek/Çift backend modu (Claude · Codex · Gemini) · ed25519 imzalı iPhone pairing · Plan Mode read-only allowlist · macOS Dock mascot · MCP server expose (14 tool, 5 `ui_*` AX-first + chained query DSL + opaqueID resolve + ⌘/⌥/⇧/⌃-click + IME-aware text + window content-area crop + **Set-of-Mark visual annotation**) · Subagent UI paneli (paralel cap=3) · LAN-first Bonjour transport (iOS) · 401 test yeşil · 31 ADR\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e📸 Daha fazla görsel\u003c/summary\u003e\n\n| Mac (yeni başlangıç) | iPhone Home (icon) |\n|---|---|\n| \u003cimg src=\"docs/assets/mac-app.png\" width=\"400\" /\u003e | \u003cimg src=\"docs/assets/ios-home-icon.png\" width=\"100\" /\u003e |\n\n\u003e Demo GIF script'i: `scripts/record-demo.sh` (macOS Screen Recording → ffmpeg/gifski → optimized GIF). `docs/assets/demo.gif` slot'a koymak için kullanılır.\n\n\u003c/details\u003e\n\n## Neden var?\n\nİki amaç:\n\n1. **Kişisel kullanım** — günlük macOS workflow'una entegre bir AI ajanı. claude/codex/gemini CLI'larını tek arayüzden çağırır, iPhone'la pairing yapar, mascot olarak masaüstünde durur.\n2. **Portfolio** — modüler Swift mimarisi, Swift 6 strict concurrency (TaskLocal scoping + actor isolation), ed25519 imzalı transport, MCP server expose; her büyük tasarım kararı bir ADR ile belgeli.\n\nİlk sürüm `pixel-agent2` (~64k satır) hobi olarak büyüdü; tüm mantığı tek SPM target altında 246 dosya, 1463 satırlık AppDelegate god class içeriyordu. v3 bu birikim yerine [v2'nin mimari derslerinden](docs/architecture-decisions-from-v2.md) çıkarılan 14 desen + 3 anti-pattern ile sıfırdan yazıldı.\n\n## Mimari\n\n```mermaid\ngraph TD\n    App[PixelMacApp]\n    MCP[pixel-mcp-server]\n    Core[PixelCore]\n    Backends[PixelBackends]\n    Tools[PixelTools]\n    Memory[PixelMemory]\n    Mascot[PixelMascot]\n    Remote[PixelRemote]\n    MCPLib[PixelMCPServer]\n\n    App --\u003e Core\n    App --\u003e Backends\n    App --\u003e Tools\n    App --\u003e Memory\n    App --\u003e Mascot\n    App --\u003e Remote\n    App --\u003e MCPLib\n    MCP --\u003e MCPLib\n    Backends --\u003e Core\n    Tools --\u003e Core\n    Memory --\u003e Core\n    Remote --\u003e Core\n```\n\n7 library + 2 executable target, her birinin kendi `XCTest` target'ı. Bağımlılıklar tek yönlü — `PixelCore`'a doğru. Modüller arası döngü SPM tarafından compile-time bloklanır.\n\nTam diyagram + sequence akışları: [docs/architecture.md](docs/architecture.md).\n\n## Mimari kararlar (ADR)\n\nHer büyük tasarım kararı [docs/adr/](docs/adr/) altında belgeli.\n\n**Foundation (v0.1.0, Hafta 1-6):**\n- [ADR-0001](docs/adr/0001-modular-spm-monorepo.md) Modüler SPM monorepo\n- [ADR-0002](docs/adr/0002-swiftui-app-lifecycle.md) SwiftUI App lifecycle (`NSApplicationDelegate` yok)\n- [ADR-0003](docs/adr/0003-tasklocal-context-propagation.md) TaskLocal context propagation\n- [ADR-0004](docs/adr/0004-chatbackend-protocol-abstraction.md) `ChatBackend` protokol soyutlaması\n- [ADR-0005](docs/adr/0005-toolarbiter-resource-mutex.md) `ToolArbiter` resource mutex\n- [ADR-0006](docs/adr/0006-jsonl-append-only-storage.md) JSONL append-only depolama\n- [ADR-0007](docs/adr/0007-test-isolation-mock-tasklocal.md) Test izolasyonu (MockBackend + TaskLocal)\n- [ADR-0008](docs/adr/0008-remote-envelope-shared-module.md) Remote envelope paylaşılan modül\n- [ADR-0009](docs/adr/0009-dependency-injection-over-singletons.md) DI over singletons\n- [ADR-0010](docs/adr/0010-cli-subprocess-backend.md) CLI subprocess backend (HTTP API'yi sildi)\n- [ADR-0011](docs/adr/0011-native-macos-toolkit.md) Native macOS toolkit (`PixelTools`)\n- [ADR-0012](docs/adr/0012-remote-envelope-schema.md) Remote envelope şeması\n- [ADR-0013](docs/adr/0013-pairing-and-relay-protocol.md) Pairing + relay protokolü\n\n**v0.2.x:**\n- [ADR-0014](docs/adr/0014-ios-app-store-assets.md) iOS App Store asset + privacy manifest\n- [ADR-0015](docs/adr/0015-ed25519-envelope-signing.md) ed25519 envelope signing (Faz 1 + 2)\n- [ADR-0016](docs/adr/0016-mcp-server-expose.md) MCP server expose Faz 1 (5 saf-data tool)\n- [ADR-0017](docs/adr/0017-plan-mode.md) Plan Mode (`--permission-mode plan` + UI toggle)\n- [ADR-0018](docs/adr/0018-mcp-bridge-unix-socket.md) MCP Faz 2 — Unix socket bridge (3 bundle-bağımlı tool)\n- [ADR-0019](docs/adr/0019-subagent-runner.md) Subagent Runner Faz 1 (`PixelSubagent` library, budget'lı tek-turlu çalıştırıcı)\n- [ADR-0020](docs/adr/0020-mcp-dispatch-subagent.md) Subagent Faz 2 — MCP tool `dispatch_subagent` (headless orchestration)\n- [ADR-0021](docs/adr/0021-lan-mode-bonjour.md) LAN-only mode Faz 1 (`PixelLAN` library: Bonjour + Network.framework, relay bypass altyapısı)\n- [ADR-0022](docs/adr/0022-remote-transport-adapter.md) LAN Faz 2 — `RemoteTransport` protocol + 4 adapter + `FallbackTransport`\n- [ADR-0023](docs/adr/0023-merge-transport-and-mac-wire-up.md) LAN Faz 3 — `MergeTransport` paralel composite + PixelMacApp wire-up\n- [ADR-0024](docs/adr/0024-subagent-ui-panel.md) Subagent Faz 3 — UI panel + paralel cap=3 + MCP/UI birleşik bridge\n- [ADR-0025](docs/adr/0025-lan-first-ios-default.md) LAN Faz 4 — iOS LAN-first default + TXT record + transport indicator\n\nAyrıca: [docs/architecture-decisions-from-v2.md](docs/architecture-decisions-from-v2.md) — birinci sürümden çıkarılan 14 desen ve 3 anti-pattern.\n\n## Kurulum\n\n```bash\ngit clone https://github.com/ErkutYavuzer/pixel-agent.git\ncd pixel-agent\nswift build -c release\nswift test                              # 250 yeşil\n./scripts/build-app.sh release \u0026\u0026 open PixelAgent.app\n```\n\nGereksinimler:\n- macOS 14+\n- Swift 6.0+\n- Aşağıdaki CLI'lardan **en az biri** yüklü ve login olmalı:\n  - [Claude Code CLI](https://github.com/anthropics/claude-code)\n  - [OpenAI Codex CLI](https://github.com/openai/codex)\n  - [Google Gemini CLI](https://github.com/google-gemini/gemini-cli)\n\nUygulama açılışta `claude`, `codex`, `gemini` binary'lerini PATH'te ve bilinen yollarda (`/usr/local/bin`, `/opt/homebrew/bin`, `~/.local/bin`, `~/bin`) tarar. Bulunanlar arasında **Tek/Çift** mod picker ile anlık geçiş. API key veya env var gerekmez — CLI'ların kendi OAuth/login state'ini kullanır.\n\n## Modüller\n\n| Modül | Sorumluluk | Bağımlılık |\n|---|---|---|\n| `PixelCore` | `ChatBackend` protokolü, `ChatOptions`, `Message`/`StreamDelta`, `AgentContext` TaskLocal | — |\n| `PixelBackends` | CLI wrapper (`claude` / `codex` / `gemini` subprocess), `CLIDetector`, `StreamJSONParser`, `CodexJSONParser` | `PixelCore` |\n| `PixelTools` | Native macOS toolkit: `DockBadge`, `SystemNotifications`, `SoundEffect` | `PixelCore` |\n| `PixelMemory` | `ConversationStore` actor (JSONL append-only + archive) | `PixelCore` |\n| `PixelMascot` | 48×48 pixel-art sprite (12×12 ASCII grid), 4 state, SwiftUI `Canvas` render | — |\n| `PixelRemote` | `RemoteEnvelope` (Codable + sig), `EnvelopeSigner` (ed25519), `KeyStore` (Keychain/InMemory), `RelayClient` + `RelayTransport`, `RemoteHost`, `RemoteTransport` protocol, `PairingCode` | `PixelCore` |\n| `PixelLAN` | Bonjour LAN bypass: `LANService` + `LANClient` (Network.framework), `LANServerTransport` / `LANClientTransport` / `FallbackTransport` adapter'ları | `PixelRemote` |\n| `PixelSubagent` | Tek-turlu subagent çalıştırıcı: `Budget` (wallclock + byte cap), `SubagentResult` enum, `SubagentRunner` actor (worker + watchdog yarışı) | `PixelCore` |\n| `PixelMCPServer` | MCP server library: `JSONValue`, `JSONRPCMessage`, `MCPServer` actor, `ToolRegistry`, `BridgeProtocol`, `BridgeClient` | — |\n| `PixelMacApp` (exe) | SwiftUI App composition root, `ChatView`, `PairingView`, `ControlSocketServer` | hepsi |\n| `pixel-mcp-server` (exe) | MCP stdio executable — `main.swift` 3 satır, `MCPServer.runStdio()` | `PixelMCPServer` |\n\n## Durum\n\n**Versiyon:** `v0.2.21` (23 May 2026) · **420 test** yeşil · **31 ADR** · 10 library + 2 executable target · **end-to-end iPhone test'i** doğrulandı\n\n### Sürüm geçmişi\n\n| Sürüm | Tarih | Öne çıkan | Test |\n|---|---|---|---|\n| `v0.1.0` | 21 May | İlk release: 6 sprint, iOS pairing iskeleti, MIT, DocC | 91 |\n| `v0.2.1` | 21 May | Dual-agent paralel sohbet | — |\n| `v0.2.2` | 21 May | Claude `--output-format stream-json` parser | — |\n| `v0.2.3` | 22 May | iOS App Store hazırlık + ed25519 Faz 1+2 + MCP Faz 1 ⚠️ proto v1→v2 | 162 |\n| `v0.2.4` | 22 May | Plan Mode + MCP Faz 2 (Unix socket bridge) | 177 |\n| `v0.2.5` | 22 May | Subagent Runner Faz 1 + dokümantasyon konsolidasyonu | 192 |\n| `v0.2.6` | 22 May | Subagent Faz 2 — MCP tool `dispatch_subagent` | 195 |\n| `v0.2.7` | 22 May | LAN-only mode Faz 1+2 — `PixelLAN` + `RemoteTransport` + 4 adapter + `FallbackTransport` | 226 |\n| `v0.2.8` | 22 May | LAN Faz 3 — `MergeTransport` + PixelMacApp wire-up (Mac side LAN+Relay paralel) | 235 |\n| `v0.2.9` | 22 May | Hotfix: Info.plist `NSLocalNetworkUsageDescription` + `NSBonjourServices` + repo public | 235 |\n| `v0.2.10` | 22 May | Subagent Faz 3 — UI panel + paralel cap=3 + MCP/UI birleşik bridge + cancel bug fix | 244 |\n| `v0.2.11` | 22 May | LAN Faz 4 — iOS LAN-first default + Bonjour TXT record + transport indicator | 250 |\n| `v0.2.12` | 23 May | PixelComputerUse Faz 1+2 (AX-first hybrid, 4 `ui_*` tool) + ToolArbiter implementasyonu + Subagent streaming cancel fix | 315 |\n| `v0.2.13` | 23 May | PixelComputerUse Faz 3a — chained query DSL (`within` + `containsText`) + opaqueID re-resolve + `ui_resolve` MCP tool | 338 |\n| `v0.2.14` | 23 May | PixelComputerUse Faz 3b — `ModifierFlags` (⌘/⌥/⇧/⌃-click) + IME-aware text injection (grapheme cluster grouping) | 362 |\n| `v0.2.15` | 23 May | PixelComputerUse Faz 3c — window content-area screenshot crop (`.windowContent` + `titlebar_offset`) | 382 |\n| `v0.2.16` | 23 May | PixelComputerUse Faz 4 — Set-of-Mark visual annotation (`ui_screenshot(elements:...)` numbered badge + outline) | 401 |\n| `v0.2.17` | 23 May | Hotfix: Launchpad'den açılınca CLI exit 127 (`env: node: No such file`) — `EnvironmentBuilder` PATH augment | 411 |\n| `v0.2.18` | 23 May | Hotfix: Gemini CLI exit 55 (trusted-directory promptu) — `--skip-trust` arg + `GEMINI_CLI_TRUST_WORKSPACE=true` env | 413 |\n| `v0.2.19` | 23 May | Backend default modeller: Claude Opus 4.7 · Codex 5.5 · Gemini 3.5 Flash · `--model` wiring + `PIXEL_*_MODEL` env override | 418 |\n| `v0.2.20` | 23 May | UX: ChatComposer Shift+Enter = newline (plain Enter submit korundu) | 418 |\n| `v0.2.21` | 23 May | Hotfix: Gemini \"root directory\" uyarısı + ModelNotFound — dedicated cwd workspace + default `gemini-2.5-flash` | 420 |\n\n### v0.2 yol haritası\n\n- ✅ stream-json parser (v0.2.2)\n- ✅ Dual-agent paralel sohbet (v0.2.1)\n- ✅ Codex CLI desteği\n- ✅ iOS App Store asset + privacy manifest (ADR-0014)\n- ✅ ed25519 envelope signing — Faz 1+2 (ADR-0015)\n- ✅ MCP server expose — Faz 1+2 (ADR-0016 + ADR-0018, 8 tool)\n- ✅ Plan Mode (ADR-0017)\n- ◐ Subagent dispatching — Faz 1 (ADR-0019) + Faz 2 (ADR-0020) + Faz 3 (ADR-0024: UI panel + paralel cap=3 + bridge birleşimi) landed; Faz 4+ streaming partial output + multi-turn workflow defer\n- ✅ LAN-only mode — Faz 1 (ADR-0021) + Faz 2 (ADR-0022) + Faz 3 (ADR-0023) + Faz 4 (ADR-0025: iOS LAN-first default + TXT record + transport indicator)\n- ☐ App Store signing + submission\n\n## iOS app \u0026 relay\n\niOS uzak istemci source dosyaları `ios/PixelAgentRemote/` altında; xcodegen flow için bkz. [ios/README.md](ios/README.md). Cloudflare Worker relay için bkz. [relay/README.md](relay/README.md). Pairing protokolü: [ADR-0013](docs/adr/0013-pairing-and-relay-protocol.md). ed25519 imzalı handshake: [ADR-0015](docs/adr/0015-ed25519-envelope-signing.md).\n\n## MCP server (claude-cli entegrasyonu)\n\npixel-agent kendi tool'larını [Model Context Protocol](https://modelcontextprotocol.io) standardı üzerinden expose eder — claude-cli ve uyumlu istemciler kullanabilir. claude-cli config'i (`~/.claude.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"pixel-agent\": {\n      \"command\": \"/path/to/pixel-agent/.build/release/pixel-mcp-server\",\n      \"args\": []\n    }\n  }\n}\n```\n\nRelease build:\n\n```bash\nswift build -c release\nls .build/release/pixel-mcp-server     # ↑ command path bu\n```\n\n**Tool'lar (9 toplam):**\n\n| Tool | Tür | PixelAgent.app gerektirir mi? |\n|---|---|---|\n| `get_clipboard`, `set_clipboard` | saf-data | hayır |\n| `get_current_time` | saf-data | hayır |\n| `get_active_app` | saf-data | hayır |\n| `get_lan_ip` | saf-data | hayır |\n| `dock_badge_set` | bridge | **evet** (Unix socket) |\n| `notify` | bridge | **evet** |\n| `play_sound` | bridge | **evet** |\n| `dispatch_subagent` | bridge | **evet** (PixelMacApp `SubagentRunner` invoke eder) |\n\nStdio sanity check (claude-cli olmadan):\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' | swift run pixel-mcp-server\n```\n\nDetay: [ADR-0016](docs/adr/0016-mcp-server-expose.md) + [ADR-0018](docs/adr/0018-mcp-bridge-unix-socket.md).\n\n## Lisans\n\nMIT — bkz. [LICENSE](LICENSE).\n\n## Teşekkür\n\nİlk sürüm `pixel-agent2`'den öğrenilenler bu projenin kalbinde — özellikle `ToolArbiter` resource mutex'i, TaskLocal scoping ve ephemeral subagent isolation desenleri. v2'den çıkarılan ders setinin tamamı: [docs/architecture-decisions-from-v2.md](docs/architecture-decisions-from-v2.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferkutyavuzer%2Fpixel-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferkutyavuzer%2Fpixel-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferkutyavuzer%2Fpixel-agent/lists"}