---
title: Gateway Inventory
read_when:
  - "understanding available gateways"
  - "adding a new gateway"
  - "creating test doubles for external services"
---

# Gateway Inventory

Catalog of all ABC/Fake gateway packages in the erk codebase. Each gateway follows the ABC/Real/Fake pattern for dependency injection and testing.

## Core Gateways

Located in `packages/erk-shared/src/erk_shared/`:

### Git (`git/`)

Git operations abstraction. See `git/abc.py` for full method list.

**Fake Features**: In-memory worktree state, branch tracking, configurable return values.

### GitHub (`github/`)

GitHub PR and repository operations.

**Fake Features**: In-memory PR state, configurable PR responses, label tracking, mutation tracking via `added_labels` property.

### GitHub Issues (`github/issues/`)

GitHub issue operations.

**Fake Features**: In-memory issue storage, comment tracking, state management.

## Higher-Level Abstractions

Located in `packages/erk-shared/src/erk_shared/`:

### BranchManager (`branch_manager/`)

Dual-mode abstraction for branch operations that works transparently regardless of Graphite availability.

**Purpose**: Provides consistent interface for operations that behave differently depending on whether Graphite is installed/enabled.

**Key Methods**:

- `get_pr_for_branch()`: Uses Graphite cache (fast) or GitHub API (fallback)
- `create_branch()`: Uses `gt create` (Graphite) or `git branch` (Git)
- `is_graphite_managed()`: Check which mode is active

**Implementations**:

- `GraphiteBranchManager`: Uses Graphite gateway for stack-aware operations
- `GitBranchManager`: Uses Git + GitHub gateways as fallback

**Factory**: Use `create_branch_manager(git=git, github=github, graphite=graphite)` to get the appropriate implementation.

**Fake Features**: `FakeBranchManager` provides in-memory PR tracking and branch creation recording.

**Related**: [Gateway Hierarchy](gateway-hierarchy.md) for architecture overview.

## Domain Gateways

Located in `packages/erk-shared/src/erk_shared/gateway/`:

### Browser (`browser/`)

System browser launch abstraction.

**Fake Features**: Success mode toggle, launch call tracking via `launched_urls` property.

### Console (`console/`)

User interaction abstraction combining TTY detection, mode-aware output, and user prompts.

**Key Methods**:

- `is_stdin_interactive()` / `is_stdout_tty()` / `is_stderr_tty()`: TTY detection
- `confirm()`: User confirmation prompts with yes/no response
- `info()` / `success()` / `error()`: Mode-aware diagnostic output

**Implementations**:

- `InteractiveConsole`: Full TTY interaction with styled output
- `ScriptConsole`: Suppressed diagnostics for shell integration (--script mode)

**Fake Features**: Configurable TTY states, pre-programmed `confirm_responses` list, prompt tracking via `confirm_prompts` property.

**When to use**: Any code that needs TTY detection or user confirmation should use `ctx.console` instead of direct stdin/stdout checks or click.confirm().

### ClaudeInstallation (`extraction/claude_installation/`)

Gateway for `~/.claude/` filesystem operations (sessions, settings, plans).

**Fake Features**: Configurable session data, project directory injection, in-memory settings.

**When to use**: Any code that needs to read from or write to `~/.claude/` paths should use this gateway instead of `Path.home()` directly.

### Clipboard (`clipboard/`)

System clipboard abstraction.

**Fake Features**: Success mode toggle, copy call tracking via `copied_texts` property.

### Time (`time/`)

Time operations abstraction for testable delays.

**Fake Features**: Fixed time injection, sleep call tracking via `sleep_calls` property, instant returns (no actual sleeping).

### Graphite (`graphite/`)

Graphite stack management operations.

**Fake Features**: Extensive state injection (branch relationships, PR info), parent/child tracking, submit call tracking.

### Erk Worktree (`erk_wt/`)

Erk worktree kit operations.

**Fake Features**: In-memory worktree state, deletion tracking.

### ErkInstallation (`gateway/erk_installation/`)

Gateway for `~/.erk/` filesystem operations (config, command history, planners).

**Fake Features**: In-memory config storage, configurable paths.

**When to use**: Any code that needs to read from or write to `~/.erk/` paths should use this gateway instead of `Path.home()` directly.

### Session Store (`extraction/claude_code_session_store/`)

Claude Code session data operations.

**Fake Features**: Configurable session data, project directory injection.

### Claude Installation (`extraction/claude_installation/`)

Consolidated gateway for all `~/.claude/` filesystem operations. Provides settings read/write, session access, and plan file management.

**Key Methods**:

- `read_settings()` / `write_settings()`: Settings file operations with backup
- `get_settings_path()`: Path to `~/.claude/settings.json`
- `get_session_log_path()`: Session log path retrieval
- `get_plan_content()`: Plan file content access

**Fake Features**: In-memory settings storage, mutation tracking via `settings_writes` property.

### Erk Installation (`gateway/erk_installation/`)

Consolidated gateway for all `~/.erk/` filesystem operations. Provides config management, version tracking, and pool state persistence.

**Key Methods**:

- `config_exists()` / `load_config()` / `save_config()`: Global config operations
- `load_pool_state()` / `save_pool_state()`: Pool state persistence
- `get_last_seen_version()` / `update_last_seen_version()`: Version tracking
- `root()`: Installation root path access

**Fake Features**: In-memory config/pool state, mutation tracking via `saved_configs`, `pool_saves`, `version_updates` properties.

### Parallel Task Runner (`parallel/`)

Parallel execution abstraction.

**Note**: No fake implementation - uses real ThreadPoolExecutor. Mock at task level instead.

## Implementation Layers

Each gateway typically has these implementations:

| Layer    | File          | Purpose                                          |
| -------- | ------------- | ------------------------------------------------ |
| ABC      | `abc.py`      | Abstract interface definition                    |
| Real     | `real.py`     | Production implementation (subprocess/API calls) |
| Fake     | `fake.py`     | In-memory test implementation                    |
| DryRun   | `dry_run.py`  | No-op wrapper for dry-run mode (optional)        |
| Printing | `printing.py` | Logs operations before delegating (optional)     |

## Usage Pattern

```python
# Production code uses ABC types
def my_command(git: Git, github: GitHub, time: Time) -> None:
    worktrees = git.list_worktrees(repo_root)
    pr = github.get_pr_for_branch(repo_root, branch)
    time.sleep(2.0)  # Instant in tests!

# Tests inject fakes
def test_my_command() -> None:
    fake_git = FakeGit(worktrees=[...])
    fake_github = FakeGitHub(prs={...})
    fake_time = FakeTime()

    my_command(fake_git, fake_github, fake_time)

    assert fake_time.sleep_calls == [2.0]
```

## Adding New Gateways

When adding a new gateway:

1. Create `abc.py` with interface definition
2. Create `real.py` with production implementation
3. Create `fake.py` with in-memory test implementation
4. Create `dry_run.py` if operations are destructive (optional)
5. Add to `__init__.py` with re-exports
6. Update `ErkContext` to include new gateway

**Related**: [Erk Architecture Patterns](erk-architecture.md#gateway-directory-structure)
