# Claude Code
Source: https://docs.shadowgit.com/ai-tools/claude-code

Give Claude Code perfect memory with ShadowGit

## Prerequisites

* Claude Code installed ([Get Claude Code](https://claude.ai/download))
* Node.js 18+ installed
* ShadowGit desktop app running with tracked repositories

## Quick Setup

Install and configure ShadowGit in one command:

```bash
# Install MCP server globally
npm install -g shadowgit-mcp-server

# Add to Claude Code
claude mcp add shadowgit -- shadowgit-mcp-server

# Restart Claude Code
```

That's it. Claude now has perfect memory of your code changes.

## Verify Installation

Ask Claude:

```
Can you list my ShadowGit repositories?
```

Claude should respond with your tracked repositories. If not, see troubleshooting below.

## What Claude can now do

### AI Session Awareness

ShadowGit now tracks your active coding sessions with Claude, automatically detecting when you're working together and preserving context across your development flow. This means Claude understands not just your code history, but also your current coding patterns and recent focus areas.

### Debug recent changes

```
Claude, what changed in my auth.ts file in the last hour?
```

### Find when bugs appeared

```
Claude, when did the login function last work correctly?
```

### Understand code evolution

```
Claude, show me how the payment processing evolved this week
```

### Compare implementations

```
Claude, what approach worked better - yesterday's or today's refactor?
```

## Example Commands

Ask Claude in natural language and it will use the right git commands:

**See recent commits:**

```
"Show me the last 20 commits in my-app"
"What did I commit today?"
```

**Check what broke:**

```
"What changed between now and 10 commits ago?"
"Show me the diff for the last hour"
```

**Find who changed a line:**

```
"Who last modified src/api.ts?"
"Show me the blame for the authentication file"
```

**See file history:**

```
"Show me the history of Header.tsx"
"What changes were made to the login component?"
```

## Session Management

Control how ShadowGit tracks your work with Claude:

**Start a session:**

```
"Start a ShadowGit session for this debugging task"
```

**Create checkpoints:**

```
"Create a ShadowGit checkpoint: Fixed authentication bug"
```

**End a session:**

```
"End the current ShadowGit session"
```

## Advanced Usage

### Working with multiple repositories

Claude can analyze across all your projects:

```
Claude, check if I've solved similar authentication issues in my other projects
```

### Time-based debugging

```
Claude, what was I working on yesterday between 2-4 PM?
```

### Pattern detection

```
Claude, do you see any patterns in when my tests fail?
```

## Troubleshooting

### Claude doesn't see ShadowGit

1. **Restart Claude Code** after adding the MCP server
2. **Check installation**:
   ```bash
   # Verify MCP server is installed
   npm list -g shadowgit-mcp-server

   # Test it works
   shadowgit-mcp-server --version
   ```

### "No repositories found"

1. Open ShadowGit desktop app
2. Add at least one repository
3. Wait for first snapshot (usually within 3 minutes)
4. Ask Claude again

### Permission errors

On macOS, you might need to grant Terminal permissions:

1. System Preferences → Security & Privacy
2. Privacy tab → Full Disk Access
3. Add Terminal or your terminal app

### Claude can't execute git commands

Make sure git is installed:

```bash
git --version
```

If not installed, [download Git](https://git-scm.com/downloads).

## Best Practices

### 1. Let ShadowGit run for a while

The more history ShadowGit captures, the smarter Claude becomes. Let it run for at least a day before expecting deep insights.

### 2. Be specific with time ranges

Instead of "recent changes", say "changes in the last 2 hours" or "changes from yesterday".

### 3. Use repository names

Always specify which repository when you have multiple:

```
Claude, in my 'frontend' repo, what changed in the last hour?
```

### 4. Combine with file context

Claude Code already reads your files. ShadowGit adds the history dimension:

```
Claude, looking at this error and my recent changes, what broke?
```

## Security

* **Read-only**: Claude can only read history, never modify code
* **Local only**: No code leaves your machine
* **Safe commands**: Only non-destructive git commands allowed

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation Guide" icon="download" href="/installation">
    General installation instructions
  </Card>

  <Card title="Cursor Setup" icon="code-simple" href="/ai-tools/cursor">
    Configure Cursor with ShadowGit
  </Card>
</CardGroup>


# Cursor
Source: https://docs.shadowgit.com/ai-tools/cursor

Configure Cursor to use ShadowGit for perfect AI memory

## Prerequisites

* Cursor installed ([Get Cursor](https://cursor.com))
* Node.js 18+ installed
* ShadowGit desktop app running with tracked repositories

## Quick Setup

1. **Install the MCP server**:
   ```bash
   npm install -g shadowgit-mcp-server
   ```

2. **Open Cursor Settings**:
   * Press `Cmd + Shift + P` (Mac) or `Ctrl + Shift + P` (Windows/Linux)
   * Search for `Cursor Settings` in the search bar
   * Click on `Tools and Integrations`
   * Under `MCP Tools`, click on `Add Custom MCP`

3. **Add ShadowGit configuration**:
   ```json
   {
     "mcpServers": {
       "shadowgit": {
         "command": "shadowgit-mcp-server"
       }
     }
   }
   ```

4. **Restart Cursor** to activate the MCP server

## Verify Installation

In Cursor's AI chat, type:

```
What ShadowGit repositories are available?
```

Cursor should list your tracked repositories. If not, see troubleshooting below.

## What Cursor can now do

### AI Session Intelligence

ShadowGit automatically tracks your coding sessions with Cursor, detecting when you're actively developing and maintaining context throughout your work. This gives Cursor deeper awareness of your coding patterns, recent changes, and development focus - making its suggestions more relevant and accurate.

### Instant debugging

```
Why is this function returning null? Check what changed in the last hour.
```

### Code archaeology

```
Find when this bug was introduced by checking the history of auth.ts
```

### Smart suggestions

```
Based on my recent changes, what's the best way to refactor this?
```

### Pattern recognition

```
Have I fixed similar issues before in this project?
```

## Using ShadowGit in Cursor

### In Chat (Cmd+K)

You can ask Cursor to analyze your code history:

```
@shadowgit show me recent changes to the login flow
```

```
@shadowgit when did the tests last pass?
```

```
@shadowgit what files changed together with api.ts?
```

### In Composer (Cmd+I)

When making larger changes, reference history:

```
Refactor this authentication flow. Check @shadowgit for what approaches 
I've tried before and avoid the patterns that didn't work.
```

### During debugging

Combine current code with history:

```
This error started appearing today. @shadowgit check what changed 
in the last 24 hours that could cause this.
```

## Advanced Configuration

### Custom installation path

If npm installed to a non-standard location:

```json
{
  "mcpServers": {
    "shadowgit": {
      "command": "/usr/local/bin/shadowgit-mcp-server"
    }
  }
}
```

### With environment variables

```json
{
  "mcpServers": {
    "shadowgit": {
      "command": "shadowgit-mcp-server",
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

## Example Workflows

### Morning debugging session

1. **Check overnight changes**:
   ```
   @shadowgit what changed since yesterday evening?
   ```

2. **Find breaking changes**:
   ```
   @shadowgit when did the tests last pass? Show me the diff.
   ```

3. **Quick fix**:
   ```
   Based on @shadowgit history, revert just the breaking change
   ```

### Code review preparation

```
@shadowgit summarize all changes to the auth module this week
```

### Learning from history

```
@shadowgit show me all the different ways I've implemented this feature
```

## Troubleshooting

### Cursor doesn't see ShadowGit

1. **Confirm installation**:
   ```bash
   which shadowgit-mcp-server
   ```

2. **Check Cursor logs**:
   * Help → Toggle Developer Tools
   * Check Console for MCP errors

3. **Restart Cursor completely**:
   * Quit Cursor (Cmd+Q / Alt+F4)
   * Start Cursor fresh

### "Command not found"

The MCP server isn't in PATH. Find it:

```bash
npm list -g shadowgit-mcp-server --depth=0
```

Use the full path in settings:

```json
"command": "/Users/you/.npm-global/bin/shadowgit-mcp-server"
```

### No repositories available

1. ShadowGit desktop app must be running
2. At least one repository must be tracked
3. Wait 3-5 minutes for first snapshots

### Permission denied

Grant Cursor full disk access (macOS):

1. System Preferences → Security & Privacy
2. Privacy → Full Disk Access
3. Add Cursor.app

## Best Practices

### 1. Context-aware queries

Instead of generic "show history", be specific:

```
@shadowgit show auth.ts changes that happened during failing tests
```

### 2. Time-box investigations

```
@shadowgit only show changes from the last 2 hours
```

### 3. Cross-file analysis

```
@shadowgit what other files usually change when I modify config.json?
```

### 4. Learn from patterns

```
@shadowgit how did I solve similar React rendering issues before?
```

## Security

* **Read-only access**: Can't modify your code or git history
* **Local processing**: Your code never leaves your machine
* **Safe operations**: Only non-destructive git commands allowed

## Tips & Tricks

### Quick history check

Create a Cursor shortcut for common queries:

* Settings → Keyboard Shortcuts
* Search for "AI Chat"
* Add custom binding for "@shadowgit log -10"

### Combine with Cursor's context

```
Looking at @file:src/api.ts and @shadowgit history, 
why might this endpoint be failing?
```

### Use for documentation

```
@shadowgit help me write docs by showing how this API evolved
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation Guide" icon="download" href="/installation">
    General setup instructions
  </Card>

  <Card title="Claude Code Setup" icon="asterisk" href="/ai-tools/claude-code">
    Configure Claude Code with ShadowGit
  </Card>
</CardGroup>


# Introduction
Source: https://docs.shadowgit.com/index

Give your AI perfect memory of your code changes

## What is ShadowGit?

ShadowGit saves every keystroke you type and feeds your complete code history to AI assistants like Claude and Cursor via MCP (Model Context Protocol).

Your AI stops guessing. It knows exactly what worked before.

<Card title="Quick Installation" icon="rocket" href="/installation" horizontal>
  Get up and running in 2 minutes with our MCP server.
</Card>

## How it works

ShadowGit runs quietly in the background, creating a parallel git repository (`.shadowgit.git`) that captures every save as a commit. The MCP server then gives your AI read-only access to this detailed history.

**New: AI Session Management** - ShadowGit automatically detects when you're working with AI tools and tracks your coding sessions, giving your AI assistant better context about your development patterns and recent changes.

```
your-project/
├── .git/              # Your normal git repo
├── .shadowgit.git/    # Automatic snapshot history (AI reads this)
├── src/
└── ...
```

## Why ShadowGit exists

<Columns cols={3}>
  <Card title="Fewer debug attempts" icon="clock">
    AI finds issues using history, not guessing. Fewer attempts to fix bugs.
  </Card>

  <Card title="Git commands not context dumps" icon="crosshairs">
    AI runs git diff instead of reading entire files. Saves thousands of tokens.
  </Card>

  <Card title="Zero lost code" icon="brain">
    Every change saved automatically. One-click restore from any moment.
  </Card>
</Columns>

## Real-world impact

* **Before**: Spend 15 minutes re-explaining your codebase to Claude
* **After**: Claude fixes the bug in 5 minutes using your code history

That's not marketing. That's math.

## Get started

<Columns cols={2}>
  <Card title="Install MCP Server" icon="download" href="/installation">
    Set up the MCP server for Claude and Cursor in 2 minutes.
  </Card>

  <Card title="Claude Code Setup" icon="asterisk" href="/ai-tools/claude-code">
    Configure Claude Code to use ShadowGit.
  </Card>

  <Card title="Cursor Setup" icon="code-simple" href="/ai-tools/cursor">
    Add ShadowGit to Cursor for perfect AI memory.
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/blade47/shadowgit-mcp">
    View source, report issues, or contribute to the MCP server.
  </Card>

  <Card title="Download ShadowGit" icon="desktop" href="https://shadowgit.com">
    Get the desktop app that captures your code changes.
  </Card>
</Columns>

## Security & Privacy

* **100% local**: Your code never leaves your machine
* **Read-only access**: AI can only read, never modify
* **No cloud uploads**: Everything stays on your computer

## Requirements

* Node.js 18 or higher
* ShadowGit desktop app (Mac, Windows, or Linux)
* An AI tool (Claude Code, Cursor, etc.)


# Installation
Source: https://docs.shadowgit.com/installation

Set up ShadowGit MCP server in 2 minutes

## Prerequisites

Before you begin, make sure you have:

1. **Node.js 18+** installed ([Download Node.js](https://nodejs.org))
2. **ShadowGit desktop app** running with at least one tracked repository ([Download ShadowGit](https://shadowgit.com))
   * Available for Mac, Windows, and Linux
3. **An AI tool** like Claude Code or Cursor

## Install the MCP Server

### Option 1: npm (Recommended)

Open your terminal and run:

```bash
npm install -g shadowgit-mcp-server
```

### Option 2: GitHub

Clone and install from the source:

```bash
# Clone the repository
git clone https://github.com/blade47/shadowgit-mcp.git
cd shadowgit-mcp

# Install dependencies and build
npm install
npm run build

# Install globally
npm install -g .
```

That's it. The MCP server is now installed globally on your system.

## Configure your AI tool

Once the MCP server is installed, you need to configure your AI assistant to use it. We have detailed guides for each tool:

<CardGroup cols={2}>
  <Card title="Claude Code" icon="asterisk" href="/ai-tools/claude-code">
    One-command setup for Claude Code
  </Card>

  <Card title="Cursor" icon="code-simple" href="/ai-tools/cursor">
    Complete Cursor configuration guide
  </Card>
</CardGroup>

## What your AI can now do

Once configured, your AI assistant can use natural language to query your code history:

### Basic Commands

**List repositories:**

```
"Show me my ShadowGit repositories"
"List all tracked projects"
```

**View recent changes:**

```
"Show me the last 10 commits in my-project"
"What changed in my-project in the last hour?"
"Show me the diff between HEAD and 5 commits ago"
```

**Debug with history:**

```
"When did the login feature break?"
"Show me all changes to authentication.js today"
"What files were modified in the last 30 minutes?"
```

### Session Management (New!)

**Control auto-commits:**

```
"Start a ShadowGit session for debugging"
"Create a checkpoint with message 'Fixed auth bug'"
"End the current ShadowGit session"
```

Your AI will automatically use git commands like `log`, `diff`, `show`, and `blame` to answer your questions efficiently.

## Troubleshooting

### "No repositories found"

Your ShadowGit app needs to be tracking at least one repository.

1. Open ShadowGit desktop app
2. Click the "+" button to add a repository
3. Wait for the first snapshot to be created
4. Try again in your AI tool

### "Command not found: shadowgit-mcp-server"

The npm installation might not be in your PATH.

**Solution 1**: Use the full path

```bash
# Find where npm installed it
npm list -g shadowgit-mcp-server

# Use the full path in your config
"command": "/usr/local/bin/shadowgit-mcp-server"
```

**Solution 2**: Reinstall with npx

```bash
npx shadowgit-mcp-server
```

### "Repository not found"

Make sure you're using the exact repository name from ShadowGit.

First ask your AI to list repositories:

```
"List my ShadowGit repositories"
```

This will show you the exact names to use. Then use the exact name when querying:

```
"Show me the git log for my-project"
```

The repository name must match exactly what ShadowGit shows.

### Claude/Cursor doesn't see the MCP server

1. Make sure you restarted the application after adding the config
2. Check that Node.js is in your PATH: `node --version`
3. Verify the server works manually: `shadowgit-mcp-server --version`

### Linux-specific notes

#### Installing ShadowGit on Linux

ShadowGit is distributed as an AppImage for Linux, which works on all distributions.

**Prerequisites for AppImage:**

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install libfuse2

# Fedora
sudo dnf install fuse fuse-libs

# Arch
sudo pacman -S fuse2
```

**Running the AppImage:**

```bash
# Download the AppImage (choose your architecture)
# For Intel/AMD systems: ShadowGit-linux-x86_64-*.AppImage
# For ARM systems: ShadowGit-linux-arm64-*.AppImage

# Make it executable
chmod +x ShadowGit-linux-*.AppImage

# Run ShadowGit
./ShadowGit-linux-*.AppImage
```

**Alternative if FUSE is not available:**

```bash
# Extract the AppImage
./ShadowGit-linux-*.AppImage --appimage-extract

# Run from extracted directory
./squashfs-root/AppRun
```

#### Data Locations on Linux

ShadowGit stores its data in the following locations:

* **Shadow repositories**: `~/.shadowgit/`
* **Application config**: `~/.config/ShadowGit/`
* **Logs**: `~/.config/ShadowGit/logs/`
* **Settings**: `~/.config/ShadowGit/config.json`

Make sure you have proper read/write permissions for these directories.

## Security Notes

* **Read-only access**: The MCP server can only read your git history, never modify it
* **Local only**: No data is sent to any external servers
* **Safe commands only**: Dangerous git commands are blocked (no push, merge, rebase)

## Next Steps

Choose your AI tool to get started:

<CardGroup cols={2}>
  <Card title="Claude Code Guide" icon="asterisk" href="/ai-tools/claude-code">
    Detailed setup and usage with Claude Code
  </Card>

  <Card title="Cursor Guide" icon="code-simple" href="/ai-tools/cursor">
    Complete Cursor configuration and tips
  </Card>
</CardGroup>