Your project context, right in the terminal

The KeepGoing CLI lets you check momentum, browse session history, get re-entry briefings, save checkpoints, and install a shell hook that shows your context every time you enter a project directory.

Running keepgoing briefing in your project:

Terminal

KeepGoing · Re-entry Briefing

Last seen: 12 days ago on feature/auth-refactor

Summary: Refactored auth middleware to support JWT rotation

Next step: Implement verifyRefreshToken helper in auth.ts

Files: auth.ts, middleware.ts, routes/token.ts (+2 more)

Install

One-line install (recommended):

Terminal

curl -fsSL https://keepgoing.dev/install.sh | bash

Or install with npm directly:

Terminal

npm install -g @keepgoingdev/cli

Commands

`keepgoing init`

Set up KeepGoing hooks and CLAUDE.md in the current project. Configures your project so AI tools and the shell hook can find your checkpoints.

Flag	Description
`--scope <s>`	Scope: "project" (default) or "user" (global)

`keepgoing status`

Show the last checkpoint for the current project. Prints the summary, next step, branch, and files touched.

Flag	Description
`--cwd <path>`	Override the working directory
`--json`	Output raw JSON of the last checkpoint, useful for scripting
`--quiet`	Output a single summary line (used by the shell hook)

`keepgoing momentum`

Show your current developer momentum: last checkpoint with branch-change detection, worktree awareness, and derived focus.

Flag	Description
`--json`	Output raw JSON
`--quiet`	Suppress output

`keepgoing briefing`

Get a re-entry briefing for this project. Summarizes session history and recent commits to help you pick up where you left off.

Flag	Description
`--json`	Output raw JSON
`--quiet`	Suppress output

`keepgoing log`

Browse session checkpoints with rich filtering. Search by date, branch, file, keyword, or view grouped by session.

Flag	Description
`-n <count>`	Number of entries to show (default: 10)
`--since <date>`	Show entries after date (ISO, "today", "yesterday", "N days ago")
`--until <date>`	Show entries before date
`--branch <name>`	Filter by branch ("all" for all branches)
`--follow <file>`	Filter by touched file path
`--search <term>`	Search in summary, next step, blocker
`--oneline`	Compact one-line format
`--stat`	Show touched file paths
`--sessions`	Group checkpoints by session
`--today`	Shorthand for --since today
`--week`	Shorthand for --since "last week"

`keepgoing save`

Save a checkpoint. Auto-generates a summary and next step from recent git activity. Use -m or -n to override with custom text.

Flag	Description
`-m, --message <text>`	Use a custom summary instead of auto-generating
`-n, --next <text>`	Use a custom next step instead of auto-generating
`--force`	Save even if a recent checkpoint exists or there are no changes

`keepgoing query`

Read stored checkpoint data directly from the SQLite database. Useful for scripting and building custom tooling on top of KeepGoing data.

Flag	Description
`<subcommand>`	One of: checkpoints, session-logs, momentum, signals, decisions, meta
`--limit <n>`	Number of entries to return (default: 10)
`--branch <name>`	Filter by branch
`--session <id>`	Filter by session ID
`--since <date>`	Show entries after date (ISO format)
`--cwd <path>`	Override the working directory

`keepgoing write`

Write activity signals, session logs, checkpoints, or decision records to the SQLite database. Primarily used by integrations and hooks, not for manual use.

Flag	Description
`<subcommand>`	One of: signal, log, checkpoint, decision
`--session <id>`	Session ID (required for signal, log, checkpoint)
`--branch <name>`	Current branch
`--trigger <type>`	Trigger type for logs: manual or auto
`--summary <text>`	Summary text (required for log)
`--next <text>`	Next step text
`--blocker <text>`	Blocker description
`--files <json>`	JSON array of touched file paths
`--commits <json>`	JSON array of commit hashes
`--data <json>`	Decision JSON data (required for decision subcommand)
`--cwd <path>`	Override the working directory

`keepgoing doctor`

Check storage health for the current project. Verifies the database exists, validates the schema version, detects orphaned sessions, and runs an integrity check.

Flag	Description
`--json`	Output results as JSON
`--cwd <path>`	Override the working directory

`keepgoing migrate`

Migrate legacy JSON storage to the SQLite database. Converts sessions.json and decisions.json to keepgoing.db and moves the old files to .keepgoing/deprecated/.

Flag	Description
`--json`	Output migration results as JSON
`--cwd <path>`	Override the working directory

`keepgoing decisions`

View decision history for this project. Shows high-signal architectural and design decisions detected from commits (free users see count; Pro to view full details).

Flag	Description
`--branch <name>`	Filter by branch, or "all" for all branches
`--limit <n>`	Number of decisions to show (default: 10)

`keepgoing refine`

Refine detected decisions using LLM classification. Processes pending decisions and unscored session logs for improved accuracy. Uses your Anthropic API key if configured, otherwise falls back to Claude CLI (Pro feature).

Flag	Description
`--dry-run`	Show what would be sent without calling the LLM
`--limit <n>`	Maximum items to process per run
`--provider <name>`	LLM provider to use (default: auto-detect)
`--enable`	Enable auto-refinement after every decision detection
`--disable`	Disable auto-refinement
`--status`	Show current auto-refinement status and provider

`keepgoing setup`

Interactive setup wizard. Walks you through configuring KeepGoing for your AI tools, IDE, and shell. Configures Claude Code, GitHub Copilot, Cursor, and/or Windsurf in one go.

Flag	Description
`[preset]`	Start with a tool pre-selected: claude, copilot, cursor, windsurf, vscode

`keepgoing config`

Manage global KeepGoing configuration. Currently used to store your Anthropic API key for LLM refinement so you do not need Claude CLI installed.

Flag	Description
`set api-key <key>`	Store an Anthropic API key in global config
`get api-key`	Show the stored API key (masked)
`unset api-key`	Remove the stored API key

`keepgoing hook install`

Install hooks for shell integration, global gitignore, and decision detection. Sets up a shell cd hook, a global gitignore entry for .keepgoing, and a global git post-commit hook for decision detection. Supports zsh, bash, and fish.

Flag	Description
`--shell <name>`	Override shell detection (zsh, bash, fish)

`keepgoing hook uninstall`

Remove the shell hook from your ~/.zshrc, ~/.bashrc, or fish config.

Flag	Description
`--shell <name>`	Override shell detection (zsh, bash, fish)

`keepgoing --version`

Show the installed CLI version and check for updates.

Hooks

Running keepgoing hook install sets up three things at once.

Step 1: Install hooks

Terminal

keepgoing hook install

Step 2: Reload your shell

Terminal

source ~/.zshrc   # or ~/.bashrc or ~/.config/fish/config.fish

Install output:

Terminal

KeepGoing hook installed in ~/.zshrc.

Global gitignore: .keepgoing added to ~/.gitignore_global

Git post-commit hook: installed at ~/.keepgoing/hooks/post-commit

1. Shell cd hook

Every time you cd into a directory with a .keepgoing/ folder, your last checkpoint is printed automatically.

Terminal

~ cd ~/projects/my-app

KeepGoing · 3 days ago · Refactored auth middleware to support JWT rotation

2. Global gitignore

Adds .keepgoing to your global gitignore (~/.gitignore_global) so session data never shows up in git status for any repository. No per-repo .gitignore edits needed.

3. Global post-commit hook

Installs a git post-commit hook at ~/.keepgoing/hooks/post-commit that runs decision detection in the background after every commit. This is how Decision Detection works without VS Code open.

The hook runs silently, never blocks your commit, and only writes to .keepgoing/decisions.json when a high-signal commit is detected. Requires a Decision Detection license. Without one, the hook exits immediately with no overhead.

Note: If your system already has core.hooksPath configured (e.g. for Husky or lint-staged), the hook file is saved but not activated automatically. The install output will show the snippet to add to your existing post-commit hook.

For a full breakdown of each hook and what it modifies, see the Git Hooks Setup page.

How it works

The CLI reads and writes the same .keepgoing/ schema used by the VS Code extension. You can use the CLI standalone or alongside the extension.

Checkpoint data is stored in a local SQLite database in your project directory. Nothing is sent to the cloud. If you have legacy JSON data from an older version, run keepgoing migrate to import it.

.keepgoing/keepgoing.db - all checkpoint, signal, and decision data
.keepgoing/state.json - last session state
.keepgoing/meta.json - project metadata

Pair with your AI tools

The CLI writes checkpoints that AI tools can read via the MCP server.

Claude Code

AI assistant that knows your project momentum

GitHub Copilot

Context-aware coding companion in your editor

Get started

Run your first status check in seconds.