airdy

airdy is an interactive setup wizard for coding-agent projects. Run it inside a project directory and it asks which agent(s) to configure, the project type, workflows, skill packages, and a git strategy, then writes the project-level config files those choices imply and optionally launches the chosen agent. It writes only project files and never scaffolds application source code.

Quickstart

npx airdy

Run it in the directory you want to set up. The wizard walks these steps:

1. Which coding agent(s) to configure (claude-code, codex).
2. Project type (web, mobile-app, backend, desktop, oss-fork, minimal) — this pre-selects the suggested skill packages for that type.
3. Development workflows (superpowers, verify-loop, ship-gate, none).
4. Skills — a single screen with curated picks for your project type pre-selected, plus options to search the marketplace or add a skill by git URL (see Skills below).
5. Git setup (git init, git clone, gh repo create, or skip).
6. Which agent to launch — or print the launch command and exit.

Skills

The skills step is one screen. Curated skills for your project type (bundled in data/curated.json, refreshed against a live feed with a 24h cache — a network failure or a corrupt bundled snapshot degrade silently to no/stale suggestions rather than aborting the wizard) come pre-selected; any packages from your user config are listed alongside them. Two more options sit at the end of the same list:

• Search marketplace… — queries SkillsMP anonymously (50 searches/day). Pick any number of results, then search again or submit an empty query to finish. Hitting the daily quota (HTTP 429) prints a message telling you to add an API key or add the skill by git URL instead, and the wizard keeps going rather than aborting. Add preferences.skillsmpApiKey in ~/.config/airdy/config.json to raise the quota.
• Advanced: add by git URL — paste one or more comma-separated git URLs (e.g. github.com/owner/repo/skills/foo) to install a skill that isn't in the marketplace or curated set.

Every non-local skill — curated, a marketplace search result, or a pasted git URL — installs the same way: npx skills add <source> --skill <name> -y, so npx must be on PATH. If it isn't, airdy warns before writing rather than failing partway through an otherwise-successful plan. Installed skills are recorded in agentsetup.json (installedSkills), so a later adjust round can list and remove them (see below).

Non-interactive runs (--yes) never open curated suggestions or the marketplace search loop. With --config <file>, skills come from that file's skillPackages and extraSkills; without --config, in a project with recorded state, --yes re-applies the recorded skill set as-is (repair), reinstalling any recorded installedSkills whose directory is missing.

Flags

| Flag | Effect | | ----------------- | -------------------------------------------------------- | | -y, --yes | Non-interactive; applies --config, or with recorded state re-applies it (repair). | | --config <file> | Answers JSON for non-interactive mode. | | --dry-run | Print the plan and the launch command; write nothing. | | --copy | Copy skills into .claude/skills instead of symlinking. | | -v, --version | Print the version. | | -h, --help | Print help. |

Configuration

Optional user config lives at ~/.config/airdy/config.json:

• packages — named skill packages (merged over the built-ins).
• presetSources — directories holding workflow modules loaded by path.
• preferences — defaults such as linkMode (link or copy) and skillsmpApiKey (raises the SkillsMP anonymous search quota above 50/day).

What it writes

Depending on the selections, airdy writes some subset of:

| Path | Purpose | | ----------------------- | ----------------------------------------------------------- | | AGENTS.md | Canonical agent instructions (workflow sections merged in). | | CLAUDE.md | One-line pointer to AGENTS.md (claude-code only). | | .gitignore | Project ignore rules (on git init / gh repo create). | | .agents/skills/<name> | Installed skill directories. | | .claude/skills | Symlink (or copy) to .agents/skills (claude-code). | | .claude/settings.json | Workflow-module hooks (deep-merged with existing). | | agentsetup.json | airdy's own state: your selections plus the paths it owns. |

Re-runs, idempotency, and conflicts

airdy is safe to re-run. Marker-based markdown sections and JSON settings are merged idempotently, so re-running does not duplicate content. agentsetup.json records the exact paths airdy has written (ownedPaths); a file airdy did not create is never overwritten silently — in interactive mode you are prompted to skip, overwrite, or merge, and under --yes such files are skipped and reported.

Re-running in a configured project (adjust mode)

Running npx airdy in a project that already has agentsetup.json opens adjust mode: every setting is shown prefilled with its recorded value, and only what you change is applied. Deselecting a workflow removes its AGENTS.md section, its hooks from .claude/settings.json, and its installed files; deselecting a skill package removes the installed skill directories; deselecting an agent retracts that agent's files; switching the skills mode migrates .claude/skills between symlink and copy. Every currently installed skill — whether it came from a curated pick, a marketplace search, or a pasted git URL — is listed pre-checked too (see Skills); deselecting one removes its directory. When removing or migrating, anything airdy cannot verify it wrote verbatim (edited sections, edited hooks, drifted copies) is asked about first — and skipped under --yes. (Re-installing an owned skills directory in copy mode still overwrites drifted copies silently — MVP ownership semantics.) The one-shot git step never re-runs in adjust mode, and a changed project type only updates the recorded setting (the AGENTS.md template is not re-applied).

If agentsetup.json cannot be parsed, airdy stops with an explicit error instead of silently treating the project as fresh or brownfield. Delete the file to rebuild the configuration through the full wizard.

npx airdy --yes (without --config) in such a project re-applies the recorded configuration as-is (repair).

Existing projects without airdy state

If the project has agent config but no agentsetup.json (an existing AGENTS.md, CLAUDE.md, .claude/settings.json, .claude/skills, .claude/hooks, or .codex/), airdy first prints a read-only import summary — which files it would merge into, leave untouched, or ask about during setup — and asks whether to continue before the wizard starts (--yes prints the summary without stopping).

Security

Every write destination is confined to the project directory. Containment is checked both lexically and via realpath — covering both a symlinked ancestor directory and the destination path itself being a symlink — so a symlink anywhere on the path cannot redirect a write outside the project tree. airdy never touches global config (~/.claude, ~/.codex).

Known limitation: containment is checked before each write, not atomically with it (TOCTOU). Exploiting the gap requires local hostile timing (something racing to swap in a symlink between the check and the write) rather than a remote or data-only attack.

Scope

This is the MVP. Local skill packages install by copying a directory; curated, marketplace-search, and git-URL skills install by shelling out to npx skills add (see Skills).