ReCursor Documentation | ReCursor Docs

Skip to content

ReCursor — A Flutter mobile app providing OpenCode-like UI/UX for AI coding agents. Bridge-first, no-login workflow: connects to your user-controlled desktop bridge via secure tunnel.

Publishing note: docs-site/src/content/docs/ is the canonical source for ReCursor documentation.

Architecture

Document	Description
architecture/overview.md	System architecture and component diagram
architecture/data-flow.md	Message flow between mobile app, bridge, and agent
project-structure.md	Flutter directory layout and module organization
data-models.md	Drift schemas, Hive models, and domain entities

Integration

Document	Description
integration/claude-code-hooks.md	Claude Code Hooks integration (event observation)
integration/agent-sdk.md	Agent SDK for parallel agent sessions
integration/opencode-ui-patterns.md	OpenCode UI component patterns for Flutter
bridge-protocol.md	WebSocket message protocol between app and bridge

Security & Operations

Document	Description
security-architecture.md	Network security, auth, cert pinning, bridge authorization, TLS implementation
offline-architecture.md	Drift/Hive storage, sync queue, conflict resolution
push-notifications.md	WebSocket-based notifications and local alerts

Protocol & API Specifications

Document	Description
bridge-protocol.md	WebSocket message protocol between app and bridge
bridge-http-api.md	REST endpoints for hooks, health, and control
error-handling.md	Error taxonomy, recovery patterns, reconnection strategies
type-mapping.md	Dart↔TypeScript cross-language type contracts

Development

Document	Description
ci-cd.md	GitHub Actions + Fastlane pipeline
testing-strategy.md	Testing pyramid and CI integration

Legal

Document	Description
legal/privacy-policy.md	Privacy policy draft for release readiness
legal/terms-of-service.md	Terms of service draft for release readiness

Architecture at a Glance

flowchart TB
    subgraph Mobile["📱 ReCursor Flutter App"]
        UI["OpenCode-like UI\n(Tool Cards, Diff Viewer, Timeline)"]
        State["Riverpod State Management"]
        WSClient["WebSocket Client"]
    end

    subgraph Desktop["💻 Development Machine"]
        Bridge["ReCursor Bridge Server\n(TypeScript)"]
        Hooks["Claude Code Hooks\n(HTTP Event Observer)"]
        AgentSDK["Agent SDK Session\n(Parallel, Optional)"]
        CC["Claude Code CLI"]
    end

    subgraph Anthropic["☁️ Anthropic API"]
        API["Claude API"]
    end

    UI <--> State
    State <--> WSClient
    WSClient <-->|wss:// (Tailscale/WireGuard)| Bridge
    Bridge <-->|HTTP POST| Hooks
    Hooks -->|Observes| CC
    Bridge <-->|Optional| AgentSDK
    AgentSDK <-->|API Calls| API
    CC <-->|Internal| API

Key Constraint: Claude Code Remote Control is first-party only (claude.ai/code, official mobile apps). Third-party clients must use Hooks for event observation and Agent SDK for parallel sessions.

Important Notes

⚠️ Claude Code Remote Control Protocol: The Remote Control feature is designed exclusively for first-party Anthropic clients. There is no public API for third-party clients to join or mirror existing Claude Code sessions.

Supported Integration Paths:

Claude Code Hooks — HTTP-based event observation (one-way)

Agent SDK — Parallel agent sessions (not mirroring)

MCP (Model Context Protocol) — Tool interoperability

Bridge-First Workflow: ReCursor uses a bridge-first, no-login model. The mobile app connects directly to a user-controlled desktop bridge. No hosted accounts, no sign-in required — just secure device pairing via QR code and optional tunneling for remote access.

Contributing

This documentation is a living document. When making changes:

Update the relevant .md file in the appropriate section
Ensure cross-references use relative paths
Add Mermaid diagrams for complex flows
Update this README index if adding new documents

Last updated: 2026-03-17