FalconDeck Agent Guide

Overview

FalconDeck is a monorepo for a local daemon-first agent control plane:

• apps/desktop - Tauri shell around the daemon
• apps/mobile - paired mobile client
• apps/remote-web - paired browser client
• apps/site - public marketing site
• packages/client-core - shared TS protocol, types, helpers
• packages/ui, packages/chat-ui - shared UI primitives
• crates/falcondeck-core - shared Rust protocol and types
• crates/falcondeck-daemon - local daemon, agent integration, unified event stream, relay bridge
• crates/falcondeck-relay - public relay with encrypted replay storage and trusted-device pairing
• ops/ansible - deploy and server config

Core Rules

• The daemon is the product; desktop is just its shell.
• Use codex app-server for Codex, not the MCP server path.
• Keep Claude on the CLI subprocess path, not the Agent SDK.
• Sessions and conversation history belong to the underlying agent. Do not add a FalconDeck conversation DB.
• Default to same-folder workflows. Do not force worktrees.
• Start shared protocol changes in crates/falcondeck-core and packages/client-core, then fan out.

Mobile App

• React Native 0.83 + Expo SDK 55. Entry point: apps/mobile/src/entry.ts.
• Package manager: npm (not pnpm). Always run npm install from monorepo root after changing any package.json.
• react-native-nitro-modules must be a direct dependency (auto-linking needs it for the NitroModules pod).
• plugins/withLibz.js links libz for react-native-mmkv's CRC32 — do not remove.
• metro.config.js pins React, React Native, and React DOM resolution to the workspace root. Preserve this single-runtime setup; duplicate copies crash the mobile app.
• babel.config.js must include react-native-unistyles/plugin with root: __dirname.
• EAS builds: make mobile-build (ad-hoc install link) or eas build --profile preview-testflight (TestFlight).
• OTA updates: make mobile-deploy pushes JS-only changes without rebuilding.
• See docs/14-mobile-app.md for full build/deploy/troubleshooting reference.

Gotchas

• The relay is stateful but not the conversation source of truth. The daemon and native agent storage are. Relay replay only smooths remote reconnects.
• Pairings are short-lived onboarding state. Trusted devices are the long-lived relationship.
• Relay replay may be pruned. When history is truncated, clients must recover from a fresh daemon snapshot, not assume full replay remains.
• Relay sequence numbers must stay monotonic after pruning. Do not derive next_seq from the last retained update.
• The daemon is currently localhost-first. falcondeck-daemon binds to 127.0.0.1 by default. Do not document direct-hosted web product behavior unless it actually exists.
• Remote and mobile access depend on daemon RPC registration. Methods like snapshot.current, thread.detail, turn.start, and approval handlers are part of that contract; changing names or flow breaks clients.
• Remote clients are clients of the daemon, not separate durable stores. Before adding remote-only persistence, check whether it belongs in the daemon or native agent storage instead.
• Production relay storage uses Postgres. File-backed relay state still exists for local, test, and simple setups.
• Keep secrets and real inventory out of git. ops/ansible/inventory/example and example vars are safe; real hosts, creds, and production inventory are not.

Working Guidelines

• Packaged Mac deployment: commit, then make desktop-install-head (builds HEAD in a clean temp worktree, installs, restarts), or make desktop-restart (restart only). make desktop-install refuses a dirty tree: other agents' uncommitted edits once shipped and kept the phone offline. These are synchronous one-shot commands with a health check. Never use launchctl submit, KeepAlive jobs, or recurring automation for a one-off restart: a leftover job previously restarted the daemon 77 times and invalidated mobile sync tokens. Do not use broad pkill on the desktop binary; MCP helpers share it.
• Multiple agents often work directly on main. Keep commits terse and scoped, commit completed work promptly, and exclude unrelated changes.
• The Mac runs near-full on disk. Clean up after yourself before handing off:
  • Delete simulators, emulators, and Docker containers/images/volumes you created (xcrun simctl delete <udid>, docker rm/rmi/volume rm). Shut down booted simulators you started.
  • Remove temp worktrees (git worktree remove), scratch clones, /tmp build dirs, smoke-test state dirs, and one-off EAS/Xcode archives you produced.
  • Prefer reusing existing target/, DerivedData, and node_modules over fresh copies; don't create extra cargo target dirs or per-worktree npm installs unless needed, and delete them when done.
  • Only remove artifacts you created. Never prune shared caches, other agents' worktrees, or the user's simulators/containers without asking.
• Read docs/ before changing protocol or architecture.
• Read docs/EXTENSIONS.md before changing extension contracts, contribution points, permissions, storage, or host behaviour.
• Read docs/HARNESSES.md before changing harness (coding CLI) detection, version checks, upgrades, or the harness API surface.
• Read DESIGN.md before changing shared UI, branding, or iconography.
• Keep AGENTS.md short and operational; put rationale in docs/.
• Prefer semantic shared UI wrappers over ad hoc utility-heavy markup.
• Preserve hosting defaults:
• connect.falcondeck.com - relay
• app.falcondeck.com - pairing landing (same public site; opens the iOS app)
• falcondeck.com - public site
• You may use Ansible and SSH on the production relay/app host for deployment, debugging, and verification when needed.

Code Review

• Run the repo-local autoreview on any significant change before handing off, not just headline features. Tests and typecheck alone are not a review.
• Changes to core functionality always warrant a review: the daemon event stream and RPC surface, relay protocol/replay/pairing, client-core sync/streaming/normalization, approval and turn flow, and storage or persistence behavior on any client.
• Also treat new features, protocol or API changes, cross-package refactors, migrations, and release work as significant.
• Skipping is fine only for trivial mechanical edits (copy, comments, isolated styling) — say so in the handoff.
• For uncommitted work, run .agents/skills/autoreview/scripts/autoreview --mode local; for work already committed to main, run --mode commit --commit <sha> per commit.
• Verify accepted findings against the real code path, fix in-scope issues, rerun focused checks, and rerun autoreview until clean.
• Record the autoreview command and result in the handoff when you skip it or when it finds follow-up work.

Priorities

1. Keep the desktop and daemon flow solid.
2. Keep relay protocol and retention/reconnect behavior correct.
3. Keep remote web and mobile aligned with daemon/relay contracts.
4. Keep the public site simple and separate from product runtime concerns.
5. Expand Claude support without regressing the Codex path.