- Swift 69.7%
- Shell 17.5%
- Python 9%
- TypeScript 1.6%
- Ruby 1.2%
- Other 1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
Adds a single-page browser client for AGsession alongside the iOS app. Same backend, different surface — Tailscale-only, no auth UI. Scope: - web/ — React 18 + Vite 5 + TypeScript, plain CSS, no UI framework - Vite dev proxy: /hermes -> http://100.67.51.123:8642 (strips Origin/Referer; gateway has an Origin allowlist that rejects http://localhost:5173) /chat -> http://100.67.51.123:11800 (rag-stack SSE, for future modes) - SSE parser handles both OpenAI streaming (hermes mode) and rag-stack unnamed data:{json} events (delta/tool/tool_log/tool_done/done/error) - Settings overlay: gear icon, backend URL editable, persisted to localStorage. VITE_HERMES_KEY in web/.env.local (gitignored). - Components: ChatView, MessageBubble (markdown via raw HTML for agent), ComposeBar (Enter sends, mode dropdown), ToolCallChip (status, log, copy-when-done), StreamingText (blinking cursor) - scripts/dev-web.sh — wrapper for `task`/manual runs: PID lock (.claude/web.pid), log capture (.claude/logs/web.log), --force kills existing instance - .claude/launch.json — preview server registry for AGsession Not in scope (yet): - Tool call streaming in hermes mode — Hermes OpenAI endpoint doesn't emit structured tool events; non-hermes modes via /chat will surface them via the existing dispatchPayload path - Build/deploy to Hetzner — dev-server only for now Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com> |
||
| .claude | ||
| .github/workflows | ||
| AGsession | ||
| AGsession.xcodeproj | ||
| AGsessionLiveActivity | ||
| deploy | ||
| docs | ||
| Packages | ||
| scripts | ||
| tools | ||
| web | ||
| .gitignore | ||
| AGENTS.md | ||
| Brewfile | ||
| CLAUDE.md | ||
| DESIGN.md | ||
| docker-compose.yml | ||
| LOGO_PROMPT.md | ||
| Makefile | ||
| opencode.json | ||
| README.md | ||
| Taskfile.orchestrator.yml | ||
| Taskfile.yml | ||
AGsession
A native iOS client for intelligent multi-agent interaction, powered by Tailscale and streaming agent backends.
Overview
AGsession (Agent Session) is a premium iOS application that provides a rich, native interface to interact with multiple AI agents running on a private Tailscale tailnet. It replaces day-to-day reliance on chat bots with a modern, real-time streaming experience optimized for iPhone 17 Pro and contemporary iOS.
Core Features
- Multi-Chat Architecture — Independent threads, each with its own mode (chat, agent, research, direct) and full local history
- Multi-Agent Switching — Native support for four rag-stack backends with streamed responses and per-agent status indicators
- Live Terminal & Log Streaming — SSH-style views for
task app:status,oxmgr status, and live service logs - Push Notifications — Native APNs integration for real-time event delivery (in development)
- Live Activities — Monitor long-running agent tasks directly from the lock screen and Dynamic Island
- Token-by-Token Streaming — Feels responsive and alive; no artificial chunking or buffering delays
- Offline-First Persistence — Full local history via SwiftData; authoritative local store with optional CloudKit sync
Architecture
Tech Stack
- Language: Swift 6 (strict concurrency mode)
- UI Framework: SwiftUI with Liquid Glass materials (iOS 26+)
- Networking: URLSession-based SSE client with Tailscale private reachability
- State Management: Swift Concurrency actors, @Observable patterns
- Persistence: SwiftData for thread/message store
- Packages: 12 local SwiftPM modules for feature isolation
Modular Design
The app is structured as a multi-module SwiftPM workspace for fast iteration, independent compilation, and offline-capable previews:
| Module | Purpose |
|---|---|
| Chat | Chat threads, messages, views, and message streaming |
| A2A | JSON-RPC 2.0 + SSE client for A2A-compliant agent endpoints |
| Approvals | Tool-call approval request/decision flow and user notification |
| Auth | Device identity via Secure Enclave (real device) or software keychain (simulator) |
| DesignSystem | Reusable SwiftUI components on system Liquid Glass materials |
| FineTuningCollector | Opt-in capture of model interactions to rotating samples.jsonl for fine-tuning |
| HermesPanel | SwiftUI overlay for the Hermes monitoring dashboard |
| LiveActivities | Live Activity lifecycle for streaming agent tasks to Dynamic Island and lock screen |
| LocalAgent | Local agent task execution, state, and tool running |
| Networking | URLSession SSE client, Tailscale reachability, bearer-token abstraction |
| Persistence | SwiftData store, compression, and integrity helpers |
| SessionsOverview | Sessions list UI, view models, and state management |
Network Architecture
Tailscale Private Reachability
The app communicates exclusively over a private Tailscale tailnet. The system Tailscale iOS app (installed separately from the App Store) provides the VPN tunnel; AGsession connects transparently via resolvable Tailscale hostnames.
- No packet-tunnel extension — The system Tailscale VPN owns the tunnel
- Authentication via tailnet — User identity is validated at the network layer
- Simulator support — The iOS Simulator inherits the Mac's Tailscale tunnel if active
Backend Endpoints
The app talks to services running on a Hetzner host (rag-stack):
agent_api(:11800/chat) — Chat and tool surface, streamed via SSEgeneric_agent(:12100/run) — Long-running task execution with stream results- Deep Research API — In-house MCP endpoint fanning out to Perplexity and Tavily
- APNs Bridge — Server-side subscription to
rag:notify:{chat_id}events
See docs/superpowers/specs/2026-05-13-tailscale-setup.md for admin setup and network topology.
Development
Prerequisites
- Xcode 16+ (with iOS 26 SDK)
- Homebrew (for Taskfile, Git, etc.)
- Tailscale (optional for development; required for production testing)
Quick Start
# Full development environment setup
./scripts/setup-macos.sh
# Or, if already set up:
task build:dev # Build, test, and generate IPA
task build:quick # Build without tests
task build:prod # Production IPA (with optimizations)
Build Commands
All commands are available via task (a make-like tool driven by Taskfile.yml):
task # List all available tasks
task menu # Interactive task selector
task doctor # Verify environment and dependencies
task build:dev # Clean, test, archive (dev build)
task build:quick # Build without tests
task build:prod # Production build with LTO and dead-strip
task release:draft -- 1.0.0 # Create draft GitHub release
task release:publish -- 1.0.0 # Publish release
Raw xcodebuild is available but not recommended; the scripts handle derived-data cleanup and proper test configurations.
Running Tests
task build:dev # Runs tests automatically as part of build
# Or manually:
xcodebuild test -scheme AGsession \
-destination 'platform=iOS Simulator,name=iPhone 17 Pro'
Code Style
The project uses Swift Format (built into recent Xcode toolchains):
swift format -i -r Sources/ Tests/
No SwiftLint rules are currently enforced. All modules are configured to use -strict-concurrency=complete in Swift 6.
Project Status
Current Release: Beta (TestFlight)
Target Device: iPhone 17 Pro (iOS 26+)
Build System: Xcode 16 + Taskfile + SwiftPM
Visibility: Private (no public TestFlight link or GitHub mirror)
Known Limitations (Beta)
- Apple Developer Program enrollment pending (affects TestFlight, Push, App Groups, entitlements)
- APNs bridge is in development
- CloudKit sync is deferred pending user demand
- Terminal transport design still in evaluation (WebSocket vs. SSE vs. polling)
Design Philosophy
UX Principles
- Token-level streaming — Responses feel alive, not chunked
- Instant thread switching — No loading spinners between conversations
- Smooth scrolling — Terminal view handles high-volume logs without stuttering
- One-handed reachability — Bottom navigation and full-screen chat focus
DX Principles
- Previews work offline — Every screen has a preview; no full-app build required
- Modules compile independently — Feature teams can work in parallel
- Mocked SSE/backend — Tests and previews don't require network
- No force unwraps — Typed errors surface cleanly via Result enums
- Swift Concurrency end-to-end — No Combine, no callbacks, no Dispatch
Technical Decisions
- SwiftUI only — Liquid Glass materials are first-class; no approximate blurs
- Local store is authoritative — SwiftData is the source of truth for threads and messages
- No third-party UI frameworks — System materials, NavigationStack, SF Symbols
- Tailscale-only auth (beta) — Device identity via Secure Enclave (production-ready layer); network layer is the gate
- Live Activities for streaming — Agents can show progress on the lock screen and Dynamic Island while running
Future Direction
Planned Features
- User-addable channels — Generic mechanism for runtime-configurable agent endpoints (WebSocket, SSE, custom)
- CloudKit sync — Optional cross-device history sync (deferred)
- On-device summarization — Leverage Apple Foundation Models for long conversation summaries
- Siri Shortcuts — Start a chat, tail a log, or trigger an agent via voice
Deferred (Out of Scope)
- Custom packet-tunnel extension (use system Tailscale VPN)
- HomeKit, CarPlay, or other capability integrations
- macOS/iPad versions (iOS-specific for now)
Documentation
Comprehensive internal documentation lives in the docs/ hierarchy:
docs/repo-wiki/— Module deep-dives and architecturedocs/superpowers/specs/— Feature design documents with rationaledocs/superpowers/plans/— Implementation task breakdownsdocs/BUILD_AND_RELEASE.md— Release procedures and signingCLAUDE.md— Full developer handbook (conventions, skills, workflows)DESIGN.md— High-level product and architectural vision
Contributing
This is a private repository. Contributions from core team members follow the standard pull request workflow:
- Create a feature branch from
main - Work in isolation; preview changes locally
- Open a PR with clear description of changes
- Address code review feedback
- Merge to
mainwhen approved
Each feature ideally lands in a single module and compiles independently for fast CI.
License
Private. Not for public distribution without explicit permission.
Built with Swift 6, SwiftUI, and a passion for streaming AI interactions.