🚀 devspace-AI

PREPARE YOUR 🍏 Mac FOR DEVELOPMENT
with GitHub Copilot assistant

🎯 Follow this guide and Copilot

⚡ Type /start ~30min to ready

🔰 No prior knowledge: just follow the guide

🇬🇧 🇫🇷

🏁 GET STARTED 🏁

1️⃣ Create GitHub account & activate Copilot

• Create an account on github.com and activate your Copilot subscription — you can use the free plan

2️⃣ Check curl

• curl downloads files from the internet via terminal — usually pre-installed on Mac

curl --version
# should show: curl 8.7.1 or higher

• If curl isn't installed, see curl.se

3️⃣ Install Homebrew

• Mac's package manager (like an app store for developers)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

• ⏱️ Takes ~10 min

• After installation, add Homebrew to your PATH (the installer will show these commands):

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

4️⃣ Install Visual Studio Code

• Your code editor — Copilot lives here

brew install --cask visual-studio-code

5️⃣ Clone devspace-AI

• Create a folder and download this project:

mkdir -p ~/Developer/devspace-AI
cd ~/Developer/devspace-AI
git clone https://github.com/punkyard/devspace-ai.git .

• Note: if git wasn't installed yet, install it first:

brew install git

6️⃣ Open in VS Code and type /start

• launch VS Code
• click File > Open folder...
• navigate to ~/Developer/devspace-AI and click Open
• click your profile icon (bottom left) and sign in with GitHub
• open the chat box (Alt+Cmd+B or Option+Cmd+B)
• type: /start

🤔 What is all this stuff by the way?

git

What: version control — tracks every change you make to code
Why: collaborate with others, undo mistakes, keep history, publish on GitHub
In practice: save your work at important moments, go back if something breaks, share code with teammates

Node.js + npm

What: JavaScript runtime + package manager (like an app store for code libraries)
Why: many modern projects need it; npm installs pre-made code others wrote
In practice: run JavaScript code on your Mac, download useful tools instead of writing them from scratch

NVM

What: Node Version Manager — lets you switch between different Node.js versions
Why: different projects need different versions
In practice: some projects work with Node 16, others need Node 18 — NVM lets you switch without breaking anything

GitHub Copilot

What: AI assistant that writes code with you
Why: explains code, suggests solutions, helps you learn faster
In practice: you describe what you want, Copilot writes it, you learn how it works

MCP Servers

What: Model Context Protocol — connections that give Copilot superpowers
Why: search the web, read docs, access tools — all inside VS Code
In practice: ask Copilot a question, it searches the web for the answer and explains it to you — no tab-switching needed

MCP servers configured in this project:

• Time MCP: canonical UTC timestamps and timezone conversions (no API key required)
• Brave Search MCP: real-time web search from VS Code
• Context7 MCP: instant access to documentation for libraries and frameworks

Homebrew

What: macOS package manager
Why: installs developer tools easily
In practice: instead of downloading installers manually, use brew install commands

curl

What: command-line tool for transferring data with URLs
Why: downloads files and scripts from the internet via terminal
In practice: used to install Homebrew and other tools

📋 after you /start

Copilot guides you through:

1. 💬 questions about your Mac
   _{identifies your environment, stored in context/environment.md}

2. 🛠️ install Git, Node.js (LTS), and NVM
   _{version manager for Node via installer script}

3. 🔑 create API keys
   _{for Brave Search MCP (free) and Context7 MCP (free, optional)}

4. ⚡ set up MCP servers
   _{Brave Search (web search) + Context7 (docs access)}

5. 🧪 test your first prompt
   _{write a prompt, see Copilot work}

6. ✅ done!
   _{your Mac is production-ready}

🔒 Each step asks for your confirmation before running: You're in control.

💡 What you'll be able to do next

🚀 Start Building: clone boilerspace-ai templates for AI-assisted projects

🌐 Search & Code: Web search in your editor with Brave MCP, no tab-switching

👥 Join & Learn: follow communities like Dev.to, Hashnode, local meetups

📥 Download & Study: clone projects from GitHub, see how real code works

🤝 Code with AI: Copilot explains each line as you write or codes for you

📰 Stay updated: Follow daily.dev, Code Report

🔒 Important notes

• API keys are safe: we use VS Code inputs and environment variables (never committed to GitHub)
• you stay in control: each step asks for your confirmation
• open source: see .github/copilot-instructions.md for the full ruleset
• canonical docs: all Copilot rules live in .github/ folder (the Single Source of Truth)
• file structure: folder structure and instruction files are indexed in .github/copilot-instructions.md

social preview not visible in Settings?

• if you do not see the "social preview" section in the repository Settings, check the following:
  • verify you have repository admin permissions (only admins can set the social preview)
  • check if the repo is private; social preview images are shared from public repositories only — a private repo that never had an image may not expose the UI
  • for organization-owned repos, your organization may restrict this setting via admin policy
  • if you cannot find "Settings" in the header, click the "More" dropdown and look for Settings
• if the UI still doesn't show social preview but you want to add an image, a fallback is to add an assets/social-preview.png in a PR for the repo and then have a repo admin upload the same image via Settings → Social preview
• verify the Open Graph image (og:image) with GraphQL openGraphImageUrl:

gh api graphql -f query='query { repository(owner:"punkyard", name:"devspace-ai"){ openGraphImageUrl } }'

• the returned url is the image GitHub uses for social previews and topic thumbnails
• if empty or pointing at the owner's avatar, the repo doesn't have a social preview set

Note: currently, there is no public API to programmatically set a social preview image — it must be uploaded manually via the repository Settings UI

🐛 Found an issue?

• problems during setup? open an issue
• have an idea? suggest it in Discussions
• roadmap: see GitHub Issues for planned features

---

GNU Affero General Public License v3 (AGPLv3) — see LICENSE

made with ⏳ by punkyard