Maple

Maple is an open-source AI client built with React, Vite, and Tauri. It runs as a web application and as native desktop/mobile applications, and uses OpenSecret for confidential authentication, inference, conversations, and related APIs.

Research chat and desktop Agent Mode are different client paths. Research chat uses the TypeScript OpenSecret SDK with the Responses and Conversations APIs; Agent Mode embeds Goose and uses the Rust OpenSecret SDK through Tauri. The local OpenAI-compatible proxy is a separate user-facing service.

Quick start

The supported development environment is the Nix flake. It pins Bun, Rust, platform tools, and native dependencies used by the repository.

nix develop
./setup-hooks.sh
just install
test -e frontend/.env.local || cp frontend/.env.example frontend/.env.local

This creates frontend/.env.local only when it is absent. Never overwrite an existing file: it may be externally managed or contain checkout-specific backend and application configuration. Inspect its source before changing its values.

The common recipes below assume the active Nix shell. For an independent call, prefix a recipe with nix develop -c.

Select the intended OpenSecret API in the ignored frontend/.env.local:

VITE_OPEN_SECRET_API_URL=http://127.0.0.1:3000

The public Maple client ID is already present in .env.example. All VITE_* values are shipped to the client and must never contain secrets.

Start the runtime you intend to exercise:

just dev          # Browser/web development only
just desktop-dev  # Tauri desktop, including Agent Mode and native features

just desktop-dev is preferred over a raw bun tauri dev: it provisions the pinned ONNX Runtime and applies a local Tauri configuration overlay when one is present.

API configuration

frontend/.env.example documents Maple's public configuration surface:

• VITE_OPEN_SECRET_API_URL selects the required OpenSecret backend.
• VITE_CLIENT_ID overrides Maple's public project ID when developing against another OpenSecret project.
• VITE_OS_FLAGS_BASE_URL selects an optional feature-flags API.
• VITE_MAPLE_BILLING_API_URL selects an optional billing API.
• VITE_FORCE_FEATURE_FLAGS is a local preview override, not authorization.

Flags and billing are independent clients; configure their dev or production API URLs for the environment being tested. A working OpenSecret chat does not prove billing- or flag-gated behavior. Provider credentials and administrative API keys belong on their servers, never in Maple.

To use a local backend, follow OpenSecret's own setup guide, including its SQL migration step, and keep the default frontend origin unless you also intend to change and validate OAuth/verification callback handling.

Common commands

Run commands from the repository root:

just                    # List recipes
just install            # Install frontend dependencies
just dev                # Web dev server
just desktop-dev        # Desktop dev application
just desktop-build-debug-overlay # Unsigned debug package with local overlay
just build              # Local web build
just format             # Format frontend source
just lint               # Lint frontend source
just rust-check         # Check the Tauri Rust crate
just rust-lint          # Rust formatting check and strict Clippy
just clean-local        # Clean only this checkout's Cargo artifacts

Bun commands run from frontend/; Cargo commands run from frontend/src-tauri/. Raw cargo clean can remove a shared Nix Cargo build directory, so use just clean-local.

Validation

Use the checked-in CI entry points rather than reconstructing them:

# Frozen install, formatting, ESLint, typecheck, and Bun tests
nix develop .#ci -c ./scripts/ci/frontend.sh

# Locked all-target Rust tests
nix develop .#ci -c ./scripts/ci/rust.sh

# PR-configured web artifact
MAPLE_WEB_ENVIRONMENT=pr nix develop .#ci -c ./scripts/ci/web.sh

# Nix/toolchain/workflow metadata; not application tests
nix flake check

There is no general checked-in browser, packaged-app, or React-to-Tauri-command integration harness. Unit tests and package builds do not prove GUI, native, backend, billing, flags, or IPC integration. A privileged IPC change therefore requires a manual smoke test through the exact desktop application and native effect. For change-specific test selection and a repeatable evidence format, use .agents/skills/validate-maple/.

PR build scripts deliberately ignore local .env* files and compile fixed PR endpoints. They prove PR packaging, not integration with the backend configured in frontend/.env.local. To smoke an exact desktop development application against that configured backend, use just desktop-dev, record the active Tauri overlay, endpoint configuration, executable and application identifier, then exercise the user entry point through Tauri IPC to the native result.

Platform development

Desktop recipes provision ONNX Runtime automatically:

just desktop-build                 # Standard application identity
just desktop-build-debug           # Standard application identity
just desktop-build-debug-overlay   # Requires .local/tauri-workspace.json

Only the overlay recipe applies .local/tauri-workspace.json while packaging. Use it when a checkout-specific bundle identity is part of the smoke test.

Linux desktop builds require the system libraries supplied by the Nix shell. For an already-built binary in a headless display environment, WebKit may need:

WEBKIT_DISABLE_COMPOSITING_MODE=1 \
WEBKIT_DISABLE_DMABUF_RENDERER=1 \
DISPLAY=:0 ./frontend/src-tauri/target/debug/maple

Apple development uses the pinned Apple shell and repository recipes:

just ios-build-onnxruntime
just ios-dev
just ios-dev-sim 'iPhone 16 Pro'
just ios-dev-device 'Your iPhone'

just ios-fix-arch mutates the generated Xcode project. Inspect and either commit or deliberately restore generated changes; do not hide them from Git.

Android development is supported from x86_64 Linux; the .#android shell is not exposed on macOS:

nix develop .#android -c just android-build

The CI scripts under scripts/ci/ are the authority for PR and release-shaped platform builds. Some are platform-specific, remove build outputs or node_modules, and deliberately ignore local .env* files in favor of fixed PR/release endpoints; read a script before running it locally.

Architecture and feature documentation

• docs/agent-mode-mcp.md explains MCP configuration and includes a deterministic feature smoke test.
• docs/agent-mode-acp.md documents the ACP edge and its trust model.
• docs/pdf-ocr.md covers the local PDF/OCR pipeline.
• AGENTS.md defines placement, security, testing, and review standards for contributors and coding agents.
• .agents/skills/ contains task-specific development, validation, security, Agent Mode, and release procedures.

frontend/src/routeTree.gen.ts and native platform projects contain generated content. Use their generators and review the resulting diff rather than editing generated output opportunistically.

Releases

Release preparation and publication are production actions. A push to master starts production-shaped signed workflows and can upload an iOS build to TestFlight; creating a GitHub Release starts the release pipeline and downstream publication. Do not use either as routine validation.

Use .agents/skills/release-maple/ for version parity, tag safety, workflow monitoring, artifact verification, and explicit store handoff. Do not use the legacy just release recipe to create an unreviewed local tag.

When the OpenSecret enclave changes, update and review the corresponding pcr0DevValues or pcr0Values in frontend/src/app.tsx as part of the attestation compatibility change.

Version changes update:

• frontend/package.json
• frontend/src-tauri/tauri.conf.json
• frontend/src-tauri/Cargo.toml
• frontend/src-tauri/gen/apple/project.yml
• frontend/src-tauri/gen/apple/maple_iOS/Info.plist
• frontend/src-tauri/Cargo.lock

Contributing

Keep changes focused, follow the nearest established patterns, add regression coverage at the owning layer, and report exactly which checks and runtime paths you exercised. Security-sensitive changes should distinguish source-confirmed facts from deployment assumptions and live-environment observations.

Before opening a pull request, run the applicable full gates above and inspect git diff --check. See AGENTS.md for the complete change and review standard.