On this page
Interactive Setup Wizard
The setup wizard configures KeepGoing for your specific toolchain. This page explains what each step does and why - so you can make informed choices rather than just clicking through.
Overview
Run the wizard once per device. It saves a profile to ~/.keepgoing/setup-profile.json so you can replay the same configuration on new projects with keepgoing init.
curl -fsSL https://keepgoing.dev/install.sh | bash
The installer runs keepgoing setup automatically. You can re-run it anytime.
Scope: project vs. user (global)
Why this step exists
KeepGoing hooks live inside Claude Code settings files. Project scope writes to .claude/settings.local.json (gitignored, scoped to this repo). User scope writes to ~/.claude/settings.json (applies to every project you open). The wizard defaults to project scope if you are inside a git repo. Choose user scope only if you want KG active in every project without running setup per-repo.
If hooks exist at both scopes, they will both fire - creating duplicate entries. The wizard detects this and offers to clean up the other scope.
This project only
.claude/settings.local.json - quiet, gitignored, scoped
All projects (global)
~/.claude/settings.json - one setup covers every repo
AI tools
Why this step exists
Each AI tool needs a different MCP registration method. Claude Code uses `claude mcp add`. Cursor and Windsurf use a global JSON file at ~/.cursor/mcp.json or ~/.windsurf/mcp.json. Copilot uses a .copilot/mcp.json in your project. KG only touches the config for tools you select - it won't modify settings for tools you don't use.
Claude Code
Registers MCP via `claude mcp add keepgoing`
GitHub Copilot
Writes .copilot/mcp.json in your project
Cursor
Writes to ~/.cursor/mcp.json
Windsurf
Writes to ~/.windsurf/mcp.json
Claude Code: plugin vs. manual
Why this step exists
If you selected Claude Code, you choose how to set it up. Plugin mode installs the KeepGoing Claude plugin - this bundles hooks, skills (like /keepgoing:reentry), and MCP config into a single `claude plugin install` command. Manual mode only registers the MCP server and lets you wire hooks yourself. Plugin mode is recommended unless you already have custom hook configuration you want to preserve.
Plugin (recommended)
auto-hooks, skills, one command
Manual
MCP server only, you manage hooks
IDE
Why this step exists
The VS Code extension and JetBrains plugin do passive context capture. They watch which files you edit and how long your sessions run, writing this data to the local SQLite database automatically. This means even when you are coding without Claude, KG is building a picture of your session. Cursor and Windsurf users already have IDE coverage built in, so this step is optional for them.
VS Code
installs keepgoing-dev.keepgoing extension
JetBrains
installs plugin for IntelliJ, WebStorm, PyCharm, etc.
Terminal only
skip IDE extensions
Hooks
Why this step exists
KeepGoing works without hooks, but they fill in gaps that the MCP server and extension can't. All three are opt-in.
Shell hook
modifies ~/.zshrc / ~/.bashrc / fish config
Fires when you cd into a project that has a .keepgoing/ folder. Prints your last checkpoint summary - a 1-second re-entry brief without opening anything.
Git hooks
installs ~/.keepgoing/hooks/ via core.hooksPath
Runs in the background after every git commit. Detects high-signal commits that indicate an architectural or design decision (Pro feature). Also fires on branch switches and merges to create automatic checkpoints.
Global gitignore
modifies ~/.gitignore_global
Adds .keepgoing to your global gitignore so the data folder never appears as untracked in any repository. Without this, every repo will show .keepgoing/ in git status.
Desktop tray (macOS)
Why this step exists
The desktop tray app sits in your menu bar and shows a live view of all your registered projects - last checkpoint, current session, and momentum score. It connects to the kgd daemon process via a Unix socket, so updates appear in real time as you work. It is optional: everything else works without it. Install it if you want project momentum visible without opening a terminal.
Install via Homebrew
brew tap keepgoing-dev/tap && brew install --cask keepgoing
Skip
install anytime later
License key
Why this step exists
Pro features (Decision Detection and Session Awareness) require a license key. This step is optional during setup - you can skip it and activate later with `keepgoing activate <key>`. License activation calls the Lemon Squeezy API to validate and stores the result in ~/.keepgoing/license.json.
Enter key now
activates Decision Detection or Session Awareness
Skip
run `keepgoing activate <key>` anytime
Running setup again
Run keepgoing setup anytime to update your configuration. The wizard detects your current state and shows what is already installed. To apply your saved profile to a new project without prompts, use:
keepgoing init keepgoing init replays your saved setup profile for the current directory. Useful when cloning a project on a new machine or adding KeepGoing to a new repo.