Install ArchDev

Install ArchDev on the machine where you run your coding agent.

Install

Run the command for your operating system in your terminal (macOS or Linux) or PowerShell (Windows):

These commands download and run the ArchDev installer.

Sign in

Follow the installer’s setup instructions to sign in and connect your agent. If setup didn't finish, run archdev auth login, then archdev setup.

Restart your agent

Start a new session so your coding agent loads ArchDev.

Review a change

In a repository with changes you haven't merged yet, ask your agent:

Use ArchDev to grade the risk of my current changes.

You’re ready when your first graded review opens in ArchDev. Read the reasons behind the grade; it is not approval to merge. See Understand risk and complexity.

For organization membership and GitHub repository access, see Set up your team. Each teammate installs ArchDev on their own machine and uses their own account.

Keep the CLI up to date

For installer or Homebrew installations on macOS and Linux:

archdev upgrade --check   # Check without changing the installation
archdev upgrade           # Update the CLI and refresh existing hooks and skills

archdev upgrade uses the release installer for installer-owned binaries and invokes Brew for Homebrew installations. On Windows, rerun the PowerShell installer above instead; a running Windows executable cannot replace itself. Development and unstamped builds are not prompted to install a release.

When installed ArchDev session hooks detect a newer stable release, they add upgrade guidance to your coding agent's context. Before finishing that turn, the agent should either upgrade if already authorized and safe, then verify the installed version and hook/skill refresh, or ask you for permission. If running jobs make an upgrade unsafe, it should explain the blocker and name the checkpoint when it will revisit the update—not silently defer. It must respect intentional version holds and avoid interrupting jobs or repeatedly retrying a failed upgrade.

Unresolved guidance repeats on subsequent user turns, at most once every 30 minutes, not after every tool call. After asking for permission, respecting a hold or decline, or reporting a failure, the agent records that outcome using archdev repo hook update-status with the session and release identified in the guidance. That stops reminders for that release in that session; resuming the same session preserves the outcome. A new session or newer discovered release may show guidance again. Upgrading also stops reminders once the hooks observe the new CLI version. Sessions without an identifiable session ID get only the initial guidance.

Only release metadata is fetched in the detached session-start worker, including sessions without a terminal. Successful checks are cached for 24 hours and failed requests back off for five minutes. The guidance arrives through the next context-capable hook. No background worker installs or replaces the CLI; the agent decides whether and when to run the update mechanism.

CI, ARCHDEV_NO_UPDATE_CHECK=1, and NO_UPDATE_NOTIFIER=1 suppress this discovery and guidance. If hooks are absent or the agent defers, use the manual mechanism above. Agent guidance is a reminder, not a guarantee that an update will happen.

If something isn't working

• ArchDev’s tools don’t show up: finish the installer’s setup instructions and start a new agent session.
• Wrong account: run archdev auth logout, then archdev auth login with the account your team uses.
• Can't access your team: check your account and ask an organization administrator to confirm your membership.
• Installation failed: check the error in your terminal and contact us with the operating system and non-sensitive error. Never share tokens or passwords.

See Your data and access before sharing private code or team updates.