# CodeLayers — Full Documentation

> CodeLayers is a spatial code explorer that visualizes codebases in 3D on iPhone, iPad, and Apple Vision Pro. It helps developers understand architecture, navigate dependencies, and assess the impact of code changes — all with zero-knowledge encryption that ensures source code never leaves the device unencrypted.

For the summary version, see https://codelayers.ai/llms.txt

---

## Getting Started

CodeLayers transforms codebases into interactive 3D visualizations where you can:

- See architecture — Files organized by dependency depth, with entry points at the top and core libraries below
- Navigate spatially — Tap to select files, see connections, zoom into details
- Understand impact — See the blast radius of code changes with color-coded visualization
- Chat with AI — Ask Claude, Gemini, or Codex about your code while seeing it spatially
- Stay private — Your code is encrypted on your machine with a 12-word phrase. Our servers never see your plaintext code.

### Try It Free (30 Seconds)

No account required. Explore any public GitHub PR in 3D from your terminal:

```
codelayers explore https://github.com/facebook/react/pull/31763
```

No clone, no checkout, no account. Opens in your browser with full architecture and blast radius. You get 10 free explores every 30 days.

### Pro Setup

Step 1: Install the CLI

```
curl -fsSL https://codelayers.ai/install.sh | bash
```

Or with Homebrew:

```
brew install codelayers-ai/tap/codelayers
```

Step 2: Get Your Mnemonic

CodeLayers uses a 12-word mnemonic phrase as your encryption key. Your encryption key syncs automatically via iCloud Keychain.

On your iPhone, iPad, or Vision Pro:
1. Download CodeLayers from the App Store
2. Sign in with Apple ID
3. The app generates your 12-word recovery phrase
4. Write it down securely

On your Mac:

```
codelayers login
```

Step 3: Sync Your Repository

```
cd ~/my-project
codelayers watch .
```

Step 4: Connect and Explore

Select your project from the CodeLayers app on iPhone, iPad, or Vision Pro. Your encrypted graph downloads and decrypts automatically.

### System Requirements

CLI: macOS 13+ (Ventura) on Apple Silicon, Git, Homebrew.
App: iPhone (iOS 18+), iPad (iPadOS 18+), Apple Vision Pro (visionOS 2+).

---

## CLI Reference

The CodeLayers CLI parses your code, builds the dependency graph, encrypts everything, and syncs to the backend where your devices receive updates in real-time.

### Installation

```
curl -fsSL https://codelayers.ai/install.sh | bash
```

Or: `brew install codelayers-ai/tap/codelayers`

### Global Options

- `-d, --debug` — Enable debug logging
- `-h, --help` — Show help
- `-V, --version` — Show version

### Commands

#### login

Authenticate by entering your 12-word mnemonic phrase.

```
codelayers login
codelayers login --force  # Force re-authentication
```

#### logout

Sign out and clear stored credentials. Does NOT delete synced data from the backend (it's encrypted and useless without your mnemonic).

```
codelayers logout
```

#### status

Show current authentication and sync status.

```
codelayers status
```

#### explore

Explore any public GitHub Pull Request in 3D — no clone, no checkout, no account required.

```
codelayers explore <PR_URL>
```

Free tier: 10 explores every 30 days. No account required.

#### sync

One-time sync of a repository to the backend.

```
codelayers sync [PATH]
codelayers sync --clean  # Force complete re-sync
```

#### watch

Watch a repository for changes and sync updates in real-time.

```
codelayers watch [PATH]
codelayers watch --agent claude  # With AI agent
codelayers watch --agent gemini
codelayers watch --agent codex
codelayers watch --mcp  # Run as MCP server
```

#### share

Create a shareable link to an interactive 3D code visualization with zero-knowledge encryption.

```
codelayers share [PATH]
codelayers share . --base origin/main --head HEAD  # PR mode
codelayers share --expires 30
codelayers share --format json  # Machine-readable output
```

Options: --base, --head, --expires, --max-views, --format, --github-repo, --github-pr, --github-pr-title.

#### shares

Manage shared visualization links.

```
codelayers shares list [PATH]
codelayers shares copy <SHARE_ID>
codelayers shares info <SHARE_ID>
codelayers shares remove <SHARE_ID>
codelayers shares cleanup
```

#### api-keys

Create and manage API keys for headless/CI authentication.

```
codelayers api-keys create <NAME> [--scopes <SCOPES>] [--expires <DAYS>]
codelayers api-keys list
codelayers api-keys revoke <KEY_ID>
```

Use with: `export CODELAYERS_API_KEY=cl_key_xxxx`

#### pair

Pair with a device using a 6-digit code to share your mnemonic.

```
codelayers pair
```

#### list

List all synced repositories.

```
codelayers list
```

#### info

Show detailed sync status for a repository.

```
codelayers info [PATH]
```

### Supported Languages

TypeScript (.ts, .tsx), JavaScript (.js, .jsx, .mjs), Python (.py), Rust (.rs), Go (.go), Java (.java), C++ (.cpp, .cc, .cxx, .h, .hpp), C# (.cs), Ruby (.rb), PHP (.php), Swift (.swift).

---

## App Guide

The CodeLayers app for iPhone, iPad, and Apple Vision Pro lets you explore your codebase in 3D.

### Installation

1. Open the App Store on your iPhone, iPad, or Vision Pro
2. Search for "CodeLayers"
3. Download and install

Requires iOS 17+ or visionOS 2+.

### Visualization

Files are displayed as spheres in 3D space, organized by topological depth. Connections between files represent imports and dependencies.

Visual encoding:
- Position (Y-axis): Higher = closer to entry points
- Color: Varies by layer (cyan to blue to purple to pink)
- Size: Based on file complexity or importance (PageRank)
- Connections: Lines show dependencies (import/call relationships)

### Blast Radius Mode

When viewing code changes, files are colored by their distance from the change:
- White: The changed file itself (distance 0)
- Red: Direct dependents (1 hop)
- Orange: 2 hops away
- Yellow: 3 hops away
- Green: 4 hops away
- Teal: 5+ hops away
- Gray: Not affected

### Navigation

- Tap: Select a node
- Double-tap: Focus on node (zoom in)
- Pinch: Zoom in/out
- Two-finger drag: Pan the view
- Look + tap: Select where you're looking (Vision Pro)

### AI Chat

The AI chat panel lets you ask questions about your code while seeing it spatially. Requires CLI running with `--agent` flag. Supports Claude Code, Gemini CLI, and Codex.

---

## Web Sharing

Create shareable links to interactive 3D code visualizations. Anyone with the link can view in their browser — no account needed.

Shares are zero-knowledge: the server stores only an encrypted blob. The encryption key lives in the URL fragment (#k=...), which browsers never send to the server.

### How It Works

1. CLI parses your codebase with tree-sitter
2. Builds dependency graph with metrics
3. Computes PR diff and blast radius (if --base/--head specified)
4. Generates random 256-bit AES key
5. Encrypts everything with AES-256-GCM
6. Uploads encrypted blob; appends key to URL fragment

### View Modes

- Depth: Color by topological depth
- Git: Color by git change status (green=added, red=removed, orange=modified)
- Impact: Color by blast radius distance from changed files

### Share Limits

Creating shares requires Pro. Max expiry: 90 days. Max payload: 50 MB. Viewing is free.

---

## GitHub Action

The CodeLayers GitHub Action (codelayers-ai/codelayers-action@v1) generates 3D visualizations for every PR.

### Quick Start

```yaml
name: CodeLayers
on:
  pull_request:

jobs:
  visualize:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: codelayers-ai/codelayers-action@v1
        with:
          api_key: ${{ secrets.CODELAYERS_API_KEY }}
```

### Inputs

- api_key (required): CodeLayers API key
- base_branch: Base branch to compare against (auto-detect from PR)
- expires_days: Days until share expires (default: 7)
- max_views: Maximum number of views (default: unlimited)
- comment: Post/update PR comment (default: true)
- link_to_pr: Link share to GitHub repo/PR metadata (default: true)

### Outputs

- share_url: Full share URL with encryption key
- share_id: Share ID (UUID)
- node_count, file_count, changed_file_count, blast_radius_count

Important: actions/checkout must use fetch-depth: 0 for accurate diff computation.

---

## AI Agents

CodeLayers integrates with Claude Code, Gemini CLI, and Codex via MCP (Model Context Protocol). 14 tools across three categories give AI agents architectural awareness that grep and file reads can't provide.

### Starting a Session

```
codelayers watch /path/to/project --agent claude
codelayers watch /path/to/project --agent gemini
codelayers watch /path/to/project --agent codex
```

### Search & Intelligence Tools (5)

- search_symbols: Find functions/classes/variables ranked by architectural importance (dependents, centrality, overlay membership). Token-aware matching splits camelCase/snake_case. 4-5x less noise than grep.
- get_skeleton: File structure without bodies — imports, constants, function signatures with graph metrics (in_degree, complexity, risk). up to 90% fewer tokens than reading the full file.
- search_call_chain: Shortest call path between two functions with per-hop graph metrics. One call replaces reading 3+ files and 5+ manual searches.
- trace_type_flow: Find all producers (return type), consumers (param type), and stores (variable type) of a given type across the codebase.
- trace_variable: Trace a variable — where it's declared, what assigns it, which functions it's passed to (with argument position).

### Visualization Tools (7)

- create_layer: Create named highlight layers in the 3D graph (colors: yellow, red, green, blue, purple)
- focus_file: Zoom 3D camera to center on a specific file
- show_dependencies: Show import/dependency lines in 3D + return structured JSON
- get_blast_radius: Dependency tree with file sizes, node types, uncommitted change flags, and overlay membership
- save_overlay / list_overlays: Persist highlight sets as encrypted overlay rings that survive across sessions
- clear_highlights: Clear all highlights when switching topics
- change_title: Update session title in the app
- set_visualization_mode: Switch modes (solar_system, city, tree, neural)

### Memory Tools (2)

- save_observation: Persist an insight (tagged) for future sessions — architecture patterns, bug root causes, gotchas
- search_memory: Recall past observations by content or tag. Agent can recover context from previous sessions.

### How Tools Work Together

The tools form a search → understand → act → remember pipeline. The agent starts by recalling past observations, searches for symbols ranked by importance, gets file skeletons instead of reading full files, traces call chains and type flows, checks blast radius before making changes, then saves new insights for future sessions.

### Session Modes

- Local Mode: Type in terminal, device observes and updates visualization
- Remote Mode: Type in app's chat panel, CLI executes commands

---

## VS Code Extension (Free)

The CodeLayers — Blast Radius extension for VS Code provides real-time dependency analysis directly in the editor. Completely free, no account or subscription required.

### Features

- Blast Radius Sidebar: Shows affected files organized by hop distance from the changed file
- Color-Coded Decorations: Red (changed file), Orange (1 hop), Yellow (2 hops), Green (3 hops), Blue (4+ hops)
- CodeLens Annotations: Inline callsite counts and "trace downstream" links above symbols
- Real-Time Analysis: 150ms debounce on file save, automatic re-analysis
- Filter Modes: All dependencies, functions only, or imports only

### Installation

Requires the codelayers CLI:
```
curl -fsSL https://codelayers.ai/install.sh | bash
```

Install the extension:
```
code --install-extension codelayers.codelayers
```

Or search "CodeLayers" in the VS Code Extensions panel.

### Configuration

- codelayers.maxHops (default: 3): Dependency chain depth limit (1–10)
- codelayers.showCodeLens (default: true): Show inline caller counts
- codelayers.defaultFilterMode (default: all): Initial filter mode (all, functions, imports)
- codelayers.warningThreshold (default: 20): File count triggering status bar warning
- codelayers.cliPath (default: auto-detect): Custom path to codelayers binary

### Supported Languages

Same 10 languages as the CLI: Rust, TypeScript, JavaScript, Python, Java, Go, C++, C#, Ruby, PHP, Swift.

VS Code Marketplace: https://marketplace.visualstudio.com/items?itemName=codelayers.codelayers
GitHub: https://github.com/codelayers-ai/codelayers-vscode

---

## Concepts

### The Dependency Graph

CodeLayers visualizes your codebase as a dependency graph. Nodes (spheres) = files. Edges (lines) = imports, function calls, type references. Larger nodes = more important (higher PageRank).

### Topological Depth

Files are arranged vertically by topological depth — their distance from the foundations:
- Bottom (Depth 0): Files that don't import anything (utils, constants, types)
- Middle layers: Business logic, services, controllers
- Top (Highest depth): Entry points (main.ts, App.swift, index.py)

A healthy codebase looks like a pyramid: many files at the bottom, fewer as you go up, few at the top.

### Blast Radius

Shows the impact of code changes. Files colored by distance from the change:
- White = changed file, Red = 1 hop, Orange = 2 hops, Yellow = 3 hops, Green/Teal = 4+ hops, Gray = unaffected.

### Privacy (Zero-Knowledge Encryption)

- Code files: Plaintext on device, encrypted blobs on server
- Function/file names: Plaintext on device, hashed identifiers on server
- 12-word phrase: Stored locally, never sent to server
- Encryption: AES-256-GCM, client-side only

---

## Pricing

### Free Tier ($0)

- 3D code visualization (all modes)
- PR diff visualization
- VS Code extension (blast radius analysis in editor)
- View shared links
- Git status coloring
- 10 public GitHub PR explores per 30 days

### Pro Tier ($7.99/month or $79.99/year)

Everything in Free, plus:
- CLI sync (watch mode) for private repos
- Blast radius visualization
- Git time travel
- AI agent integration (Claude/Gemini/Codex)
- MCP visualization tools
- Web sharing (zero-knowledge links)
- GitHub Action for PRs
- API keys for CI/CD
- Zero-knowledge encryption

Manage subscription through Apple ID settings. Cancel anytime.

---

## Troubleshooting

### Common Issues

- "No Projects Found": Ensure CLI is running with `codelayers watch`, verify same mnemonic on both devices
- "Connection Lost": Check internet, prevent Mac sleep with `caffeinate -i codelayers watch .`
- "Unable to Decrypt": Mnemonic mismatch — re-import via Settings > Privacy > Re-import Recovery Phrase
- "Command not found: codelayers": Reinstall with `brew install codelayers-ai/tap/codelayers`
- AI chat unavailable: CLI must run with `--agent` flag

### Getting Help

- Documentation: https://codelayers.ai/docs
- Email: support@codelayers.ai

---

## Links

- Website: https://codelayers.ai
- App Store: https://apps.apple.com/app/codelayers/id6756067177
- GitHub: https://github.com/codelayers-ai
- Bluesky: https://bsky.app/profile/codelayers.bsky.social
- Status: https://status.codelayers.ai