Installation

aidokit ships as a Node.js CLI. The expected entry point is npx — no global install required. This page lists prerequisites, install commands, and verification.

Prerequisites

aidokit detects prereqs and prints the install command for your OS, but it never auto-installs anything (see --skip-prereq-check; rationale: ADR-0008 in the repo). Install these yourself before running aidokit init:

Tool	Version	Required for
Node.js	≥ 20.0.0	Runtime for aidokit and for emitted `.mjs` hook scripts.
Git	any recent	The target project is assumed to be a git repo (or will become one).
Claude Code	≥ 2.1.32	Required for the `claude-code` adapter.
Codex CLI	latest stable	Required for the `codex` adapter.
GitHub Copilot CLI	latest stable	Required for the `copilot` adapter.
Beads CLI	optional	Task graph + decision memory backend. Optional at Minimum, recommended at Standard, near-required at Strict.

Per-OS install hints

Node.js 20+

macOS · Linux · Windows

brew install node@20            # macOS (Homebrew)
sudo apt install nodejs         # Debian / Ubuntu
scoop install nodejs            # Windows (Scoop)
winget install OpenJS.NodeJS    # Windows (winget)

Claude Code

shell

curl -fsSL claude.ai/install.sh | bash        # macOS / Linux
iwr claude.ai/install.ps1 -useb | iex         # Windows PowerShell

Beads CLI

See github.com/steveyegge/beads. Optional at v0.1; aidokit falls back to a flat-file task index when Beads is absent.

Install aidokit

Pre-1.0 alpha (current)

The latest npm dist-tag is intentionally unset pre-1.0 so users do not silently get pre-release builds. Opt in explicitly via the alpha tag:

shell

npx aidokit@alpha init

If you run npx aidokit init (no tag) pre-1.0, the CLI prints a message directing you to the @alpha tag.

v1.0 GA

From v1.0:

shell

npx aidokit init

Global install (optional)

Not required — npx is preferred. If you want a global binary:

shell

npm install -g aidokit@alpha    # pre-1.0
npm install -g aidokit          # v1.0+

Verify the install

shell

npx aidokit@alpha --version
npx aidokit@alpha --help

From v1.0, also verify the npm provenance signature on the package:

shell

npm audit signatures

Note Every @aidokit/* package and the unscoped aidokit CLI publish with npm provenance attestations from v1.0 onward.

What gets installed

npx aidokit@alpha init downloads aidokit and its workspace dependencies into the npx cache. It does not install anything globally and does not modify your shell rc, PATH, SSH keys, or credential stores. It only writes into the project directory you run it from and (optionally) ~/.aido/ for user-level preferences.

Uninstall

Because npx does not install globally, there is nothing to uninstall. To remove generated files from a project you bootstrapped:

shell

# From the project root
rm -rf .claude .codex .copilot .aido .aido-staging
rm -f CLAUDE.md AGENTS.md
rm -f .github/copilot-instructions.md
# Optionally:
rm -rf docs agent-artifacts .beads

Removing docs/ and agent-artifacts/ deletes your project's workflow content — only do this if you started fresh and have not put work into them.

Troubleshooting

Symptom	Fix
`npx aidokit init` says "no version satisfies"	Pre-1.0: use `npx aidokit@alpha init`.
"Prerequisite missing: Claude Code"	Install Claude Code (see above). Exit code 10.
"PREREQ_VERSION_TOO_LOW"	Upgrade the named prereq to the minimum version.
EACCES on Linux	Don't run as root. aidokit writes only to the project dir and `~/.aido/`; both should be user-owned.
Windows: "running scripts is disabled"	PowerShell execution policy. Run as Administrator: `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`.