Install

Ideafy ships as a macOS desktop app (Electron). Two editions — Public and Team — each have their own DMG. This page covers the first install; for the detailed per-edition guide, see Editions overview.

System requirements

macOS 12 or later (Monterey, Ventura, Sonoma, Sequoia)
Apple Silicon or Intel — universal binary
Git available on PATH — required for worktrees and dev server orchestration. Install from git-scm.com or brew install git
Node.js (LTS) and npm available on PATH — required when Ideafy installs the Claude Code plugin and its bundled MCP server. Install from nodejs.org or brew install node
An AI agent CLI on your machine: Claude Code, Gemini CLI, Codex CLI, or OpenCode. Pick whichever you already use; you can switch later
One-time CLI sign-in. After installing your CLI of choice, run it once from a terminal (claude, gemini, codex, or opencode auth login) and complete the authentication flow. Ideafy spawns the CLI as a non-interactive child process and cannot prompt for credentials, so the first login has to happen in your shell

Quick check: run git --version, npm --version, and your CLI's --version in a terminal before launching Ideafy. If any of them prints command not found, install the missing tool first — Ideafy will surface a clear error in-app, but it's faster to verify up front.

Which edition do I need?

Just exploring, working solo, or contributing to the OSS repo? → Public (free, open-source DMG on GitHub)
Small team sharing work through a pool? → Team (paid)

See Editions overview for the feature matrix.

Download & install

Download the .dmg for your edition (GitHub for Public, the purchase page for Team).
Open the DMG.
Drag Ideafy.app into Applications.
First launch: macOS Gatekeeper asks for confirmation. Right-click → Open the first time if the app isn't notarised yet.

The app opens to a blank projects list. You're in solo mode until you either create a project or sign in to a team.

What Ideafy writes to disk

When you launch for the first time, Ideafy creates:

~/Library/Application Support/ideafy/ — the SQLite database, conversation history, settings
~/Library/Application Support/ideafy/device-info.encrypted — device ID + name, encrypted via the macOS Keychain
Project-local files (only when you create a project in a folder):
- .worktrees/kanban/... — per-card git worktrees (only when you start work on a card)
- .claude/skills/ and .claude/settings.json — when you install the Ideafy MCP server and skills into that project (opt-in)

Nothing is uploaded anywhere in Public edition. The Team edition syncs pool-linked projects through Supabase once you sign in.

Uninstall

Drag Ideafy.app to the Trash
Delete ~/Library/Application Support/ideafy/ to remove local data
Per-project: delete .claude/skills/ and .claude/settings.json if you installed them

See Migrate between editions if you're switching editions rather than uninstalling.

Prev: Philosophy Next: Sign up & Authentication Up: User guide index