# Overview

Metagit gives you situational awareness across Git repositories. It helps multi-repo projects feel manageable by keeping stack details, generated artifacts, dependencies, and related metadata in one place.

## About

This tool works well for scenarios like:

1. At-a-glance view of a project's technical stacks, languages, external dependencies, and generated artifacts.
2. Switching between many Git projects during the day without losing context.
3. Isolating outside dependencies that weaken the security and dependability of your software delivery pipelines.
4. Automated documentation of a code's provenance.
5. Helping new contributors get from onboarding to first commit faster.

Metagit is designed for developers, SREs, and AI agents who work across connected repositories. It tracks the dependencies and project relationships that are easy to miss when you only look at one repo at a time.

## Audience

This tool targets:

- DevOps Engineers
- Polyglot developers
- New team members
- Project Managers
- SREs
- Solution Engineers
- AI Agents (more to come!)

## Metagit is NOT...

### ...an SBOM tool

SBOM output is often thousands of lines and includes full transitive dependency trees. That level of detail is usually too heavy for day-to-day situational awareness and agent context. Metagit may read SBOM manifests as an input in the future, but it is not trying to replace SBOM tooling.

Metagit uses common project files (for example `go.mod`, `package.json`, and `requirements.txt`) for detection and validation boundaries. These are used to identify stack composition, not to provide exhaustive version intelligence.

### ...a Git client

Despite the name, this still relies on Git and your existing hosting platform.

### ...a full project packer

Metagit intentionally focuses on the highest-value project signals. It does not package full repositories. If you need full-project packing, use [repomix](https://github.com/yamadashy/repomix/tree/main).

### Why brevity?

One of the core goals is reducing cognitive load when understanding project relationships. A practical side effect is lower token usage for automated AI workflows.

## How it works

Metagit stores project configuration metadata in `.metagit.yml` inside the repository. That file follows a schema that the CLI can validate and read.

If you use Metagit for dozens of repositories (an umbrella workspace), you can edit the config manually or refresh it with heuristics and AI-assisted workflows.

## Modes

Metagit supports several operating modes:

### Workspace mode

This is the first planned open-source CLI mode.

In this mode, you group related repositories into one workspace that you can open in VS Code or access individually from the terminal.

> **AKA** Multi-repo as Monorepo

You use one top-level umbrella project with a single metagit definition file that tracks related repositories and local target folders. You can then sync that workspace locally.

The metagit configuration file is committed to version control as its own project artifact.

**Managed repo lookup:** Use `metagit search` / `metagit find` for quick CLI lookup of repos declared in `.metagit.yml` (with optional tags and JSON output). MCP clients can call `metagit_repo_search`, and `metagit api serve` exposes the same search and resolve behavior over a small local JSON HTTP API for agents and scripts.

This mode is useful for:

- Creating umbrella projects for new team members of a multi-repo project
- Individual power users that need to quickly pivot between several project repositories that comprise a larger team effort
- Keeping loosely coupled Git projects grouped without relying on submodules

### Metadata mode

This mode uses the same config file as workspace mode, with additional metadata such as primary language, frameworks, and other context you want available when entering a repo.

Configuring this by hand for one project is simple. Doing it across dozens or thousands of repos is not. Metagit uses detection heuristics to automate as much as possible and can use AI workflows where deterministic code is not enough.

> **Note**: AI-assisted detection should be monitored and converted into deterministic logic over time.

In this mode, Metagit helps answer questions like:

- What other projects are related to this project?
- What application and development stacks does this project use?
- What external dependencies exist for this project?
- What artifacts does this project create?
- What branch strategy is employed?
- What version strategy is employed?

> **External dependencies** are a common source of pipeline instability.

## Related guides

- [Installation](install.md) — global install, tab completion, MCP, first-run `metagit init`
- [For AI agents](agents.md) — context packs, CLI vs MCP, session workflow
- [Terminology](terminology.md) — workspace, project, repo hierarchy
- [CLI reference](cli_reference.md)
