Frequently asked questions
What platforms does Genesis support?
Linux, macOS, Windows (via WSL), and native Windows. Genesis automatically detects the operating system during initial configuration. Linux and macOS offer optimal performance, WSL is fully supported, and native Windows works but may require installing Unix utilities through Scoop or Chocolatey.
Can I use Genesis on native Windows?
Yes, but WSL is recommended. Native Windows with PowerShell requires manual installation of tools like make, grep, and sed via Scoop or Chocolatey. Paths use backslashes, which can affect shell scripts. The default project location becomes %USERPROFILE%\claude\<name>\. Configure git config --global core.autocrlf true for line endings.
How do I change the locale?
Edit personalisation.md in ~/claude/genesis/ and adjust the Locale field under Language and Locale settings. Changes take effect in the next Claude session and apply to all subsequent projects. Existing projects keep their original locale in their own CLAUDE.md.
Do Genesis updates affect my existing projects?
No. Each generated project is completely independent with its own configuration files written at generation time. Updating Genesis only changes templates for future projects.
Can I add custom agents and skills?
Yes. See the Customisation guide for details on adding entries to the agent catalogue, creating templates, and adding stack profiles. Contributions back to the project are welcome.
How do I validate a generated project?
The /validate skill checks Claude infrastructure completeness: CLAUDE.md, settings.json, agents, skills, memory files, and MCP configuration.
cd ~/claude/genesis
claude
/validate ~/claude/<project-name>Can I use Genesis with an existing project?
Genesis is designed for new projects only. Existing directories trigger a refusal to prevent accidental overwrites. For existing codebases, generate a temporary project matching the desired stack and manually transfer relevant files (CLAUDE.md, agents, skills, settings.json).
How many agents should a project have?
Domain agents are limited to 3–4 per project to prevent workspace saturation. Three workflow agents are always included, giving you typically 6–7 total agents. You can add more manually after generation.
How does Genesis handle different Claude plans?
Genesis detects your plan tier during setup and assigns a scaffold profile:
- Pro: Lean scaffolding (~5–8k tokens, 2.5–4% of 200k context) with 1–2 domain agents
- Max: Standard scaffolding (~10–15k tokens, 5–7.5% of 200k context) with 2–3 domain agents
- ProMax: Full scaffolding (~15–25k tokens, 1.5–2.5% of 1M context) with 3–4 domain agents
- API: User specifies context budget during setup
See Plans and Context for the full comparison.
Can I change my scaffold profile?
Yes. Edit environment.md in the Genesis root, change the Scaffold profile value under Claude Plan to lean, standard, or full. Changes affect new projects only.
Which plan is best?
Genesis works on all plans that support Claude Code (Pro and above). Pro offers full functionality with lean scaffolding. Max provides solid infrastructure with higher rate limits. ProMax delivers the best experience with 1M context, comprehensive infrastructure, and extended sessions without compaction.
What happens when context runs out?
Claude Code automatically compacts conversations when the context window fills. You can run /compact manually. All generated projects include a statusline showing context usage percentage.
Does the scaffold profile affect coding quality?
No. The scaffold profile only controls how much Claude Code infrastructure is generated. A lean project has identical coding standards and quality rules to a full project; the difference is specialised agent and skill availability.
Can I change the default project location?
Yes. Edit the Project base value under Paths in environment.md. The default is ~/claude/. Change it to ~/projects/ (or wherever you prefer) and all new projects will be created there.
What is the risk evaluator?
A cross-cutting agent that evaluates potentially dangerous operations before they execute. It covers databases, external APIs, cloud services, message queues, and infrastructure. Severity 1–2 (read-only, local edits) proceeds automatically. Severity 3 (migrations, staging writes) warns you. Severity 4–5 (DROP TABLE, production writes) halts and demands confirmation.
Can I disable the risk evaluator?
Remove risk-evaluator.md from .claude/agents/ and the PreToolUse hook from .claude/settings.json. It's a safety mechanism, not a requirement.
Does Genesis support monorepos?
Genesis generates single-project scaffolds. For monorepos, generate each package separately then restructure, or describe your monorepo layout during the interview for Genesis to accommodate.
Common errors
"command not found: claude"
The CLI isn't installed or isn't on PATH. Install with npm install -g @anthropic-ai/claude-code and verify with npm config get prefix that the npm global bin directory is on your PATH.
"Target directory already exists"
Genesis only creates new projects. Pick a different name or remove the existing directory: rm -rf ~/claude/<name>.
"git: not a git repository"
You're not in the Genesis directory. Navigate to ~/claude/genesis/ before starting Claude.
MCP server connection failures
MCP servers need the underlying services running. PostgreSQL MCP servers need an active PostgreSQL instance. docker compose up -d is the simplest approach.
"Permission denied" on tool execution
Claude Code needs explicit Bash permissions in .claude/settings.json. Python projects need entries like "Bash(python:*)", "Bash(pip:*)", "Bash(pytest:*)", "Bash(ruff:*)".
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.mdFormatter hook fires constantly
The PostToolUse hook runs stack formatters on every matching file edit. This is intentional. Adjust via the hook configuration in .claude/settings.json in generated projects.
"No such file or directory" for memory files
Memory files live at ~/.claude/projects/-home-xeeva-claude-<name>/memory/. If they're missing, regenerate the project or manually create the directory and files using the templates in .claude/skills/genesis/templates/.