Develop Maple Agent

Develop Maple Agent

Read root AGENTS.md, apps/maple-agent/AGENTS.md (the component's CLAUDE.md), its README, and the affected source and tests. The component builds the maple-agent-app Cargo package into the maple-agent executable; that name does not identify an arbitrary running development instance.

app/src/backend.rs adapts the transport-neutral runtime under crates/maple-agent/ to GPUI. Keep window/UI concerns in app, and shared account/session/tool policy in the runtime. The runtime consumes the in-tree maple-proxy library and independently selects maple-sdk in the workspace manifest and lockfile. Follow the SDK consumer version policy: prefer a published pin and allow local links during active development. Keep the runtime and embedded proxy on one SDK source/version. Research's Tauri runtime remains independently owned.

Build with the component environment

From the repository root:

cd apps/maple-agent
nix develop --no-update-lock-file
just ci

just ci checks formatting, lint across default/headless/single-mode features, and warning-denied workspace builds/tests. Use just release for optimized build and performance evidence. Root just agent-check, agent-build, and agent-dev enter this component environment. The repository pre-commit hook runs cargo fmt, one workspace Clippy pass, and the workspace tests in this shell when Agent files are staged; set MAPLE_HOOK_FULL=1 for the complete just ci. Root nix flake check --no-update-lock-file additionally validates workflow selection and security contracts when CI, Nix, or routing changes.

Agent has its own Cargo and Nix lockfiles. CI selects Agent for proxy runtime changes and for Rust SDK build inputs, both path dependencies it builds from the tree, but not for TypeScript SDK changes. Component-only changes should not unnecessarily select Research packaging. Maintain the root selectors, their tests, .github/workflows/agent-ci.yml, and unsigned PR selection in .github/workflows/agent-desktop-build.yml together. The desktop workflow intentionally builds both profiles on every master push.

Linux Nix packages use a pure source fileset rooted at the monorepo, including the sibling SDK/proxy source and SDK assets. Validate it when adding a new local dependency or build-time file. Never bypass a missing dependency hash by enabling an unlocked or credential-bearing fetch.

Launch the exact workspace

If an external workspace manager owns this checkout, use its documented launcher and generated environment. Preserve its local/hosted service choices, isolated XDG config/data, development bundle ID, and shared proxy reservation. Agent does not load dotenv files. Do not copy production credentials into source or silently use the legacy GPUI state directory.

For macOS app-identity checks, source the managed environment and run just debug-app inside the component Nix shell, then launch the exact printed bundle path. Managed debug bundles record only public service configuration and both XDG roots in LSEnvironment, so GUI launches preserve isolation; Missing roots fail packaging. The default signing identity is ad hoc; this proves local package startup, not official distribution signing or TCC grants. Track and stop only the process started by the current task. Never kill all maple-agent processes.

Shared Cargo intermediates belong to other worktrees too. Preserve inherited build settings; use only this component's just clean-local for authorized cleanup. Do not run raw cargo clean against the shared cache.