Introduction

日本語

ForgeKairos is a fork of the Zed code editor. It takes in Zed's releases one at a time (it is currently based on Zed v1.22.0) and adds:

• a multilingual UI, starting with English and Japanese (Display language and translations)
• control over outbound traffic started by AI features, denied by default (Outbound network control)
• AI that is off until you turn it on, with local LLMs first and Claude Code integration (AI)
• a symbol index and a call graph for large C and C++ projects (C and C++ code navigation)
• terminal macros, quick connections and session logs (Terminal macros and sessions)
• a commit graph with history editing and a merge request box (Git)
• Markdown input helpers and a structured editor for Mermaid diagrams (Markdown and Mermaid)
• a spreadsheet-like grid for CSV and TSV files (CSV and TSV grid)
• SSH remoting to old Linux hosts and terminals that survive disconnects (Remote development)

Changes from Zed lists every change in one place. This site describes only what ForgeKairos adds or changes. For everything else, see Zed's documentation.

Supported systems

ForgeKairos is developed for Windows and distributed as a Windows installer. For macOS and Linux, see Installation and updates. Remote development works with Linux hosts.

Not affiliated with Zed Industries

"Zed" is a trademark of Zed Industries, Inc. ForgeKairos is an independent fork; it is not affiliated with, endorsed by or supported by Zed Industries. Names of Zed's own services, such as Zed AI and Zed Pro, are used only to refer to those services.

License

ForgeKairos keeps the licenses of Zed: mostly GPL-3.0-or-later, with some crates under Apache-2.0, as each crate states (see LICENSE-GPL and LICENSE-APACHE). Zed is copyright Zed Industries, Inc. The clang-format binary included in the Windows installer is part of the LLVM project and is licensed under Apache-2.0 with LLVM Exceptions. Other third-party material is listed in THIRD_PARTY_NOTICES.md.

Repository

https://github.com/SeiyaFunaokaJP/ForgeKairos

The repository's history is connected to Zed's, and each Zed release is merged in turn.

Changes from Zed

日本語

This page lists, in one place, how ForgeKairos behaves differently from Zed. Renaming and other cosmetic changes are left out. Each section links to the page with the details.

Language

• The UI can be shown in other languages, starting with English and Japanese. The sources keep the English text; translations are gettext PO files in locales/. The language is chosen with ui_language and applies without a restart; action descriptions and the settings schema are translated too. (Display language and translations)
• Translations can be tried or added without rebuilding, and a remote server shows its messages in the client's language.

Network and privacy

• Outbound traffic started by AI features is denied by default and allowed per host (Settings → Network). Redirects are checked hop by hop, and a consent prompt can add a host. (Outbound network control)
• ACP agents, MCP servers and the npm that installs agents get a loopback proxy checked against the same allowlist, also on SSH remotes.
• Nothing is sent to Zed: telemetry, crash reports and Zed's hosted edit prediction are off, and collaboration (calls, screen sharing, LiveKit) is not built.
• Updates are checked only against this repository's GitHub Releases, and automatic updates are off by default. (Installation and updates)
• Links that a language server or Copilot asks to open are shown for confirmation first, and only http and https addresses are opened.

AI

• Every AI feature is off until you turn it on (agent.enabled), and no default model is set: a running local LLM is picked up. (AI)
• A cloud provider can be used only after you accept a warning that your data may be stored or used for training. Providers you added can be edited and removed in the settings.
• The Claude Code CLI can run in a tab of the agent panel and connect to ForgeKairos as its IDE (a loopback IDE server with highlight, annotation, tour, definition, reference and symbol search tools).
• Agent commands run in a sandbox, also on SSH remotes (network namespace and slirp4netns on Linux). Running outside it is an explicit choice by you, never by the agent.
• Tool permissions gain an AI Judge mode in which a separate model judges whether a command is safe, and an Edit Only profile.
• After an agent writes into a project folder, that folder's own code (formatters, linters, build scripts) is paused until you review and resume it.
• MCP servers, language servers and formatters defined in a project's settings do not start until you approve that exact content.
• Private files and files outside the project are hidden from agents, also under other spellings of the same path.
• Large attachments are sent as outlines within a size budget; the model selector collapses non-favorite groups; untrusted folders get no tools, with an explanation.
• Agent threads can be opened as tabs, split, moved to another panel or another window.

Workspace

• Tabs and panels can be dragged out of the window to open in a window of their own, and panels can be dragged between docks.
• A dock can show two panels together (by default the agent and the browser on the right).
• A built-in browser panel (Microsoft Edge WebView2, Windows only), whose tabs can move to and from the editor and terminal panes.
• Docks and defaults closer to VS Code: project, outline and Git panels on the left, the agent on the right, menus in the title bar, a terminal open at start, whitespace shown, Japanese font fallbacks, and status bar buttons for Vim mode, SSH remotes and formatting. (Settings reference)
• The Windows installer adds Open with ForgeKairos to Explorer's right-click menu.
• Missing language servers and formatters are offered for installation into your data folder from a notification.

C and C++

• A name-based symbol index covers the whole project without compilation information and backs up the language server for go to definition and symbol search. (C and C++ code navigation)
• A call graph panel shows callers and callees.
• The hover shows what a type holds (struct members, enum constants, macro definitions).
• clangd's indexing, thread count and memory are configurable, and it can be restarted when it uses too much memory.
• C and C++ are formatted with clang-format (bundled on Windows) in a GNU-based style.
• After a language server restart, buffers that are still open are reopened correctly.

Terminal

• Macros with variables, branches and waits for output, edited as cards in a tab and kept in folders. (Terminal macros and sessions)
• Quick connections for SSH and Telnet, with passwords optionally kept in the OS credential store.
• Session logs, and file transfer (SFTP, SCP, FTP) from the terminal.

Git

• A commit graph with history rewriting (amend, fix up, squash, reorder, drop, reword) by menus and drag and drop, refused up front when it cannot work and offering a way to undo. (Git)
• A merge request box to assemble a branch from chosen commits, and comparison of two refs.
• Explanations of each operation in the UI, and a Git guide.
• Older git versions (such as the one on Ubuntu 18.04) are supported, and failures are shown in the Git panel.

Markdown and Mermaid

• Formatting actions and a formatting bar, image insertion (including pasting), text color, highlight and size, and export to PDF. (Markdown and Mermaid)
• A structured editor for Mermaid diagrams in a tab, and label editing in the preview.
• The preview renders <details>, <br>, a single newline as a line break, and uses the full width by default.

CSV and TSV

• CSV and TSV files open as a spreadsheet-like grid: editing, rows and columns, filters, cell colors and comparison. Edits go to the text buffer, so undo and saving work as usual. (CSV and TSV grid)

Remote development

• A statically linked remote server is bundled, so Linux hosts with an old glibc (tested on Ubuntu 18.04) work without downloads. (Remote development)
• One server process per host serves all projects on it, and connections recover automatically after a network drop or sleep.
• SSH terminals keep running across disconnects and restarts and replay their output when you reconnect.
• Hosts without internet access download language servers and other tools through your machine.
• On Linux, file watching leaves inotify capacity for other programs and polls the rest; the project panel has a manual refresh.

Installation and updates

日本語

Windows installer

ForgeKairos is distributed as a Windows installer, forgekairos-windows-<arch>-setup.exe, from the GitHub Releases of the repository.

• It installs for the current user, without administrator rights, into a ForgeKairos folder under the user's programs folder.
• It requires 64-bit Windows 10 version 1709 or later.
• The installer offers: a desktop icon (off by default), Open with ForgeKairos in Explorer's right-click menu for files and for folders, file associations, and adding the command-line tool to PATH.
• The application is ForgeKairos.exe; the command-line tool is bin\forgekairos.exe.
• The installer includes clang-format (used to format C and C++) and the bundled remote server for Linux hosts.

On Windows 11, the Open with ForgeKairos entry may appear under "Show more options".

Updates

Automatic updates are off (auto_update is false). To check for an update, use Check for Updates in the application menu (or auto update: check in the command palette). ForgeKairos looks for updates only in this repository's GitHub Releases, never in Zed's. Release notes open the release page on GitHub.

Only releases are considered by default. To be offered pre-releases too, turn on Include Pre-releases under Settings → General → Auto Update ("auto_update_include_prereleases": true). Among the releases it considers, ForgeKairos picks the one with the highest version in its tag, not the most recently published one.

An update is downloaded only from this repository's release downloads. When GitHub lists a SHA-256 digest for the installer, an installer that does not match it is not installed. When the check fails (GitHub cannot be reached, or the download does not match), ForgeKairos says so instead of reporting that it is up to date. A release without an installer for this system is skipped, as if there were no newer version.

Moving from Zed-JP-Enhance

ForgeKairos was previously named Zed-JP-Enhance.

• Install ForgeKairos by hand. Zed-JP-Enhance cannot update itself to ForgeKairos. The ForgeKairos installer installs over it and removes its registrations.

• Uninstall Zed-JP-Enhance and do not run both. The older version's sandbox does not protect ForgeKairos's folders.

• Your data moves on the first normal start. ForgeKairos renames the old folders (Zed-JP-Enhance under %APPDATA% and %LOCALAPPDATA% on Windows) to its own; nothing is copied. Settings, the network allowlist, consents, databases and threads come along. The data is not moved when:

  • the new folder already has content,
  • Zed-JP-Enhance is running (this start keeps using the old folder and tells you so),
  • a rename fails (anything already moved is moved back, with a notice),
  • ForgeKairos is started with --user-data-dir, or as a helper process or the command-line tool.

  If Zed-JP-Enhance later creates its folder again, ForgeKairos tells you once.

• The C and C++ symbol index is rebuilt in a new format.

• The official Zed's folders are never read or moved.

Data folders

Project settings stay in .zed/ in each project, and environment variables keep their ZED_ names.

Other operating systems

ForgeKairos is developed and tested on Windows. The packaging scripts for macOS and Linux are kept, but those packages have not been built or tested.

Display language and translations

日本語

ForgeKairos shows its UI in the language you choose. English and Japanese ship with the app. The UI text in the sources is English; translations are gettext PO files in the repository's locales/ folder.

Choosing the language

Open Settings → General → Display Language, or set ui_language in settings.json:

{ "ui_language": "ja" }

Menus, settings and the command palette switch at once. Some other text, such as tab titles, switches after a restart.

What is translated

• Menus, the settings window, the command palette and panel text.
• Command palette entries are found by their translated name and by their English name.
• Descriptions of actions (shown in the keymap editor and in the hovers of the keymap and settings files) and descriptions in the settings file's JSON schema. In the keymap file, the arguments of the actions ForgeKairos adds are described in the display language; those of Zed's own actions stay English.
• Built-in snippets, such as the Mermaid diagrams offered in Markdown, have a copy per language.

Text that ForgeKairos sends to a language model (tool descriptions, system prompts, tool results) stays English, so the display language does not change what a model is told. Log messages are not translated.

Language fallback

A message falls back from the most specific tag to the base language, then to English: pt-BR → pt → English. A message that is missing, empty or marked #, fuzzy shows the next language in the chain.

Trying or adding a translation without rebuilding

Put PO files in <config directory>/locales/<tag>/. The config directory is:

Entries there override the bundled ones message by message, and a folder there can add a language that is not bundled. The files are read when ForgeKairos switches to the language; restart after editing them. Problems in the files are shown in a notification and written to the log; the readable entries are still used.

Remote hosts

On SSH, WSL and Docker remotes, text written by the remote server (such as some git errors and terminal notices) is translated on the remote with the catalogs built into the server, in the language sent when ForgeKairos connects. Files in your config directory do not reach the server. The server uses one language for all clients connected to it: the one that connected last.

Contributing a translation

The file layout, the PO header, placeholders, plurals, contexts and the i18n_tool command-line tool are described in locales/README.md.

AI and network restrictions at a glance

日本語

These diagrams show how ForgeKairos restricts AI and outbound network traffic. For the detailed rules, see Outbound network control and AI.

Is a request let through?

An HTTP request started by an AI feature is checked in this order.

flowchart TD
    R["Outbound request"] --> O{"Marked as the editor's own traffic?<br/>(language servers, extensions, updates, Git, ...)"}
    O -- "Yes" --> FREE["Not restricted"]
    O -- "No (treated as AI traffic)" --> L{"Loopback?<br/>127.0.0.0/8, ::1, localhost"}
    L -- "Yes" --> ALLOW["Allowed"]
    L -- "No" --> B{"Built-in allowance?<br/>(marketplace, ACP registry,<br/>ForgeKairos update check; fixed paths only)"}
    B -- "Yes" --> ALLOW
    B -- "No" --> A{"Host matches the allowlist?<br/>network_allowlist.json"}
    A -- "Yes" --> ALLOW
    A -- "No" --> DENY["Denied"]
    ALLOW --> RD{"Redirect?"}
    RD -- "No" --> DONE["Sent"]
    RD -- "Yes: check the next hop the same way<br/>(credential headers dropped on a host change)" --> L

• Loopback is let through even with an empty allowlist, so local LLMs (Ollama, LM Studio, llama.cpp) work without any setup.
• Allowing a host allows every port on it.

Who is restricted, and through which path

flowchart LR
    subgraph APP["ForgeKairos"]
        AI["AI features<br/>providers, edit predictions,<br/>fetch and web search, MCP (HTTP)"]
        TOOLS["Editor tools<br/>language servers, extensions,<br/>updates, Git, remote server"]
        GATE["Allowlist check<br/>(loopback + built-in allowances + allowed_hosts)"]
        PROXY["Loopback proxy<br/>(loopback + allowed_hosts only;<br/>no built-in allowances)"]
    end
    subgraph CHILD["Child processes"]
        ACP["ACP agents"]
        MCP["MCP servers (stdio)"]
        NPM["npm installing agents"]
    end
    SB["Agent sandbox<br/>(WSL / bubblewrap / Seatbelt)"]
    BR["Built-in browser"]
    NET(("Internet"))

    AI --> GATE --> NET
    TOOLS -- "not restricted" --> NET
    ACP & MCP & NPM -- "HTTP_PROXY / HTTPS_PROXY" --> PROXY --> NET
    SB -- "sandbox's own allowances ∩ allowlist" --> NET
    BR -- "not restricted by default;<br/>browser.use_egress_proxy routes it through the allowlist" --> NET

• The child-process proxy relies on the program reading the proxy environment variables. A program that ignores them cannot be restricted. Turn it off with proxy_child_processes: false.
• The sandbox can narrow the allowlist but never widen it.

Before a cloud AI provider is used

By default no AI runs, and nothing is sent to an external provider.

sequenceDiagram
    actor U as User
    participant FK as ForgeKairos
    participant AL as Allowlist
    participant P as Cloud provider

    Note over FK: agent.enabled = false (default). All AI is off
    U->>FK: Settings → AI → Enable the agent
    Note over FK: Local LLMs (loopback) work from here
    U->>FK: Choose an external provider
    FK-->>U: Warning (input and conversations are sent) and required hosts
    U->>FK: Tick the acknowledgement
    Note over FK: Recorded in acknowledged_external_ai_providers
    U->>AL: Add to allowlist
    FK->>P: Requests get through only now
    Note over U,AL: Revoking asks whether to remove hosts<br/>that no other provider uses

Acknowledging without adding the hosts leaves traffic to that provider denied.

When the agent runs a command or tool

flowchart TD
    T["Agent tool call"] --> AC{"Always confirmed in every mode?<br/>safety rules, always_confirm,<br/>outside the sandbox, permission escalation,<br/>writes to .zed or settings, outside the project"}
    AC -- "Yes" --> ASK["Ask the user"]
    AC -- "No" --> M{"agent.tool_permissions.default"}
    M -- "confirm (default)" --> ASK
    M -- "deny" --> NO["Not run"]
    M -- "allow" --> RUN
    M -- "auto" --> J{"Ask the judge model<br/>(10-second limit)"}
    J -- "SAFE" --> RUN
    J -- "anything else" --> ASK
    ASK -- "Approved" --> RUN["Run inside the sandbox"]
    RUN --> NETSB["Network limited by the allowlist<br/>credentials (~/.ssh, .npmrc, ...) unreadable"]
    RUN --> PAUSE["After a write to the project,<br/>that folder's own code (formatters,<br/>language server build scripts, ...)<br/>is paused until resumed"]

• auto sends the command and paths to the judge model's provider, so a local model is recommended.
• The only way to turn the sandbox off is agent.sandbox_permissions.allow_unsandboxed, and while it is off every command is confirmed.

SSH remotes

flowchart LR
    subgraph LOCAL["Local machine"]
        AL["Allowlist<br/>(the local one only)"]
        CL["ForgeKairos"]
    end
    subgraph REMOTE["Remote host"]
        RS["Remote server"]
        RP["Remote loopback proxy<br/>(not on Windows remotes)"]
        RA["ACP agents / MCP servers"]
    end
    NET(("Internet"))

    AL --> CL
    CL -- "sent on connect and on every change" --> RS
    RS --> RP
    RA -- "HTTP_PROXY" --> RP --> NET
    RS -- "downloads<br/>(relay_http_through_client, on by default)" --> CL --> NET

A remote with no internet access can still fetch language servers through the local machine.

Outbound network control

日本語

ForgeKairos denies outbound traffic started by AI features unless you allow its host. The list of allowed hosts is the network allowlist.

For diagrams of the whole picture, see AI and network restrictions at a glance.

What the allowlist controls

The allowlist applies to traffic that AI features start:

• AI model providers and edit prediction providers
• the agent's fetch and web search tools
• MCP servers (HTTP and OAuth)
• external agents (ACP) and the download of their binaries
• the npm that installs agents
• commands an agent runs in the sandbox

It does not restrict the editor's own tools: language servers, formatters, debug adapters, extensions, node and npm run for those tools, app updates, the remote server, Git, and the built-in browser (see Built-in browser).

A request that is not marked as the editor's own traffic is treated as AI traffic.

Deny by default

A controlled request is refused unless its host matches an entry of the allowlist. Loopback is always allowed: 127.0.0.0/8, ::1, ::ffff:127.0.0.1 and localhost (*.localhost is not). Local LLM servers on this machine (Ollama, LM Studio, llama.cpp) therefore work with an empty list.

Redirects are checked hop by hop against the list. When a redirect goes to another host, credential headers such as authorization, cookie, x-api-key and api-key are dropped.

Built-in allowances, limited to specific paths, need no entry:

• the extension marketplace
• the ACP agent registry and its icons
• the update check against ForgeKairos's GitHub Releases

Editing the allowlist

Open Settings → Network → Egress Control → Network Allowlist. There you can add, edit and remove hosts, reload the file, and open network_allowlist.json in the editor (the file is created if it does not exist). Changes take effect without a restart.

The file is in the config directory, next to settings.json:

{
  "allowed_hosts": [
    "api.openai.com",
    "*.example.com",
    "[fd00::1]"
  ],
  // optional, true when left out
  "proxy_child_processes": true
}

• An entry is an exact host name, *.domain (subdomains only, not the domain itself), or an IPv4 or IPv6 address.
• Matching ignores case and a trailing dot; international names are compared in Punycode.
• Ports are not matched: allowing a host allows every port.
• Comments and trailing commas are allowed.
• A missing, empty or unreadable file means loopback only. Invalid entries are skipped and logged. When the file cannot be parsed, the settings page does not edit it.

Adding hosts from a consent prompt

• Enabling an external AI provider shows the hosts it needs, with an Add to Allowlist button. Without them, traffic to that provider stays denied.
• Installing or updating an ACP agent checks the vendor's download hosts and, when one is not on the list, asks before adding it. Each update checks again; the consent given at installation does not carry over.
• MCP server templates show the hosts they need, with the same button.

Agents and MCP servers

ACP agents, MCP servers and the npm that installs agents get a loopback proxy through HTTP_PROXY and HTTPS_PROXY (NO_PROXY is set to loopback). The proxy allows only the hosts of allowed_hosts and loopback; the built-in allowances do not apply. It forwards through your own proxy setting when one is set.

• Turn it off with "proxy_child_processes": false, or with the switch Apply the Proxy to AI Agent Child Processes in the settings page. A change applies to child processes started after it.
• The proxy relies on the program reading the proxy variables. A program that ignores them is not restrained.
• When an agent's env setting already sets a proxy variable, nothing is injected.

SSH remotes

The allowlist on your machine is the only list. It is sent to the remote server when you connect and again whenever it changes. The remote server runs its own loopback proxy for ACP agents and MCP servers that run on the remote (not on Windows remote hosts).

With remote.relay_http_through_client (on by default), the remote host's downloads go through your machine. A remote without internet access can then still fetch language servers.

The agent sandbox

The network a sandboxed command can reach is the sandbox's own grant limited by the allowlist (plus loopback). The sandbox can narrow the allowlist but not widen it. This also holds on WSL and on SSH remotes. Changes take effect from the next command.

Built-in browser

The built-in browser panel is operated by you, like a terminal, and is not restricted by default. Turn on browser.use_egress_proxy (Apply the Allowlist to the Built-in Browser) to route it through the allowlist; this takes effect the next time the browser starts.

Telemetry, collaboration and updates

• This build sends neither telemetry nor crash reports to Zed, and does not show them in the settings.
• Collaboration (calls and screen sharing) is not built into ForgeKairos.
• auto_install_extensions is empty, so nothing is downloaded at startup.
• auto_update is off. The update check asks only ForgeKairos's GitHub Releases (see Installation and updates).
• Edit prediction is off (edit_predictions.provider is "none").

AI

日本語

For the AI features that ForgeKairos shares with Zed (the agent panel, inline assistant, providers), see Zed's AI documentation. This page describes what ForgeKairos changes and adds. For diagrams of how AI and network access are restricted, see AI and network restrictions at a glance.

Off by default

Every AI feature is off until you turn it on. Use Enable Agent at the top of Settings → AI (the setting agent.enabled, default false). The change applies without a restart, and you can turn it off again the same way.

Do not use disable_ai to turn AI off: it is a one-way switch.

• No default model is set. When you enable the agent, the first authenticated provider is used, so a running local Ollama or LM Studio is picked up without configuration.
• Edit prediction is off (edit_predictions.provider is "none").
• The agent panel does not open on startup (agent.starts_open is false).

Local LLMs

Ollama (localhost:11434), LM Studio (localhost:1234) and llama.cpp (localhost:8080) run on loopback, which the network allowlist always allows. They need no consent and no allowlist entry. OpenAI-compatible and Anthropic-compatible servers can be added as custom providers.

A provider you added can be edited or removed later with the pencil and trash buttons on its header in Settings → AI → LLM Providers.

• Editing leaves the API key field empty; an empty field keeps the saved key. Changing the API URL asks for the key again, so a saved key is never sent to another URL, and removes the key saved for the old URL from the system keychain. Turning on Connect without an API key removes the saved key too. Neither removes a key that another provider with the same URL uses. A new host asks for consent again.
• Renaming the provider moves the agent settings that name it, and its consent, to the new name. Saved threads keep the old name.
• Removing asks first and lists what goes: the settings entry, the saved API key (kept when another provider uses the same URL), the consent and its allowlist hosts, and the model choices that name the provider. Remove Provider in the provider's own view does the same.
• Providers defined in a release channel, OS or profile override are shown as not editable there.

Cloud providers

Before an external AI provider can be used, ForgeKairos shows a warning that your input and conversations are sent to the provider and may be stored or used for training. You enable the provider by ticking the confirmation checkbox. Until then, no request is sent to it.

• The warning lists the hosts the provider needs, with an Add to Allowlist button (see Outbound network control).
• Accepted providers are stored in acknowledged_external_ai_providers. Removing an entry brings the warning back. Withdrawing consent offers to remove the hosts that no other accepted provider needs.
• Project settings cannot accept the warning for you.
• Copilot and Zed's hosted edit prediction need the same consent.

Claude subscriptions

The built-in Anthropic provider uses an API key only. To use a Claude Pro or Max subscription, use Claude Code:

• Launch Claude Code opens the official, unmodified Claude Code CLI. With the agent enabled it opens as a tab in the agent panel; otherwise in the terminal panel. Sign-in is done in the CLI by Anthropic's own flow; ForgeKairos does not handle the URLs or tokens.
• The Claude agent over ACP accepts subscription sign-in with its own /login. An API key also works and takes precedence when both are set. To hide the subscription sign-in, set agent_servers.<id>.allow_subscription_sign_in to false.
• The built-in agent and the permission judge (below) never use a subscription.

The IDE server for Claude Code

With ide_server.enabled (Enable IDE Server, off by default), ForgeKairos runs a loopback server on 127.0.0.1 that the Claude Code CLI connects to. It makes no outbound connections. While it runs, it writes ~/.claude/ide/<port>.lock for each local project.

Through it, the CLI can:

• open diffs in a ForgeKairos tab with Accept and Reject (the CLI does the write)
• read diagnostics, the open editors, the current selection, and the workspace folders
• open and save files
• read the tail of the last failed task (ide_server.share_task_output)

With ide_server.assist_tools (Give Agents IDE Tools, on by default), agents also get an MCP server named zed with these tools: highlightCode, annotateCode, startCodeTour, clearAnnotations, getHover, getDocumentSymbols, searchSymbols, findDefinition, findReferences, getCallHierarchy and getTypeLayout. Annotations are not saved and are cleared with Esc. Symbol search uses no model and no embeddings.

The built-in agent has the matching tools hover, search_symbols, call_hierarchy, type_layout, highlight_code, annotate_code, code_tour and clear_annotations.

The agent sandbox

Commands an agent runs always run in a sandbox. The agent cannot ask to run outside it. If the sandbox cannot be created, you can retry or cancel.

• Windows uses a ForgeKairos helper on WSL; Linux uses bubblewrap; macOS uses Seatbelt.
• Credentials such as ~/.ssh, .npmrc, cloud CLI configuration, browser profiles and ForgeKairos's own data are not readable from the sandbox.
• External ACP agents run inside the sandbox too (on Windows, in WSL).
• Git operations that write repository metadata (such as commits) are left to you.
• The sandbox's network is limited by the network allowlist.
• agent.sandbox_permissions.allow_unsandboxed (default false) is the only switch that turns the sandbox off. While it is off, every command asks for confirmation.

Running outside the sandbox

You can start Claude Code or an ACP agent outside the sandbox yourself:

• Launch Claude Code Outside the Sandbox… in the agent panel's + menu
• the buttons in launch failure notifications and ACP failure cards
• relaunching from the panel's ⋯ menu
• agent.claude_code_run_outside_sandbox and agent_servers.<id>.run_outside_sandbox (both default false, read only from the user settings file)

Outside the sandbox, a banner is always shown and the tab name says so (for example "Claude Code (Outside the Sandbox)"). Your usual ~/.claude sign-in is used. Consent for an ACP thread is kept per thread; revoke it on the AI page (Consent to Launch Outside the Sandbox).

Tool permissions

agent.tool_permissions.default takes "confirm" (default), "allow", "deny" or "auto". The agent panel's menu offers Confirm Actions, AI Judge (Auto-Run If Safe) and Auto-Approve (In Sandbox).

• "auto" asks a separate model (agent.permission_judge_model, otherwise the fast model, then the default model) about each action, with a 10-second limit. Only an answer of SAFE runs the action without asking. The command and paths are sent to that model's provider, so a local model is recommended.
• These are always confirmed, in every mode: built-in security rules and always_confirm rules, commands outside the sandbox, sandbox escalations, writes to .zed, global settings, skills or symlinks, and file operations outside the project.

The profiles are Write (default), Ask, Edit Only and Minimal. Edit Only reads and edits files but has no terminal, fetch, delete or MCP tools.

Pausing project code after agent writes

When agent.pause_worktree_code_after_agent_writes is on, after an agent writes into a project folder, that folder's own code (formatters, ESLint, the Python interpreter, rust-analyzer's build scripts) does not run until you review the changes and click Resume. It is off by default; only the user settings file can turn it on. While folders are paused, the status bar shows how many; click it to review and resume.

MCP servers

Settings → AI → MCP Servers shows each server's state, tests connections and adds servers. Servers you add there go to your user settings. The form has bundled templates (filesystem, github, playwright, fetch, memory) that show the hosts they need.

MCP servers, language servers and external formatters defined in a project's .zed/settings.json do not start until you approve that exact content; any change asks again. Approvals are listed under Settings → General → Security, where they can be revoked. session.trust_all_worktrees does not approve them.

Files hidden from agents

Files matching private_files (by default .env*, *.pem, *.key, *.cert, *.crt, secrets.yml) or file_scan_exclusions, files outside the project, and symlinks that point outside are hidden from the agent's tools and from attachments. For such files, definitions and references return only the location (path and line), not the text. The check also catches other spellings of the same path (case, Windows short names, Unicode normalization).

One response of definitions, references or call hierarchy opens at most 1000 new files and 64 MiB in total.

Attachments

Large attachments are sent as an outline with a note on how to read more, within the limits of agent.context_attachments (see Settings reference). Each attachment chip shows an estimate of its size; right-click it to choose Auto, Full or Summary. Branch diffs are summarized, and the agent can read the full diff with its git_diff tool.

Model selector

When you have favorite models (agent.favorite_models), the other provider groups are collapsed under a heading with their count, and the group of the model in use stays open. Search matches group names too. The Agents section at the bottom launches Claude Code or starts a thread with another agent.

Untrusted folders

In a folder you have not trusted, the agent's profile is reduced to Minimal (no tools). A notice above the input explains this, and the model is told why it has no tools. Trusting the folder restores the tools at once.

C and C++ code navigation

日本語

ForgeKairos adds a name-based symbol index for C and C++, a call graph panel, the contents of types in the hover, and settings that limit clangd's memory. For language servers in general, see Zed's C and C++ documentation.

Symbol index

In a project with C or C++ files, ForgeKairos builds an index of names (symbol_index.enabled = "auto"). The index needs no compilation information and runs nothing; it is also built in projects you have not trusted. It holds functions and prototypes, #defines, structs, unions, enums and typedefs, enum constants, globals, direct and member calls, function pointer assignments and calls inside macro bodies.

• The index is stored in the app's data folder, one per project folder. In measurements it took roughly half the size of the sources.
• Indexes not used for 90 days are deleted.
• Results that come from the index are marked as name matches, because a name can match an unrelated symbol of the same name.

Go to definition

In C and C++, when the language server returns nothing, fails, or takes longer than symbol_index.language_server_timeout_ms (1500 ms), go to definition uses the index. One match jumps there directly, with a short notice; several matches are listed. The fallback does not apply inside comments and strings. It works for F12, Ctrl+click and hover links.

Symbol search

Project symbol search (ctrl-t) shows the index's answers first and adds the language server's results when they arrive, without duplicates. Qualified C++ names such as ns::f can be searched.

Call graph panel

The call graph panel shows a tree of the callers or callees of a function. It asks one level at a time, only when you expand a node. By default the root does not follow the cursor; you choose it.

In the panel, Left collapses and Right expands a row, Space previews the call site, ctrl-c (cmd-c) copies the name, and alt-left / alt-right move through the history of roots. Pressing Enter again on a row with several call sites moves to the next one.

• Index answers appear first; the language server's answers are merged in when they arrive.
• Recursion is marked. Indirect calls through function pointers list their candidates.
• When a name has several definitions, the panel lists the candidates for the root.
• Callees listed in call_graph_panel.excluded_callees (such as printk and printf) are counted in a final row and shown on request.

See the call_graph_panel settings in the Settings reference.

Type contents in the hover

Hovering a name in C or C++ also shows what its type holds, below the language server's hover:

• the name, its kind and where it is defined
• the chain of typedefs (for example alias_t → outer_t → struct outer)
• the members of a struct, union or class, expandable level by level
• the constants of an enum, and the text of a macro
• a switch between definitions of the same name

The contents are found by name in the index, not resolved by the language server. Turn them off with symbol_index.hover_type_contents.

clangd memory

• The defaults add no arguments. If your lsp.clangd.binary.arguments already has the same kind of flag, nothing is added. Changing a setting restarts clangd.
• memory_limit_mb and max_workers are read only from your user settings.
• Memory is measured over clangd and all its child processes. The language server menu shows it.
• The notification for a memory limit offers to switch to light mode.

AI tools

The built-in agent has call_hierarchy and type_layout; agents connected through the IDE server have getCallHierarchy and getTypeLayout (see AI). Both are read-only. Names from files hidden from agents are withheld.

C and C++ formatting

C and C++ files (including .h) are formatted with clang-format and a style based on GNU: a space before parentheses, 120 columns, no single-line blocks or functions, indented case labels, and includes left unsorted. "Format Selections" formats only the selected lines. clang-format is looked up in the app's folder, its bin folder, the copy installed from a missing-tool notification, and then PATH. The Windows installer includes clang-format.

Terminal macros and sessions

日本語

ForgeKairos adds terminal tools in the style of Tera Term: macros that send text and wait for output, quick connections over SSH and Telnet, session logs, and file transfer.

Macros

A macro is a list of steps run against the active terminal.

Variables

${name} is replaced in the text to send and in patterns. An undefined variable stays as written, so a typo stays visible; write $${ for a literal ${. A value inserted into a regular expression is escaped.

A variable gets its value from:

• Capture Into on a Wait for Text step, or on a Branch step (on its "Then" side)
• a named group of a regular expression, (?P<name>…)
• a Set Variable step

The editor warns about a ${name} that has no value yet at that point of the macro, and shows regular expression errors in place. How Branches and Variables Work in the editor explains them with examples.

Branches

• Branch matches against the output since the last Send (default), the whole screen, or a variable. An unset variable takes the "Else" side. Branch does not wait; put a Wait for Text step in front of it when needed.
• Wait for Text can have an On Timeout branch instead of stopping the macro.
• Branches can be nested.

The macro editor

The macro editor opens as a tab in the center pane. Opening a macro that is already open switches to its tab.

• Each step is a card. Click the header to fold or unfold it; Expand All and Collapse All act on every card.
• The + on the line between cards inserts a step. Drag a card's header onto a + to move it, also into or out of a branch.
• A branch shows its two sides as columns ("Then" and "Else"), stacked when the tab is narrow.
• Move up, move down and delete are in each card's … menu and its right-click menu.
• A folded card with an error shows an icon.

Unsaved changes show a dot on the tab, and closing asks whether to save. Tabs of macros that were open come back after a restart, without unsaved changes. When the macro file changes outside the editor, a tab without unsaved changes follows it; a tab with unsaved changes asks before overwriting.

Folders

Macros are kept in folders. Folders can be empty, have an order, and two folders can hold macros of the same name. Add a folder with New Folder…; a folder's right-click menu creates, renames, moves and deletes. When a folder that is not empty is deleted, you choose whether its macros move to Unfiled or are deleted. Folders do not nest. The Run Macro… picker groups macros by folder (terminal.macro_picker_folders_collapsed opens it with every folder collapsed).

Where macros are saved

Macros, folders and quick connections are saved in terminal_sessions.json in the config directory (%APPDATA%\ForgeKairos on Windows, ~/.config/forgekairos on macOS and Linux). Writes are atomic, and edits to the file are picked up while ForgeKairos runs.

Quick connect

Quick connect opens an SSH or Telnet session in a new terminal tab, with a host, port, user, an optional macro to run after connecting, and logging. If Windows's telnet.exe is not installed, ForgeKairos tells you how to enable it.

Passwords can be remembered (Remember password, off by default). They are kept in the operating system's credential store (on Windows, Credential Manager), never in the JSON file. SSH receives the password through askpass on the first prompt only; Telnet watches for a password prompt once.

Session logs

A terminal's output can be saved to a log file (toggle, start, stop, reveal the file, or open it in the editor following its end). Logging pauses while a remembered password is entered. See the terminal.session_log settings in the Settings reference.

File transfer

File Transfer… in the terminal's right-click menu (or terminal: open file transfer) opens a two-pane window for SFTP, SCP, FTP and FTPS. It runs the operating system's own sftp, scp and curl. The target is taken from the active terminal. In an SSH remote project, the local side can be the remote host. Transfers are your actions; agents cannot start them.

Git

日本語

ForgeKairos adds a commit graph with history-editing operations, a box for building merge request branches, an operation guide, and support for old versions of git. For Zed's Git panel, see Zed's Git documentation.

The Git menu

The menu bar has a Git menu: Open Git Graph, Create Branch…, Switch Branch…, Amend Last Commit, Fixup into an Earlier Commit…, Create Merge Request, Compare Two Branches…, Fetch, Pull, Push, Force Push with Lease…, Stash… and Git Guide.

Commit graph

The graph shows ref chips for HEAD, local and remote branches and tags. You can show all branches, the current branch or a chosen one, pick a tag from a searchable list, and select several commits with Shift or Ctrl. The details of a commit show the latest tag before it.

Right-click a commit to:

• create a branch from it (and switch to it, or not)
• check it out (detached HEAD)
• tag it
• cherry-pick it into the current branch, or revert it
• reword its message
• reset to it: soft, mixed or hard (hard asks first)
• drop it

Operations that do not apply are shown greyed out with the reason.

Rewriting history

• Amend: the Git panel's commit area has an "Amend" checkbox; it warns when that commit was already pushed.
• Fixup: puts the current changes (staged only, or all) into an earlier commit. It is refused before it starts when it cannot work: during a rebase or merge, with conflicts, on a detached HEAD, for a commit outside the current branch, or with a merge in the range. The success message offers Undo….
• Squash, reorder, drop: a dialog lists the commits with keep, squash, drop and reword, and rows can be dragged to reorder.
• Force push: after a rewrite, force push is offered only "with lease", and only when the commit was already pushed. Force pushing always asks for confirmation.

Before any rewrite, ForgeKairos refuses to start if an ignored local file (such as .env) would be overwritten. A rewrite that stops on a conflict shows a banner with continue, skip and abort.

Drag and drop

• Drag files in the Git panel onto the staged or unstaged section to stage or unstage them.
• Drag files onto a commit in the graph to fix them up into that commit.
• Drag a commit onto another commit to reorder.
• Drag a commit onto the HEAD chip to cherry-pick it.
• Drag the HEAD chip onto a commit to reset to it (soft, mixed or hard).

Merge request box

Create Merge Request opens a box beside the graph. Choose your development branch and the base, drag commits into the box, write the message and the branch name (default mr/<branch>), and create the branch. Your current branch stays checked out.

After creating it, ForgeKairos compares the result and classifies each file, for example as matching, changed by an excluded commit, or possibly missing (with the commits involved). It warns when the merge request branch is not based on the latest base. Commits not yet placed are marked in the graph, and you can step through them.

Comparing two refs

Compare Two Branches… opens a tab with the changed files and read-only diffs between two refs.

Search

The graph's search accepts author:, tag:, branch:, path:, file:, since:, after:, until:, before:, change:, merge: and sha:, combined with AND.

Help in the UI

• ? (git: show guide) in the graph toolbar, the Git panel header and the merge request box opens the Git Guide: amend, fixup, reword, squash, cherry-pick, merge requests, branches, undoing, reset modes, comparing, tags and search.
• A line under the button row explains the button under the mouse. Menus show a short explanation beside each item; disabled items give the reason; destructive items carry a caution.

More operations

The Git panel and the command palette add: initialize a repository, add and remove remotes, merge a branch, make the local branch match the remote (asks first), create a patch from the working tree, the staged changes or the last commit, and apply a patch.

Many refs

Staging and committing stay responsive with tens of thousands of tags or branches. When there are 1,000 or more loose refs, a banner offers to pack them.

Old git

Git integration also works with old git (for example on older Linux servers). Features that need a newer git than the one installed are refused with a message that names the required version. In projects you have not trusted, with git older than 2.12, operations that run hooks and push, pull and fetch are refused. When git status fails, the Git panel shows the error in a banner.

Markdown and Mermaid

日本語

ForgeKairos adds Markdown input helpers, a wider preview with more HTML support, image and text color helpers, PDF export, and a structured editor for Mermaid diagrams. For Zed's Markdown support, see Zed's Markdown documentation.

Input helpers

• Enter continues block quotes, bullet and numbered lists, and task lists; Tab indents a list item.
• In Markdown, Enter first adds the two trailing spaces of a hard line break (hard_break_on_newline, on for Markdown). Shift+Enter does the opposite once.
• Formatting actions: block quote, bold, italic, strikethrough, inline code, headings 1 to 3, bullet list, numbered list, task list, link, horizontal rule and code block. ctrl-b, ctrl-i and ctrl-shift-x (cmd on macOS) apply bold, italic and strikethrough in Markdown files only.
• While a Markdown file is open, a formatting bar appears below the toolbar (toolbar.markdown_format_bar). It also inserts <details>, images and Mermaid diagrams, and sets text color, highlight and paragraph text size.
• Headings, fenced code blocks and <details> can be folded from the gutter, and all headings of a level can be folded at once.

Preview

• The eye button opens the preview in the same pane; Ctrl+click (Cmd+click on macOS) opens it beside the editor.
• The preview uses the full width of the pane (markdown_preview.limit_content_width is off).
• A single newline is shown as a line break (markdown_preview.soft_break_as_hard_break).
• Table columns get a minimum width; a table scrolls sideways only when the columns do not fit.
• Supported HTML includes <details> and <summary> (click to open or close), <br>, <div align>, <center>, <b>, <kbd>, <u>, <s>, <hr>, <sub>, <sup> and <a href>. Links with javascript:, data: and vbscript: are refused.

Images

markdown: insert image (also on the formatting bar) opens a dialog for the path, alternative text, alignment and size. It writes ![alt](path), an <img> with width and height, or a <div align> around the image, depending on what you set. Paths are relative to the Markdown file; an image from outside the project is copied into an images folder. This also works on SSH and WSL remotes.

• Pasting an image into a saved Markdown file saves it as images/image-YYYYMMDD-HHMMSS.<ext> and links it.
• Dropping a file from the operating system copies it; dropping one from the project panel links it.
• Paths are completed after ](, ![](, src=" and href=".

Tables

markdown: edit table opens the pipe table under the cursor (or a blank table) as a grid of cells. You can insert, delete and move rows and columns, set each column's alignment, and paste a range copied from a spreadsheet, which is spread across the table. Update writes the table back as Markdown.

Text color, highlight and size

• Text color writes <span style="color: …"> (8 colors).
• Highlight writes <mark> (yellow) or <mark style="background-color: …">.
• Paragraph text size writes <span style="font-size: …"> around a paragraph.

These are refused, with a message, where they would break the markup (inside tags, comments or code, or across links and table cells). GitHub drops style attributes, so colors and sizes do not show there.

Export to PDF

markdown: export to pdf (from the toolbar, the preview or the tab's right-click menu) writes a PDF with the same name next to the saved Markdown file. It uses Microsoft Edge in headless mode, or pandoc from PATH when Edge is not found. The page is A4, Mermaid diagrams are included, and text colors are kept.

Mermaid

Mermaid diagrams are drawn by ForgeKairos itself (no JavaScript), in the Markdown preview and in the agent panel.

• Insert Mermaid Diagram (formatting bar, right-click menu, or the mermaid-* snippets) inserts a diagram of a chosen type.
• Edit Mermaid Diagram… (right-click, the Edit button on a diagram in the preview, or the formatting bar) opens a structured editor for the diagram at or near the cursor, as a tab beside your files: the form on the left and a large preview on the right (drag the line between them; in a narrow pane they are stacked). The preview enlarges or shrinks the diagram to fill the pane, or shows it at the size you pick with the zoom buttons or Ctrl+scroll (with scrolling when it is larger than the pane). Opening the same diagram again brings its tab forward. Apply (Ctrl+Enter, or saving the tab) writes the diagram back as one undo step and keeps the tab open; a dot on the tab marks edits not yet applied, and closing the tab asks what to do with them. If the diagram is changed in the document while the tab has no edits, the tab follows it; with edits, the tab warns and does not write over it unless you choose to overwrite. Lines the editor does not understand are kept as they are; syntax it cannot reproduce makes it refuse to open, with the reason. These tabs are not restored when ForgeKairos restarts.
• In the preview, double-click a label to edit it in flowcharts, ER diagrams, state, class, sequence, pie and Gantt diagrams.
• A diagram that makes the renderer fail shows an error in its place instead of stopping ForgeKairos.

The structured editor supports 26 diagram types: flowchart, sequence, class, state, entity relationship, Gantt, pie, GitGraph, mindmap, timeline, user journey, quadrant chart, XY chart, radar, requirement, C4, block, Sankey, packet, Venn, Kanban, treemap, architecture, tree view, Ishikawa and event modeling.

CSV and TSV grid

日本語

ForgeKairos opens .csv, .tsv, .psv and .ssv files as a spreadsheet-like grid (tabular_data.open_as_grid). The file's text stays the source: every grid operation is an edit of the text, undone in one step, and saving, the unsaved marker, Git diffs and autosave work as for any text file.

• The grid toolbar opens the text beside the grid; in the text editor, the eye button opens the grid. Both stay in sync. Alt+click switches the tab between grid and text in place.
• Cells that contain line breaks are shown in full (tabular_data.multiline_cells).
• "First Row Is Header" can be turned off.

Editing

• Copy uses the tab-separated format that spreadsheets read.
• Input methods (for example Japanese input) work in cells.
• Blank lines are kept as rows, and the existing quoting is preserved.

Rows and columns

• A + row and an Add Column column sit at the ends; thin bands on every row and column boundary insert there.
• The right-click menus of cells, row headers and column headers insert, delete and clear.
• The fill handle copies a single cell (with Ctrl, a number counts up by 1). From two or more cells that form a series of numbers or dates (including weekdays and Japanese date formats), it continues the series (with Ctrl, it copies).
• Dragging the border of a selection moves the cells; Ctrl+drag copies them.
• Ctrl+click adds ranges to the selection.

Filter

The ▾ on each column header (or Alt+Down) filters by a list of values or by text: contains, does not contain, equals, starts with, ends with, blank, not blank. Up to two conditions per column can be combined with AND or OR. Filters and sorting are remembered per file.

Cell colors

Cells, rows, columns or the whole table can be given one of 8 fill and text colors. The colors are stored by ForgeKairos, not in the file.

Compare

Compare the grid with the version at Git HEAD, with another file, or between selected cells, rows or columns. The two sides are shown side by side with cell and character differences highlighted, and the comparison is updated when either side changes. Cells with several lines are compared in full.

Not supported

Formulas, number and date formatting, merged cells, and reordering columns by dragging are not supported.

Remote development

日本語

For connecting to SSH hosts, WSL and containers, see Zed's remote development documentation. This page describes what ForgeKairos changes.

The bundled remote server

ForgeKairos ships a statically linked (musl) remote server for Linux x86_64 and uploads it when you connect, without asking. Because it does not depend on the host's glibc, it works on Linux hosts too old for VS Code's remote server; it has been tested with Ubuntu 18.04. WSL and Docker connections use the same server.

The remote server's files are named forgekairos-remote-server-*. When it cleans up old files on the host, it deletes only ForgeKairos's own files, never those of the official Zed.

One server process per host

Connections from one ForgeKairos to the same host share one server process, and each project is a session inside it. A session ends 10 minutes after its last connection; the process exits 60 seconds after its last session. When it starts, it removes its own leftovers: old state of sessions that are gone, server logs beyond the newest 5, and language server versions not used for 30 days.

Reconnecting

After a network drop or sleep, ForgeKairos reconnects automatically: it retries up to 15 times over about three minutes, and checks the connection as soon as the computer wakes up. A dead connection is detected within about 45 seconds.

Connecting takes fewer round trips: the host's environment is examined in one SSH command and the results are remembered.

Terminals that survive disconnects

On SSH hosts other than Windows, the remote server keeps the shell of each terminal alive (terminal.remote_persistence.enabled, on by default). Commands keep running when the connection drops or ForgeKairos is restarted. When you reconnect, the recent output (up to 4 MiB) is shown again and the terminal continues. The shell ends when you close the tab, or after terminal.remote_persistence.detached_timeout_hours (24) without a terminal attached.

Tasks, agent shells, WSL, Docker and Windows hosts do not use this.

Hosts without internet access

With remote.relay_http_through_client (on by default), the host's downloads (language servers, node, extensions, agent binaries) go through your machine. Language servers can then be installed on a host that cannot reach the internet. The setting applies without reconnecting.

When a language server or formatter is missing, a notification offers to install it (dev_tools.suggest_missing). While connected to a remote host, it is installed on that host.

File watching on Linux

On Linux (locally and on remote hosts), ForgeKairos adds inotify watches only while all of the user's processes together use less than a quarter of the watch limit, and watches the remaining folders by polling. Builds and other tools on the host then do not run out of watches. Changes in polled folders appear a few seconds later.

Old git on the host

Git integration works with old versions of git on the host. See Git.

Git status of untracked files

In very large repositories, git.status_untracked_files set to "normal" or "no" makes git status cheaper. Over SSH, the same value is used on the host.

File transfer

In an SSH project, the terminal's file transfer can use the remote host as its local side; the transfer commands then run on the host. See Terminal macros and sessions.

Settings reference

日本語

This page lists the settings that ForgeKairos adds to Zed, and the Zed settings whose default it changes. The values are those of the bundled assets/settings/default.json. For every other setting, see Zed's configuration documentation.

The outbound network allowlist is not a setting in settings.json; it is kept in network_allowlist.json (see Outbound network control).

Settings added by ForgeKairos

General and layout

Editor and files

C and C++

AI and agents

The agent profiles also gain an Edit Only profile (agent.profiles.edit): it reads and edits files but never runs commands or reaches the network, and leaves out deleting, moving and copying paths. agent.tool_permissions.default accepts a fourth value, "auto" (see AI).

Terminal

Built-in browser

The browser panel uses Microsoft Edge WebView2 on Windows. On other platforms it shows a "not supported" notice and a way to open an external browser.

Remote and development tools

Zed settings with a different default

Building on Windows

日本語

This page summarizes how to build ForgeKairos on Windows. Zed's own build notes are in Zed's development documentation.

Requirements

• Visual Studio 2022 with the C++ workload, MSVC v143, the Spectre-mitigated libraries, the Windows 11 SDK 10.0.26100, and CMake (the copy that comes with Visual Studio works)
• rustup; the toolchain pinned by rust-toolchain.toml and its targets are installed on the first build
• Long paths enabled in Git (core.longpaths) and in Windows (LongPathsEnabled)
• RUSTFLAGS not set
• Plenty of free disk space: a full target folder can exceed 100 GB

Building

powershell -NoProfile -File script\build.ps1            # debug build in target\debug
powershell -NoProfile -File script\build.ps1 -Run       # build, then start it
powershell -NoProfile -File script\build.ps1 -Release   # release build in target\x86_64-pc-windows-msvc\release

The script:

• adds the CMake that comes with Visual Studio to PATH when CMake is missing
• warns when disk space is low
• builds with -j 8 (-Jobs changes it); unlimited parallelism can make rustc run out of memory
• builds the remote server for Linux (x86_64-unknown-linux-musl, statically linked) with zig and cargo-zigbuild, installing them when missing (zig through winget), and places it next to the editor as forgekairos-remote-server-linux-x86_64.gz
• downloads slirp4netns, used by the agent sandbox on remote hosts
• places clang-format.exe in bin\ next to the editor

It writes to target\debug, or target\x86_64-pc-windows-msvc\release with -Release; when CARGO_TARGET_DIR is set, to that folder instead of target.

The editor is ForgeKairos.exe and the command-line tool forgekairos-cli.exe, both in target\debug (or target\x86_64-pc-windows-msvc\release); the command-line tool looks for the editor next to itself. The installer installs the command-line tool as bin\forgekairos.exe; in the build folder it has another name, because Windows does not tell forgekairos.exe from ForgeKairos.exe.

A release build uses the stable channel's data folder, the same one an installed ForgeKairos uses. To keep them apart, start it with --user-data-dir <folder>.

Installer

script\build.ps1 does not make an installer. script\bundle-windows.ps1 does: it makes a release build (for x86_64-pc-windows-msvc, into target\x86_64-pc-windows-msvc\release), builds the Windows remote server, cross-builds the Linux one, adds clang-format with its license and slirp4netns, and runs Inno Setup 6 (winget install JRSoftware.InnoSetup). The installer is written to target\forgekairos-windows-x86_64-setup.exe. Options include -Architecture, -Install (install the result), -ReleaseTag <tag> (the GitHub release tag the build is published under, which the update check compares with), -ClangFormatPath and -Fast (see below). It needs Visual Studio 2022 and network access (it downloads ConPTY, the AMD GPU Services library, slirp4netns and, when missing, zig).

pwsh -NoProfile -File script\bundle-windows.ps1

The installer reuses a release build made by script\build.ps1 -Release: both build the same packages (zed, cli and auto_update_helper in one cargo run) for the same target, in the Visual Studio developer environment, with the release channel set. Anything that differs (a plain cargo build --release, another set of packages, a build outside the developer environment) makes cargo rebuild the C dependencies and the editor. With nothing changed cargo takes seconds; after a commit, which changes the commit hash compiled into the editor, recompiling and linking the editor with the release profile's thin LTO takes about half an hour.

-Fast makes an installer to try out on this machine, not to publish: it builds with the release-fast profile (no LTO, limited debug info) into target\x86_64-pc-windows-msvc\release-fast and compresses with lzma2/fast. Its first run builds every dependency again for that profile, which also takes disk space.

It needs PowerShell 7 (pwsh, winget install Microsoft.PowerShell). Started from Windows PowerShell 5.1 (powershell), it runs itself again under pwsh with the same options, and stops with an explanation when pwsh is not installed.

Other operating systems

script/bundle.ps1 (PowerShell 7; on Linux and macOS also script/bundle, which runs it with pwsh) makes the packages for every operating system from one command. -Os chooses which: windows, linux, macos or all; without it, the system it runs on.

pwsh -NoProfile -File script/bundle.ps1 -Os windows    # script\bundle-windows.ps1, see above
pwsh -NoProfile -File script/bundle.ps1 -Os linux      # on Windows: in Docker inside WSL
pwsh -NoProfile -File script/bundle.ps1 -Os macos -Wait
pwsh -NoProfile -File script/bundle.ps1 -Os all -DryRun

The packages are left in target under the names the update check looks for: forgekairos-windows-x86_64-setup.exe, forgekairos-linux-x86_64.tar.gz, forgekairos-macos-aarch64.dmg and forgekairos-macos-x86_64.dmg, plus the remote servers forgekairos-remote-server-linux-x86_64.gz and forgekairos-remote-server-macos-<arch>.gz.

Like the Windows installer, the Linux and macOS packages carry what SSH, WSL and Docker connections install on a Linux host: the Linux x86_64 remote server (forgekairos-remote-server-linux-x86_64.gz) and slirp4netns-linux-x86_64. Without them the editor would have to download the server, which the default network policy blocks. They sit where the editor looks for them: in libexec/ next to the editor in the Linux package, and in Contents/Resources of the macOS app. clang-format is not included on Linux and macOS: the editor runs the clang-format on PATH, from the distribution's package manager, Homebrew (brew install clang-format) or Xcode.

Options: -Architecture (x86_64 or aarch64 of what is built on this machine; by default this machine's), -MacosArchitecture (both, aarch64 or x86_64: what the workflow builds for macOS; it builds Windows and Linux for x86_64), -ReleaseTag (as for the installer), -Jobs <n> (cargo's -j), -Ci (make everything through the workflow), -Wait (wait for the workflow and download what it made into target/ci-<run id>/), -Ref (the branch or tag the workflow builds; by default the current branch), -DryRun (print the commands instead of running them), and for Windows -Fast, -Install and -ClangFormatPath, which it hands to script\bundle-windows.ps1.

Linux

On Linux, install the build dependencies with script/linux first; the package then links against the host's glibc and runs only on systems with that version or newer. On Windows the script builds in an ubuntu:22.04 container (glibc 2.35) of the Docker in WSL (wsl.exe -e docker), so the package runs on Ubuntu 22.04, Debian 12 and newer. The image installs the dependencies with script/linux and the toolchain of rust-toolchain.toml. -LinuxImage chooses another base image, -Container uses a container on a Linux host too.

The checkout is mounted into the container, so the build uses your working tree (including uncommitted changes). The cargo registry and the target folder live in the Docker volumes forgekairos-bundle-cargo-ubuntu-22.04 and forgekairos-bundle-target-ubuntu-22.04 inside WSL, not under target; remove them with wsl.exe -e docker volume rm to free the space (the target folder takes some tens of GB). The first run builds the image and every dependency; later runs only rebuild what changed.

macOS

macOS packages are made on a Mac (Xcode, script/bundle-mac; zig, brew install zig, to cross-build the Linux remote server with cargo-zigbuild, which the script installs when missing), or by the GitHub Actions workflow below, which script/bundle.ps1 -Os macos starts on any other system with the GitHub CLI (gh workflow run, after gh auth login). The workflow builds the branch as it is on GitHub, so push first. Without signing secrets the app is signed ad hoc and macOS refuses to open the downloaded app the first time: allow it under System Settings, Privacy & Security, "Open Anyway", or remove the quarantine flag with xattr -dr com.apple.quarantine /Applications/ForgeKairos.app. With the secrets MACOS_SIGNING_IDENTITY, MACOS_CERTIFICATE, MACOS_CERTIFICATE_PASSWORD, APPLE_NOTARIZATION_KEY, APPLE_NOTARIZATION_KEY_ID and APPLE_NOTARIZATION_ISSUER_ID set in the repository, it is signed with that Developer ID and notarized.

The release workflow

.github/workflows/forgekairos_release.yml builds on GitHub-hosted runners: Windows x86_64 on windows-2022, Linux x86_64 on ubuntu-22.04, and macOS aarch64 and x86_64 on macos-14 (x86_64 cross-compiled). Each job runs script/bundle.ps1 -Os <os> and uploads its package as an artifact named after the file. It runs only when started (from the Actions tab with the inputs os, macos_arch and release_tag, or by script/bundle.ps1) and when a v* tag is pushed; for a tag, a last job creates a draft GitHub release with all the packages for you to check and publish.

The repository is private, so the workflow uses the account's billed Actions minutes, and macOS minutes count ten times. A full run takes hours per job on the standard runners (a release build with thin LTO), so start only the systems you need (-Os macos, the macos_arch input). The jobs cache the cargo registry and the build with Swatinem/rust-cache, which makes a rerun without dependency changes cheaper; GitHub keeps at most 10 GB of caches per repository and drops the oldest first.

Making a release

1. Choose the tag: v and the version in crates/zed/Cargo.toml (v1.22.0). A pre-release adds a suffix (v1.22.0-pre, v1.22.0-pre.2); a tag with a - is published as a pre-release, which the update check offers only to those who turned on auto_update_include_prereleases. Pass the tag as -ReleaseTag to every build: it is compiled in, and the update check compares the releases on GitHub with it.

2. Build Windows and Linux here:

   pwsh -NoProfile -File script/bundle.ps1 -Os windows -ReleaseTag v1.22.0
   pwsh -NoProfile -File script/bundle.ps1 -Os linux -ReleaseTag v1.22.0
   

3. Build macOS through the workflow (push the commit first; billed minutes): pwsh -NoProfile -File script/bundle.ps1 -Os macos -ReleaseTag v1.22.0 -Wait downloads the disk images and the macOS remote servers into target/ci-<run id>/.

4. Create a draft release and upload the packages under their names (the update check finds them by these names):

   gh release create v1.22.0 --repo SeiyaFunaokaJP/ForgeKairos --draft --target (git rev-parse HEAD) --title "ForgeKairos v1.22.0" --generate-notes
   gh release upload v1.22.0 --repo SeiyaFunaokaJP/ForgeKairos `
       target/forgekairos-windows-x86_64-setup.exe `
       target/forgekairos-linux-x86_64.tar.gz target/forgekairos-remote-server-linux-x86_64.gz `
       (Get-ChildItem -Recurse -File target/ci-<run id>).FullName
   

   Add --prerelease for a pre-release. Check the draft, then publish it on GitHub, which creates the tag.

Pushing the tag instead (git push origin v1.22.0) makes the workflow build every system and create the draft release itself; that costs the most minutes. Publishing a draft creates the tag, which can start the workflow too: cancel that run (gh run cancel) when the packages are already uploaded.

The update check reads the releases without signing in, so it sees nothing while the repository is private.

Checks

The upstream rules still apply: use ./script/clippy rather than cargo clippy. For translation checks, see locales/README.md.

Known limitations

日本語

Platforms

• ForgeKairos is developed and tested on Windows. The macOS and Linux packages have not been built or tested.
• The built-in browser panel needs Microsoft Edge WebView2 and works only on Windows.
• The bundled remote server is for Linux x86_64 hosts.
• On Windows 11, Open with ForgeKairos may appear only under "Show more options".
• Collaboration (calls and screen sharing) is not included.

Network control

• The proxy given to agents and MCP servers works only for programs that read the proxy environment variables.
• The allowlist does not restrict the editor's own tools (language servers, extensions, updates, Git) or, by default, the built-in browser.
• Outside the sandbox, an agent's network is restrained only as far as it honors the proxy settings.

Translation

• Text sent to language models and log messages stay English.
• Some labels, such as tab titles, switch language only after a restart.
• A remote server uses one display language for all clients connected to it.

C and C++

• The symbol index matches by name: a result can be an unrelated symbol of the same name. Results from the index are marked as name matches.
• After a language server restart, diagnostics for files that no one has open stay cleared. "Restart All Servers" with no file open leaves the servers stopped.
• With clangd.index_mode = "light", references, call hierarchy and renames cover only open files.

Remote development

• Terminals that survive disconnects work only on SSH hosts other than Windows, and not for tasks or agent shells.
• Folders watched by polling on Linux show external changes a few seconds late.

Markdown, Mermaid and CSV

• Text colors and sizes use HTML style attributes, which GitHub does not render.
• Editing Mermaid labels by double-clicking in the preview works only for flowcharts, ER, state, class, sequence, pie and Gantt diagrams. The structured editor refuses to open a diagram whose syntax it cannot reproduce.
• The CSV grid has no formulas, number or date formatting, merged cells, or column reordering by dragging.