Add Grok Build (xAI's official Grok 4.5 coding CLI) as a covered connector — detection is scaffolded; needs a parser + factory

[etafund]

Feature request: add Grok Build (xAI's official Grok 4.5 coding CLI) to the covered connectors — detection is already half-scaffolded; it needs a parser + factory registration

Thanks for cass — indexing session history across every harness is exactly the kind of thing that should exist. This is a request to add Grok Build, xAI's official terminal coding agent (the grok CLI, now powered by Grok 4.5), as a covered connector so its sessions get indexed and searched alongside Codex/Claude/Gemini/etc.

Good news up front: grok is already partially wired for detection + display in both cass and the underlying franken_agent_detection (FAD) crate — the probe roots, canonical-slug aliases, display name, and CSS all exist. The only genuinely missing piece is the actual GrokConnector parser (and its factory registration), plus syncing a couple of hard-pinned lists/docs/tests.

I've written this to be directly actionable by a coding agent reviewing via gh issue view (your stated workflow). Filing as an issue, not a PR, per your contribution policy.

TL;DR for the implementing agent

• The connector implementations live in the external crate franken_agent_detection (pinned in Cargo.toml:92 at rev 3c30766…), not in this repo. cass's src/connectors/*.rs are thin re-export stubs.
• Already done for grok (both crates): KNOWN_CONNECTORS entry, canonical_connector_slug aliases (grok/grok-cli/grok-build/xai-grok), default_probe_roots (~/.grok/sessions, ~/.grok/auth.json), default_probe_paths_tilde, and cass-side display name ("Grok"), CSS class (.agent-grok), and filename slug.
• Missing: a GrokConnector implementing the Connector trait in FAD + a line in get_connector_factories(); then a FAD rev-bump + a 1-line re-export stub in cass; then update the hard-pinned DOCUMENTED_CONNECTOR_NAMES test and the ConnectorKind enum, plus README/AGENTS/SKILL/CHANGELOG.
• ⚠️ The session on-disk format for the official Grok Build is not yet publicly documented. FAD already assumes ~/.grok/sessions (JSONL, mirroring the ~/.codex/sessions pattern). See "Determining the session format" — this is the one real research task; everything else is mechanical wiring.

---

What is "Grok Build"?

Grok Build is xAI's official coding-agent CLI — same category as Claude Code, Codex, Gemini CLI. As of mid-2026 it runs on Grok 4.5 (grok-4.5); grok-code-fast-1 is the earlier fast coding model. API base https://api.x.ai/v1.

• Command / binary: grok (installed to ~/.grok/bin/grok). Install: curl -fsSL https://x.ai/cli/install.sh | bash (native binary, currently 0.1.x).
• The FAD probe-roots code already anticipates it — its comment reads "xAI Grok CLI / Grok Build TUI keep their state under ~/.grok/."

⚠️ Disambiguation. A separate, popular community CLI, superagent-ai/grok-cli (npm grok-dev, formerly @vibe-kit/grok-cli), is not affiliated with xAI and also lives in ~/.grok/. It stores sessions in ~/.grok/grok.db (SQLite) — which, unlike the official CLI, is a fully-inspectable schema (details in the appendix). This issue targets the official Grok Build, but the community DB is a concrete, ready-to-parse alternative/companion worth knowing about.

---

Current state of grok scaffolding (verified)

Anchored to coding_agent_session_search@8110944 and FAD rev 3c30766db8708a6b63101fdb085a8cdbb74f0d1d (the rev pinned in Cargo.toml:92).

Already present — no work needed:

Where	What exists	Location
FAD	"grok" in KNOWN_CONNECTORS	src/lib.rs:137
FAD	alias map grok/grok-cli/grok-build/xai-grok → grok	src/lib.rs:167 (canonical_connector_slug)
FAD	probe roots ~/.grok/sessions, ~/.grok/auth.json, ~/.grok	src/lib.rs:627–637 (default_probe_roots)
FAD	tilde path list (for cass sources probe)	src/lib.rs:1102–1105 (default_probe_paths_tilde)
FAD	probe-path test asserting the three ~/.grok/* roots	src/lib.rs:1499–1502
cass	display name "grok" => "Grok"	src/html_export/renderer.rs:536 (agent_display_name)
cass	CSS class "grok" => "agent-grok"	src/html_export/renderer.rs:507 (agent_css_class)
cass	CSS style .agent-grok .message-assistant { … }	src/html_export/styles.rs:1580
cass	filename slug "grok" => "grok"	src/html_export/filename.rs:552 (agent_slug)

Missing — the actual work: there is no grok.rs connector parser in FAD (src/connectors/ has none), and grok is not in FAD's get_connector_factories() (src/connectors/mod.rs:206). So grok can be detected/probed but never scanned, and it's absent from the public connector set.

---

Implementation blueprint

Because of the two-crate split, the change spans FAD (the parser) and cass (rev-bump + list-sync). The closest template is Codex, since Grok Build's assumed layout (~/.grok/sessions/…jsonl) mirrors Codex's (~/.codex/sessions/rollout-*.jsonl).

Part 1 — franken_agent_detection (the parser)

• New src/connectors/grok.rs — struct GrokConnector + impl Connector (src/connectors/mod.rs:64). The trait needs detect(), scan()/scan_with_callback(), and ideally discover_source_files(). Copy src/connectors/codex.rs (full JSONL streaming exemplar: home() honoring an env override, sessions_dir(), is_rollout_file(), rollout_files() via WalkDir, streaming scan_with_callback). If Grok's schema is simpler, src/connectors/pi_agent.rs or src/connectors/kimi.rs are lighter JSONL starting points. Emit NormalizedConversation/NormalizedMessage with agent_slug = "grok".
• src/connectors/mod.rs — add pub mod grok; (near line 20, alphabetical).
• src/connectors/mod.rs:206 — add ("grok", || Box::new(grok::GrokConnector::new())), to get_connector_factories(). This is the one mandatory registration — everything downstream (including cass's public connector list) auto-derives from it.
• src/lib.rs:267 env_override_roots() — add a "grok" arm only if Grok Build honors a home override (none documented; skip otherwise).
• FAD conformance tests + fixtures under src/connectors/conformance_tests.rs and fixtures/grok/….
• Cut a new FAD rev.

Part 2 — coding_agent_session_search (rev-bump + list-sync)

• Cargo.toml:92 — bump the FAD rev to the one containing GrokConnector. Add "grok" to that dep's features = [...] list only if you feature-gated the connector in FAD.
• New src/connectors/grok.rs — one-line re-export stub, template = src/connectors/claude_code.rs:

  pub use franken_agent_detection::connectors::grok::GrokConnector;

  (Use the src/connectors/codex.rs wrapper pattern instead only if you need cass-local message augmentation.)
• src/connectors/mod.rs (≈ lines 200–222) — add pub mod grok;.
• tests/spec_connector_enumeration_completeness.rs:67 — add "grok" to the hard-pinned DOCUMENTED_CONNECTOR_NAMES array (currently 22 → 23) and update the "22" prose in the file's doc comment. This test fails until updated — it asserts cass diag --json connector names exactly equal this set. (Its module doc is effectively the canonical "adding a connector" checklist.)
• src/indexer/mod.rs:23304 — add a Grok variant to enum ConnectorKind (e.g. #[serde(rename = "gk", alias = "Grok")] Grok,), plus arms in ConnectorKind::from_slug (≈ 22524) and ::slug (≈ 22550), so incremental watch_state.json timestamps track Grok.
• (No change needed) capabilities_connector_names() (src/lib.rs:68580) auto-appends new factory slugs; the --agent grok filter is free-form and works once the connector emits agent_slug="grok"; the HTML-identity test already passes thanks to the existing display-name/CSS entries.
• Docs: README.md — add grok to the intro list (≈ line 14), the "Universal Connectors" path list (≈ lines 359–384, e.g. - **Grok Build**: ~/.grok/sessions (JSONL)), and bump the "22 coding agents" counts (≈ lines 355, 2135) to 23. AGENTS.md — provider table (≈ 538–552) + connectors tree (≈ 461–471). SKILL.md — add a row and fix the stale "11 agents" count (≈ line 8, table ≈ 578–583). CHANGELOG.md — add an entry.
• Tests: new tests/connector_grok.rs (template tests/connector_codex.rs — builds a ScanContext, writes fixture JSONL into a TempDir, asserts agent_slug/message count/timestamps), fixtures under tests/fixtures/grok_real/…, and register in tests/fixtures/connectors/MANIFEST.json. Check enumerating tests too: tests/e2e_multi_connector.rs, tests/connector_factory.rs.

---

Determining the session on-disk format (the one real research task)

The official Grok Build session/transcript format is not publicly documented (its installer only sets up ~/.grok/{bin,downloads,completions} + config; it doesn't reveal where the binary writes history). FAD's existing probe root assumes ~/.grok/sessions, and the natural bet — given xAI modeled the CLI on the Codex/Claude generation — is per-session JSONL under ~/.grok/sessions/. That needs to be confirmed empirically before the parser is finalized:

curl -fsSL https://x.ai/cli/install.sh | bash
grok login
grok "write a hello world in python"     # generate a session
find ~/.grok -maxdepth 3 -newermt '-10 min' -type f   # what got written, and where?
#   → if you see *.jsonl under ~/.grok/sessions, model the parser on codex.rs
#   → if you see a *.db (SQLite), model it on FAD's SQLite connectors (cursor/opencode)
#   → dump one record: head -c 2000 <that file>   (or: sqlite3 <db> '.schema')

If the official format turns out to be undocumented/unstable and you'd rather ship something concrete first, the community grok-dev CLI's ~/.grok/grok.db is a fully-specced SQLite store (schema in the appendix) that a GrokConnector (or a sibling slug) could parse today. Flagging this so nobody burns time hunting for docs that don't exist yet.

---

Acceptance criteria

• grok appears in cass diag --json and the DOCUMENTED_CONNECTOR_NAMES completeness test passes at 23 connectors.
• Running cass against a machine with Grok Build sessions indexes them; cass search … --agent grok and HTML export work (display name "Grok", .agent-grok styling already wired).
• Detection distinguishes the official store from the community CLI's ~/.grok/grok.db (or covers both intentionally).
• README / AGENTS / SKILL / CHANGELOG updated; new tests/connector_grok.rs + fixtures green.

---

Appendix — community grok-dev ~/.grok/grok.db schema (confirmed, ready to parse today)

SQLite (WAL mode → also grok.db-wal / grok.db-shm), PRAGMA user_version = 3. Core tables:

• workspaces(id, scope_key UNIQUE, canonical_path, git_root, display_name, last_seen_at) — sessions grouped per repo.
• sessions(id, workspace_id, title, recap_text, model, mode, cwd_at_start, cwd_last, status, created_at, updated_at) — id is a 12-char hex.
• messages(session_id, seq, role, message_json, created_at, PRIMARY KEY(session_id, seq)) — one row per message; role ∈ system|user|assistant|tool; message_json is a Vercel AI SDK ModelMessage (string or array-of-parts content).
• tool_calls(session_id, message_seq, tool_call_id, tool_name, args_json, status, …), tool_results(tool_call_row_id, output_kind, output_json, success, …), usage_events(…), compactions(…).
• All timestamps ISO-8601 TEXT. Resume via grok --session latest / grok -s <id>.

Source (read from repo source): https://github.com/superagent-ai/grok-cli → src/storage/{db,migrations,transcript,sessions}.ts.

---

Sources

• Official Grok CLI installer (command name, ~/.grok/ layout): https://x.ai/cli/install.sh · product page https://x.ai/cli
• Model IDs: https://docs.x.ai/developers/grok-4-5 (grok-4.5), https://x.ai/news/grok-code-fast-1
• Community CLI + grok.db schema: https://github.com/superagent-ai/grok-cli (npm grok-dev)

Notes: I can help capture a real ~/.grok/sessions sample or draft tests/connector_grok.rs fixtures if useful. Suggested labels: enhancement, help wanted (the parser needs the official format pinned down first). Thanks for considering it!

[Dicklesworthstone]

Research update on the one open question in this issue — the official Grok Build session on-disk format — now confirmed empirically on a Linux host with the official CLI installed (~/.grok/bin/grok → grok-0.2.103-linux-x86_64), plus serde metadata mined from the binary itself. FAD's ~/.grok/sessions probe-root assumption is correct, and the format is per-session JSONL, mirroring the Codex generation as predicted.

Confirmed on-disk layout (grok 0.2.103)

~/.grok/sessions/
├── session_search.sqlite                 # global search index over sessions
└── <percent-encoded-absolute-cwd>/       # e.g. %2Fdata%2Fprojects%2Ffoo
    ├── prompt_history.jsonl              # one line per submitted prompt
    └── <uuidv7-session-id>/              # e.g. 019f75d0-ebe1-7db0-a59a-60af9ffa9e71
        ├── chat_history.jsonl            # THE transcript (parse this)
        ├── summary.json                  # session metadata (parse this)
        ├── events.jsonl                  # runtime events (turn_started/turn_ended, mcp_*)
        ├── prompt_context.json
        ├── system_prompt.txt
        ├── updates.jsonl
        ├── rewind_points.jsonl
        └── *.lock siblings for each jsonl/json

Sessions are keyed by working directory exactly as the docs claim; the cwd directory name is the percent-encoded absolute path.

summary.json (metadata source)

Observed verbatim (values redacted to structure):

{
  "info": { "id": "<uuidv7>", "cwd": "/abs/path" },
  "session_summary": "…",
  "created_at": "2026-07-18T15:20:54.103795421Z",
  "updated_at": "2026-07-18T15:20:59.770364197Z",
  "num_messages": 4,
  "num_chat_messages": 5,
  "current_model_id": "grok-build",
  "next_trace_turn": 1,
  "chat_format_version": 1,
  "request_id": "<uuid>",
  "grok_home": "/home/user/.grok",
  "last_active_at": "2026-07-18T15:20:59.770364197Z",
  "generated_title": "…",
  "agent_name": "grok-build-plan",
  "sandbox_profile": "off"
}

chat_history.jsonl record shape

Internally tagged on "type". Observed live records:

• {"type":"system","content":"<plain string>"} — the system prompt.
• {"type":"user","content":[{"type":"text","text":"…"}]} — content is an array of typed parts.
• User records carry optional "prompt_index" (int, ties back to prompt_history.jsonl) and optional "synthetic_reason" (harness-injected context like <user_info>, skills reminders, MCP failure notices).

The binary's serde metadata (xai-chat-state crate, visible via strings) pins the full variant set of the chat record enum:

system | user | assistant | tool_result | backend_tool_call | reasoning

and the associated field names: tool_calls, tool_call_id, arguments, model_fingerprint, images, tool_type, web_search, prior_turn_interrupt, compaction_meta, project_instructions. synthetic_reason values include auto_continue, auto_recovery, interjection, task_completed, subagent_completed, notification_drain, goal_summary, scheduler_fired, mid_turn_abort, permission_rejected, permission_cancelled, unknown.

prompt_history.jsonl line shape (observed verbatim, one per prompt):

{"timestamp":"2026-07-18T15:20:09.467538639Z","session_id":"<uuidv7>","prompt":"…","is_bash":false}

What is still unconfirmed

The exact serialized shape of assistant / tool_result / reasoning records. The probe host has no working xAI credentials, so every captured turn ended (events.jsonl: {"type":"turn_ended","outcome":"error"}) before the model produced output — the transcripts contain only system + user records. The variant/field names above are certain; the nesting (e.g. whether tool_calls is OpenAI-style {id, function:{name, arguments}} or flat {tool_call_id, tool_type, arguments}) is not.

If anyone running Grok Build with a live account can paste 3-4 redacted lines of a chat_history.jsonl containing one assistant record with a tool_calls entry and its matching tool_result record, the parser + conformance fixtures can be locked down immediately.

Implementation implications (vs. the blueprint in the issue body)

• The codex.rs template is right, with one structural difference: discovery must walk two levels (sessions/<encoded-cwd>/<session-uuid>/chat_history.jsonl) instead of globbing rollout-*.jsonl, and percent-decode the cwd dir for workspace attribution.
• summary.json supplies title/timestamps/model without scanning the transcript; chat_format_version (currently 1) is the forward-compat gate.
• Parser should skip type:"system" and synthetic_reason-tagged user records (harness noise), map assistant+tool_result into normalized messages, and tolerate unknown type values (the enum will grow).
• events.jsonl / updates.jsonl / rewind_points.jsonl can be ignored for indexing.

Keeping this open until the assistant/tool record shapes are confirmed and the FAD GrokConnector + factory registration land.