# 4.2 App Takeover

## Overview

App takeover means letting CC Switch's proxy intercept and forward a specific application's API requests.

When takeover is enabled:
- The app's API requests are forwarded through the local proxy
- Request logs and usage statistics can be recorded
- Failover functionality becomes available

## Prerequisites

The proxy service must be started before using the app takeover feature.

## Enable Takeover

### Location

Settings > Advanced > Proxy Service > App Takeover area

### Steps

1. Ensure the proxy service is started
2. Find the "App Takeover" area
3. Enable the toggle for the desired apps

### Takeover Toggles

| Toggle | Effect |
|--------|--------|
| Claude Takeover | Intercept Claude Code requests |
| Codex Takeover | Intercept Codex requests |
| Gemini Takeover | Intercept Gemini CLI requests |

Multiple app takeovers can be enabled simultaneously.

## How Takeover Works

### Configuration Changes

When takeover is enabled, CC Switch modifies the app's configuration file to point the API endpoint to the local proxy.

**Claude configuration change**:

```json
// Before takeover
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}

// After takeover
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
  }
}
```

**Codex configuration change**:

```toml
# Before takeover
base_url = "https://api.openai.com/v1"

# After takeover
base_url = "http://127.0.0.1:15721/v1"
```

**Gemini configuration change**:

```bash
# Before takeover
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com

# After takeover
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
```

### Request Forwarding

When the proxy receives a request:

1. Identifies the request source (Claude/Codex/Gemini)
2. Looks up the currently enabled provider for that app
3. Forwards the request to the provider's actual endpoint
4. Records the request log
5. Returns the response to the app

## Takeover Status Indicators

### Main Interface Indicators

When takeover is enabled, the main interface shows the following changes:

- **Proxy logo color**: Changes from colorless to green
- **Provider cards**: The currently active provider shows a green border

### Provider Card States

| State | Border Color | Description |
|-------|--------------|-------------|
| Currently Active | Blue | Provider in the config file (non-proxy mode) |
| Proxy Active | Green | Provider actually used by the proxy |
| Normal | Default | Unused provider |

## Disable Takeover

### Steps

1. Turn off the corresponding app's takeover toggle in the proxy panel
2. Or directly stop the proxy service

### Configuration Restoration

When disabling takeover, CC Switch will:

1. Restore the app configuration to its pre-takeover state
2. Save current request logs

## Takeover and Provider Switching

### Switching Providers in Takeover Mode

When switching providers in takeover mode:

1. Click the "Enable" button on a provider in the main interface
2. The proxy immediately uses the new provider to forward requests
3. **No need to restart the CLI tool**

This is a major advantage of takeover mode: provider switching takes effect instantly.

### Switching Without Takeover

When switching providers without takeover:

1. Configuration file is modified
2. CLI tool must be restarted for changes to take effect

## Multi-app Takeover

Multiple apps can be taken over simultaneously, each managed independently:

- Independent provider configurations
- Independent failover queues
- Independent request statistics

## Use Cases

### Scenario 1: Usage Monitoring

Enable takeover + log recording to monitor API usage.

### Scenario 2: Quick Switching

With takeover enabled, switching providers does not require restarting CLI tools.

### Scenario 3: Failover

Enabling takeover is a prerequisite for using the failover feature.

## Notes

### Performance Impact

The proxy adds minimal latency (typically < 10ms), negligible for most scenarios.

### Network Requirements

In takeover mode, CLI tools must be able to access the local proxy address.

### Configuration Backup

Before enabling takeover, CC Switch backs up the original configuration and restores it when disabled.

## FAQ

### Requests Fail After Takeover

Check:
- Is the proxy service running normally
- Is the provider configuration correct
- Is the network working properly

### Configuration Not Restored After Disabling Takeover

Possible causes:
- Proxy exited abnormally
- Configuration file was modified by another program

Solutions:
- Manually edit the provider and re-save
- Or re-enable and then disable takeover