# Freebuff CLI Architecture: Key Files and Code Flow Explained

> Explore the Freebuff CLI architecture. Discover key files like entry.ts and index.tsx and understand the code flow in this modular TypeScript pipeline.

- Repository: [Codebuff/freebuff](https://github.com/CodebuffAI/freebuff)
- Tags: architecture
- Published: 2026-09-01

---

**The Freebuff CLI architecture relies on a modular TypeScript pipeline centered in `cli/src/`, where [`entry.ts`](https://github.com/CodebuffAI/freebuff/blob/main/entry.ts) handles mode detection, [`index.tsx`](https://github.com/CodebuffAI/freebuff/blob/main/index.tsx) orchestrates the React-based UI bootstrap, and specialized utility modules manage terminal commands, API clients, and state persistence.**

Freebuff's command-line interface is implemented as a TypeScript-first, React-driven terminal application. In the `CodebuffAI/freebuff` repository, the CLI code lives under `cli/src/` and follows a strict separation of concerns between process entry, argument parsing, UI rendering, and external command execution. Understanding these core files reveals how the tool manages authentication, project context, and safe subprocess spawning while maintaining an interactive terminal UI.

## Entry Point and Mode Detection

The architecture begins at [`cli/src/entry.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/entry.ts), which serves as the process entry point. This file determines whether the current invocation should run as a **terminal-command broker** or launch the standard interactive UI.

When `process.argv` indicates a broker invocation, the entry script calls `serveTerminalCommandBroker()` to start a detached helper process. Otherwise, it dynamically imports `./index` to enter the normal UI initialization path. This dual-mode design prevents external command output from corrupting the main interface's stdio streams.

## CLI Bootstrapping and Argument Parsing

Once inside the UI path, control passes to [`cli/src/index.tsx`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/index.tsx), the primary bootstrap coordinator. This file chains together several initialization steps:

1. **Argument parsing** via [`cli/src/cli-args.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/cli-args.ts), which wraps the Commander.js library to convert flags like `--login`, `--publish`, or `--smoke-tree-sitter` into a typed options object
2. **Environment preparation**, including project root detection and authentication token retrieval
3. **Client initialization**, where `initializeApp({ cwd })` and `setApiClientAuthToken()` configure the API layer
4. **Renderer setup**, creating an OpenTUI renderer and TanStack Query client
5. **Cleanup handler installation** to ensure terminal state restoration on exit

The `parseArgs()` function from [`cli-args.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli-args.ts) returns structured options that determine whether to execute one-off commands (such as `runPlainLogin()` for authentication flows) or proceed to the interactive React application.

## Core UI and State Management

The top-level React component resides in [`cli/src/app.tsx`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/app.tsx). This component coordinates the high-level application state, including:

- **Authentication gating** and session management through `use-freebuff-session`
- **Project selection** via the built-in Project Picker UI
- **Chat history** and conversation state
- **Freebuff session enforcement** before allowing tool access

Supporting this is [`cli/src/project-files.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/project-files.ts), which centralizes project-root detection, chat identifier generation, and per-project data storage. When users switch projects through the UI, `handleProjectChange` updates the global `projectRoot`, resets the Codebuff client, and persists the recent path to disk, ensuring chat continuity across application restarts.

## Terminal Command Execution

External shell commands (triggered when users press `:` followed by a command like `git status`) are handled by [`cli/src/utils/terminal-command-broker.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/utils/terminal-command-broker.ts). Rather than spawning processes directly within the UI thread—which would corrupt the terminal interface—this module implements a detached helper pattern.

The broker creates a `TerminalCommandSpawnRequest`, spawns the process via `child_process.spawn` in an isolated subprocess, and communicates results through a JSON protocol file. Error classification via `classifyTerminalBrokerFailure` ensures proper analytics tracking without crashing the main renderer.

## API Client and Authentication

API communication is abstracted through two coordinated files:

- **[`cli/src/utils/codebuff-client.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/utils/codebuff-client.ts)**: A singleton wrapper around the Codebuff SDK that maintains the authentication token, tracks request lifecycles, and exposes a reusable client to React components
- **[`cli/src/utils/codebuff-api.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/utils/codebuff-api.ts)**: Lower-level API configuration and endpoint management used by the client wrapper

During bootstrap, [`index.tsx`](https://github.com/CodebuffAI/freebuff/blob/main/index.tsx) retrieves the stored token and calls `setApiClientAuthToken()` to configure the singleton before any UI components mount.

## Utility and Cleanup Services

Several cross-cutting utilities in `cli/src/utils/` support the main architecture:

- **[`renderer-cleanup.ts`](https://github.com/CodebuffAI/freebuff/blob/main/renderer-cleanup.ts)**: Installs process-exit handlers (`SIGINT`, `SIGTERM`, crashes) to restore the terminal to a sane state
- **[`logger.ts`](https://github.com/CodebuffAI/freebuff/blob/main/logger.ts)**: Structured logging for debugging and error reporting
- **[`analytics.ts`](https://github.com/CodebuffAI/freebuff/blob/main/analytics.ts)**: Event dispatch for usage tracking, including broker failure classification
- **[`terminal-watchdog.ts`](https://github.com/CodebuffAI/freebuff/blob/main/terminal-watchdog.ts)**: Windows-specific health monitoring to detect and recover from terminal state corruption

## Execution Flow Example

The following code illustrates how these files interact during a standard launch:

```typescript
// cli/src/entry.ts
if (isTerminalCommandBrokerInvocation(process.argv)) {
  await serveTerminalCommandBroker();   // Detached helper mode
} else {
  await import('./index');              // Normal UI path
}

// cli/src/index.tsx – main bootstrap
async function main() {
  const { initialPrompt, command, ...options } = parseArgs();   // cli-args.ts
  await initializeApp({ cwd });
  setApiClientAuthToken(getAuthToken());

  if (command === 'login')   await runPlainLogin();
  if (command === 'publish') await handlePublish(options);

  const queryClient = createQueryClient();             // TanStack Query
  const renderer = await createCliRenderer(...);       // OpenTUI

  installProcessCleanupHandlers(renderer);               // renderer-cleanup.ts
  startTerminalWatchdog();                               // Windows health

  createRoot(renderer).render(
    <QueryClientProvider client={queryClient}>
      <App projectRoot={getProjectRoot()} />             // app.tsx
    </QueryClientProvider>
  );
}
void main();

```

## Summary

- **[`cli/src/entry.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/entry.ts)** detects execution mode and routes between the terminal broker and UI bootstrap
- **[`cli/src/cli-args.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/cli-args.ts)** parses command-line flags using Commander.js into typed options
- **[`cli/src/index.tsx`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/index.tsx)** orchestrates the full startup sequence, including React renderer initialization
- **[`cli/src/app.tsx`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/app.tsx)** serves as the root React component managing authentication and project state
- **[`cli/src/project-files.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/project-files.ts)** handles project-root detection and chat persistence
- **[`cli/src/utils/terminal-command-broker.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/utils/terminal-command-broker.ts)** safely executes external commands in detached processes
- **[`cli/src/utils/codebuff-client.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/utils/codebuff-client.ts)** provides a singleton SDK wrapper for API communication
- **[`cli/src/utils/renderer-cleanup.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/utils/renderer-cleanup.ts)** ensures terminal restoration on process exit

## Frequently Asked Questions

### What file handles argument parsing in the Freebuff CLI?

The file [`cli/src/cli-args.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/cli-args.ts) manages argument parsing by wrapping the Commander.js library. It exports a `parseArgs()` function that converts raw process arguments into a typed options object, handling flags like `--login`, `--publish`, and various smoke-test options.

### How does Freebuff prevent terminal corruption when running shell commands?

Freebuff uses [`cli/src/utils/terminal-command-broker.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/utils/terminal-command-broker.ts) to spawn external commands in a detached subprocess via `child_process.spawn`. This broker communicates with the main UI through a JSON protocol file, ensuring that stdout/stdio from tools like `git` or `npm` never interfere with the React-based terminal interface managed by OpenTUI.

### Where is the project root and chat history stored in Freebuff?

The [`cli/src/project-files.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/project-files.ts) module centralizes project-root detection, chat identifier management, and per-project data storage. It provides functions to retrieve the current working directory, persist recent paths, and maintain chat continuity across application restarts.

### What happens when I run the `login` command?

When you execute `codebuff-tui login`, [`cli-args.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli-args.ts) captures the `login` command flag, and [`cli/src/index.tsx`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/index.tsx) calls `runPlainLogin()`. This function initiates a browser-based OAuth flow, retrieves the authentication token, and stores it via the singleton client in [`cli/src/utils/codebuff-client.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/utils/codebuff-client.ts) for subsequent API requests.