Install and connect

Install the extensionCopy Anchor Link

In VS Code the extension is named GitDB, and its identifier is keyes-ai.gitdb-vscode. To install it from its .vsix package file:

1. Open the Command Palette with Ctrl+Shift+P (Cmd+Shift+P on macOS).
2. Run Extensions: Install from VSIX… and select the .vsix file.

When the install finishes, a GitDB icon appears in the activity bar and the status bar shows GitDB: Not connected.

Connect for the first timeCopy Anchor Link

1. Start the connection in one of these ways:
   • Click GitDB: Not connected in the status bar.
   • Open the GitDB view in the activity bar and click Connect to GitDB.
   • Run GitDB: Connect from the Command Palette.
2. Your browser opens gitdb.co. If you're not signed in, sign in first. The authorization page comes back after you sign in.
3. Click Authorize VS Code. This lets VS Code access your repositories on your behalf.
4. Your browser sends you back to VS Code. If your browser or VS Code asks for permission to open the link, allow it.
5. A list titled Select a GitDB repository opens. It shows each repository as organization/name along with its description. Type to filter the list, then pick a repository.

When the connection is ready, you'll see GitDB: Connected to organization/name @ branch | MCP: running. The status bar shows the repository and branch, and the Files, Refs, History, and Repos views appear under the GitDB icon.

Things to know about connectingCopy Anchor Link

• Finish within 5 minutes. If you don't, VS Code shows GitDB sign-in timed out. Please try connecting again. Run GitDB: Connect again.
• Verify your email first. Authorization fails with a request to verify your email if your gitdb.co email address hasn't been verified. See Create an account.
• The picker shows up to 20 repositories. These are the 20 most recently updated repositories you can access. If yours isn't listed, connect to any repository first. Then use Search Repos… in the Repos view to find it, as described in Switch repositories.
• You need a repository first. If your account has no repositories, the extension asks you to create one on gitdb.co first. See Create your first repository.
• You start on the default branch. The extension opens the repository's default branch. If that branch can't be found, it uses main or master. If neither exists, it opens the first branch it finds and warns: no default branch (main/master) is set. Set a default branch in the repository's settings on gitdb.co to fix this.

Signing in laterCopy Anchor Link

VS Code keeps your sign-in in its secure storage, so later connections skip the browser and go straight to the repository list. If your saved sign-in is no longer valid, GitDB: Connect opens the browser sign-in again.

Automatic connection when VS Code startsCopy Anchor Link

After your first connection, VS Code reconnects to the same repository every time it starts, as long as you're still signed in. It always opens the repository's default branch, not the branch you were on last time.

If the automatic connection fails, you'll see GitDB: could not connect to "organization/name" and the repository list opens so you can pick again. If the repository has been deleted on gitdb.co, the extension drops it and shows the list without an error.

The extension saves the repository in your User settings as gitdb.defaultRepo. To stop connecting automatically, clear that setting. Connecting to a repository sets it again.

Switch repositoriesCopy Anchor Link

You can switch to another repository in any of these ways:

• In the Repos view, right-click a repository and choose GitDB: Switch to This Repo.
• In the Repos view, click the search icon (GitDB: Search Repos…) and type part of a name. It searches every repository you can access, matching names and descriptions, and shows up to 20 matches. Pick one to switch to it.
• Run GitDB: Connect again and pick from the list.

Switching reconnects the extension to the new repository, on its default branch. VS Code will also reconnect to that repository the next time it starts. Your drafts in the previous repository stay saved on GitDB and come back when you connect to it again. The extension's MCP server restarts for the new repository, so if you use an AI agent, copy its configuration again (see MCP server for AI agents).

To switch branches instead, see Views and search.

DisconnectCopy Anchor Link

Run GitDB: Disconnect to end the connection:

• The GitDB views close and the status bar shows GitDB: Not connected.
• The MCP server the extension runs for you stops.
• Your drafts stay saved on GitDB.

Disconnect doesn't sign you out, and it doesn't turn off automatic connection. The next time VS Code starts, it reconnects to the same repository. To prevent that, clear gitdb.defaultRepo as described above.

Version 0.1.5 has no sign-out command. Your sign-in stays in VS Code's secure storage after you disconnect.

Disconnecting also doesn't affect an AI agent that's using a copied MCP configuration. That configuration keeps working until its access token expires (see MCP server for AI agents).

Troubleshooting sign-inCopy Anchor Link

For more detail, turn on the gitdb.trace setting in your User settings. The extension then writes connection diagnostics to the GitDB Auth output channel (View › Output). Tokens, codes, and URLs are never logged.