# TeamAI Single-Repo Mode (`--self`): Complete Guide and When to Use It > Master TeamAI single-repo mode with the --self flag. Learn when to use it for a self-contained knowledge hub storing skills and config in .teamai alongside your code. - Repository: [Tencent/teamai-cli](https://github.com/tencent/teamai-cli) - Tags: how-to-guide - Published: 2026-09-11 --- **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`](https://github.com/Tencent/teamai-cli/blob/main/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`](https://github.com/Tencent/teamai-cli/blob/main/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`](https://github.com/Tencent/teamai-cli/blob/main/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: ```bash # 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`](https://github.com/Tencent/teamai-cli/blob/main/teamai.yaml) configuration with `mode: self`, and prepares the `teamai-reports` orphan branch for analytics. To reset an existing configuration without confirmation prompts: ```bash 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`](https://github.com/Tencent/teamai-cli/blob/main/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`](https://github.com/Tencent/teamai-cli/blob/main/src/init.ts). - This mode eliminates external repository clones, streamlining workflows for mono-repos and small teams. - Configuration persists in [`.teamai/teamai.yaml`](https://github.com/Tencent/teamai-cli/blob/main/.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`](https://github.com/Tencent/teamai-cli/blob/main/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`](https://github.com/Tencent/teamai-cli/blob/main/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`](https://github.com/Tencent/teamai-cli/blob/main/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.