Setup Guide | Genesis

This guide walks you through installing Genesis, running first-time setup, and creating your first project.

Prerequisites

Claude Code CLI (v1.x+)

npm install -g @anthropic-ai/claude-code

You'll need an Anthropic API key or a Claude Pro/Team subscription with Claude Code access.

git (v2.x+)

Platform	Command
Debian / Ubuntu	`sudo apt install git`
Fedora	`sudo dnf install git`
Arch	`sudo pacman -S git`
macOS	`brew install git`
Windows (Scoop)	`scoop install git`
Windows (Choco)	`choco install git`

Node.js (v18+)

Install via nvm (recommended) or from the official installer.

Supported shells

Genesis works with bash, zsh, and PowerShell.

Clone the repository

Linux / macOS / WSL

git clone https://github.com/xeeva/Genesis.git ~/claude/genesis

Windows (PowerShell)

git clone https://github.com/xeeva/Genesis.git $env:USERPROFILE\claude\genesis

The conventional path is ~/claude/genesis/. Genesis expects to live here by default.

First-time setup

Launch Claude from the Genesis directory:

cd ~/claude/genesis && claude

Genesis detects that it hasn't been configured and runs first-time setup automatically.

Step 1: Environment detection

Genesis detects your operating system, shell, package manager, and Claude plan. Your plan determines the scaffold profile:

Plan	Profile	Context
Pro	Lean	200k
Max	Standard	200k
ProMax	Full	1M
API	Ask	Varies

ProMax provides the best Genesis experience. The 1M context window means comprehensive infrastructure with minimal overhead.

Step 2: Personalisation

Default settings: Australian English locale, no em dashes, terse output, mandatory testing. You can change these in personalisation.md at any time.

Step 3: Prerequisite check

Genesis verifies that claude, git, and node are available and provides platform-tailored installation guidance for anything missing.

Your first project

After setup completes, describe a project:

"Create a Python FastAPI service called widget-api with PostgreSQL and Redis"

Phase 1: Interview

Genesis extracts the project name, purpose, tech stack, and key integrations from your message. Detailed messages get 1–2 follow-up questions; vague ones get up to 4.

Phase 2: Plan

You'll see a structured plan showing the project name, path, tech stack, agents, skills, MCP servers, and folder structure. You can request adjustments before confirming.

Phase 3: Generate

The entire project is created in a single pass. Infrastructure files, memory files, application boilerplate, docs, and configuration.

Phase 4: Summary

Genesis confirms creation with a component summary and next steps. Navigate to the project directory and start coding.

Troubleshooting

"command not found: claude"

The Claude Code CLI isn't installed or isn't on your PATH. Run npm install -g @anthropic-ai/claude-code and verify with which claude. If using nvm, ensure your npm global bin is on your PATH.

"Target directory already exists"

Genesis only creates greenfield projects. Pick a different name or remove the existing directory with rm -rf ~/claude/<name>.

Setup runs every time

Genesis checks for personalisation.md and environment.md on launch. Verify both exist:

ls ~/claude/genesis/personalisation.md ~/claude/genesis/environment.md

MCP server connection failures

MCP servers need the underlying services running. If you configured a PostgreSQL MCP server, you need a PostgreSQL instance. docker compose up -d is the simplest approach for local development.

Windows-specific issues

WSL is the recommended environment for Windows. If using native Windows, configure line endings (git config --global core.autocrlf true) and keep projects on the local filesystem rather than network drives.