Local vs Cloud Contexts

What are local and cloud contexts?

Local contexts live in .git/gitwhy/contexts/ inside your repository. They’re created when you or your agent saves reasoning with git why save. Local contexts are private, offline, and instant — no account needed. GitWhy can also read WhySpec change context from gitwhy/changes/ inside the repo root. That compatibility path is read-only from GitWhy’s perspective; git why save still writes native GitWhy context into .git/gitwhy/contexts/. Legacy .gitwhy/changes/ remains supported as a fallback while older repos migrate. Cloud contexts are local contexts that have been synced to app.gitwhy.dev. Once in the cloud, they can be shared with your team, posted as PR comments, accessed from any machine, and backed up safely.

GitWhy is local-first. Everything starts on your machine. Cloud is an optional upgrade that adds collaboration and backup — it never changes the local workflow.

When to use cloud

Use case	Why cloud helps
Team collaboration	Share reasoning across the team — no more “why was this built this way?”
PR comments	gitwhy-bot posts structured context directly on pull requests
Multi-machine sync	Access your contexts from any machine via the dashboard
Backup	Contexts are safely stored even if the local repo is deleted

Commands: local vs cloud

CLI commands
MCP tools

Works locally (no auth)	Requires cloud auth
`git why save`	`git why push`
`git why get <id>`	`git why push --share`
`git why log`	`git why post-pr`
`git why tree`
`git why search <query>`
`git why setup` (partial)

See the CLI Reference for full command documentation and flags.

Works locally (no auth)	Requires cloud auth
`gitwhy_save()`	`gitwhy_sync()`
`gitwhy_get()`	`gitwhy_publish()`
`gitwhy_search()`	`gitwhy_post_pr()`
`gitwhy_list()`
`gitwhy_status()`

See the MCP Server page for setup instructions and tool reference.

Accessing your contexts

CLI
TUI
Web Dashboard
MCP

Use CLI commands for non-interactive, pipe-friendly output:

git why log              # list all contexts
git why get ctx_a1b2c3d4 # retrieve by ID
git why tree             # show domain/topic tree
git why search "JWT"     # search by keyword

Output goes to stdout — pipe it, redirect it, or script around it. See the CLI Reference for all commands.

When run in a terminal (TTY), git why log, tree, and search auto-open an interactive TUI with navigation, search, and detail view.

Browse all saved contexts with their linked commits, agents, and domains.

TUI tree view showing domain and topic hierarchy

Navigate contexts organized by domain and topic across branches.

Search across all contexts by keyword — results show commit links, domains, and agents.Learn more about the Terminal UI.

Your agent retrieves contexts without leaving the conversation:

You: "What contexts do we have for authentication?"

Agent: [calls gitwhy_list(domain="authentication")]
GitWhy: [returns domain/topic tree with context summaries]

You: "Search for JWT decisions."

Agent: [calls gitwhy_search(query="JWT")]
GitWhy: [returns matching contexts]

You: "Get context ctx_a1b2c3d4."

Agent: [calls gitwhy_get(id="ctx_a1b2c3d4")]
GitWhy: [returns full structured markdown]

See the MCP Server page for setup and all eight tools.

Sync to cloud

Authenticate

git why setup

Opens your browser for authentication. Your API key is stored globally.

Push to cloud

git why push <context-id>

Syncs saved contexts to GitWhy cloud (private by default).

Share with team

git why push <context-id> --share

Publishes contexts so your team can see them on the dashboard.

See the CLI reference for all flags and options.

Authenticate

Authentication is handled during git why setup. Once complete, MCP tools automatically use your credentials.

Sync to cloud

Agent: [calls gitwhy_sync()]
GitWhy: [contexts uploaded privately]

Share with team

Agent: [calls gitwhy_publish(ids='["ctx_a1b2c3d4"]')]
GitWhy: [contexts shared with team]

Next steps

Team Sync

Share and discover context across your team.

PR Comments

Post context summaries on pull requests.

Web Dashboard

Browse contexts at app.gitwhy.dev.

TUI

Interactive terminal interface for browsing contexts.

Getting Started

Core Features

Sharing & Collaboration

Interfaces

Integration Guide

CLI Reference

Context Format

Plans & Pricing

Local vs Cloud Contexts

What are local and cloud contexts?

When to use cloud

Commands: local vs cloud

Accessing your contexts

Sync to cloud

Next steps

Team Sync

PR Comments

Web Dashboard

TUI

​What are local and cloud contexts?

​When to use cloud

​Commands: local vs cloud

​Accessing your contexts

​Sync to cloud

​Next steps

Team Sync

PR Comments

Web Dashboard

TUI

What are local and cloud contexts?

When to use cloud

Commands: local vs cloud

Accessing your contexts

Sync to cloud

Next steps