How to Use Freebuff for Code Formatting: CLI Guide and Architecture

Freebuff provides an AI-powered code formatting interface that invokes external formatters like Prettier through a unified CLI, automatically sanitizing and truncating output for safe display.

Freebuff is an open-source AI coding assistant framework that includes a built-in code formatting pipeline. The formatting tool processes your files through the freebuff format command while streaming sanitized, length-limited results back to your terminal. This guide explains how to use the CLI effectively and explores the underlying architecture implemented in the CodebuffAI/freebuff repository.

Basic Usage with the Freebuff CLI

To format code using Freebuff, invoke the formatter through the CLI entry point defined in freebuff/cli/release.ts. The tool accepts file paths, directories, or glob patterns as arguments.

Install Freebuff globally (if not already installed):

bun install -g @codebuff/freebuff

Run the formatter on a single file or entire project:

# Format a specific file

freebuff format src/index.ts

# Format recursively from current directory

freebuff format .

The CLI dispatches to the format tool definition located in agents/types/tools.ts, which specifies the input schema, output type, and termination semantics including the endsAgentStep flag that signals completion of the formatting operation.

CLI Options and Flags

Freebuff supports several flags to control formatting behavior and output visibility.

Dry-Run Mode and Diff Preview

Use --dry-run to preview changes without modifying files. This flag displays the diff through the truncation-safe output handler:

freebuff format --dry-run src/utils.ts

The runtime implementation in sdk/src/tools/run-terminal-command.ts executes the formatter as a child process and captures the diff output. When displaying results, the format() method automatically truncates content exceeding the character limit and inserts the [...TRUNCATED DUE TO LENGTH...] sentinel to maintain UI responsiveness.

Custom Configuration Files

Point to custom formatter configurations using the --config flag:

freebuff format . --config .prettierrc.cjs

The CLI passes this configuration path through to the underlying formatter process. According to the tool schema in agents/types/tools.ts, the formatter accepts configuration overrides while maintaining the same output sanitization rules.

Output Length Limiting

Control the maximum streamed output size with --max-output:

freebuff format src/ --max-output 5000

This parameter directly configures the truncation threshold in the format() method, ensuring that large formatting jobs do not flood the terminal or AI context windows.

Architecture and Implementation Details

The formatting pipeline consists of three coordinated components across the codebase.

Tool Definition in agents/types/tools.ts

The format tool is formally defined in agents/types/tools.ts. This file declares the tool's interface, including input parameters (file paths, config options), return type specifications, and the endsAgentStep boolean that marks the completion of a formatting step in the agent's execution loop.

Runtime Execution in sdk/src/tools/run-terminal-command.ts

The actual execution logic resides in sdk/src/tools/run-terminal-command.ts. The format() method in this file:

• Spawns the external formatter process (Prettier, ESLint --fix, or custom)
• Captures stdout and stderr streams
• Sanitizes ANSI color codes for safe display
• Applies length truncation with the [...] marker
• Returns a structured JSON response containing the formatted output or error details

CLI Entry Point in freebuff/cli/release.ts

Argument parsing and command dispatch occur in freebuff/cli/release.ts. This file maps the format subcommand to the runtime tool invocation, handling path resolution, flag validation, and error propagation back to the user.

Output Formatting in common/src/util/format-code-search.ts

Multi-file diff formatting and pretty-printing utilities are provided by common/src/util/format-code-search.ts. This helper module supports the presentation layer by structuring output when formatting multiple files simultaneously, ensuring consistent diff formatting across the CLI output.

Practical Examples

Format a single file with verbose output:

freebuff format src/components/Button.tsx

Preview changes across the entire codebase before applying:

freebuff format --dry-run . --config ./prettier.config.js

Format with strict output limits for AI context windows:

freebuff format src/lib/ --max-output 2000 --dry-run

Summary

• Use freebuff format <path> to invoke the AI-powered formatter on files or directories, with the CLI entry point located in freebuff/cli/release.ts.
• Preview changes safely by adding --dry-run to see diffs without writing files, with output sanitized and truncated by the format() method in sdk/src/tools/run-terminal-command.ts.
• Customize behavior through --config for formatter settings and --max-output for length limits, as defined in the tool schema at agents/types/tools.ts.
• Multi-file support leverages common/src/util/format-code-search.ts for structured diff presentation when formatting entire projects.

Frequently Asked Questions

What formatter engine does Freebuff use by default?

According to the agents/types/tools.ts schema and runtime implementation, Freebuff defaults to Prettier for JavaScript/TypeScript files, though the architecture supports any external formatter that accepts file paths via CLI arguments. You can override the engine by specifying a custom executable through the --config flag or modifying the tool definition.

How does Freebuff handle large formatting outputs?

The format() method in sdk/src/tools/run-terminal-command.ts implements automatic truncation. When output exceeds the default or user-specified character limit (set via --max-output), the system inserts a [...TRUNCATED DUE TO LENGTH...] marker and discards remaining content to protect terminal performance and AI context window limits.

Where is the formatting tool defined in the source code?

The tool interface is defined in agents/types/tools.ts, which specifies the format tool's parameters, return types, and the endsAgentStep termination flag. The runtime implementation that executes the actual formatting command resides in sdk/src/tools/run-terminal-command.ts, while the CLI wrapper is found in freebuff/cli/release.ts.

Can I format multiple files with different configurations?

Yes. Invoke freebuff format multiple times with different --config flags targeting specific directories, or use a single command on a parent directory. The common/src/util/format-code-search.ts utility handles the aggregation and display of multi-file results, though each formatting operation respects the configuration file found in its target path or specified via CLI flags.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}