---
title: "Usage"
manual: "AI Cowriter for TYPO3"
version: "3.1"
permalink: "https://docs.typo3.org/permalink/netresearch/t3-cowriter:usage@3.1"
source: "Usage/Index.rst"
rendered: "2026-09-27T04:02:08+00:00"
---

# Usage {#usage}

## Using the AI Cowriter {#using-the-ai-cowriter}

Once the extension is installed and configured:

1.  Open any content element with a rich text field in the TYPO3 backend
1.  You will see a new AI Cowriter button in the CKEditor toolbar

![CKEditor toolbar with Cowriter button](../Images/CowriterToolbarButton.png)

1.  Optionally select the text you want to process (or leave empty to use
    the full content element)
1.  Click the Cowriter button — a dialog opens

## Task-based dialog {#task-based-dialog}

![Cowriter task dialog](../Images/CowriterDialogCropped.png)

The Cowriter dialog lets you choose what to do with your content:

-   ****Task selection****

    Choose from predefined tasks like "Improve Text", "Summarize",
    "Extend / Elaborate", "Fix Grammar & Spelling", or translations.
    Each task has a description shown below the dropdown. You can also
    select "Custom instruction" to write a freeform prompt.

-   ****Saved prompts****

    Below the instruction, **Save as prompt** stores the current
    instruction under a title. Your prompts appear in the task list under
    **My prompts**; choosing one fills the instruction, and
    **Delete prompt** next to the description removes it. With
    **Share with other editors**, other editors find the prompt
    under **Shared prompts** once an administrator has approved it
    ([Saved prompts](https://docs.typo3.org/permalink/netresearch/t3-cowriter:configuration-saved-prompts@3.1)). Until then your list marks it
    "awaiting approval". A saved prompt runs as a custom instruction.

-   ****LLM configuration****

    Choose which [LLM configuration](https://docs.typo3.org/p/netresearch/nr-llm/main/en-us/Configuration/ConfigFields.html#configuration-llm) runs
    the task. The first option, "Task setting", keeps the configuration
    the task names, or the default configuration when the task names
    none. The list shows only the configurations your backend groups may
    use; a configuration restricted to other groups is neither listed
    nor accepted. The picker appears once the list has loaded and stays
    hidden when there is nothing to choose.

-   ****Audience, tone of voice and length** (optional)**

    Pick an audience and a tone of voice from the prompt snippets the
    administrator maintains in nr-llm, and a length step from
    **Much shorter** to **Much longer**. They apply to this
    request only. When the page TSconfig sets a target length for the
    content element's type, the length step scales that target, and the
    result shows the word count next to it
    ([Audience, tone and target length](https://docs.typo3.org/permalink/netresearch/t3-cowriter:configuration-style@3.1)).

-   ****Versions****

    Ask for one, two or three versions. With more than one, a choice above
    the result switches between them, and **Insert** takes the one
    shown. Several versions arrive together, not while they are written.

-   ****Tools** (off by default)**

    With **Let the AI look up content with tools that change
    nothing**, the model may call the nr-llm tools that run without an
    approval, for example to search the site's content, before it answers.
    A tool of the site that changes content needs an approval in nr-llm,
    and the dialog has no step to give one, so it is not offered. A tool
    from a remote MCP server is judged by what its operator declares: only
    one declared as needing approval is left out. Which tools a
    backend user may use is set in nr-llm; with none left, the task runs
    without tools. The answer is not streamed and comes as one version;
    the result line names the number of tool steps.

-   ****Context scope****

    Control how much context the AI receives:

    -   **Selection** — only the highlighted text (pre-selected when
        you have a selection)
    -   **Full content** — the entire editor content
    -   **Content element** — the full tt_content record
    -   **Page content** — all content on the current page
    -   **Parent page** / **Grandparent page** — include ancestor
        page content for broader context

    Options that require a record context (Content element and above)
    are disabled when the record cannot be detected.

-   ****Reference pages** (optional)**

    Add pages whose content should be included as reference material.
    Search by title or UID, and specify a relation label (e.g.,
    "style guide", "reference material").

-   ****Additional instructions** (optional)**

    Add ad-hoc rules for the current request, e.g., "Write in formal
    tone" or "Keep sentences short".

-   ****Execute and preview****

    Click **Execute** to send the request to the LLM. The answer
    appears in the preview while the model writes it; when it is
    complete, the preview shows the final text with the model name. You
    can then:

    -   Click **Insert** to replace the content in the editor
    -   Click **Reset** to clear the result and adjust settings
    -   Click **Execute** again to refine the result (the
        previous output becomes the new input)
    -   Click **Cancel** to discard

## Available tasks {#available-tasks}

[Tasks](https://docs.typo3.org/p/netresearch/nr-llm/main/en-us/Configuration/TaskFields.html#configuration-tasks) are configured in the
nr-llm extension (`tx_nrllm_task` table) with
`category = 'content'`. The following default tasks are provided:

| Task | Description |
| --- | --- |
| Improve Text | Enhance readability and quality while preserving meaning |
| Summarize | Create a concise summary of the content |
| Extend / Elaborate | Add depth, detail, and examples |
| Fix Grammar & Spelling | Correct grammar and spelling with minimal changes |
| Translate to English | Translate content to English |
| Translate to German | Translate content to German |

> [!TIP]
> You can add custom tasks by creating new records in
> **Admin Tools** \> **LLM Management** with
> `category = 'content'`. Use `{{input}}` in the prompt template
> as placeholder for the user's content.

## Inline translation {#inline-translation}

The **Translate** dropdown in the CKEditor toolbar lets you translate
selected text without opening the full dialog.

1.  Select the text you want to translate
1.  Click the Translate button (globe icon) in the toolbar
1.  Choose the target language from the dropdown
1.  A notification confirms the translation is in progress
1.  The selected text is replaced with the translation

Supported languages:

-   German, English, French, Spanish, Italian
-   Dutch, Portuguese, Polish, Japanese, Chinese

The translation uses the default
[LLM configuration](https://docs.typo3.org/p/netresearch/nr-llm/main/en-us/Configuration/ConfigFields.html#configuration-llm) from the
nr-llm extension. Administrators can optionally pass a
`configuration` parameter via the API to route translations
through a specific LLM provider (e.g. DeepL or a dedicated
translation model).

> [!NOTE]
> Inline translation requires text to be selected. A warning
> notification appears if no text is selected. For translating
> entire content elements, use the task-based dialog instead.

> [!TIP]
> Translation preserves HTML formatting. If you select bold or
> linked text, the formatting is maintained in the translated
> output.

## Alt text generation {#alt-text-generation}

The **Vision** button (image icon) generates alt text for images using
LLM vision analysis.

1.  Click on an image in the editor to select it
1.  Click the Vision button in the toolbar
1.  A notification confirms the analysis is in progress
1.  The alt text is set on the image automatically

> [!NOTE]
> You must select an image before clicking the Vision button.
> A warning notification appears if no image is selected.

> [!TIP]
> This is useful for accessibility compliance — generate descriptive
> alt text for images without leaving the editor.

## Tasks shortcut {#tasks-shortcut}

The **Tasks** dropdown (document icon) lets you open the Cowriter
dialog with a specific task pre-selected, skipping the task selection
step.

1.  Click the Tasks button (document icon) in the toolbar
1.  Select a task from the dropdown (tasks are loaded from nr-llm)
1.  The Cowriter dialog opens with the chosen task pre-selected
1.  Review, optionally adjust instructions, and execute

Tasks are loaded once when you first open the dropdown and cached for
the duration of the editing session. If you create new tasks in the
LLM module, reload the page to see them in the dropdown.

> [!NOTE]
> If no tasks with `category = 'content'` are configured, a
> notification guides you to the LLM module to create them.

## Field suggestions {#usage-field-suggestions}

Outside the rich text editor, the **Suggest values with AI** button
(light bulb icon) next to a form field asks the LLM for alternative
values. By default it sits next to these page properties:

-   **SEO** \> **Title for search engines**
    (`pages.seo_title`, only with the system extension `seo`)
-   **SEO** \> **Description** (`pages.description`)
-   **SEO** \> **Keywords** (`pages.keywords`)
-   **General** \> **URL Segment** (`pages.slug`)

1.  Click the light bulb button next to the field (or focus it and press
    `Enter` or `Space`)
1.  The suggestions appear in a list below the field; by default there
    are three
1.  Click a suggestion (or move to it with the arrow keys and press
    `Enter`) to insert it into the field; the cursor moves into the
    field
1.  Save the record to keep the value

![Page properties, SEO tab: three AI suggestions listed below the Title for search engines field, with a close button and a status line under the list](../Images/Usage/FieldSuggestionsSeoTitle.png)

Nothing is saved automatically: a picked suggestion only changes the form,
exactly as if you had typed it, and `Escape` closes the list without
changing anything.

The suggestions are generated from the page title, the current value of
the field (including text you typed but have not saved yet) and the text
of the content elements on the page. In a workspace, the page and its
content elements are read as they look in your workspace; drafts of other
workspaces are never used. They follow the length guidance of
the field: at most 60 characters for the SEO title and 160 characters for
the description; keywords are a comma-separated list. For the URL segment
the AI only proposes the words of the last path segment. TYPO3 adds the
parent page path and turns the words into a valid URL segment. It checks
that the URL segment is unique the same way as for a segment you type in.

The button only appears for fields you may edit, and the server checks
your permissions again for every request: you need write access to the
table, access to the field if it is an exclude field, and edit rights on
the page (for a new page: the right to create pages below the parent
page).

Categories are not filled by the button. For tags, use the
**Keywords** suggestions and copy the terms you want to use.

## Model override {#model-override}

You can override the default model for a specific prompt by using the
`#cw:` prefix followed by the model identifier:

```text
#cw:gpt-5.2-thinking Write a detailed technical analysis of our API architecture
```

The model name must match a model available in your configured LLM provider.
Valid model names follow the pattern: alphanumeric characters, hyphens, underscores,
dots, colons, and forward slashes.

> [!TIP]
> This feature is useful for switching to a reasoning model (like `gpt-5.2-thinking`
> or `claude-opus-4-5`) for complex prompts while keeping a faster model as the default.