Files
zed/docs
Frederick Morlock 9a8ab54db4 agent: Allow auto title generation to be disabled (#63998)
# Objective

The objective of this PR is to add a configuration option to disable
automatic title generation for agent threads. This feature is desirable
for users (e.g. as discussed in #63701) with token-based or compute
constraints as it can prevent unnecessary (for some) overhead from title
generation in addition to unnecessary large cache misses.

My personal motivation is that automatic title generation pushes my
entire context to my compute backend, which is a complete cache miss
because (it appears) the prefix to the prompt is different. Whether it
is intentional or not, automatic title generation can fire concurrent to
actual generation (see Misc Notes [1]), slowing down my machine (and the
output) considerably.

## Solution

This PR adds a configuration option, which is exposed in the UI as well
as through the standard settings.json channels, to disable automatic
title generation. It's worth noting that manual title generation, as
well as manual thread renaming, is still preserved. The configuration
merely disables the _automatic_ title generation when the option is
enabled.

Ignoring the code for setting up the configuration option, this PR
effectively adds a single condition to the `generate_title` call in
`thread.rs` (in `run_turn_internal` that constitutes the automatic title
generation. To my knowledge, this is what constitutes the "automatic
title generation" and in the situation where I've seen it triggered
reliably, it is no longer triggered when the disabling option is set.

## Testing

- Did you test these changes? If so, how?
- _Yes. I tested the functionality manually through disabling the
"Auto-Generate Thread Titles" option in the Settings UI and triggering
the condition where I knew automatic title generation would fire
(described in Misc Notes [1]). I also tested manual title renaming and
the "Regenerate thread title" function to ensure those functions were
not affected. I also ran `cargo test --workspace`, which succeeded, and
did UI regression tests (although it appears that my settings menu
changes were not covered by them, since they did not fail when I didn't
update the baseline)_
- _I also added automated tests for the feature, as well as tests to
ensure that manual title generation is not affected._
- Are there any parts that need more testing?
- _I was unable to fully test "Regenerate thread title" because it seems
incompatible with my local LLM (it gets updated to a blank string after
the compute backend returns). This is the case with the latest stable
Zed (v1.19.2) and does not constitute a regression in my eyes. The
automated tests I wrote should cover any regressions for users with a
fully functional "Regenerate thread title" button._
- How can other people (reviewers) test your changes? Is there anything
specific they need to know?
- _Try to trigger automatic title generation with "Auto-Generate Thread
Titles" enabled and disabled. You can verify that manual title
generation ("Regenerate Thread Title") and manual title renaming also
works._
- _It's worth noting that hosting my own compute backend (oMLX) was
crucial in discovering and diagnosing this problem. If a tester does not
have access to this, they will need to find another method of knowing if
the `generate_title` method fires (such as a simple `println!`)._
- If relevant, what platforms did you test these changes on, and are
there any important ones you can't test?
- _**I only tested my changes on macOS 27 beta**, although the change
set should be platform agnostic._

## Self-Review Checklist:

- [X] I've reviewed my own diff for quality, security, and reliability
- [X] Unsafe blocks (if any) have justifying comments
- [X] The content adheres to Zed's UI standards
([UX/UI](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md#uiux-checklist)
and
[icon](https://github.com/zed-industries/zed/blob/main/crates/icons/README.md)
guidelines)
- [X] Tests cover the new/changed behavior
- [X] Performance impact has been considered and is acceptable

## Showcase

I have provided a screenshot of the location of the new toggle below

<details>
  <summary>Click to view screenshot of Settings page</summary>
<img width="1012" height="863" alt="Screenshot 2026-09-09 at 9 41 27 PM"
src="https://github.com/user-attachments/assets/5dd14f38-8cd1-46d1-b5bf-f2a6fb68c628"
/>

Above is a screenshot of the placement of the new Settings Menu item
("Auto-Generate Thread Titles"). It is disabled, which is not the
default.

</details>

## Misc Notes

[1]: My "sure fire" way of triggering the automatic title generation (at
an inconvenient time) is to stop a prefill request after sending a
message in an existing thread (which will trigger the automatic title
generation) then resend the message. Perhaps a healthier behaviour would
be to cancel in-progress title generation if another generation request
come in, but I think it is advantageous to give users an option to
disable automatic title generation regardless.

**LLM-Use Disclosure:** I used an LLM to assist in isolating the part of
the code responsible for automatic title generation triggering and
generating a portion of the code I am posting here. I have thoroughly
understood, checked, and tested the code which I am submitting manually,
and take full professional responsibility for its quality. I have added
a `Signed-off-by` section to my commit message to indicate my signing
off, and a `Co-Authored-By` section to indicate LLM use.

**No LLM was used in the writing of this PR text or commit message.**

Thank you! Please let me know if you want me to change anything.

---

Release Notes:

- Feature: Added a configuration option to disable automatic title
generation for agent threads

---------

Signed-off-by: Frederick Morlock <me@freddy.us>
Co-authored-by: Hennadii Chernyshchyk <genaloner@gmail.com>
Co-authored-by: Smit Barmase <heysmitbarmase@gmail.com>
2026-11-06 19:51:13 +00:00
..
2026-07-23 05:26:09 +00:00
…

Zed Docs

Welcome to Zed's documentation.

This is built on push to main and published automatically to https://zed.dev/docs.

To preview the docs locally you will need to install mdBook (cargo install mdbook@0.4.40), generate the action metadata, and then serve:

script/generate-action-metadata
mdbook serve docs

The first command dumps an action manifest to crates/docs_preprocessor/actions.json. Without it, the preprocessor cannot validate keybinding and action references in the docs and will report errors. You only need to re-run it when actions change.

If you use Nix, the development shell provides a pinned mdbook (0.4.40) and a prebuilt docs preprocessor, so you can build the docs without installing anything or compiling the preprocessor on every run:

nix develop -c mdbook build docs

(When actions.json has not been generated, action/keybinding validation is skipped with a warning rather than failing the build.)

It's important to note the version number above. For an unknown reason, as of 2025-04-23, running 0.4.48 will cause odd URL behavior that breaks things.

Before committing, verify that the docs are formatted in the way Prettier expects with:

cd docs && pnpm dlx prettier@3.5.0 . --write && cd ..

Preprocessor

We have a custom mdBook preprocessor for interfacing with our crates (crates/docs_preprocessor).

If for some reason you need to bypass the docs preprocessor, you can comment out [preprocessor.zed-docs-preprocessor] from the book.toml.

Images and videos

To add images or videos to the docs, upload them to another location (e.g., zed.dev, GitHub's asset storage) and then link out to them from the docs.

Putting binary assets such as images in the Git repository will bloat the repository size over time.

Internal notes:

  • We have a Cloudflare router called docs-proxy that intercepts requests to zed.dev/docs and forwards them to the "docs" Cloudflare Pages project.
  • The CI uploads a new version to the Cloudflare Pages project from .github/workflows/deploy_docs.yml on every push to main.

Table of Contents

The table of contents files (theme/page-toc.js and theme/page-doc.css) were initially generated by mdbook-pagetoc.

Since all this preprocessor does is generate the static assets, we don't need to keep it around once they have been generated.

Referencing Keybindings and Actions

When referencing keybindings or actions, use the following formats:

Keybindings

{#kb scope::Action} - e.g., {#kb zed::OpenSettings}.

This will output a code element like: <code>Cmd + , | Ctrl + ,</code>. We then use a client-side plugin to show the actual keybinding based on the user's platform.

By using the action name, we can ensure that the keybinding is always up-to-date rather than hardcoding the keybinding.

Keymap Overlays

{#kb:keymap_name scope::Action} - e.g., {#kb:jetbrains editor::GoToDefinition}.

This resolves the keybinding from a keymap overlay (e.g., JetBrains) first, falling back to the default keymap if the overlay doesn't define a binding for that action. This is useful for sections where the documentation expects a special base keymap to be configured.

Supported overlays: jetbrains.

Actions

{#action scope::Action} - e.g., {#action zed::OpenSettings}.

This will render a human-readable version of the action name, e.g., "zed: open settings", and will allow us to implement things like additional context on hover, etc.

Creating New Templates

Templates are functions that modify the source of the docs pages (usually with a regex match and replace). You can see how the actions and keybindings are templated in crates/docs_preprocessor/src/main.rs for reference on how to create new templates.

The consent banner is the markup in theme/index.hbs, driven by theme/analytics.js. That script loads c15t.js from our Inth backend (DOCS_CONSENT_IO_INSTANCE) with c15t's stock UI turned off. Inth serves the c15t version our hosted backend runs, so there is no bundle to update in this repo. The banner only appears when DOCS_CONSENT_IO_INSTANCE is set.

References

  • Template Trait: crates/docs_preprocessor/src/templates.rs
  • Example template: crates/docs_preprocessor/src/templates/keybinding.rs
  • Client-side plugins: docs/theme/plugins.js

Postprocessor

A postprocessor is implemented as a sub-command of docs-preprocessor that wraps the built-in HTML renderer and applies post-processing to the HTML files, to add support for page-specific title and meta tag description values.

An example of the syntax can be found in git.md, as well as below:

---
title: Some more detailed title for this page
description: A page-specific description
---

# Editor

The above code will be transformed into (with non-relevant tags removed):

<head>
  <title>Editor | Some more detailed title for this page</title>
  <meta name="description" contents="A page-specific description" />
</head>
<body>
  <h1>Editor</h1>
</body>

If no front matter is provided, or if one or both keys aren't provided, the title and description will be set based on the default-title and default-description keys in book.toml respectively.

Implementation details

Unfortunately, mdBook does not support post-processing like it does pre-processing, and only supports defining one description to put in the meta tag per book rather than per file. So in order to apply post-processing (necessary to modify the HTML head tags) the global book description is set to a marker value #description# and the HTML renderer is replaced with a sub-command of docs-preprocessor that wraps the built-in HTML renderer and applies post-processing to the HTML files, replacing the marker value and the <title>(.*)</title> with the contents of the front matter if there is one.

Known limitations

The front matter parsing is extremely simple, which avoids needing to take on an additional dependency, or implement full YAML parsing.

  • Double quotes and multi-line values are not supported, i.e. Keys and values must be entirely on the same line, with no double quotes around the value.

The following will not work:

---
title: Some
  Multi-line
  Title
---

neither this:

---
title: "Some title"
---
  • The front matter must be at the top of the file, with only white-space preceding it.
  • The contents of the title and description will not be HTML escaped. They should be simple ASCII text with no unicode or emoji characters.