Synced from monorepo
Changes: - Gate session-lifecycle heap steady state with a dhat soak - Unbreak merge lifecycle e2e after default model → grok-4.5 - Scan home-scope rules dirs at <root>/rules - Complete text-input paste and terminal parity - Gate project roles and personas - Use canonical editing in dialogs - Use canonical editing in search bars - Reject ambiguous MCP tool IDs - Harden Git operands for plugins - Simplify queue drain API - Pass RFC 9207 iss through MCP OAuth token exchange - Show leader roster when local agents map is empty - Use canonical editing in Persona views - Remove marketplace default-skills auto-install and purge old installs - Use canonical editing in extension forms - Add canonical dashboard text editing - Use canonical editing in settings - Add /summarize as a /recap alias - Restore previous agent when exiting dashboard - Use tool_choice auto for compaction - Settings toggle for snap-prompt-to-top on send - Update default models to grok-4.5 - Source login shell once for local bash (env + alias/function snapshot) - Template hardcoded param names in server-native tool descriptions - Fix System-Reminder XML tag injection in CLAUDE.md via agents_md - Fix remote workspace-server hardcoding LSP trust (repo code execution risk) - Clear orphaned tool-call updates at turn end - Suppress task wake after cancel - Send x-grok-client-identifier on direct API tool calls - Harden dashboard peek lease transitions - Host /btw side panel in live region (minimal mode) - Bound scroll presentation latency - Highlight multi-line constructs correctly in diffs and the file viewer - Block web_fetch non-public IPs; local opt-in is explicit-host only - Seed coding_data_retention_opt_out=false for OAuth e2es in pty-harness - Follow up clipboard delivery feedback - Use canonical editing in pickers - Route TextArea through canonical editor - Persistent "watching" status row; quieter turn markers - Gate sensitive edit targets - Expose agent registry counts and gate session churn on them - Default coding data sharing to opt-out until server preference applies - Wire chat attachment ids through gateway prompts - On auth refresh failure, issue retry - Forward preview provenance and computer lifecycle state - Document independent privacy controls and scope /privacy output - Strip SamplingError Display prefix on rate-limit UI copy - Stop dumping Cloudflare HTML into Retry failed - Disable in-place prompt edit (scroll jank on enter) - Strip forced ANSI color from gh pr view JSON - Plumb bash tool description onto ToolUsageCard wire
This commit is contained in:
grokkybara[bot]
parent
98c3b2438a
commit
7cfcb20d2b
292 changed files with 23315 additions and 9209 deletions
|
|
@ -14,6 +14,14 @@ grok
|
|||
|
||||
Grok stores credentials in `~/.grok/auth.json` and reuses them across sessions. Grok refreshes access tokens automatically in the background. When a token can't be refreshed, Grok prompts you to sign in again. Credentials without a server-provided expiry fall back to a 30-day lifetime.
|
||||
|
||||
### Credential storage
|
||||
|
||||
Tokens in `~/.grok/auth.json` (and MCP OAuth tokens in `~/.grok/mcp_credentials.json`) are written with owner-only permissions (`0600` on Unix). Anyone with filesystem access to those paths can use the credentials, so:
|
||||
|
||||
- Prefer full-disk encryption (FileVault, BitLocker, LUKS, or equivalent).
|
||||
- Do not copy `auth.json` or `mcp_credentials.json` into shared directories, tickets, or chat.
|
||||
- On multi-user hosts, keep `$HOME` / `$GROK_HOME` private to your account.
|
||||
|
||||
### Re-authenticate
|
||||
|
||||
To switch accounts or resolve an authentication problem, run:
|
||||
|
|
@ -261,6 +269,25 @@ During a session, the active method handles all mid-session refreshes.
|
|||
|
||||
---
|
||||
|
||||
## Related settings
|
||||
|
||||
`/privacy` does not change these config knobs:
|
||||
|
||||
| Setting | How to set it |
|
||||
|---------|---------------|
|
||||
| `[features] telemetry` | `config.toml` or `GROK_TELEMETRY_ENABLED` |
|
||||
| `[telemetry] trace_upload` | `config.toml` or `GROK_TELEMETRY_TRACE_UPLOAD` |
|
||||
| External OpenTelemetry | `GROK_EXTERNAL_OTEL` / `[telemetry] otel_*`. See [Monitoring Usage](24-monitoring-usage.md). |
|
||||
|
||||
On team accounts, only a team admin can toggle privacy with `/privacy`.
|
||||
Team admins can also enable or disable Zero Data Retention (ZDR) for their team.
|
||||
See [How to enable ZDR](https://docs.x.ai/developers/faq/security#how-to-enable-zdr).
|
||||
When ZDR is on, `/privacy` cannot change coding-data sharing.
|
||||
|
||||
See [Monitoring Usage](24-monitoring-usage.md#related-settings) and [Configuration](05-configuration.md#telemetry).
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Debug logging
|
||||
|
|
|
|||
|
|
@ -399,7 +399,11 @@ Report an issue or send feedback.
|
|||
|
||||
### `/btw`
|
||||
|
||||
Send an aside to the agent without interrupting the current task.
|
||||
Send an aside to the agent without interrupting the current task. In minimal
|
||||
mode (`--minimal`), the answer appears in a dismissible panel above the prompt.
|
||||
**Esc** dismisses the panel; a finished answer is saved into native scrollback,
|
||||
while a late response to a dismissed loading panel is dropped. Side Q/A is not
|
||||
part of the main turn.
|
||||
|
||||
```
|
||||
/btw also check the error handling
|
||||
|
|
@ -513,8 +517,16 @@ Show or toggle privacy and data-retention status.
|
|||
|
||||
```
|
||||
/privacy
|
||||
/privacy opt-in
|
||||
/privacy opt-out
|
||||
```
|
||||
|
||||
Does not change `[features] telemetry`, `trace_upload`, or external OTEL settings.
|
||||
See [Monitoring Usage](24-monitoring-usage.md#related-settings).
|
||||
On team accounts, only a team admin can toggle privacy with `/privacy`.
|
||||
Team admins can also enable or disable Zero Data Retention (ZDR) for their team:
|
||||
[How to enable ZDR](https://docs.x.ai/developers/faq/security#how-to-enable-zdr).
|
||||
|
||||
---
|
||||
|
||||
## Configuration and UI
|
||||
|
|
|
|||
|
|
@ -58,6 +58,9 @@ collapsed_edit_blocks = false # show edits as one-line +N/-M diffstat s
|
|||
# back-to-back same-file edits into one row, expand for the
|
||||
# diffs (default: false; pager.toml [scrollback.blocks.edit]
|
||||
# expanded_by_default/line_summary override its fold shape)
|
||||
page_flip_on_send = true # pin a just-sent prompt at the top of the viewport so the
|
||||
# response starts on a fresh page (default: true); set false
|
||||
# so sending never moves the scroll position
|
||||
screen_mode = "fullscreen" # default render mode: "fullscreen" | "minimal"
|
||||
# (unset → fullscreen); set via /settings → Default screen mode
|
||||
|
||||
|
|
@ -182,6 +185,14 @@ you for that session only.
|
|||
|
||||
A CLI flag always wins over the config value for that invocation.
|
||||
|
||||
#### Snap prompt to top on send
|
||||
|
||||
By default, sending a prompt scrolls it to the top of the viewport so the
|
||||
response starts on a fresh page. Set `[ui] page_flip_on_send = false` (or
|
||||
toggle **Snap prompt to top on send** in `/settings` → Appearance) to leave
|
||||
the scroll position unchanged when you send. Applies on the next send; no
|
||||
restart.
|
||||
|
||||
#### Scrolling
|
||||
|
||||
Four `[ui]` settings tune mouse-wheel and trackpad scrolling in the
|
||||
|
|
@ -226,8 +237,14 @@ timeout_secs = 1800 # seconds to wait when enabled (default:
|
|||
[toolset.web_fetch]
|
||||
proxy_endpoint = "https://proxy.example.com" # egress proxy URL
|
||||
allowed_domains = ["docs.rs", "x.ai"] # override the built-in allowlist
|
||||
allow_local = false # true = allow localhost / 127.0.0.0/8 / ::1 only
|
||||
```
|
||||
|
||||
`allow_local` is off by default (SSRF fail-closed). When `true` (or
|
||||
`GROK_WEB_FETCH_ALLOW_LOCAL=1`), `web_fetch` may reach **explicit** loopback
|
||||
hosts only — private, link-local, and cloud-metadata ranges stay blocked.
|
||||
Resolution: TOML > env > default off.
|
||||
|
||||
`[toolset.ask_user_question]` is honored across **requirements.toml**, **managed
|
||||
config**, and **user `config.toml`**. Precedence: requirements → env
|
||||
(`GROK_ASK_USER_QUESTION_TIMEOUT_ENABLED` /
|
||||
|
|
@ -370,16 +387,16 @@ Session cells remain staged until a foreign-session scanner consumes them. Each
|
|||
```toml
|
||||
[compat.cursor]
|
||||
skills = true # scan ~/.cursor/skills/ and <cwd>/.cursor/skills/
|
||||
rules = true # scan <cwd>/.cursor/rules/
|
||||
agents = true # scan ~/.cursor/ for AGENTS.md files
|
||||
rules = true # scan ~/.cursor/rules/ and <dir>/.cursor/rules/
|
||||
agents = true # scan ~/.cursor/ for named instruction files
|
||||
mcps = true # scan ~/.cursor/mcp.json and <cwd>/.cursor/mcp.json
|
||||
hooks = true # scan ~/.cursor/hooks.json and <cwd>/.cursor/hooks.json
|
||||
sessions = true # staged; no scanner consumer yet
|
||||
|
||||
[compat.claude]
|
||||
skills = true # scan ~/.claude/skills/ and <cwd>/.claude/skills/
|
||||
rules = true # scan <cwd>/.claude/rules/
|
||||
agents = true # scan ~/.claude/ for CLAUDE.md / CLAUDE.local.md
|
||||
rules = true # scan ~/.claude/rules/ and <dir>/.claude/rules/
|
||||
agents = true # scan ~/.claude/ and <dir>/.claude/CLAUDE*.md
|
||||
mcps = true # scan ~/.claude.json for MCP servers
|
||||
hooks = true # scan ~/.claude/settings.json for hooks
|
||||
sessions = true # staged; no scanner consumer yet
|
||||
|
|
@ -390,6 +407,8 @@ sessions = true # staged; no scanner consumer yet
|
|||
|
||||
Codex `skills`, `rules`, `agents`, `mcps`, and `hooks` cells are reserved and currently inert; they do not enable `.codex` discovery.
|
||||
|
||||
For Claude and Cursor, `rules` and `agents` are independent: disabling named instruction files does not disable either the home or project rules directory, and disabling rules does not disable named files. Claude's `agents` cell gates home-level `~/.claude/` named files and project `<dir>/.claude/CLAUDE*.md`; generic top-level `Claude.md`, `CLAUDE.md`, and `CLAUDE.local.md` remain recognized. Project rule paths are scanned at every directory from the repo root to the current directory.
|
||||
|
||||
Each cell can be toggled via environment variable or `config.toml`. See the
|
||||
environment-variables reference for the env var names. Resolution order:
|
||||
env var > config.toml > default (on).
|
||||
|
|
@ -546,7 +565,15 @@ See [Keyboard Shortcuts](03-keyboard-shortcuts.md) for the complete reference.
|
|||
|
||||
### Telemetry
|
||||
|
||||
The `[features] telemetry` toggle (in the `[features]` block above) is the master switch for anonymous usage telemetry. When telemetry is enabled, enterprises that run their own collector can redirect it or selectively disable parts of it under `[telemetry]`:
|
||||
Independent knobs (see [Monitoring Usage](24-monitoring-usage.md#related-settings)):
|
||||
|
||||
- **`[features] telemetry`** / `GROK_TELEMETRY_ENABLED`: product analytics master switch. `/privacy` does not change it.
|
||||
- **`/privacy`** / Settings: coding data sharing (separate from telemetry).
|
||||
- **`[telemetry] trace_upload`** / `GROK_TELEMETRY_TRACE_UPLOAD`: session traces; follows telemetry when unset.
|
||||
- **`[telemetry] otel_*`** / `GROK_EXTERNAL_OTEL`: external OTEL to your collector (below).
|
||||
|
||||
When telemetry is enabled, enterprises that run their own collector can redirect
|
||||
it or selectively disable parts of it under `[telemetry]`:
|
||||
|
||||
```toml
|
||||
[telemetry]
|
||||
|
|
@ -558,7 +585,7 @@ trace_upload = false # disable session/trac
|
|||
|
||||
Set these only to point telemetry at your own infrastructure or to turn parts of it off. The built-in endpoint and credentials are managed by Grok; leave them unset to use the defaults.
|
||||
|
||||
The same `[telemetry]` table also configures the **external OpenTelemetry stream** — an independent opt-in (it does not require the telemetry toggle above) that ships a curated, content-free usage schema to your *own* OTLP collector. Collector auth is supplied via `OTEL_EXPORTER_OTLP_HEADERS` and is never stored on disk. See [Monitoring & Usage](24-monitoring-usage.md) for the full schema, env vars, and privacy model.
|
||||
The same `[telemetry]` table also configures the **external OpenTelemetry stream**, an independent opt-in (it does not require the telemetry toggle above) that ships a curated, content-free usage schema to your *own* OTLP collector. Collector auth is supplied via `OTEL_EXPORTER_OTLP_HEADERS` and is never stored on disk. See [Monitoring & Usage](24-monitoring-usage.md) for the full schema, env vars, and privacy model.
|
||||
|
||||
```toml
|
||||
[telemetry]
|
||||
|
|
@ -751,6 +778,7 @@ Key environment variables. See the README for the complete list.
|
|||
| `GROK_MEMORY` | Enable (`1`) or disable (`0`) cross-session memory |
|
||||
| `GROK_SUBAGENTS` | Enable (`1`) or disable (`0`) subagents |
|
||||
| `GROK_WEB_FETCH` | Enable (`1`) or disable (`0`) the web_fetch tool |
|
||||
| `GROK_WEB_FETCH_ALLOW_LOCAL` | Allow `web_fetch` to explicit loopback hosts only (`localhost` / `127.0.0.0/8` / `::1`). Same as `[toolset.web_fetch] allow_local`. Default off. Private/metadata stay blocked. |
|
||||
| `GROK_AGENT` | Custom agent definition path or name |
|
||||
| `GROK_SANDBOX` | Sandbox profile (off, workspace, devbox, read-only, strict; or a custom profile name) |
|
||||
|
||||
|
|
@ -773,6 +801,9 @@ Key environment variables. See the README for the complete list.
|
|||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `GROK_TELEMETRY_ENABLED` | Enable/disable telemetry |
|
||||
| `GROK_TELEMETRY_TRACE_UPLOAD` | Enable/disable session trace upload |
|
||||
| `GROK_TELEMETRY_MIXPANEL_ENABLED` | Enable/disable Mixpanel specifically |
|
||||
| `GROK_EXTERNAL_OTEL` | External OTEL to your collector (see [24-monitoring-usage.md](24-monitoring-usage.md)) |
|
||||
| `GROK_FEEDBACK_ENABLED` | Enable/disable feedback system |
|
||||
| `GROK_DEPLOYMENT_KEY` | Management API key for enterprise |
|
||||
|
||||
|
|
|
|||
|
|
@ -35,7 +35,15 @@ In addition to AGENTS.md files, Grok scans for `*.md` files in rules directories
|
|||
| `<dir>/.claude/rules/` | Claude compatibility (configurable) |
|
||||
| `<dir>/.cursor/rules/` | Cursor compatibility (configurable) |
|
||||
|
||||
Grok scans the Claude and Cursor rules directories by default. To disable scanning for a specific vendor, set its cell in the `[compat]` config section or the corresponding environment variable. See [Configuration](05-configuration.md#harness-compatibility) for details.
|
||||
Grok also scans home-level rules, regardless of where it starts. These roots are already vendor-specific, so rules live directly under `rules/`:
|
||||
|
||||
| Location | Notes |
|
||||
|----------|-------|
|
||||
| `$GROK_HOME/rules/` (default `~/.grok/rules/`) | Always scanned; applies to all projects |
|
||||
| `~/.claude/rules/` | Controlled by `compat.claude.rules` |
|
||||
| `~/.cursor/rules/` | Controlled by `compat.cursor.rules` |
|
||||
|
||||
Home rules load first, in the table order, followed by project files from repo root to the current directory. Files are alphabetical within each rules directory. The vendor `rules` cells control both home and project rules independently of the corresponding `agents` cells. Claude's `agents` cell controls named files under `~/.claude/` and project `<dir>/.claude/CLAUDE*.md`; generic top-level names such as `Claude.md`, `CLAUDE.md`, and `CLAUDE.local.md` remain recognized. See [Configuration](05-configuration.md#harness-compatibility).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -43,7 +51,7 @@ Grok scans the Claude and Cursor rules directories by default. To disable scanni
|
|||
|
||||
Grok scans for project rules in this order:
|
||||
|
||||
1. **Global rules**: `~/.grok/` (applies to all projects)
|
||||
1. **Home rules**: `$GROK_HOME`, then enabled `~/.claude/` and `~/.cursor/` sources
|
||||
2. **Repo rules**: If inside a git repo, every directory from the repo root down to the current working directory (inclusive)
|
||||
3. **CWD-only**: If not inside a git repo, only the current working directory
|
||||
|
||||
|
|
|
|||
|
|
@ -186,6 +186,18 @@ To toggle the prompt queue instead, press `Ctrl+;`.
|
|||
|
||||
---
|
||||
|
||||
## The Watching Status Line
|
||||
|
||||
Whenever background work is still running while the agent looks idle — between turns, or while a turn is blocked on a user-interruptible wait — a persistent status line appears above the prompt:
|
||||
|
||||
```
|
||||
◎ watching · 1 command · 2 monitors · 1 loop · 1 subagent
|
||||
```
|
||||
|
||||
It counts running background commands, monitors, scheduled `/loop` tasks, and background subagents, and updates live as each finishes. Any of them can wake the agent for a new turn (commands and subagents on completion, monitors on events, loops on their timer), so the cue stays up until nothing is left. Completions land in the transcript as a single "Task completed" chip — the transcript never repeats "N commands still running" lines.
|
||||
|
||||
---
|
||||
|
||||
## Use Cases and Patterns
|
||||
|
||||
### Dev Server + Coding
|
||||
|
|
|
|||
|
|
@ -9,6 +9,22 @@ own OpenTelemetry collector, so platform teams can monitor adoption, token
|
|||
consumption, tool-permission decisions, and errors across the fleet — without
|
||||
any data flowing through SpaceXAI.
|
||||
|
||||
## Related settings
|
||||
|
||||
These knobs are independent of each other (and of this guide's external OTEL stream):
|
||||
|
||||
| Setting | How to set it |
|
||||
|---------|---------------|
|
||||
| Telemetry master switch | `[features] telemetry` / `GROK_TELEMETRY_ENABLED` |
|
||||
| `/privacy` | `/privacy opt-in` / `/privacy opt-out`, or Settings |
|
||||
| Trace upload | `[telemetry] trace_upload` / `GROK_TELEMETRY_TRACE_UPLOAD` |
|
||||
| External OpenTelemetry | `GROK_EXTERNAL_OTEL` / `[telemetry] otel_*` (this guide) |
|
||||
|
||||
See also [Authentication](02-authentication.md#related-settings) and
|
||||
[Configuration](05-configuration.md#telemetry).
|
||||
|
||||
## External OTEL stream
|
||||
|
||||
The external stream is:
|
||||
|
||||
- **Off by default**, and requires a *double opt-in* (a master switch **and**
|
||||
|
|
@ -19,7 +35,7 @@ The external stream is:
|
|||
- **Structurally separate** from SpaceXAI-internal telemetry: its exporters carry
|
||||
only the headers you configure, never SpaceXAI credentials.
|
||||
- **Independent of SpaceXAI data-retention opt-outs**: it works even when
|
||||
`telemetry` is disabled and for ZDR (zero-data-retention) teams — those
|
||||
`telemetry` is disabled and for ZDR (zero-data-retention) teams. Those
|
||||
settings govern SpaceXAI-side retention; the external stream is governed solely
|
||||
by your own OTEL configuration.
|
||||
|
||||
|
|
|
|||
|
|
@ -50,3 +50,5 @@ Automate, script, and integrate Grok Build with other systems.
|
|||
| 20 | [Background Tasks and Monitoring](20-background-tasks.md) | `background: true`, `/loop`, `monitor`, and `Ctrl+G` to demote |
|
||||
| 21 | [Terminal Support and Troubleshooting](21-terminal-support.md) | tmux, SSH, truecolor, clipboard, and OSC 52 |
|
||||
| 22 | [Permissions and Safety Controls](22-permissions-and-safety.md) | `dontAsk` mode, auto-approved tools, the safe-bash list, and restrictive PreToolUse hooks (such as git/gh-only) |
|
||||
| 23 | [Agent Dashboard](23-dashboard.md) | Central overview of local sessions and forks |
|
||||
| 24 | [Monitoring Usage (External OpenTelemetry)](24-monitoring-usage.md) | Customer OTEL export |
|
||||
|
|
|
|||
Loading…
Reference in a new issue