{"id":50416084,"url":"https://github.com/alexxanderdiaz/ai-coding-stack","last_synced_at":"2026-05-31T06:00:44.217Z","repository":{"id":361285242,"uuid":"1253739486","full_name":"alexxanderdiaz/ai-coding-stack","owner":"alexxanderdiaz","description":"Portable toolkit for AI coding tools (Claude Code, Codex, Antigravity): install them + scaffold any project with cross-tool AGENTS.md context and session continuity.","archived":false,"fork":false,"pushed_at":"2026-05-29T23:25:37.000Z","size":277,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T00:20:08.338Z","etag":null,"topics":["agents-md","ai","antigravity","claude-code","codex","coding-agents","cross-platform","developer-tools","project-scaffolding"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexxanderdiaz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-29T19:09:10.000Z","updated_at":"2026-05-29T23:25:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alexxanderdiaz/ai-coding-stack","commit_stats":null,"previous_names":["alexxanderdiaz/ai-coding-stack"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/alexxanderdiaz/ai-coding-stack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexxanderdiaz%2Fai-coding-stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexxanderdiaz%2Fai-coding-stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexxanderdiaz%2Fai-coding-stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexxanderdiaz%2Fai-coding-stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexxanderdiaz","download_url":"https://codeload.github.com/alexxanderdiaz/ai-coding-stack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexxanderdiaz%2Fai-coding-stack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33718446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents-md","ai","antigravity","claude-code","codex","coding-agents","cross-platform","developer-tools","project-scaffolding"],"created_at":"2026-05-31T06:00:38.922Z","updated_at":"2026-05-31T06:00:44.209Z","avatar_url":"https://github.com/alexxanderdiaz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🧩 ai-coding-stack\n\n**A portable toolkit for AI coding tools — install them, and scaffold any project with cross-tool context + session continuity. Windows · Linux · macOS.**\n\nWorks with **Claude Code · Codex · Antigravity · opencode · Cursor · Windsurf** (and any tool that reads `AGENTS.md`).\n\n![Platform](https://img.shields.io/badge/OS-Windows%20%7C%20Linux%20%7C%20macOS-blue)\n![Core](https://img.shields.io/badge/core-Node.js-green)\n![License](https://img.shields.io/badge/license-MIT-green)\n![CI](https://github.com/alexxanderdiaz/ai-coding-stack/actions/workflows/ci.yml/badge.svg)\n![npm](https://img.shields.io/npm/v/ai-coding-stack)\n\n\u003c/div\u003e\n\n---\n\n## What it does\n\n1. **Sets up the tools (first-run wizard)** — `node setup.js` detects which of Claude Code, Codex, Antigravity, opencode, Cursor, Windsurf are installed, then in one step **installs the missing ones and applies the ready-to-use config** (Context7 MCP) to every selected tool — new *and* already-installed. Missing package managers (Node.js/Homebrew) are bootstrapped automatically. If a tool already has MCP config, the wizard asks once: **merge** (keep yours, add Context7) or **fresh + backup** (`.bak`). You authenticate each with your own account afterwards.\n2. **Scaffolds projects** (`project-init`, a separate later step) — auto-detects your stack and writes a lean, best-practice context file set so any AI coding tool understands your project from the first prompt:\n   - `AGENTS.md` — **single source of truth**, cross-tool (Codex, Antigravity, Cursor, opencode, Windsurf).\n   - `CLAUDE.md` — short pointer to AGENTS.md (Claude Code).\n   - `GEMINI.md` — Antigravity-specific overrides (pointer to AGENTS.md).\n   - `STATE.md` — a **session-continuity log**.\n3. **Keeps continuity** — type `catchup` to resume exactly where you left off (any tool), `wrapup` to save state before closing. A Claude Stop hook also snapshots git into `STATE.md`.\n\nNo personal config, no accounts baked in. You bring your own.\n\n---\n\n## Prerequisites\n\n- **Git** — required to clone this repo and used by expert discovery (`project-init`). Install it first: `winget install Git.Git` (Windows) · `brew install git` (macOS) · `sudo apt install git` / your distro (Linux).\n- **Node.js ≥ 18** — the toolkit runs on Node. `setup.js` will **auto-install Node.js/npm** if missing (apt/dnf/pacman/zypper/apk on Linux, Homebrew on macOS, winget on Windows) — pass `--no-deps` to skip that bootstrap.\n- A platform package manager for installing the agents:\n  - **Windows** — `winget` (built-in on Win10/11; else install *App Installer*).\n  - **macOS** — [Homebrew](https://brew.sh) (setup prints the one-line installer if missing).\n  - **Linux** — your distro's package manager for CLIs. **GUI IDEs (Cursor, Windsurf, Antigravity) have no Linux auto-installer** — setup prints the download URL to install them manually.\n\nWhat gets installed per OS:\n\n| Tool | Type | Windows | macOS | Linux |\n|------|------|---------|-------|-------|\n| Claude Code | CLI + app | winget | npm + cask | npm (CLI only) |\n| Codex | CLI | winget | npm | npm |\n| opencode | CLI | npm | npm | npm |\n| Antigravity | IDE | winget | cask | manual |\n| Cursor | IDE | winget | cask | manual |\n| Windsurf | IDE | winget | cask | manual |\n\n---\n\n## Quickstart\n\n### Option A — npm (no clone)\nRun the wizard straight from npm:\n```bash\nnpx ai-coding-stack            # runs the first-run wizard\n```\nOr install globally to get the `ai-coding-stack` (wizard) and `aics-init` (scaffold) commands anywhere:\n```bash\nnpm install -g ai-coding-stack\nai-coding-stack                # wizard: detect → install + configure\naics-init --about \"REST API for recurring billing\"   # scaffold the current folder\n```\n\n### Option B — git clone\n```bash\n# Linux / macOS\ngit clone https://github.com/alexxanderdiaz/ai-coding-stack.git\ncd ai-coding-stack \u0026\u0026 ./setup.sh\n```\n```powershell\n# Windows\ngit clone https://github.com/alexxanderdiaz/ai-coding-stack.git\ncd ai-coding-stack\npowershell -ExecutionPolicy Bypass -File .\\setup.ps1\n```\n\n### Non-interactive (either install method)\n```bash\nai-coding-stack --tools all                    # install + configure all tools (no prompts)\nai-coding-stack --tools claude,codex,opencode  # a subset\nai-coding-stack --tools all --fresh            # fresh+backup existing MCP config\nai-coding-stack --tools all --no-deps          # skip Node/Homebrew bootstrap\naics-init --about \"REST API for recurring billing\"   # scaffold cwd (or: node setup.js --init)\n```\n\u003e With a git clone, use `node setup.js …` / `node project-init.js …` instead of the global commands.\n\nThen authenticate (your accounts):\n- **Claude Code:** `claude` → `/login`\n- **Codex:** `codex login`\n- **opencode:** `opencode login`\n- **Cursor:** open the app → sign in\n- **Windsurf:** open the app → sign in\n- **Antigravity:** open the app → sign in with Google\n\n---\n\n## The setup wizard, screen by screen\n\nRun `ai-coding-stack` (or `npx ai-coding-stack` / `node setup.js`) with no flags:\n\n**1. Detection** — lists every tool and whether it's already installed:\n```\nDetected on this machine:\n  ✓ Claude Code\n  · Codex            (not installed)\n  ✓ opencode\n  · Cursor           (not installed)\n  ...\n```\n\n**2. Tool selection** (arrow-key, all preselected):\n```\nSet up which tools? (installs missing + configures all selected)\n ❯ ◉ All tools\n   ◉ Claude Code   installed — add config\n   ◉ Codex         install + config\n   ◉ opencode      installed — add config\n   ...\n ↑/↓ move · space toggle · enter confirm\n```\n- **All tools** row toggles everything. `space` toggles one; `enter` confirms.\n- Selecting a tool that's already installed = just add config (no reinstall); a missing one = install + config.\n- Non-TTY (pipes/CI): falls back to a numbered prompt (`0`=all, comma list, or Enter).\n\n**3. Prerequisite bootstrap** — installs Node.js/npm if missing (skip with `--no-deps`).\n\n**4. Install + configure**, per selected tool:\n- installs the CLI/GUI (or prints a download URL where there's no auto-installer),\n- writes **Context7 MCP** config (opencode/Cursor/Windsurf; Claude gets a `claude mcp add` one-liner),\n- installs the **`project-init` command** into the tool (Claude/opencode/Codex/Antigravity).\n\n**5. Existing config** — only if a selected tool already has MCP servers:\n```\nExisting MCP config found for: opencode — how to add Context7?\n ❯ Merge          keep your servers, add Context7 (non-destructive)\n   Fresh + backup back up to .bak, then write a clean config\n```\n\n**6. Auth notes** — how to sign in to each selected tool.\n\n**7. Scaffold now?** — optional (default **No**):\n```\nScaffold the current folder as a project now?  (/path/to/cwd)\n ❯ No    all set — say \"project-init\" in a tool later, or `node setup.js --init`\n   Yes   run project-init here now (AGENTS.md + experts)\n```\nEither way you finish with **✓ Setup complete** — tools are installed/configured and `project-init` is available inside them.\n\n---\n\n## project-init in detail\n\n```bash\nnode project-init.js . --about \"what the project is\"\n```\nAuto-detects the stack — `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` / `pom.xml` / Gradle / Docker, plus **Terraform** (`*.tf`), **Azure Bicep** (`*.bicep`), **Shell** (`*.sh`), and **Azure CLI / azd** (`azure.yaml` / `.azure/`) — → real `build`/`test`/`lint` commands (e.g. `terraform init/validate/fmt/plan`, `az bicep build/lint`, `shellcheck`). Writes the four files with lean, agents.md-2026 best-practice sections: **Goal · Commands · Structure · Non-obvious patterns · Permissions/boundaries · Conventions · Commits/PR · Continuity**. The agent fills *Structure* and *Non-obvious patterns* by inspecting the repo.\n\n### Use it from inside a tool (skill)\nThe setup wizard **already installs `project-init` as a command** into each compatible tool's global skills dir (Claude `~/.claude/skills/`, opencode `~/.config/opencode/skills/`, Codex `~/.codex/skills/`, Antigravity `~/.gemini/skills/`). So just open the tool in a project folder and say **“project-init”** / “set up this project” — it scaffolds `AGENTS.md` and downloads/configures the experts that project needs. (Cursor/Windsurf use per-project rules, no global command — run `node setup.js --init` there.)\n\n---\n\n## Expert discovery (skills \u0026 agents)\n\n`project-init` can suggest and install best-fit **skills and agents** for your stack\nand purpose, rendered to each tool's native format:\n\n```bash\nnode project-init.js . --about \"REST API for billing\" --with-experts   # prints suggestions\nnode install-experts.js . --tools claude,codex --experts api-backend-pro,code-reviewer --dry-run\nnode install-experts.js . --tools claude,codex --experts api-backend-pro,code-reviewer --yes\n```\n\n- Experts come from a **bundled, vetted catalog** (`catalog/`) — offline, no third-party code.\n- Rendered per tool: Claude `.claude/agents/*.md`, Codex `~/.codex/agents/*.toml`,\n  Antigravity `.agent/workflows/*.md`; skills go to each tool's `skills/` dir.\n- **Claude/Antigravity install project-local; Codex installs globally (`~/.codex`, affects all projects).**\n- **Writes require `--yes`** (the installer previews otherwise); `--dry-run` previews, `--force` overwrites.\n- Always review generated files before relying on them.\n\n### Live discovery from trusted collections\nBeyond the bundled catalog, `project-init` can pull best-fit skills/agents from a\ncurated allowlist of popular collections (`catalog/sources.json`) — fetched, pinned,\nand installed only where relevant:\n```bash\nnode lib/fetch-source.js wshobson-agents          # clone (pinned) -\u003e {path, ref}\nnode lib/scan-source.js \u003cpath\u003e claude-plugin-marketplace   # list what's inside\nnode install-experts.js . --tools claude,codex --source-id wshobson-agents \\\n  --source-path \u003cpath\u003e --layout claude-plugin-marketplace --ref \u003cref\u003e --pick code-reviewer --dry-run\nnode install-experts.js . --update --dry-run        # refresh installed experts\n```\n- Sources are an **allowlist** (host-checked HTTPS, `--depth 1`, SHA-pinned, symlinks rejected, **never executed**; permissive license only).\n- Installs are recorded in `.aics-experts.json` (provenance); `--update` re-fetches latest with a preview and `--yes` gate.\n- Fresh at install; nothing auto-updates silently.\n\n**Three layers (quality-first):** 1) bundled catalog (offline) -\u003e 2) live trusted sources (above) -\u003e 3) **generate** a bespoke skill/agent only for gaps:\n```bash\n# the agent authors a spec to /tmp/spec.md, then:\nnode install-experts.js . --tools claude,codex --generate --spec-file /tmp/spec.md --dry-run\n```\nGenerated experts are recorded as `source: \"generated\"` and skipped by `--update`.\n\n---\n\n## Demo\n\n![ai-coding-stack project-init demo](docs/demo.gif)\n\n```text\n# next day, in any tool — resume exactly where you left off:\n\u003e catchup\n  → reads STATE.md + git log → \"Last session: added auth middleware. Next: wire Stripe webhooks.\"\n```\n\n## Optional: back up your own config\n\n`sync/backup.sh` archives the shareable parts of **your** `~/.claude` / `~/.codex` (secrets excluded) to a destination you choose — no personal paths baked in:\n```bash\nAICS_DEST=~/my-dotfiles ./sync/backup.sh      # to a local dir / git repo\nAICS_RCLONE=myremote:ai-config ./sync/backup.sh   # to your own rclone remote\n./sync/restore.sh ai-config-YYYYMMDD.tgz\n```\n\n## Optional: Context7 docs MCP\n\n[Context7](https://context7.com) injects version-accurate library docs into the agent's context (Next.js, React, Tailwind, etc.), cutting hallucinated/deprecated APIs. It's a hosted MCP server — **bring your own key** (free at context7.com); nothing is stored in this repo.\n\n```bash\n# get a key at https://context7.com, then set it in your environment:\nexport CONTEXT7_API_KEY=\"\u003cyour-key\u003e\"\n\n# propagate Context7 MCP to opencode / Cursor / Windsurf:\nnode lib/propagate-mcp.js all\n# or subset:\nnode lib/propagate-mcp.js opencode,cursor\n```\n\nThe key is read from your environment and written using each tool's native env-interpolation syntax (no plaintext API keys on disk). *(Claude Code registers Context7 separately via `claude mcp add` — see install.js / the section above.)*\n\n## Components\n\n| File | Role |\n|------|------|\n| `setup.js` · `setup.sh` · `setup.ps1` | First-run wizard / bootstrap |\n| `ensure-tools.js` | Detect + install each tool's GUI \u0026 CLI (+ Node/brew prereq bootstrap) |\n| `lib/tui.js` | Zero-dep arrow-key menu (numbered fallback on non-TTY) |\n| `project-init.js` | Cross-tool project scaffolder |\n| `lib/detect-stack.js` | Stack + real commands detection |\n| `lib/propagate-mcp.js` | Write Context7 MCP into each tool's config (env-interpolated) |\n| `hooks/state-snapshot.js` | Claude Stop hook → git snapshot in STATE.md |\n| `skills/project-init/` | In-tool `project-init` command (installed into tools by setup) |\n| `catalog/` | Vetted expert catalog + canonical specs |\n| `lib/match-experts.js` | Stack + purpose → expert shortlist |\n| `lib/render-expert.js` | Spec → per-tool native format |\n| `install-experts.js` | Install rendered experts into selected tools |\n| `catalog/sources.json` | Trusted-source allowlist for live discovery |\n| `lib/fetch-source.js` | Clone (pinned) + host allowlist + symlink reject |\n| `lib/scan-source.js` | Enumerate skills/agents in a fetched source |\n\n---\n\n## Docs\n\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — how it fits together (with diagrams)\n- [docs/USAGE.md](docs/USAGE.md) — end-to-end examples\n- [docs/PROJECT-INIT.md](docs/PROJECT-INIT.md) — the generated files + best practices\n\n## Releasing\n\nPublishing is automated via **npm Trusted Publishing** (OIDC + provenance, no tokens):\n1. One-time on npmjs.com: package → **Settings → Trusted Publishing** → add publisher\n   (owner `alexxanderdiaz`, repo `ai-coding-stack`, workflow `release.yml`).\n2. Then: `npm version patch \u0026\u0026 git push --follow-tags` → the `release.yml` workflow\n   runs the smoke tests and publishes with a verified provenance badge.\n\n## License\n\n[MIT](LICENSE) © 2026 Alexander Diaz.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexxanderdiaz%2Fai-coding-stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexxanderdiaz%2Fai-coding-stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexxanderdiaz%2Fai-coding-stack/lists"}