# How to Use Freebuff for Code Linting: AI-Powered Linting with the Freebuff SDK

> Learn how to use Freebuff for code linting with its powerful AI-powered SDK. Get structured feedback via CLI or programmatically for cleaner code.

- Repository: [Codebuff/freebuff](https://github.com/CodebuffAI/freebuff)
- Tags: how-to-guide
- Published: 2026-08-21

---

**Freebuff provides an AI-powered linter through its SDK that sends code to a language model with specialized lint prompts and returns structured feedback, accessible via both CLI and programmatic interfaces.**

Freebuff, an open-source project from the CodebuffAI organization, ships with a built-in linting capability that leverages large language models to analyze code quality. Unlike traditional static analysis tools, **freebuff code linting** uses AI to detect style violations, type-safety issues, and best-practice problems while providing specific fix suggestions. This guide walks through the complete implementation based on the actual source code in the `CodebuffAI/freebuff` repository.

## Installation and Setup

Before running the linter, you must install the project dependencies and build the TypeScript sources. According to the [`package.json`](https://github.com/CodebuffAI/freebuff/blob/main/package.json) configuration in the repository root, this process pulls in the necessary dev tools including TypeScript and the runtime environment.

```bash

# From the repository root

bun install
bun run build

```

The installation step is essential because Freebuff’s package ecosystem relies on Bun as its runtime and package manager. Once complete, you have access to the full SDK including the `run` function located in [`sdk/src/run.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/src/run.ts), which serves as the primary entry point for all AI-powered operations including linting.

## Running the Built-in Lint Example

Freebuff ships with a ready-made example that demonstrates the linting workflow without requiring any custom code. This example lives at [`sdk/e2e/examples/sdk-lint.example.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/e2e/examples/sdk-lint.example.ts) and provides a complete reference implementation.

Execute the example directly from the command line:

```bash
bun run sdk/e2e/examples/sdk-lint.example.ts

```

### Understanding the Example Code

The built-in example imports the `run` function from the relative path `../../src/run` and constructs a lint prompt for a hard-coded code snippet:

```typescript
// sdk/e2e/examples/sdk-lint.example.ts
import { run } from '../../src/run'

const CODE_TO_LINT = `
function add(a,b){return a+b}
`

await run({
  prompt: `Act as a linter. Find issues in this code and provide specific feedback:

${CODE_TO_LINT}`,
  model: 'gpt-4o-mini',
})

```

When executed, this script sends the prompt to the configured language model (defaulting to `gpt-4o-mini`, though any model supported by the runtime works), receives a structured list of warnings, and prints the formatted report to the console. The example demonstrates how **freebuff for code linting** handles formatting issues, implicit types, and spacing violations.

## Programmatic Linting with the SDK

For production use cases or CI/CD integration, you should import the SDK directly and wrap the linting logic in a reusable function. This approach allows you to lint arbitrary code strings or files dynamically.

### Importing the run Function

The core SDK entry point is exported from [`sdk/src/run.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/src/run.ts). Import this function to execute prompts against the language model runtime:

```typescript
// my-lint-tool.ts
import { run } from 'freebuff/sdk/src/run'

async function lintSource(source: string) {
  const result = await run({
    prompt: `You are a TypeScript linter. Point out all style, type-safety, and best-practice issues in the following code and suggest fixes.

${source}`,
    model: 'gpt-4o-mini',
  })
  return result
}

// Example usage
const source = `const foo = (a,b)=>a+b`
lintSource(source).then(console.log)

```

The `run` function accepts a configuration object containing the `prompt` string and the `model` identifier, returning a Promise that resolves to a plain-text lint report.

### Crafting the Lint Prompt

Effective **code linting with freebuff** depends on prompt engineering. The system constructs the lint prompt by prepending role instructions ("Act as a linter" or "You are a TypeScript linter") before the source code. This context primes the model to return structured feedback rather than conversational responses.

## Where the Linter Logic Lives

Understanding the repository structure helps when customizing lint behavior or debugging issues. The linting functionality spans several key files:

- **SDK Entry Point**: The `run` function in [`sdk/src/run.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/src/run.ts) executes prompts against the selected LLM and returns raw text responses.
- **System Prompt Definitions**: The file [`packages/agent-runtime/src/system-prompt/prompts.ts`](https://github.com/CodebuffAI/freebuff/blob/main/packages/agent-runtime/src/system-prompt/prompts.ts) contains the generic prompt templates, including the lint instruction signals that tell the runtime to treat lint as a first-class command (as indicated by the comment `- Commands to run (install/dev/test/lint/build)`).
- **Lint Example**: The runnable reference implementation at [`sdk/e2e/examples/sdk-lint.example.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/e2e/examples/sdk-lint.example.ts) serves as the canonical example for SDK-based linting.
- **CLI Utilities**: Helper functions in [`cli/src/utils/open-file.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/utils/open-file.ts) support file reading operations for CLI-based linting workflows.

## Interpreting Lint Output

Freebuff returns a plain-text block formatted like traditional linter output, making it compatible with existing tooling and editors. A typical response includes numbered issues with specific fix suggestions:

```

1️⃣  Missing space before function parentheses.
   Suggested fix: `function add (a, b) { … }`

2️⃣  Implicit `any` type detected for parameter `b`.
   Suggested fix: add an explicit type annotation.

3️⃣  Unused variable `result`.
   Suggested fix: remove the declaration or use the variable.

```

You can pipe this output to standard Unix tools like `sed` or `grep`, integrate it with VS Code problem matchers, or parse it into JSON if your workflow requires structured data. The text-based format ensures **freebuff code linting** works seamlessly with legacy toolchains that expect standard lint reporter output.

## Summary

- **Freebuff** provides AI-powered linting through the `run` function exported from [`sdk/src/run.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/src/run.ts).
- The built-in example at [`sdk/e2e/examples/sdk-lint.example.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/e2e/examples/sdk-lint.example.ts) demonstrates the complete workflow using `gpt-4o-mini` or any supported model.
- Lint prompts are constructed with role-specific instructions and source code, processed through the runtime defined in [`packages/agent-runtime/src/system-prompt/prompts.ts`](https://github.com/CodebuffAI/freebuff/blob/main/packages/agent-runtime/src/system-prompt/prompts.ts).
- Output follows standard linting format with numbered issues and fix suggestions, compatible with CLI pipes and editor integrations.
- Installation requires `bun install` and optionally `bun run build` from the repository root.

## Frequently Asked Questions

### What models does Freebuff support for linting?

Freebuff supports any model available through its agent runtime configuration. The examples use `gpt-4o-mini` by default, but you can specify other models like GPT-4, Claude, or local models by changing the `model` parameter in the `run` function configuration. The runtime abstraction in `packages/agent-runtime` handles the provider-specific API calls.

### Can I integrate Freebuff linting into my CI/CD pipeline?

Yes. Because the linter returns standard exit codes and plain-text output, you can wrap the `run` function in a Node.js script or use the CLI to lint files in CI environments. Import the SDK in your pipeline scripts, read files into strings, pass them to `run` with a lint prompt, and fail the build if the output contains error patterns or specific severity markers.

### How does Freebuff compare to traditional linters like ESLint?

Traditional linters use static analysis rules and AST parsing, while **freebuff for code linting** uses LLM reasoning to catch contextual issues, logic errors, and style violations simultaneously. Freebuff excels at understanding intent and suggesting semantic fixes that rule-based tools miss, though it requires an API call and incurs latency costs that traditional linters avoid.

### Where is the lint prompt defined in the source code?

The system prompt definitions reside in [`packages/agent-runtime/src/system-prompt/prompts.ts`](https://github.com/CodebuffAI/freebuff/blob/main/packages/agent-runtime/src/system-prompt/prompts.ts), where the runtime recognizes `lint` as a first-class command alongside `install`, `dev`, `test`, and `build` operations. The specific lint instructions (like "Act as a linter") are passed directly to the `run` function's `prompt` parameter in your implementation code, as shown in [`sdk/e2e/examples/sdk-lint.example.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/e2e/examples/sdk-lint.example.ts).