limbo-code 0.1.0__tar.gz → 0.1__tar.gz

{limbo_code-0.1.0 → limbo_code-0.1}/.github/workflows/test.yml

@@ -17,14 +17,20 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          cache: pip
 
+      # Install from uv.lock so CI renders snapshots with the exact same
+      # textual/rich/syrupy versions the baselines were generated with.
       - name: Install dependencies
-        run: pip install -e ".[dev]"
+        run: uv sync --frozen --extra dev
+        env:
+          UV_PYTHON: ${{ matrix.python-version }}
 
       - name: Run tests
-        run: python -m pytest -v
+        run: uv run python -m pytest -v

{limbo_code-0.1.0 → limbo_code-0.1}/.gitignore

@@ -11,3 +11,4 @@ venv/
 dist/
 build/
 .pi-subagents/
+snapshot_report.html

{limbo_code-0.1.0 → limbo_code-0.1}/AGENTS.md

@@ -44,17 +44,25 @@ src/limbo/
 └── ui/
     ├── app.py              # Textual App subclass (CSS_PATH = app.tcss)
     ├── app.tcss            # Centralized stylesheet for the whole TUI
+    ├── theme.py            # limbo-dark / limbo-light Theme definitions (RFC LIM-16 palette)
+    ├── syntax.py           # Pygments styles matching the theme palette (tool-card highlighting)
+    ├── contrast.py         # WCAG contrast checker over the theme palettes
     ├── commands.py         # SlashCommandRegistry: menu metadata + dispatch in one place
     ├── screens/
     │   └── main.py         # Single-column chat screen + event handling + slash commands
     │   └── session_picker.py # Modal session switcher (/sessions)
+    │   └── model_picker.py   # Modal model switcher (/model), grouped by provider
     └── widgets/
-        ├── chat.py         # Chat flow: user/assistant(Markdown)/tool cards/errors
+        ├── chat.py         # Chat flow: user/assistant(Markdown)/tool cards/errors + scroll-follow
         ├── input.py        # Multi-line user input
-        ├── status_bar.py   # Top status bar: agent state + model/workdir
+        ├── status_bar.py   # Top status bar: spinner state + elapsed + tokens + model/workdir
         ├── tool_card.py    # Inline tool-call card (one-line summary, expandable)
         └── confirm.py      # Confirmation modal (ConfirmDialog, Confirmed/Rejected events)
 
+scripts/
+├── check_contrast.py       # Palette contrast report/CI gate (P2-3)
+└── ui_walkthrough.py       # Render 5 key UI states to SVG for visual review (§7.4)
+
 tests/
 ├── test_models.py
 ├── test_config.py
@@ -85,8 +93,8 @@ tests/
 
 ## AgentLoop Details
 
-- `Agent.run()` yields `AgentEvent` types: `TextDelta`, `ToolCallRequest`, `ToolResultEvent`, `ErrorEvent`
-- The loop respects `config.llm.max_iterations` (default 10)
+- `Agent.run()` yields `AgentEvent` types: `TextDelta`, `ThinkingDelta`, `ToolCallRequest`, `ToolResultEvent`, `ErrorEvent`, `UsageUpdate` (cumulative session token count, emitted after each LLM call)
+- The loop respects `config.llm.max_iterations` (default 50)
 - Multi-tool calls in a single assistant turn are executed sequentially
 - When a tool requires confirmation, placeholder `role="tool"` messages are inserted for all remaining calls in that turn so the message history stays valid for the OpenAI API
 - After a confirmed tool is applied, `Agent.continue_after_confirmation()` resumes the loop, first executing remaining placeholders, then returning to the LLM
@@ -123,36 +131,48 @@ api_key = "..."           # Required
 model = "deepseek-chat"   # Default
 base_url = "https://api.deepseek.com/v1"
 temperature = 0.2
-max_iterations = 10
+max_iterations = 50
 
 [tools]
 bash_enabled = true
 
 [ui]
-theme = "textual-dark"   # optional Textual built-in theme name
+theme = "limbo-dark"     # optional: limbo-dark (default) / limbo-light / any Textual built-in
+show_banner = true       # startup ASCII art on fresh sessions
 
 [safety]
 dangerous_commands = ["rm", "git reset --hard"]
 sensitive_files = [".env", "id_rsa", "id_ed25519", ".ssh"]
+
+[providers.glm]      # optional per-provider override (base_url / api_key /
+base_url = "..."     # api_key_env / headers); beats the global [llm] values
 ```
 
 ## UI Layout
 
 Pi-style single-column layout (top to bottom):
-- **Status bar (1 line)**: Agent state on the left (`● idle / thinking… / running <tool>…`), model + workdir on the right
+- **Status bar (1 line)**: Agent state on the left (`● idle`, or animated `⠋ thinking… / running <tool>…` with elapsed seconds), model + cumulative tokens + workdir on the right
 - **Chat flow**: The conversation as a single scrolling stream — user messages (`❯` prefix), assistant replies rendered as streaming Markdown, inline tool-call cards (`✓/⏸/✗` one-line summaries, click or `ctrl+o` to expand full output), error lines
 - **Input box**: The only persistent rounded border on screen; Enter submits, Shift+Enter inserts a newline
 - **Hint line (1 line)**: Key hints in muted color
 
 Confirmation modal: `ConfirmDialog` shows tool output with `y`/`n`/`Esc` shortcuts and "Apply"/"Reject" buttons.
 
-All styles live in `ui/app.tcss`; widgets do not define `DEFAULT_CSS`. The theme is configurable via `[ui] theme` in `config.toml` (Textual built-in theme names).
+All styles live in `ui/app.tcss`; widgets do not define `DEFAULT_CSS`. Colors must
+reference theme semantic variables only (no bare hex; 2048 tiles and the mascot
+banner art are exempt). The palette and per-state color rules are defined in
+`ui/theme.py` (RFC LIM-16): `limbo-dark` is the default, `limbo-light` is also
+built in, and `[ui] theme` can select any Textual built-in theme — custom CSS
+variables fall back to the limbo-dark values via `App.get_theme_variable_defaults()`.
+Run `python scripts/check_contrast.py` after touching the palette: all *used*
+text/background pairs must stay ≥ 4.5:1.
 
 ## Key Design Decisions
 
 - **No provider field**: Provider is inferred from `base_url`, `model`, `api_key`
 - **Async Agent, sync tools**: Tools run via `asyncio.to_thread()` — they are synchronous by default but executed in a thread pool
 - **Session persistence**: Full conversation history rewritten on each save (safe for MVP-scale conversations). Sessions are resumable — see [docs/session-management.md](./docs/session-management.md): `limbo --continue` / `--resume <id>`, and in-TUI `/sessions`, `/new`, `/export` commands
+- **Runtime model switching**: `/model` (picker or direct arg) rebuilds the LLM client mid-session — `MainScreen` sets `config.llm.model` first, then `agent.update_llm()` re-resolves the spec (context window, vision gate, compaction budget); the choice is written back to `config.toml` via tomlkit (comment-preserving, `save_model_to_config`). Busy turns refuse the switch
 - **System message**: Built into `Agent._init_system_message()` — tool descriptions and guidelines are hardcoded
 - **Bash safety filter**: Heuristic only — tokenizes the command, checks against pattern list. Known bypass vectors (subshells, command substitution, variable indirection) are documented.
 
@@ -162,9 +182,13 @@ All styles live in `ui/app.tcss`; widgets do not define `DEFAULT_CSS`. The theme
 pytest tests/ -v                     # all tests
 ruff check src tests                 # lint
 mypy src                             # type check (strict=false)
+python scripts/check_contrast.py     # palette WCAG contrast gate
+python scripts/ui_walkthrough.py     # export key UI states as SVGs to docs/assets/walkthrough/
 ```
 
-Tests use `pytest-asyncio` for async tests, `respx` for HTTP mocking (LLM client), and temp directories for tool tests.
+Tests use `pytest-asyncio` for async tests, `respx` for HTTP mocking (LLM client),
+temp directories for tool tests, and `pytest-textual-snapshot` for UI snapshots
+(`pytest --snapshot-update` after intentional visual changes; review the SVG diff).
 
 ## Common Patterns
 

limbo_code-0.1/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: limbo-code
+Version: 0.1
+Summary: A minimal terminal AI coding agent
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=1.30
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pygments>=2.17
+Requires-Dist: textual>=8.0
+Requires-Dist: toml>=0.10
+Requires-Dist: tomlkit>=0.13
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-textual-snapshot>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pygments>=2.17; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Limbo
+
+A minimal terminal AI coding agent.
+
+## Install
+
+Requires Python 3.11 or later.
+
+```bash
+pip install -e .
+```
+
+## Configure
+
+Create `~/.limbo/config.toml`:
+
+```toml
+[llm]
+api_key = "your-api-key"
+model = "deepseek-chat"
+base_url = "https://api.deepseek.com/v1"
+```
+
+Limbo speaks to LLMs through a **provider/model catalog**
+(`src/limbo/llm/catalog.py`). Each provider declares its API dialect,
+endpoint, and credential env var; each model carries its own context window,
+max output tokens, and thinking/reasoning behavior. A client factory
+(`src/limbo/llm/factory.py`) picks the client implementation from the
+provider's API dialect, so non-OpenAI dialects can be added without touching
+call sites. Models not in the catalog fall back to generic
+OpenAI-compatible defaults driven by `base_url` + `model` + `api_key`.
+
+Built-in providers:
+
+| Provider | API dialect | Endpoint | Key env var |
+|----------|-------------|----------|-------------|
+| `deepseek` | openai-completions | `https://api.deepseek.com/v1` | `DEEPSEEK_API_KEY` |
+| `moonshotai` (Kimi) | openai-completions | `https://api.moonshot.ai/v1` | `MOONSHOT_API_KEY` |
+| `kimi-coding` (Kimi For Coding) | anthropic-messages | `https://api.kimi.com/coding` | `KIMI_API_KEY` |
+| `glm` (GLM Coding Plan) | openai-completions | `https://open.bigmodel.cn/api/coding/paas/v4` | `ZHIPUAI_API_KEY` |
+| `codex` (OpenAI Codex) | openai-responses | `https://api.openai.com/v1` (override with your relay) | `CODEX_API_KEY` |
+
+Built-in Codex models include `gpt-5.5`, `gpt-5.6-sol`/`terra`/`luna`,
+`gpt-5.4`, `gpt-5.4-mini`, and `gpt-5.3-codex-spark`. **`gpt-5.5` is
+verified by live test against the target relay** (its 1M context is
+relay-reported); the other entries mirror pi's built-in catalog and are
+unverified — availability depends on the relay in use, and unknown or
+unsupported models fall back to the generic OpenAI-compatible defaults.
+Codex speaks the
+OpenAI **Responses API** (`POST {base_url}/responses`), served by a
+dedicated client (`src/limbo/llm/responses_client.py`, plain httpx SSE):
+system messages become `instructions`, tool definitions are flattened, and
+reasoning models stream `reasoning` summaries and replay encrypted
+reasoning items across turns. Limbo targets **API-key relays**, not the
+ChatGPT subscription backend (OAuth) — point the provider at your relay
+and make sure its model IDs match the catalog:
+
+```toml
+[llm]
+model = "gpt-5.5"
+
+[providers.codex]
+base_url = "https://my-relay.example.com/v1"
+api_key_env = "CODEX_API_KEY"
+```
+
+Built-in GLM Coding Plan models: `glm-4.7`, `glm-5.1`, `glm-5.2` (1M
+context), `glm-5-turbo`, `glm-5v-turbo` (vision), and `glm-4.5-air`. The
+Coding Plan is a subscription with its own endpoint and keys — a coding-plan
+key only works on the `/api/coding/paas/v4` endpoints (not the pay-per-token
+`/api/paas/v4` ones) and vice versa. For the international endpoint set
+`[providers.glm] base_url = "https://api.z.ai/api/coding/paas/v4"` (see
+below).
+
+Built-in Kimi models include `kimi-k3` (1M context, pay-per-token), and for
+Kimi For Coding subscriptions: `k3` (1M context), `kimi-for-coding`, and
+`kimi-for-coding-highspeed` (256K context). The two use different endpoints
+and keys — a `sk-kimi-*` Kimi For Coding key only works with the
+`kimi-coding` models (`k3`, ...) and vice versa.
+
+Switching to a catalog model only requires changing `model` — the provider's
+endpoint and key env var are picked up automatically:
+
+```toml
+[llm]
+model = "k3"             # Kimi For Coding; base_url/api_key resolve from the catalog
+```
+
+The `anthropic-messages` dialect is served by a dedicated client
+(`src/limbo/llm/anthropic_client.py`, plain httpx SSE) selected by the
+client factory. It converts OpenAI-style tool definitions to Anthropic's
+shape, merges consecutive tool results into a single user turn, and replays
+assistant thinking blocks with their signature.
+
+For the mainland-China Moonshot endpoint, set `base_url =
+"https://api.moonshot.cn/v1"` explicitly (a configured `base_url` always
+wins over the catalog — unless a `[providers.<id>]` override says otherwise,
+see below).
+
+### Per-provider overrides
+
+An optional `[providers.<id>]` section overrides a single catalog provider
+without touching the global `[llm]` settings — e.g. pointing a provider at a
+relay, renaming its credential env var, or adding extra headers:
+
+```toml
+[providers.glm]
+base_url = "https://api.z.ai/api/coding/paas/v4"  # international endpoint
+
+[providers.codex]
+base_url = "https://my-relay.example.com/v1"
+api_key_env = "CODEX_API_KEY"     # rename the env var read for the key
+headers = { x-relay = "on" }       # extra headers on every request
+```
+
+All fields are optional; unset fields fall back to the catalog. Resolution
+order for `base_url` (first hit wins):
+
+1. `[providers.<id>] base_url`
+2. `[llm] base_url` (when changed from the DeepSeek default)
+3. the catalog provider's built-in endpoint
+
+and for the API key: `[providers.<id>] api_key` → `[llm] api_key` → the
+environment variable (`[providers.<id>] api_key_env` rename, else the
+catalog's default env var).
+
+> **Note:** rule 1 is the single exception to the long-standing "an explicit
+> `[llm] base_url` always wins" behavior — a per-provider override is more
+> specific than the global setting. If you configure both, the
+> `[providers.<id>]` value is used for that provider's models.
+
+### Optional LLM settings
+
+```toml
+[llm]
+temperature = 0.2        # 0.0 - 2.0, default 0.2
+max_iterations = 50      # safety limit on tool-turn loops, default 50
+max_tokens = 8192        # output cap; default = the model's catalog value
+thinking_effort = "high" # reasoning control; default = provider behavior
+```
+
+`thinking_effort` is interpreted per model dialect:
+
+- `k3`, `kimi-for-coding*` (Anthropic adaptive thinking): `low` | `high` |
+  `max` → `thinking: {type: adaptive}` + `output_config.effort`. Thinking
+  cannot be disabled; temperature is omitted while thinking is enabled.
+- `kimi-k3` (moonshotai, OpenAI-style): `low` | `high` | `max` → sent as
+  `reasoning_effort`. Thinking cannot be disabled on K3.
+- `kimi-k2-thinking`, `kimi-k2.5`+ (DeepSeek-style): any non-`off` value →
+  `thinking: {type: enabled}`; `"off"` → `thinking: {type: disabled}`
+  (except `kimi-k2.7-code*`, where thinking is always on).
+- `glm-*` (z.ai-style): like DeepSeek-style but with `clear_thinking: false`
+  so thinking is preserved across turns; `glm-5.2` additionally maps
+  `low`/`high`/`max` to `reasoning_effort` (`low` clamps to `high`).
+- `gpt-5.*` codex models (Responses API): `low` | `medium` | `high` |
+  `xhigh` → `reasoning: {effort, summary: auto}`; 5.6-generation models
+  (`gpt-5.6-*`) also accept `max`. Temperature is omitted for reasoning
+  models.
+- Non-reasoning models: ignored.
+
+Reasoning output streams into the chat as muted thinking blocks and is
+stored on the assistant message so it can be replayed to APIs that require
+it (Kimi K3 rejects tool-call replays without `reasoning_content`).
+
+Optional tool settings:
+
+```toml
+[tools]
+bash_enabled = true
+```
+
+### Session storage
+
+Conversations are saved as JSONL files in `~/.limbo/sessions/` so you can
+review or debug them later. Use the `--session-dir` argument to redirect them
+to another location.
+
+Old session files are not automatically cleaned up; remove them manually when
+you no longer need them.
+
+## Run
+
+```bash
+limbo --workdir /path/to/project
+limbo --model glm-4.7        # override the configured model for this run
+```
+
+### Switching models at runtime
+
+Use `/model` in the TUI: without an argument it opens a picker that lists
+catalog models grouped by provider (context window, reasoning capability,
+and the current model are annotated; providers without a resolvable API key
+are dimmed with a hint). `/model <name>` switches directly — unknown names
+fall back to generic OpenAI-compatible defaults. The picker re-reads
+`config.toml` every time it opens, so edits (e.g. a newly added
+`[providers.<id>]`) apply without a restart.
+
+A switch takes effect immediately (no restart): the LLM client is rebuilt,
+and the new model is written back to `config.toml` (comments preserved via
+tomlkit) so the next launch keeps it. If the write fails, the switch still
+applies for the current session. Switching is refused while a turn is in
+flight.
+
+## Safety
+
+Limbo executes every tool call immediately, without asking for confirmation.
+File tools (`read`, `edit`, `write`, `grep`, `find`, `ls`) are bounded to the
+current working directory and reject paths that escape it, including via
+symlinks. The boundary check resolves the path before each operation, so a
+symlink swapped between the check and the operation (a time-of-check-to-time-of-use
+race) could escape the workdir. **This is a known limitation for the MVP.**
+
+Bash is an exception: it is started in the working directory but is **not**
+sandboxed. Commands can `cd ..`, use absolute paths, and read or write outside
+the workdir. In addition, commands that match dangerous patterns such as `rm`
+or `git reset --hard` are **rejected outright**.
+The pattern list is configurable but cannot be disabled from the UI. Bash
+commands are filtered with a simple heuristic, but that filter can be bypassed
+by subshells (`bash -c 'rm -rf /'`), command substitution (`$(rm -rf /)`),
+variable indirection, options before the command name
+(`git -C /foo reset --hard`), variable assignments before the command name
+(`VAR=1 rm -rf /`), and similar shell constructs. Only run Limbo with
+trusted commands and in repositories you can afford to modify or lose.
+
+If you need to work with untrusted projects, disable the bash tool entirely:
+
+```toml
+[tools]
+bash_enabled = false
+```
+
+## Development
+
+Run tests:
+
+```bash
+pytest tests/ -v
+```
+
+Run linting and type checks:
+
+```bash
+ruff check src tests
+mypy src
+```

{limbo_code-0.1.0 → limbo_code-0.1}/README.md

@@ -37,6 +37,40 @@ Built-in providers:
 | `deepseek` | openai-completions | `https://api.deepseek.com/v1` | `DEEPSEEK_API_KEY` |
 | `moonshotai` (Kimi) | openai-completions | `https://api.moonshot.ai/v1` | `MOONSHOT_API_KEY` |
 | `kimi-coding` (Kimi For Coding) | anthropic-messages | `https://api.kimi.com/coding` | `KIMI_API_KEY` |
+| `glm` (GLM Coding Plan) | openai-completions | `https://open.bigmodel.cn/api/coding/paas/v4` | `ZHIPUAI_API_KEY` |
+| `codex` (OpenAI Codex) | openai-responses | `https://api.openai.com/v1` (override with your relay) | `CODEX_API_KEY` |
+
+Built-in Codex models include `gpt-5.5`, `gpt-5.6-sol`/`terra`/`luna`,
+`gpt-5.4`, `gpt-5.4-mini`, and `gpt-5.3-codex-spark`. **`gpt-5.5` is
+verified by live test against the target relay** (its 1M context is
+relay-reported); the other entries mirror pi's built-in catalog and are
+unverified — availability depends on the relay in use, and unknown or
+unsupported models fall back to the generic OpenAI-compatible defaults.
+Codex speaks the
+OpenAI **Responses API** (`POST {base_url}/responses`), served by a
+dedicated client (`src/limbo/llm/responses_client.py`, plain httpx SSE):
+system messages become `instructions`, tool definitions are flattened, and
+reasoning models stream `reasoning` summaries and replay encrypted
+reasoning items across turns. Limbo targets **API-key relays**, not the
+ChatGPT subscription backend (OAuth) — point the provider at your relay
+and make sure its model IDs match the catalog:
+
+```toml
+[llm]
+model = "gpt-5.5"
+
+[providers.codex]
+base_url = "https://my-relay.example.com/v1"
+api_key_env = "CODEX_API_KEY"
+```
+
+Built-in GLM Coding Plan models: `glm-4.7`, `glm-5.1`, `glm-5.2` (1M
+context), `glm-5-turbo`, `glm-5v-turbo` (vision), and `glm-4.5-air`. The
+Coding Plan is a subscription with its own endpoint and keys — a coding-plan
+key only works on the `/api/coding/paas/v4` endpoints (not the pay-per-token
+`/api/paas/v4` ones) and vice versa. For the international endpoint set
+`[providers.glm] base_url = "https://api.z.ai/api/coding/paas/v4"` (see
+below).
 
 Built-in Kimi models include `kimi-k3` (1M context, pay-per-token), and for
 Kimi For Coding subscriptions: `k3` (1M context), `kimi-for-coding`, and
@@ -60,14 +94,47 @@ assistant thinking blocks with their signature.
 
 For the mainland-China Moonshot endpoint, set `base_url =
 "https://api.moonshot.cn/v1"` explicitly (a configured `base_url` always
-wins over the catalog).
+wins over the catalog — unless a `[providers.<id>]` override says otherwise,
+see below).
+
+### Per-provider overrides
+
+An optional `[providers.<id>]` section overrides a single catalog provider
+without touching the global `[llm]` settings — e.g. pointing a provider at a
+relay, renaming its credential env var, or adding extra headers:
+
+```toml
+[providers.glm]
+base_url = "https://api.z.ai/api/coding/paas/v4"  # international endpoint
+
+[providers.codex]
+base_url = "https://my-relay.example.com/v1"
+api_key_env = "CODEX_API_KEY"     # rename the env var read for the key
+headers = { x-relay = "on" }       # extra headers on every request
+```
+
+All fields are optional; unset fields fall back to the catalog. Resolution
+order for `base_url` (first hit wins):
+
+1. `[providers.<id>] base_url`
+2. `[llm] base_url` (when changed from the DeepSeek default)
+3. the catalog provider's built-in endpoint
+
+and for the API key: `[providers.<id>] api_key` → `[llm] api_key` → the
+environment variable (`[providers.<id>] api_key_env` rename, else the
+catalog's default env var).
+
+> **Note:** rule 1 is the single exception to the long-standing "an explicit
+> `[llm] base_url` always wins" behavior — a per-provider override is more
+> specific than the global setting. If you configure both, the
+> `[providers.<id>]` value is used for that provider's models.
 
 ### Optional LLM settings
 
 ```toml
 [llm]
 temperature = 0.2        # 0.0 - 2.0, default 0.2
-max_iterations = 10      # safety limit on tool-turn loops, default 10
+max_iterations = 50      # safety limit on tool-turn loops, default 50
 max_tokens = 8192        # output cap; default = the model's catalog value
 thinking_effort = "high" # reasoning control; default = provider behavior
 ```
@@ -82,6 +149,13 @@ thinking_effort = "high" # reasoning control; default = provider behavior
 - `kimi-k2-thinking`, `kimi-k2.5`+ (DeepSeek-style): any non-`off` value →
   `thinking: {type: enabled}`; `"off"` → `thinking: {type: disabled}`
   (except `kimi-k2.7-code*`, where thinking is always on).
+- `glm-*` (z.ai-style): like DeepSeek-style but with `clear_thinking: false`
+  so thinking is preserved across turns; `glm-5.2` additionally maps
+  `low`/`high`/`max` to `reasoning_effort` (`low` clamps to `high`).
+- `gpt-5.*` codex models (Responses API): `low` | `medium` | `high` |
+  `xhigh` → `reasoning: {effort, summary: auto}`; 5.6-generation models
+  (`gpt-5.6-*`) also accept `max`. Temperature is omitted for reasoning
+  models.
 - Non-reasoning models: ignored.
 
 Reasoning output streams into the chat as muted thinking blocks and is
@@ -108,8 +182,25 @@ you no longer need them.
 
 ```bash
 limbo --workdir /path/to/project
+limbo --model glm-4.7        # override the configured model for this run
 ```
 
+### Switching models at runtime
+
+Use `/model` in the TUI: without an argument it opens a picker that lists
+catalog models grouped by provider (context window, reasoning capability,
+and the current model are annotated; providers without a resolvable API key
+are dimmed with a hint). `/model <name>` switches directly — unknown names
+fall back to generic OpenAI-compatible defaults. The picker re-reads
+`config.toml` every time it opens, so edits (e.g. a newly added
+`[providers.<id>]`) apply without a restart.
+
+A switch takes effect immediately (no restart): the LLM client is rebuilt,
+and the new model is written back to `config.toml` (comments preserved via
+tomlkit) so the next launch keeps it. If the write fails, the switch still
+applies for the current session. Switching is refused while a turn is in
+flight.
+
 ## Safety
 
 Limbo executes every tool call immediately, without asking for confirmation.