No Docs

[dagelf]

Grok CLI Forks Review

Snapshot date: 2026-03-04 (local workspace state)
Compared projects:

• https://github.com/AlHeloween/grok-cli/ (@vibe-kit/grok-cli, 0.0.34)
• https://github.com/involvex/super-agent-cli (@involvex/super-agent-cli, 0.0.94)

1) Top-Level Differences

Area	grok-cli	super-agent-cli
Primary identity	Grok-focused CLI with Grok-native client features	Multi-provider "super agent" CLI (Grok, Gemini, OpenAI, Anthropic, etc.)
Fork lineage	Tracks superagent-ai/grok-cli with upstream remote to AlHeloween/grok-cli	Independent repo (involvex/super-agent-cli), documented rename from grok-cli in docs/Plan.md
Agent backend	GrokAgent + GrokClient with both Chat Completions and Responses API agent-tools path	SuperAgent over provider abstraction (LLMProvider) with many provider implementations
Web/search strategy	Explicit split: Responses API + web_search tool path for Grok 4.1 fast / recency queries	Passes search_parameters via provider options when Grok model + recency heuristic match
Context management	Message/history capped by count (MAX_MESSAGES=50, MAX_CHAT_ENTRIES=100) via ChatHistoryManager	Token-budget pruning (SUPER_AGENT_MAX_CONTEXT_TOKENS, default 100000)
Platform/features	Strong local RAG + Aurora modules; MCP; Morph optional	Plugins/repositories, VS Code extension workspace, web/Firebase integration, image generation
UI modes	Standard chat flow + commands	Explicit plan/code/debug modes + shell mode + command palette

2) Top-Level Loop (Agent Execution Loop)

grok-cli

• Main loop pattern in src/agent/grok-agent.ts: while (toolRounds < maxToolRounds) with default 400.
• Flow:
  1. Append user message.
  2. Select request path:
     • Responses API + agent tools (with optional web_search), or
     • Legacy chat completions.
  3. If tool calls exist: increment round, emit assistant/tool call entries, execute tools sequentially, append tool outputs, request next model step.
  4. If no tool calls: emit final assistant answer and stop.
• Streaming path has the same loop shape, with incremental token updates and cancellation checks.

super-agent-cli

• Main loop pattern in src/agent/super-agent.ts: also while (toolRounds < maxToolRounds) with default 400.
• Flow:
  1. Append user message.
  2. Prune conversation to token budget.
  3. Call active provider with tools (+ optional Grok search_parameters).
  4. If tool calls exist: increment round, execute tool calls, append tool outputs, call provider again.
  5. If no tool calls: emit final answer and stop.
• Streaming path mirrors this with reducer-based chunk accumulation and cancellation checks.

3) Dependencies (Top-Level)

Shared core deps

• Both: openai, @modelcontextprotocol/sdk, ink, react, commander, dotenv, axios, ripgrep-node, tiktoken, vitest, TypeScript/ESLint stack.

grok-cli leaning

• RAG/document stack: @sqliteai/sqlite-wasm, pdf-parse, mammoth, xlsx, xml2js, cheerio.
• Focused runtime without workspace monorepo.

super-agent-cli leaning

• Provider/platform breadth: @google/generative-ai, firebase, ws, open, bcrypt, mime.
• Workspace-oriented build (@plugins/*, vscode-extension), prettier plugins, richer packaging scripts.

4) Traps / Risks

1. Documentation drift in super-agent-cli:

• AGENTS.md says no tests configured, but repo has test scripts and extensive src/tests/* plus testing docs.

2. Roadmap/status drift in super-agent-cli:

• docs/ROADMAP.md says test framework work is in progress at 0%, while changelog/docs/tests indicate test infra already landed.

3. Documentation drift in grok-cli:

• AGENTS.md references docs paths (docs/...) that are missing in this snapshot.

4. Search API behavior mismatch risk:

• grok-cli explicitly distinguishes legacy chat completions vs Responses API for web search.
• super-agent-cli Grok provider still routes through chat completions payload with optional search_parameters; this can break if provider behavior changes.

5. Context trimming behavior differs:

• grok-cli: fixed message-count cap may discard relevant context earlier.
• super-agent-cli: token-based pruning is better sized but can still drop critical early instructions silently.

6. UI completeness gap in super-agent-cli:

• Status bar contextSize={0} is a TODO (real context usage not wired).

5) State of Completion

grok-cli

• Current package version here: 0.0.34.
• Active recent work shown in changelog (RAG menu, chat restore, coverage script, search updates).
• No explicit roadmap file found in this snapshot.
• Test files exist in-tree (especially RAG/Aurora and utilities), so project is not test-empty.

super-agent-cli

• Current package version here: 0.0.94.
• Extensive feature surface already shipped (multi-provider, plugins, repo manager, VS Code extension, web/Firebase, image generation).
• Extensive test scaffolding and suites exist under src/tests.
• Several docs still describe older status (v0.0.79 framing, pre-test statements), so completion messaging is inconsistent across docs.

6) Roadmaps

grok-cli

• No dedicated roadmap document found in this repo snapshot.
• Direction inferred from README/changelog: strengthen Grok-native flows, RAG tooling, and chat/session ergonomics.

super-agent-cli

• Explicit roadmap exists: docs/ROADMAP.md.
• Structured by priorities P0-P4, with phased targets (Q1-Q3 2026), planned releases (v0.1.0, v0.2.0, v0.3.0), and progress table.
• Caveat: roadmap/progress values are stale relative to current code and changelog.

Bottom Line

• super-agent-cli is the broader, more platformized fork (provider abstraction + plugins + VS Code/web ecosystem).
• grok-cli is the tighter Grok-centric branch with stronger Grok-specific request-path handling and heavier local RAG/Aurora emphasis.
• Both share nearly identical tool-loop architecture; biggest divergence is product scope and provider abstraction depth, not the fundamental control loop.