feat: Compact CoT display

[RoyBA]

Summary

Adds two new [UI] config options (cot_display and show_step_details) that give app developers control over how Chain of Thought steps are displayed in the chat interface.

Motivation

When an agent uses many tools sequentially, the default "list" display creates a long vertical stack of individual step accordions. This can overwhelm users who only care about the final result. The new compact mode provides a ChatGPT-style collapsible summary.

New Config Options

Added to .chainlit/config.toml under [UI]:

Option	Values	Default	Description
cot_display	"list" | "compact"	"list"	list = current behavior (each step as its own accordion). compact = all steps collapsed into one summary line.
show_step_details	true | false	true	When false, steps render as flat labels without expandable input/output.

Compact Mode Behavior

• Shows animated "Using {tool_name}" label while the run is active
• Shows "Used N steps" (or "Used N tools" in tool_call cot mode) when complete
• Clicking expands to reveal individual steps in a bordered list
• Only activates when there are 2+ visible steps (single steps render normally)
• Includes avatar matching the Message component pattern
• Works with nested agent architectures (LangChain, LangGraph, LlamaIndex) where tools are wrapped under intermediate run steps

Changes

Backend:

• config.py — Added cot_display and show_step_details to UISettings model + TOML template
• translations/*.json — Added usedSteps and usedTools keys to all 23 language files

Frontend:

• messageContext.ts / MessageContext.tsx — Added cotDisplay and showStepDetails to context
• MessagesContainer/index.tsx / ReadOnlyThread.tsx — Wire config values into context
• Messages/index.tsx — Compact mode branching logic for CL_RUN_NAMES handler
• Messages/CompactSteps.tsx — New component for compact step summary
• Messages/Message/Step.tsx — Respect showStepDetails to render flat label

Types:

• libs/react-client/src/types/config.ts — Added TS types for new config fields

Testing

• Backend: 784 tests pass (4 pre-existing failures unrelated to this PR)
• Frontend: 32 unit tests pass
• ESLint: Clean
• Prettier: Clean
• Manual: Tested with a 5-tool sequential demo app and a LangGraph ReAct agent in both list and compact modes

Backward Compatibility

Both options default to the existing behavior (list / true). No breaking changes — apps without these config keys behave identically to before.

⚠️ Translations: Existing apps with local .chainlit/translations/ files will see lint warnings for the new usedSteps/usedTools keys on startup. This only affects users who opt into cot_display = "compact". To pick up the new keys, delete the local .chainlit/translations/ folder and restart — Chainlit will regenerate it from the updated source. This follows the same pattern as all prior translation additions in this project.

---

Summary by cubic

Adds a compact Chain of Thought display with a toggle to hide step details, reducing chat clutter. Compact mode shows “Using …” until the assistant answer starts to avoid flicker.

• New Features

  • [UI] config: cot_display = "list" | "compact" (default "list"), show_step_details = true | false (default true).
  • Compact mode: shows “Using {tool}” until the answer begins, then “Used N steps/tools”; expands on click; only when 2+ visible steps; counts nested steps; supports nested agent runs.
  • Frontend/backend/types: new CompactSteps component; context adds cotDisplay and showStepDetails; Step honors showStepDetails; ReadOnlyThread respects features.latex and dataPersistence; TS types updated.
  • Translations: added usedSteps/usedTools across all locales; Dutch usedTools updated to “hulpmiddelen”; improved pt‑PT orthography.
  • Tests: added Cypress E2E coverage for compact display (collapse/expand, single-step passthrough, nested counting) with stable data-testid hooks.
  • UI polish: added small margin to step and accordion triggers for better spacing.

• Migration

  • No breaking changes. Defaults keep the current UI.
  • To enable: set [UI] cot_display = "compact" (and optionally show_step_details = false) in .chainlit/config.toml.
  • If you have a local .chainlit/translations/ folder, delete it to regenerate and pick up usedSteps/usedTools.

^{Written for commit 62d4d7a. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 32 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[github-actions]

This PR is stale because it has been open for 14 days with no activity.

[liebki]

This looks nice!

[github-actions]

This PR is stale because it has been open for 14 days with no activity.

[dokterbob]

Nice job, very comprehensive, cool/useful new feature!

However, to be able to maintain it, we really kinda need ... E2E tests.
Any chance you could add a substantial/comprehensive E2E test for this feature? 🥺 🙏🏼

[cubic-dev-ai]

All reported issues were addressed across 5 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[RoyBA]

Nice job, very comprehensive, cool/useful new feature!

However, to be able to maintain it, we really kinda need ... E2E tests. Any chance you could add a substantial/comprehensive E2E test for this feature? 🥺 🙏🏼

Thanks! 🙏 Just pushed a comprehensive E2E test (compact_steps) covering:

• multiple steps collapsing into one summary + expanding on click
• a single step staying uncollapsed
• nested steps counted recursively to trigger compact mode

I also added data-testid hooks to CompactSteps for stable selection. All 3 specs pass locally. Let me know if you'd like any additional cases covered!

---

[dokterbob]

Thanks! My time is limited... if 1 or (ideally) 2 community members could take this for a spin and report their experiences here I'd super appreciate! @liebki @lamylio perhaps?

@RoyBA Thanks for your responsiveness!

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[dokterbob]

@codex review

[lamylio]

Thanks for the work on this, I tested it a bit and yup! I think it's a better way to display steps than before.

However I found two edge issues / unexpected (imo) behavioural difference :

1. Nested assistant messages are visible by default, but hidden in compact mode

Test code snippet (part-of) :

@cl.step(type="tool", name="answering-agent")
async def answering_agent():
    await tool1();
    await tool2();
    await cl.Message(content="Nested final answer").send()

@cl.on_message
async def main(_message: cl.Message):
    await answering_agent();

In the existing list display, Message deliberately renders assistant-message children outside their parent step accordion. Consequently, an assistant reply remains visible even when the step that produced it is collapsed. (great)

Image 1: List mode (works properly)

In compact mode, non-message descendants are rendered inside CompactSteps’ accordion, while only direct message children are rendered outside it. An assistant message whose parent_id refers to a nested step therefore remains inside the compact accordion and is invisible until the summary is expanded.

Image 2 : Compact mode (unexpected)

2. Nested steps disappear completely with show_step_details = false

@cl.step(type="tool", name="branch")
async def branch():
    await leaf()
    return "Branch result"

@cl.step(type="tool", name="root")
async def root():
    await branch()
    return "Root result"

@cl.on_message
async def main(_message: cl.Message):
    await root()
    await cl.Message(content="Final answer").send()

With the default show_step_details = true, root, branch, and leaf remain accessible by expanding their respective parent steps. When the option is set to false the parent is rendered as a flat label and its child steps are no longer rendered, at all.

I personally would expect this option to remove the input/output accordion details while preserving the visible step hierarchy (or at least on one level), since the default behavior exposes those nested steps.

[dokterbob]

Thanks for extensive feedback @lamylio. @RoyBA What do you think of their suggestions/feedback?