Zed Editor Skill

Configure and customize the Zed code editor by reading and writing its JSON config files, managing keybindings (including

workspace::SendKeystrokes

Config File Locations

macOS

~/Library/Application Support/Zed/settings.json    # Editor settings
~/Library/Application Support/Zed/keymap.json       # Keybindings
~/Library/Application Support/Zed/tasks.json        # Global tasks

Linux

~/.config/zed/settings.json
~/.config/zed/keymap.json
~/.config/zed/tasks.json

Per-project overrides

<project>/.zed/settings.json
<project>/.zed/tasks.json

Detect OS first — check

uname

Core Workflow

1. Detect OS to resolve config paths
2. Read existing config before making any changes (preserve user's work)
3. Validate JSON — all Zed configs are JSON arrays or objects; malformed JSON will silently break the editor config
4. Write changes using careful JSON merging — don't clobber existing bindings/settings
5. Verify the file is valid JSON after writing

Reading Config Safely

# macOS
CONFIG_DIR="$HOME/Library/Application Support/Zed"
# Linux
CONFIG_DIR="$HOME/.config/zed"

# Read keymap (may not exist yet)
cat "$CONFIG_DIR/keymap.json" 2>/dev/null || echo "[]"
# Read settings
cat "$CONFIG_DIR/settings.json" 2>/dev/null || echo "{}"

Keybindings (keymap.json)

The keymap file is a JSON array of binding objects. Each object can have an optional

context

bindings

Structure

[
  {
    "context": "Editor && vim_mode == normal",
    "bindings": {
      "key-combo": "action::Name",
      "key-combo": ["action::Name", { "param": "value" }]
    }
  }
]

Key Syntax

Keys use modifier-key format separated by

-

• Modifiers:

  cmd

  ,

  ctrl

  ,

  alt

  ,

  shift

  ,

  fn

• Special keys:

  up

  ,

  down

  ,

  left

  ,

  right

  ,

  enter

  ,

  escape

  ,

  tab

  ,

  space

  ,

  backspace

  ,

  delete

  ,

  home

  ,

  end

  ,

  pageup

  ,

  pagedown

• Letters/numbers:

  a

  -

  z

  ,

  0

  -

  9

• Multi-key sequences:

  "g e"

  (space-separated, typed in sequence)

Examples:

"cmd-shift-p"

"ctrl-w h"

"alt-down"

"g e"

Context Expressions

Contexts scope bindings to specific UI states. Use

&&

||

!

>

Common contexts:

• Editor

  — any editor pane

• Terminal

  — terminal panel

• ProjectPanel

  — file tree

• Dock

  — any dock panel

• vim_mode == normal

  /

  insert

  /

  visual

  — vim mode states

• VimControl

  — normal + visual modes combined

• menu

  — autocomplete/palette is open

• EmptyPane

  — no file open

Examples:

"context": "Editor && vim_mode == normal && !menu"
"context": "Terminal"
"context": "VimControl && !menu"

workspace::SendKeystrokes — Command Chaining

This is Zed's most powerful keybinding primitive. It dispatches a sequence of keystrokes synchronously, letting you chain multiple actions into a single keybinding without writing an extension.

Syntax

"key": ["workspace::SendKeystrokes", "keystroke1 keystroke2 keystroke3"]

Keystrokes are space-separated. Each keystroke uses the same modifier-key syntax as keybinding keys.

Important Constraints

• Synchronous only: SendKeystrokes dispatches all keys before any async operation completes. You CANNOT rely on async results (opening files, language server responses, command palette searches) between keystrokes.
• No cross-view chaining: You cannot send keys to a view that opens as a result of a previous keystroke in the same sequence.
• Async operations include: opening command palette, language server communication, changing buffer language, network requests.

Patterns

Chain copy + deselect:

"alt-w": ["workspace::SendKeystrokes", "cmd-c escape"]

Move down N lines:

"alt-down": ["workspace::SendKeystrokes", "down down down down"]

Select syntax node + copy + undo selection:

"cmd-alt-c": [
  "workspace::SendKeystrokes",
  "ctrl-shift-right ctrl-shift-right ctrl-shift-right cmd-c ctrl-shift-left ctrl-shift-left ctrl-shift-left"
]

Vim yank to end of line (neovim style):

{
  "context": "vim_mode == normal && !menu",
  "bindings": {
    "shift-y": ["workspace::SendKeystrokes", "y $"]
  }
}

Vim insert mode escape via jk:

{
  "context": "Editor && vim_mode == insert",
  "bindings": {
    "j k": ["workspace::SendKeystrokes", "escape"]
  }
}

Strategy for Building SendKeystrokes Chains

1. First identify the individual actions needed (use

   zed: open default keymap

   or the All Actions reference)
2. Find the existing keybindings for each action
3. Chain those key combos in a single SendKeystrokes string
4. Test that none of the intermediate actions are async

Common Actions Reference

Editor Actions

editor::Copy

editor::Cut

editor::Paste

editor::Undo

editor::Redo

editor::SelectAll

editor::Format

editor::ToggleComments

editor::MoveLineUp

editor::MoveLineDown

editor::DuplicateLineDown

editor::SelectLargerSyntaxNode

editor::SelectSmallerSyntaxNode

editor::GoToDefinition

editor::GoToDeclaration

editor::GoToImplementation

editor::Rename

editor::ToggleCodeActions

editor::Newline

editor::Tab

editor::Outdent

editor::FoldAll

editor::UnfoldAll

Workspace Actions

workspace::NewFile

workspace::Save

workspace::SaveAll

workspace::Open

workspace::ToggleLeftDock

workspace::ToggleRightDock

workspace::ToggleBottomDock

workspace::ActivateNextPane

workspace::ActivatePreviousPane

workspace::SendKeystrokes

Navigation

file_finder::Toggle

project_symbols::Toggle

buffer_search::Deploy

project_search::ToggleFocus

outline::Toggle

go_to_line::Toggle

tab_switcher::Toggle

diagnostics::Deploy

Terminal

terminal_panel::ToggleFocus

workspace::NewTerminal

Git

git_panel::ToggleFocus

git::Diff

git::OpenModifiedFiles

git::StageAndNext

git::UnstageAndNext

git::ToggleStaged

git::Commit

git::GenerateCommitMessage

git::Fetch

git::Push

git::Pull

git::Restore

editor::GoToHunk

editor::GoToPreviousHunk

editor::ExpandAllDiffHunks

editor::ToggleSelectedDiffHunks

Settings (settings.json)

Settings is a JSON object. Key settings to know about:

{
  // Font
  "buffer_font_family": "Berkeley Mono",
  "buffer_font_size": 14,

  // Theme
  "theme": "One Dark",

  // Vim/Helix mode
  "vim_mode": true,
  "helix_mode": false,

  // Formatting
  "format_on_save": "on",
  "formatter": "auto",

  // Tab settings
  "tab_size": 2,
  "hard_tabs": false,

  // Soft wrap
  "soft_wrap": "editor_width",
  "preferred_line_length": 100,

  // Autosave
  "autosave": { "after_delay": { "milliseconds": 1000 } },

  // Per-language overrides
  "languages": {
    "Python": {
      "tab_size": 4,
      "formatter": {
        "external": {
          "command": "black",
          "arguments": ["-"]
        }
      }
    }
  },

  // Inlay hints
  "inlay_hints": {
    "enabled": true
  },

  // Telemetry
  "telemetry": {
    "diagnostics": false,
    "metrics": false
  },

  // AI / Assistant
  "assistant": {
    "default_model": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-5-20250514"
    }
  }
}

Git Settings

{
  "git_panel": {
    "button": true,
    "dock": "left",
    "default_width": 360,
    "status_style": "icon",
    "sort_by_path": false,
    "tree_view": false
  },
  "git": {
    "git_gutter": "tracked_files",
    "inline_blame": {
      "enabled": true,
      "delay_ms": 600,
      "show_commit_summary": true
    },
    "hunk_style": "staged_hollow"
  }
}

Tasks (tasks.json)

Tasks let you run shell commands from Zed with access to editor context variables.

Structure

[
  {
    "label": "Run current file",
    "command": "python $ZED_FILE",
    "use_new_terminal": false,
    "allow_concurrent_runs": false,
    "reveal": "always"
  }
]

Available Environment Variables

$ZED_FILE

$ZED_FILENAME

$ZED_DIRNAME

$ZED_RELATIVE_FILE

$ZED_RELATIVE_DIR

$ZED_STEM

$ZED_ROW

$ZED_COLUMN

$ZED_SELECTED_TEXT

$ZED_WORKTREE_ROOT

Task Options

use_new_terminal

true

false

false

allow_concurrent_runs

true

false

false

reveal

"always"

"no_focus"

"never"

"always"

hide

"never"

"always"

"on_success"

"never"

cwd

env

{}

tags

[]

CLI Usage

# Open a file or directory
zed .
zed file.txt
zed project/ file.txt

# Open in new window
zed --new file.txt

# Diff two files
zed --diff old.rs new.rs

# Wait for file to close (for EDITOR usage)
zed --wait file.txt

# Open at specific line:column
zed file.txt:42
zed file.txt:42:10

# Set as default editor
export EDITOR="zed --wait"
export VISUAL="zed --wait"

# Open settings/keymap directly
zed zed://settings
zed zed://keymap

# macOS: choose release channel
zed --stable file.txt
zed --preview file.txt
zed --nightly file.txt

Extensions

Installed extensions location

• macOS:

  ~/Library/Application Support/Zed/extensions/installed/

• Linux:

  ~/.local/share/zed/extensions/installed/

Extensions are primarily managed through the Zed UI (

cmd-shift-x

ctrl-shift-x

Workflow: Adding a Custom Keybinding

This is the most common task. Follow this procedure:

1. Read the current keymap:

   cat "$CONFIG_DIR/keymap.json" 2>/dev/null || echo "[]"
   

2. Parse the JSON and check for conflicting bindings on the same key in the same context.

3. Determine the action(s) needed. If a single action suffices, bind directly:

   "cmd-shift-d": "editor::DuplicateLineDown"
   

4. If multiple actions are needed, use

   workspace::SendKeystrokes

   :
   • Look up existing keybindings for each desired action
   • Chain them:

     ["workspace::SendKeystrokes", "key1 key2 key3"]

   • Verify none are async

5. Add the binding to the appropriate context block (or create a new one).

6. Write the file and validate JSON:

   python3 -c "import json; json.load(open('$CONFIG_DIR/keymap.json'))" && echo "Valid JSON"
   

Workflow: Opening a Project in Zed

# Check if zed CLI is available
which zed || echo "Zed CLI not installed. Run 'Zed > Install CLI' from the app menu."

# Open project
zed /path/to/project

# Open project with specific file focused
zed /path/to/project /path/to/project/src/main.rs

Workflow: Creating a Project Task Runner

1. Create

   .zed/tasks.json

   in the project root
2. Define tasks that use Zed environment variables
3. Run tasks from the command palette or bind them to keys

Example — Rust project:

[
  {
    "label": "cargo run",
    "command": "cargo run",
    "cwd": "$ZED_WORKTREE_ROOT"
  },
  {
    "label": "cargo test current file",
    "command": "cargo test --lib $ZED_STEM",
    "cwd": "$ZED_WORKTREE_ROOT",
    "reveal": "always"
  },
  {
    "label": "cargo clippy",
    "command": "cargo clippy --all-targets",
    "cwd": "$ZED_WORKTREE_ROOT",
    "hide": "on_success"
  }
]

Gotchas

• JSON only — Zed configs don't support comments (unlike VS Code's JSONC). Strip any

  //

  comments before writing.
• Array vs Object —

  keymap.json

  and

  tasks.json

  are arrays

  []

  .

  settings.json

  is an object

  {}

  .
• Later bindings win — If two bindings match the same context+key, the one defined later takes precedence. User bindings always override defaults.
• SendKeystrokes is synchronous — Don't try to chain actions that depend on async results (file opens, palette searches, LSP responses).
• Context matching — Contexts match at specific tree levels.

  vim_mode

  is set at

  Editor

  level, so

  "Workspace && vim_mode == normal"

  will never match.
• Zed auto-reloads config — changes to keymap.json and settings.json take effect immediately without restarting.

Claude Code Integration: Change Review Workflow

This workflow bridges Claude Code (running in Warp, Ghostty, or any external terminal) with Zed for seamless change review.

How It Works

1. A PostToolUse hook in Claude Code records every file edit to a session manifest
2. A Zed task reads the manifest and opens all changed files at the right lines
3. Git review keybindings let you cycle through diffs, stage/revert per hunk

Setup

Step 1: Install the hook

Copy the hook script to a permanent location:

mkdir -p ~/.claude/hooks
cp hooks/post-tool-use.sh ~/.claude/hooks/post-tool-use.sh
chmod +x ~/.claude/hooks/post-tool-use.sh

Step 2: Configure Claude Code

Add to

~/.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/post-tool-use.sh"
          }
        ]
      }
    ]
  }
}

Step 3: Add the Zed tasks

Merge the contents of

examples/tasks.json

• macOS:

  ~/Library/Application Support/Zed/tasks.json

• Linux:

  ~/.config/zed/tasks.json

Step 4: Add review keybindings (optional)

Merge

examples/keymap.json

• macOS:

  ~/Library/Application Support/Zed/keymap.json

• Linux:

  ~/.config/zed/keymap.json

Step 5: Configure git panel (optional)

Merge

examples/settings.json

Usage

1. Run Claude Code in your terminal -- it edits files as usual
2. Switch to Zed
3. Run the "Review Claude Changes" task from the command palette (

   cmd-shift-p

   > "task: spawn" > "Review Claude Changes")
4. All files Claude edited open at the relevant lines
5. Use

   alt-]

   /

   alt-[

   to jump between diff hunks
6. Use

   alt-\

   to expand all diffs inline
7. Use the git panel to stage/revert changes
8. When done reviewing, run "Clear Claude Change Manifest" to reset

Change Manifest

Changes accumulate per Claude Code session at

~/.claude/changes/<session-id>.json

~/.claude/changes/latest.json

Format:

{
  "session_id": "abc123",
  "started": "2026-02-14T10:30:00Z",
  "changes": [
    {"file": "/path/to/file.rs", "line": 42, "tool": "Edit", "timestamp": "..."},
    {"file": "/path/to/new.rs", "line": 1, "tool": "Write", "timestamp": "..."}
  ]
}