v1.0.0

Released: April 2026

This is the first public release of the ARCY AI SDK (@arcyai/sdk), covering the full integration lifecycle: scanning your codebase, embedding the assistant, defining guided flows, syncing identity, and monitoring sessions from your ARCY dashboard.

SDK package

ARCYProvider

The root component that connects your app to ARCY.

• publicKey for identifying your app
• userId, userTraits, organizationId, organizationTraits for associating sessions with your users and accounts
• role for scoping guided flows to specific user roles
• metadata for passing plan tier, feature flags, and other session context

AI modes

The embedded assistant operates in three modes, switchable from a tab bar in the chat panel.

Chat. The user asks where something is. ARCY responds and optionally highlights the relevant element on the page.

Teach. The user asks how to do something. ARCY generates an ordered coachmark walkthrough that highlights one UI element at a time.

Agent. The user tells ARCY what to do. ARCY creates an action plan and executes steps using a constrained action model: click, focus, fill, navigate. Two sub-modes: Ask (per-step confirmation) and Auto (sequential execution). Destructive actions are never included in agent plans.

Proactive intervention

Background behavior analysis that detects struggle signals (repeated clicking, extended inactivity, form abandonment). When a signal fires, ARCY silently queries and, if a relevant teach response is found, shows a small prompt offering help. Enabled by default. Users can toggle it from the ARCY settings panel.

Guided flows

Step-by-step walkthroughs defined in .arcy/flows/*.yaml that the SDK runs automatically or on demand.

• autoStart and once for first-time onboarding flows that run exactly once per user
• targetRoutes with exact paths and prefix wildcard support (/settings*)
• priority for tie-breaking when multiple flows could auto-start on the same route
• completionEvent for event-driven step advancement via window.dispatchEvent
• allowSkip per step for controlling whether the user can bypass that step

data-arcy attributes

Add data-arcy="<id>" to any element to make it targetable by the assistant, guided flow steps, and agent actions.

useArcy hook

Returns visitorId: the stable anonymous ID the SDK assigns to the browser via localStorage. Useful for linking anonymous visitor sessions to registered users at sign-in.

CLI

arcy init

Scans your project locally, reads your source files (up to 30 files, 120KB total), and sends them to AWS Bedrock to generate a .arcy/ knowledge graph: structured YAML files the AI uses to understand your product, including guided flow definitions and app navigation. Also adds data-arcy attributes to detected key elements. Shows a consent prompt before transmitting anything. Supports --scan-preview. AWS Bedrock does not train on customer data.

arcy sync

Rescans your codebase after code changes: updates data-arcy anchors and expands .arcy/ YAML files with any new routes or components detected.

arcy push

Reads your local .arcy/ YAML files and pushes the knowledge graph to your ARCY app. Changes are served to the SDK on every session, so flow updates reach users without a client deployment.

arcy pull

Fetches the latest knowledge graph from your ARCY app and writes the YAML files into your local .arcy/ directory.

arcy status

Shows sync state, guided flow count, session count, and whether a live session was received in the last five minutes.

arcy log

Full push history with timestamps, flow counts, and delta annotations showing what changed between each push.

arcy rm

Reverses arcy init: surgically removes ARCY-related code from your existing files (ARCYProvider wrapper, data-arcy attributes, SDK imports) using local pattern matching, deletes ARCY-created files (.arcy/, .arcy-manifest.json), removes @arcyai/sdk from package.json, and deletes the app from your ARCY account.