# How to Suggest a New Feature for Freebuff: The Complete Contributor Workflow

> Suggest a new feature for Freebuff via GitHub Issues using our Feature Request template. Learn the complete contributor workflow and how your contributions are integrated.

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

---

**Freebuff accepts feature suggestions through GitHub Issues using the Feature Request template, but code contributions must remain within scoped directories like `cli/`, `sdk/`, `agents/`, `packages/agent-runtime/`, `packages/code-map/`, and `scripts/tmux/`, with PRs undergoing automated structural validation before maintainers port changes to the private upstream repository.**

Freebuff is an open-source project hosted at `CodebuffAI/freebuff` that welcomes community feature ideas, though it operates as a public mirror of a private upstream repository. To suggest a new feature for Freebuff effectively, contributors must follow a specific workflow that ensures proposals are properly documented, scoped correctly, and compatible with the automated porting system that syncs changes between repositories.

## Phase 1: Proposal and Discovery

### Search Existing Issues

Before creating a new request, browse the open issues in the `CodebuffAI/freebuff` repository to verify your idea has not been proposed. Filter the issue tracker by the *feature* label to identify existing suggestions that match your concept.

### Create a Feature Request Issue

If your idea is novel, open a new issue and select the **Feature Request** template. According to the [`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md) guidelines, your description must include:

- A concise, descriptive title stating the feature clearly.
- Detailed motivation explaining why the feature is needed and who benefits.
- A high-level design sketch or example usage, with optional code snippets.
- Analysis of potential impact on existing functionality, particularly if modifying core areas such as `cli/`, `sdk/`, or `agents/`.

## Phase 2: Development Preparation

### Verify Contribution Scope

Freebuff restricts public contributions to specific directories to maintain the integrity of the private upstream system. You may only modify files within:

- `cli/`
- `sdk/`
- `common/`
- `agents/`
- `packages/agent-runtime/`
- `packages/code-map/`
- `scripts/tmux/`

Contributions adding new backend services, database schemas, billing logic, or secret-management code are explicitly prohibited in the public mirror. Consult the **Public Contributions** section of [`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md) for the complete list of permissible paths.

### Set Up Local Development Environment

Clone the repository and install dependencies using the Bun runtime:

```bash
bun install

```

After making changes, compile the project using the provided build scripts:

```bash
bun run build:sdk
bun run build:freebuff

```

## Phase 3: Implementation and Testing

### Write Code and Tests

Develop your feature within the scoped directories. For example, when adding a new CLI flag like `--dry-run`, you would extend `cli/src/commands/*` to accept the option. The implementation must handle the flag appropriately:

```diff
diff --git a/cli/src/commands/deploy.ts b/cli/src/commands/deploy.ts
@@ -5,6 +5,7 @@ import { Command } from 'commander';
 
 export const deploy = new Command('deploy')
   .description('Deploy agents to the cloud')
+  .option('--dry-run', 'Show actions without executing')
   .action(async (opts) => {
-    await performDeployment();
+    if (opts.dryRun) {
+      console.log('[dry-run] Would perform deployment');
+      return;
+    }
+    await performDeployment();
   });

```

Write unit tests for any new public APIs or CLI commands. Freebuff's test suite runs automatically on pull-request creation. Place tests appropriately, such as in [`cli/src/__tests__/dry-run.test.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/__tests__/dry-run.test.ts) for CLI functionality. Consult [`docs/testing.md`](https://github.com/CodebuffAI/freebuff/blob/main/docs/testing.md) for detailed instructions on running the test suite locally.

## Phase 4: Submission and Review

### Submit a Pull Request

Submit your change as a PR against the **public** repository. Your PR must:

- Stick to the scoped paths listed above.
- Include a clear title and description that repeats the motivation from the issue.
- Provide a brief summary of the implementation approach.

### Navigate Automated Checks

A bot runs three automated structural checks (title, description, and scope) a few seconds after the PR is opened. These checks validate that your contribution adheres to formatting rules and directory restrictions. If any check fails, edit the PR until they succeed; failing checks block merging.

### Maintainer Review and Porting

Since the public repository is a read-only mirror, maintainers do not merge PRs directly into it. Instead, they **port** accepted changes into the private source tree. The next export sync will bring the updated code back into the public view.

### Handle Revisions and Follow-up

If a maintainer closes your PR, they will leave a comment explaining the reasoning. Closed PRs are not final rejections. You can reply to address concerns and request the PR be reopened after clarification.

## Summary

- Freebuff accepts feature suggestions via GitHub Issues using the Feature Request template, requiring detailed motivation and design sketches.
- Contributions must remain within scoped directories: `cli/`, `sdk/`, `common/`, `agents/`, `packages/agent-runtime/`, `packages/code-map/`, and `scripts/tmux/`.
- Local development requires `bun install` and build commands `bun run build:sdk` and `bun run build:freebuff`.
- All PRs must pass three automated structural checks (title, description, scope) before maintainer review.
- Accepted changes are ported to the private upstream repository rather than merged directly in the public mirror.

## Frequently Asked Questions

### What directories can I contribute to in Freebuff?

According to the [`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md) source file, public contributions are limited to `cli/`, `sdk/`, `common/`, `agents/`, `packages/agent-runtime/`, `packages/code-map/`, and `scripts/tmux/`. These directories contain the CLI tooling, SDK libraries, and agent runtime code that are safe for community modification. Adding backend services or database schemas is not permitted.

### Why won't my PR be merged directly into the public repository?

The `CodebuffAI/freebuff` repository operates as a public mirror of a private upstream repository. Because of this architecture, maintainers **port** accepted changes into the private source tree rather than merging PRs directly. The changes then appear in the public mirror during the next scheduled sync.

### What are the three automated structural checks for PRs?

The automated validation system checks three specific structural elements: the PR title format, the description completeness, and whether the changed files remain within the permitted contribution scope (directories). These checks run automatically seconds after PR creation and block merging until all criteria pass.

### Can I suggest features that require new backend services?

No. The source code analysis explicitly prohibits contributions that add new backend services, database schemas, billing logic, or secret-management code in the public mirror. While you can suggest these features via Issues, the implementation must be handled by internal maintainers due to security and architectural constraints.