EchoBird: Instructions file for Codex

AGENTS.md — EchoBird

Instructions for agents (ZCode / Claude Code / Codex) working in this repo. Read this before modifying code.

Project shape

Tauri desktop app: React + TypeScript + Vite frontend in src/, Rust backend in src-tauri/. Two-tier tool/feature registries often ship in both a bundled copy and a remote copy (e.g. src/data/<x>.json vs docs/api/<...>/index.json) — when adding or editing an entry, update both files unless told otherwise; they share one schema and the remote wins at runtime. Prettier governs the frontend JSON/TS; rustfmt governs src-tauri/.

Keep internal development reports, research notes, and integration playbooks in the ignored internal-docs/ directory. docs/ is the public website.

Desktop interaction rules

• EchoBird is a desktop application, not a website. Do not add custom hover tips, custom tooltips, or other web-style hover-only guidance.
• Keep the mouse cursor as the system default everywhere. Do not use cursor: pointer or any other cursor-changing style for buttons, links, draggable areas, disabled controls, or other interactive elements.

Existing behavior first

• For integration work, read internal-docs/integration-memory.md when present (local-only feedback). Recheck current code; older notes may describe retired layouts or an earlier, incomplete implementation.
• Before adding or extending a tool integration, read internal-docs/tool-integration-playbook.md when present. Record the platform capability table before changing code.
• Before adding a feature similar to one already in the app, identify the reference files and trace the full interaction through handlers, effects, and backend calls. Compare loading, selection, refresh, errors, and saved state; matching the appearance alone is insufficient.
• Reuse existing components and behavior. Keep provider-specific differences limited to necessary authentication, storage, and API details. Do not add automatic actions, new interaction flows, or new frameworks unless the task requires them. State any necessary behavioral difference and its reason before implementing it.
• Tool detection and executable resolution belong in services/tool_manager.rs with catalog entries in tools/<id>/paths.json; Windows Store package lookup uses services/msix.rs. Launch through services/process_manager.rs and create background commands with utils/process.rs so Windows console suppression is shared. Keep explicit interactive terminal launches separate.
• Evaluate Windows, macOS, and Linux for every new integration. Separate vendor availability from EchoBird implementation gaps; do not silently restrict an existing cross-platform client to Windows. Verify native paths, credential storage, process handling, and installation on supported systems, and state any platform limitation before release.
• Before implementation, record the requested capabilities against all three platforms, with the existing code to reuse and the verification for each. Distinguish implemented, unverified, and vendor-unavailable; do not turn an excluded capability into new scope to fill the table.
• A visual-only request must preserve unrelated typography, spacing, layout, and interaction. Keep the latest user-approved result as the baseline.
• If existing implementations disagree, follow the user's confirmed behavior and these conventions. Do not silently choose one and call it consistent. Ask a focused question only when a product decision remains unresolved.
• For behavior changes, establish regression expectations from the agreed workflow before coding. Cover entry, exit, tool/tab switching, missing local state, pending requests, and failures where relevant. Assert which network calls, writes, and dialogs must not happen during passive navigation.
• Review against the reference behavior as well as code correctness. Passing tests alone does not establish consistency. Report what was reused and any necessary differences; keep unrelated implementations outside the change.
• Before calling an integration complete, reconcile that capability table with evidence for detection, installation, launch, and the requested account or model operations. A Windows build or UI approval does not verify other OSes or native account switching. Report build, fixture, and live-client checks separately; verify test instrumentation with a positive control.
• At a handoff or interruption, save the current goal, approved decisions, reference files, changed/committed state, verification limits, and next step in a local note. Resume from that note and current Git state; do not restart the design or silently drop unfinished parts when the user gives feedback.