TeamAI Single-Repo Mode (`--self`): Complete Guide and When to Use It

Use the --self flag when your current Git repository should serve as the TeamAI knowledge hub, storing skills and configuration in .teamai/ alongside your source code while isolating reports to a dedicated orphan branch.

The Tencent/teamai-cli supports two distinct operational scopes: the default multi-repo mode that clones a separate team repository, and the single-repo mode triggered by the --self flag. This guide explains how single-repo mode works under the hood—referencing the actual source implementation—and identifies the specific scenarios where it outperforms the default approach.

How Single-Repo Mode Works

TeamAI typically operates by cloning a dedicated team repository to store shared knowledge and generate reports. In single-repo mode, the CLI treats your current Git repository as the team repository itself, eliminating external clones.

According to the CLI definition in src/index.ts, the --self flag configures the tool so that "Knowledge lives on main under .teamai/; reports go to the teamai-reports orphan branch" [src/index.ts#L56-L57]. This architecture keeps all TeamAI data within your existing project boundaries while maintaining clean separation between source code and analytics.

The initSelfRepo Implementation

The initialization logic resides in src/init.ts, where the initSelfRepo function executes the setup. As documented in the source comments, this routine handles "Single-repo mode init" where "The current git repo IS the team repo" [src/init.ts#L666-L672].

The function performs four critical steps:

1. Validation – Confirms the current directory is a valid Git repository.
2. Skeleton Creation – Generates the .teamai/ directory structure directly in the project root.
3. Configuration – Writes teamai.yaml containing mode: self to persist the setting [src/init.ts#L84-L92].
4. Report Partitioning – Configures an isolated work-tree that routes reports to the teamai-reports orphan branch without touching your active working directory.

Multi-Repo vs. Single-Repo Architecture

Understanding the distinction helps determine when to use the --self flag:

• Multi-repo (default) – The CLI clones a separate team repository. Knowledge populates .teamai/ in that external clone, and reports live in a teamai-reports orphan branch of the team repo.
• Single-repo (--self) – No clone occurs. Knowledge stores in your project root under .teamai/, and the teamai-reports branch is created within the same repository using a detached work-tree to preserve working tree cleanliness.

When to Use the --self Flag

Enable single-repo mode in the following scenarios:

Your project already functions as the team repository If you work in a mono-repo where the entire codebase is shared among teammates, single-repo mode avoids redundant clones and keeps AI knowledge co-located with the code it describes.

You require minimal onboarding complexity When you want to avoid managing a separate remote team repository, --self simplifies setup—teammates only need to clone the project once to access both source code and TeamAI configuration.

You want version-controlled knowledge All skills, rules, and learnings stored in .teamai/ commit directly to your main branch and travel with your code history, ensuring synchronization between project state and AI behavior.

You need isolated report storage without repository bloat Reports generate on the teamai-reports orphan branch via an isolated work-tree, keeping analytics version-controlled but completely separate from your development files.

Initializing Single-Repo Mode

Activate the mode using the init command with the --self flag:

# Initialize TeamAI in the current repository (single-repo mode)

teamai init . --self

# Equivalent shorthand

teamai init --self

This command validates your Git repository, creates the .teamai/ folder, writes the teamai.yaml configuration with mode: self, and prepares the teamai-reports orphan branch for analytics.

To reset an existing configuration without confirmation prompts:

teamai init . --self --force

The --force flag bypasses safety checks and regenerates the configuration, useful when migrating from multi-repo to single-repo mode.

Summary

• The --self flag activates single-repo mode, making your current Git repository the TeamAI knowledge hub according to the logic in src/index.ts.
• Knowledge stores in .teamai/ on your main branch, while reports isolate to the teamai-reports orphan branch via the initSelfRepo function in src/init.ts.
• This mode eliminates external repository clones, streamlining workflows for mono-repos and small teams.
• Configuration persists in .teamai/teamai.yaml with the explicit setting mode: self.

Frequently Asked Questions

What is the difference between teamai init and teamai init --self?

The default teamai init clones a separate team repository to store knowledge and reports externally, requiring management of two distinct remotes. Using --self treats your current directory as the team repository itself, storing the .teamai/ folder locally and keeping all TeamAI data within the existing Git project boundaries.

Does single-repo mode pollute my working branch with report files?

No. As implemented in src/init.ts, reports are stored in the teamai-reports orphan branch using an isolated work-tree mechanism. This ensures your active working tree remains clean and uncluttered while analytics remain version-controlled within the same repository.

Can I switch from multi-repo to single-repo mode after initialization?

Yes. Run teamai init . --self --force to overwrite the existing configuration. The --force flag bypasses confirmation prompts and rewrites teamai.yaml with mode: self, effectively relocating the knowledge base from an external clone into your current repository.

Where does the single-repo mode store its configuration?

The configuration is stored in teamai.yaml within the .teamai/ directory at your project root. This file explicitly sets mode: self, which the CLI parses during subsequent operations—as seen in the configuration handling logic—to determine whether to look for knowledge locally or in an external team repository.

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