How the Public Freebuff Repository Mirrors the Private Codebuff Source Tree

The Freebuff repository is a public mirror of the private Codebuff source tree, where the private codebase serves as the single source of truth and contributions flow through a port-and-export workflow rather than direct merges.

The CodebuffAI/freebuff repository on GitHub represents the open-source interface to a larger proprietary ecosystem. Understanding the relationship between the public Freebuff repository and the private Codebuff source tree is essential for contributors and SDK users. While the public mirror exposes the CLI, SDK, and agent definitions, the proprietary core—including billing systems, deployment scripts, and secret management—remains secured in the private repository and exported automatically.

The Mirror Architecture: Private Codebuff as the Source of Truth

The private Codebuff repository functions as the single source of truth for the entire platform. All core logic, internal microservices, billing infrastructure, and deployment automation live exclusively in this private tree. The public Freebuff repository you interact with on GitHub is a read-only mirror generated through an automated export process.

Maintainers never commit directly to the public repository. Instead, when the private codebase changes, a CI-driven export step regenerates the public mirror, syncing CONTRIBUTING.md, README.md, and the sdk/ directory with the current state of the private source. This ensures the public Freebuff repository always reflects the private Codebuff tree while keeping proprietary components hidden.

The Contribution Workflow: From Public Pull Request to Private Merge

Contributions follow a specific port-and-export cycle that preserves the integrity of the source of truth:

1. Contributor opens a pull request against the public CodebuffAI/freebuff repository.
2. Maintainer reviews and ports the patch into the private Codebuff repository, applying it to the actual source of truth.
3. Private CI processes the change, running internal tests against the full stack including proprietary services.
4. Export regenerates the mirror, pushing the updated open-source subset (CLI, SDK, agents, docs) back to the public Freebuff repo.
5. Public PR is closed as the changes now exist in the mirror, effectively "merged" via the export rather than a direct Git merge.

According to the CONTRIBUTING.md file in the public repository, this workflow ensures that "accepted public contributions are ported into the private repo and then exported back here." Consequently, you will never see a merge commit from a public pull request in the Freebuff history; the commits originate from the private export instead.

Code Structure: What Lives in Public Versus Private

The public mirror contains only the open-source surface area of the Codebuff platform. Key public components include:

• sdk/src/client.ts – The public SDK entry point that wraps private Codebuff logic.
• sdk/src/run.ts – The core runtime that marshals tool calls and proxies them to private services.
• agents/ – Public agent definitions that mirror implementations in the private tree.
• common/ – Shared TypeScript types and utilities used by both public and private code.

The private repository contains the corresponding backend implementations. When you instantiate CodebuffClient from the public SDK, your calls travel to the private Codebuff API hosted in the source tree. The private side handles the actual execution of tools, agent orchestration, billing validation, and secret management, ensuring these sensitive operations never expose implementation details in the public mirror.

Working with the Public Freebuff SDK

Even though the heavy lifting occurs in the private Codebuff source tree, you interact with the system through the public SDK installed from the Freebuff repository. The following TypeScript example demonstrates how the public client forwards requests to the private backend:

// Example: Using the public Freebuff SDK (which wraps private Codebuff logic)
import { CodebuffClient } from '@codebuff/sdk';

// Create a client – the SDK forwards calls to the private backend via the
// Codebuff API (the private repo hosts the API implementation).
const client = new CodebuffClient({
  apiKey: process.env.CODEBUFF_API_KEY, // read from env at runtime
  // …other options
});

// Run a tool (e.g., read a file) – the request travels through the public SDK
// to the private Codebuff server, which performs the operation.
const result = await client.runTool('read_files', {
  cwd: './src',
  pattern: '**/*.ts',
});
console.log(result);

In this workflow, the public sdk/src/client.ts and sdk/src/run.ts files provide the interface, while the private Codebuff source tree hosts the API implementation that fulfills these requests.

Summary

• The private Codebuff repository is the single source of truth containing all core logic, billing, and deployment code.
• The public Freebuff repository is a read-only mirror generated through an automated export process from the private tree.
• Pull requests to the public repo are ported into the private repo by maintainers and never merged directly; the next export synchronizes the changes back to the mirror.
• The public SDK (sdk/src/client.ts) exposes the interface, but execution depends on the private Codebuff API.
• Proprietary components remain exclusively in the private repository, ensuring they are never exposed in the public CodebuffAI/freebuff mirror.

Frequently Asked Questions

Why doesn't Codebuff merge pull requests directly into the public repository?

Direct merges would create divergent histories between the mirror and the source of truth. The private repository drives the export process unidirectionally. When you submit a patch, maintainers apply it to the private Codebuff tree, and the subsequent automated export regenerates the public Freebuff repository with your changes included. This guarantees that the private codebase always maintains authoritative control over the release state.

How long does it take for an accepted contribution to appear in the public Freebuff repository?

Once a maintainer ports your patch into the private Codebuff source tree, the export CI pipeline typically regenerates the public mirror within minutes to hours depending on the build cycle. The CONTRIBUTING.md file notes that the public repository reflects the current state of the private code only after this export step completes, not immediately upon private acceptance.

Can I run the Freebuff CLI entirely offline using only the public repository?

No. While the CLI code and SDK (sdk/src/run.ts) are available in the public mirror, the execution of tools and agent orchestration requires the private Codebuff API. The CodebuffClient class forwards all operational requests to backend services hosted from the private repository. Without connectivity to these private services, the public CLI cannot perform core functions like tool execution or agent management.

What files indicate that Freebuff is a mirror rather than a standalone repository?

The CONTRIBUTING.md file explicitly states that "this repository is a public mirror of the Freebuff/Codebuff source tree" and identifies the private repository as the source of truth. Additionally, the README.md clarifies that "Freebuff is built on Codebuff, the open multi-agent framework," acknowledging the dependency on the private source tree even as it documents the public interface.

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