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

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 configuration in the repository root, this process pulls in the necessary dev tools including TypeScript and the runtime environment.

# 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, 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 and provides a complete reference implementation.

Execute the example directly from the command line:

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:

// 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. Import this function to execute prompts against the language model runtime:

// 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 executes prompts against the selected LLM and returns raw text responses.
• System Prompt Definitions: The file 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 serves as the canonical example for SDK-based linting.
• CLI Utilities: Helper functions in 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.
• The built-in example at 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.
• 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, 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.

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