# build-with-groq/groq-code-cli architecture

> Architecture diagram of the GitHub repository build-with-groq/groq-code-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/build-with-groq/groq-code-cli
- Repository: https://github.com/build-with-groq/groq-code-cli

## Overview

##### Project type and purpose
- This is an open-source, extensible coding CLI (command-line interface) written in TypeScript/Node.js with a React-based text UI (“TUI”) layer.
- It provides a pluggable slash-command and tool framework that calls out to the Groq AI API for code generation/analysis.

##### File structure
- Top-level artifacts:
- package.json & tsconfig.json → build & dependency config
- docs/ → UX screenshots & thumbnail
- src/ → ANSI-TUI code, core logic, commands, tools, utils
- src/core → “agent” orchestration and CLI entry point
- src/commands → slash-command definitions (handler + metadata)
- src/tools → tool schemas + implementations + validators
- src/ui → React components, hooks for the TUI layer
- src/utils → file I/O, local settings, markdown utilities
- Build scripts: npm run build/dev, publish as a global ‘groq’ binary.

##### Key README insights
- Core entry: src/core/cli.ts → bootstraps the CLI, loads commands/tools, wires up the UI.
- Agent: src/core/agent.ts → encapsulates request/response to Groq API + tool invocation.
- TUI: React components in src/ui render message history, input overlays, invoke slash commands.
- Extensibility: add tools via tool-schemas.ts + tools.ts; add slash-commands under commands/definitions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External actor
    User["User keystroke"]:::external

    %% CLI Runner
    subgraph "CLI Runner"
        CLIEntry["CLI Entry Point\n(cli.ts)"]:::internal
    end

    %% Core Layer
    subgraph "Core Layer"
        Agent["Agent\n(agent.ts)"]:::internal
    end

    %% Command Module
    subgraph "Command Module"
        CmdDispatcher["Command Dispatcher\n(base.ts / index.ts)"]:::internal
        ClearCmd["clear Command\n(clear.ts)"]:::internal
        HelpCmd["help Command\n(help.ts)"]:::internal
        LoginCmd["login Command\n(login.ts)"]:::internal
        ModelCmd["model Command\n(model.ts)"]:::internal
        ReasoningCmd["reasoning Command\n(reasoning.ts)"]:::internal
    end

    %% Tool Module
    subgraph "Tool Module"
        ToolSchemas["Tool Schemas\n(tool-schemas.ts)"]:::internal
        ToolExecutors["Tool Executors\n(tools.ts)"]:::internal
        Validators["Validators\n(validators.ts)"]:::internal
    end

    %% UI Layer
    subgraph "UI Layer"
        App["App Component\n(App.tsx)"]:::ui
        Chat["Chat Component\n(Chat.tsx)"]:::ui
        History["Message History\n(MessageHistory.tsx)"]:::ui
        Input["Message Input\n(MessageInput.tsx)"]:::ui
        Diff["Diff Preview\n(DiffPreview.tsx)"]:::ui
        TokenMetricsDisplay["Token Metrics\n(TokenMetrics.tsx)"]:::ui
        ToolHistItem["Tool History Item\n(ToolHistoryItem.tsx)"]:::ui
        LoginOv["Login Overlay\n(Login.tsx)"]:::ui
        ContinueOv["Max Iterations Continue\n(MaxIterationsContinue.tsx)"]:::ui
        ModelSelOv["Model Selector\n(ModelSelector.tsx)"]:::ui
        ApprovalOv["Pending Tool Approval\n(PendingToolApproval.tsx)"]:::ui
        SuggestionsOv["Slash Command Suggestions\n(SlashCommandSuggestions.tsx)"]:::ui
        useAgentHook["useAgent Hook\n(useAgent.ts)"]:::internal
        useTokenHook["useTokenMetrics Hook\n(useTokenMetrics.ts)"]:::internal
    end

    %% Utils & Config
    subgraph "Utils & Config"
        FileOps["File Ops\n(file-ops.ts)"]:::internal
        LocalSettings["Local Settings\n(local-settings.ts)"]:::internal
        Markdown["Markdown Processor\n(markdown.ts)"]:::internal
        Constants["Constants\n(constants.ts)"]:::internal
        LocalConfig[".groq folder\n(Local Config)"]:::persistence
    end

    %% External Service
    subgraph "External Services"
        GroqAPI["Groq AI API"]:::external
    end

    %% Relationships
    User -->|type| Input
    Input -->|invoke slash command| CmdDispatcher
    CmdDispatcher -->|dispatch| Agent
    Agent -->|load schemas| ToolSchemas
    ToolSchemas -->|registry| ToolExecutors
    ToolExecutors -->|validate| Validators
    ToolExecutors -->|execute tool| Agent
    Agent -->|API call| GroqAPI
    GroqAPI -->|response| Agent
    Agent -->|returns result| useAgentHook
    useAgentHook -->|provides data| Chat
    Agent -->|read/write| FileOps
    Agent -->|read/write| LocalSettings
    FileOps -->|persist| LocalConfig
    LocalSettings -->|persist| LocalConfig
    App -->|renders| Chat
    App -->|renders| History
    App -->|renders| Diff
    App -->|renders| TokenMetricsDisplay
    App -->|renders| ToolHistItem
    App -->|uses| useAgentHook
    App -->|uses| useTokenHook

    %% Click Events
    click CLIEntry "https://github.com/build-with-groq/groq-code-cli/blob/main/src/core/cli.ts"
    click Agent "https://github.com/build-with-groq/groq-code-cli/blob/main/src/core/agent.ts"
    click CmdDispatcher "https://github.com/build-with-groq/groq-code-cli/blob/main/src/commands/base.ts"
    click CmdDispatcher "https://github.com/build-with-groq/groq-code-cli/blob/main/src/commands/index.ts"
    click ClearCmd "https://github.com/build-with-groq/groq-code-cli/blob/main/src/commands/definitions/clear.ts"
    click HelpCmd "https://github.com/build-with-groq/groq-code-cli/blob/main/src/commands/definitions/help.ts"
    click LoginCmd "https://github.com/build-with-groq/groq-code-cli/blob/main/src/commands/definitions/login.ts"
    click ModelCmd "https://github.com/build-with-groq/groq-code-cli/blob/main/src/commands/definitions/model.ts"
    click ReasoningCmd "https://github.com/build-with-groq/groq-code-cli/blob/main/src/commands/definitions/reasoning.ts"
    click ToolSchemas "https://github.com/build-with-groq/groq-code-cli/blob/main/src/tools/tool-schemas.ts"
    click ToolExecutors "https://github.com/build-with-groq/groq-code-cli/blob/main/src/tools/tools.ts"
    click Validators "https://github.com/build-with-groq/groq-code-cli/blob/main/src/tools/validators.ts"
    click App "https://github.com/build-with-groq/groq-code-cli/blob/main/src/ui/App.tsx"
    click Chat "https://github.com/build-with-groq/groq-code-cli/blob/main/src/ui/components/core/Chat.tsx"
    click History "https://github.com/build-with-groq/groq-code-cli/blob/main/src/ui/components/core/MessageHistory.tsx"
    click Input "https://github.com/build-with-groq/groq-code-cli/blob/main/src/ui/components/core/MessageInput.tsx"
    click Diff "https://github.com/build-with-groq/groq-code-cli/blob/main/src/ui/components/display/DiffPreview.tsx"
    click TokenMetricsDisplay "https://github.com/build-with-groq/groq-code-cli/blob/main/src/ui/components/display/TokenMetrics.tsx"
    click ToolHistItem "https://github.com/build-with-groq/groq-code-cli/blob/main/src/ui/components/display/ToolHistoryItem.tsx"
    click LoginOv "https://github.com/build-with-groq/groq-code-cli/blob/main/src/ui/components/input-overlays/Login.tsx"
    click ContinueOv "https://github.com/build-with-groq/groq-code-cli/blob/main/src/ui/components/input-overlays/MaxIterationsContinue.tsx"
    click ModelSelOv "https://github.com/build-with-groq/groq-code-cli/blob/main/src/ui/components/input-overlays/ModelSelector.tsx"
    click ApprovalOv "https://github.com/build-with-groq/groq-code-cli/blob/main/src/ui/components/input-overlays/PendingToolApproval.tsx"
    click SuggestionsOv "https://github.com/build-with-groq/groq-code-cli/blob/main/src/ui/components/input-overlays/SlashCommandSuggestions.tsx"
    click useAgentHook "https://github.com/build-with-groq/groq-code-cli/blob/main/src/ui/hooks/useAgent.ts"
    click useTokenHook "https://github.com/build-with-groq/groq-code-cli/blob/main/src/ui/hooks/useTokenMetrics.ts"
    click FileOps "https://github.com/build-with-groq/groq-code-cli/blob/main/src/utils/file-ops.ts"
    click LocalSettings "https://github.com/build-with-groq/groq-code-cli/blob/main/src/utils/local-settings.ts"
    click Markdown "https://github.com/build-with-groq/groq-code-cli/blob/main/src/utils/markdown.ts"
    click Constants "https://github.com/build-with-groq/groq-code-cli/blob/main/src/utils/constants.ts"

    %% Styles
    classDef internal fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef ui fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef persistence fill:#eeeeee,stroke:#9e9e9e,color:#424242
```
