# git-ai-project/git-ai architecture

> Architecture diagram of the GitHub repository git-ai-project/git-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/git-ai-project/git-ai
- Repository: https://github.com/git-ai-project/git-ai
- Video tour (about a minute): https://gitdiagram.com/git-ai-project/git-ai/video

## Overview

1. **What this repo is**
   - `git-ai` is a Rust-first CLI and background service for attributing AI-generated code at line level.
   - The core architectural promise is: agents/editor plugins report what they changed, and Git AI persists that provenance through commits and later Git rewrites using Git Notes plus local state.

2. **Top-level runtime split**
   - The Rust crate under `src/` is the authoritative engine and CLI.
   - Companion editor/agent integrations live under `agent-support/`:
     - VS Code / Cursor / Windsurf / OpenCode in TypeScript
     - IntelliJ in Kotlin
     - Visual Studio in C#
     - lightweight agent wrappers such as `pi` and `amp`
   - These integrations are adapters, not the source of truth; they feed change events and session metadata back into the Rust core.

3. **CLI and command boundary**
   - `src/main.rs` and `src/commands/` expose user-facing commands such as blame, stats, checkpointing, install hooks, login/logout, daemon control, and Git rewrite helpers.
   - This layer is the primary entry point for shell users and for automation in CI or background agents.

4. **Daemon as the orchestration layer**
   - `src/daemon/` is the long-lived coordination process.
   - It watches repo activity, ingests change streams, normalizes traces, resolves checkpoints, and reacts to Git operations like commit, amend, rebase, merge, stash, cherry-pick, and reset.
   - Internally it is split into analyzers, coordinators, reducers, workers, and telemetry plumbing, which suggests an event-driven pipeline rather than a single monolith.

5. **Authorship engine**
   - `src/authorship/` is the core attribution engine.
   - It turns raw change evidence into line/range ownership, handles move/rebase detection, merges human and AI edits, manages prompt/session associations, and reconstructs attribution after history rewriting.
   - This is where the repository’s key invariant lives: attribution must follow the code, not just the commit that first introduced it.

6. **Git integration and persistence**
   - `src/git/` wraps repo inspection, status, refs, diffing, notes, and rewrite-log handling.
   - Git Notes are the durable storage mechanism for attribution metadata attached to commits.
   - The system also keeps local repo/working state so it can repair attribution during transient states before the final note is written.

7. **Change ingestion from agents and IDEs**
   - `src/streams/` parses transcript/event formats from many agents: Claude, Copilot, Codex, Cursor, Droid, Gemini, OpenCode, Pi, Windsurf, Amp, and related variants.
   - `src/commands/checkpoint_agent/` and the agent-support packages translate editor or agent activity into checkpoint events.
   - The data flow is: agent/editor activity -> transcript/event parser -> checkpoint model -> authorship reconstruction.

8. **Notes, metrics, and reporting**
   - `src/notes/` manages note storage/migration and a reference server for note-related operations.
   - `src/metrics/` tracks operational and usage metrics locally, including event attribution and stats aggregation.
   - User-facing readouts like `git ai stats` and `git ai blame` are built from these persisted notes plus repository history.

9. **Auth and optional remote services**
   - `src/auth/` and `src/api/` exist for login, identity, credentials, and remote note/metrics operations.
   - The README emphasizes local-first use, but the codebase also supports enterprise/team flows where data can be synchronized or aggregated across repos and SCM providers.
   - `src/ci/` and the GitHub/GitLab workflow templates show that attribution preservation is also supported in hosted CI and PR workflows.

10. **Installation and managed integrations**
   - `src/mdm/` plus `install.sh`, `install.ps1`, and the `scripts/` directory handle distribution, agent hook installation, editor detection, and auxiliary setup.
   - This layer is responsible for making integrations present and compatible across platforms, but it stays outside the core attribution algorithm.

11. **External boundaries**
   - The system depends heavily on the local Git executable/repository state and optionally on remote SCM systems like GitHub/GitLab for CI and sync workflows.
   - It is designed to work offline for core attribution, with remote services only enhancing team-wide reporting or integration.

12. **Quality and verification surface**
   - The repo is test-heavy: Rust integration tests, transcript fixtures, Git-compat tests, and editor-extension tests.
   - That test layout reflects the architecture: the interesting risk is not UI rendering, but correctness across Git operations, transcript parsing, and attribution preservation through history rewrites.

Main entry points: [`src/commands`](https://github.com/git-ai-project/git-ai/tree/main/src/commands) (Commands), [`src/mdm`](https://github.com/git-ai-project/git-ai/tree/main/src/mdm) (Installers), [`tests/integration`](https://github.com/git-ai-project/git-ai/tree/main/tests/integration) (Integration tests), [`src/authorship`](https://github.com/git-ai-project/git-ai/tree/main/src/authorship) (Authorship)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Rust core"]
  node_main["CLI entry<br/>Rust bin<br/>[main.rs]"]
  node_commands["Commands<br/>Rust cmd layer"]
  node_daemon["Daemon<br/>Rust service"]
  node_authorship{{"Authorship<br/>Rust engine"}}
  node_git[("Git core<br/>Rust git")]
  node_streams["Streams<br/>Rust parsers"]
  node_notes[("Notes store<br/>Rust persistence")]
  node_metrics[("Metrics<br/>Rust telemetry")]
  node_auth[("Auth<br/>Rust identity")]
  node_api["Remote API<br/>Rust client"]
  node_ci["CI flows<br/>Rust ci"]
  node_mdm["Installers<br/>Rust distribution"]
end

subgraph group_integrations["Adapters"]
  node_vscode["VS Code<br/>TS adapter"]
  node_opencode["OpenCode<br/>TS adapter"]
  node_pi["Pi wrapper<br/>TS adapter"]
  node_intellij["IntelliJ<br/>Kotlin plugin"]
  node_visualstudio["Visual Studio<br/>C# extension"]
  node_amp["Amp wrapper<br/>TS adapter"]
end

subgraph group_tests["Verification"]
  node_tests_integration["Integration tests<br/>Rust tests"]
  node_tests_fixtures["Fixtures<br/>test data"]
  node_tests_gitcompat["Git compat<br/>test harness"]
  node_tests_transcripts["Transcript fixtures<br/>test data"]
end

node_main -->|"dispatches"| node_commands
node_commands -->|"controls"| node_daemon
node_commands -->|"invokes"| node_authorship
node_commands -->|"queries"| node_git
node_commands -->|"reads/writes"| node_notes
node_daemon -->|"ingests"| node_streams
node_daemon -->|"reconstructs"| node_authorship
node_daemon -->|"watches"| node_git
node_authorship -->|"uses"| node_git
node_authorship -->|"persists"| node_notes
node_authorship -->|"reports"| node_metrics
node_streams -->|"validated by"| node_tests_transcripts
node_git -->|"verified by"| node_tests_gitcompat
node_notes -->|"exercised by"| node_tests_integration
node_metrics -->|"exercised by"| node_tests_integration
node_auth -->|"authenticates"| node_api
node_api -->|"syncs"| node_notes
node_ci -->|"integrates with"| node_git
node_ci -->|"preserves"| node_authorship
node_mdm -->|"installs"| node_vscode
node_mdm -->|"installs"| node_intellij
node_mdm -->|"installs"| node_visualstudio
node_mdm -->|"installs"| node_opencode
node_mdm -->|"installs"| node_pi
node_mdm -->|"installs"| node_amp
node_mdm -.->|"detects"| node_vscode
node_vscode -->|"feeds checkpoints"| node_commands
node_intellij -->|"feeds checkpoints"| node_commands
node_visualstudio -->|"feeds checkpoints"| node_commands
node_opencode -->|"emits"| node_streams
node_pi -->|"emits"| node_streams
node_amp -->|"emits"| node_streams
node_tests_integration -->|"covers"| node_commands
node_tests_integration -->|"covers"| node_daemon
node_tests_integration -->|"covers"| node_authorship
node_tests_integration -->|"covers"| node_streams
node_tests_integration -->|"covers"| node_mdm

click node_main "https://github.com/git-ai-project/git-ai/blob/main/src/main.rs"
click node_commands "https://github.com/git-ai-project/git-ai/tree/main/src/commands"
click node_daemon "https://github.com/git-ai-project/git-ai/tree/main/src/daemon"
click node_authorship "https://github.com/git-ai-project/git-ai/tree/main/src/authorship"
click node_git "https://github.com/git-ai-project/git-ai/tree/main/src/git"
click node_streams "https://github.com/git-ai-project/git-ai/tree/main/src/streams"
click node_notes "https://github.com/git-ai-project/git-ai/tree/main/src/notes"
click node_metrics "https://github.com/git-ai-project/git-ai/tree/main/src/metrics"
click node_auth "https://github.com/git-ai-project/git-ai/tree/main/src/auth"
click node_api "https://github.com/git-ai-project/git-ai/tree/main/src/api"
click node_ci "https://github.com/git-ai-project/git-ai/tree/main/src/ci"
click node_mdm "https://github.com/git-ai-project/git-ai/tree/main/src/mdm"
click node_vscode "https://github.com/git-ai-project/git-ai/tree/main/agent-support/vscode"
click node_opencode "https://github.com/git-ai-project/git-ai/tree/main/agent-support/opencode"
click node_pi "https://github.com/git-ai-project/git-ai/tree/main/agent-support/pi"
click node_intellij "https://github.com/git-ai-project/git-ai/tree/main/agent-support/intellij"
click node_visualstudio "https://github.com/git-ai-project/git-ai/tree/main/agent-support/visualstudio"
click node_amp "https://github.com/git-ai-project/git-ai/tree/main/agent-support/amp"
click node_tests_integration "https://github.com/git-ai-project/git-ai/tree/main/tests/integration"
click node_tests_fixtures "https://github.com/git-ai-project/git-ai/tree/main/tests/fixtures"
click node_tests_gitcompat "https://github.com/git-ai-project/git-ai/tree/main/tests/git-compat"
click node_tests_transcripts "https://github.com/git-ai-project/git-ai/tree/main/tests/transcripts/fixtures"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_commands,node_daemon,node_authorship,node_git,node_streams,node_notes,node_metrics,node_auth,node_api,node_ci,node_mdm toneBlue
class node_vscode,node_opencode,node_pi,node_intellij,node_visualstudio,node_amp toneAmber
class node_tests_integration,node_tests_fixtures,node_tests_gitcompat,node_tests_transcripts toneMint
```

## Components

### Rust core

Authoritative CLI, daemon, attribution engine, and persistence layers.

- [CLI entry](https://github.com/git-ai-project/git-ai/blob/main/src/main.rs): Rust bin · Primary executable entry point and command dispatch. · `src/main.rs`
- [Commands](https://github.com/git-ai-project/git-ai/tree/main/src/commands): Rust cmd layer · User-facing commands for blame, stats, checkpointing, hooks, login, daemon control, and Git helpers. · `src/commands`
- [Daemon](https://github.com/git-ai-project/git-ai/tree/main/src/daemon): Rust service · Long-lived orchestration process that ingests events, tracks repo activity, and reacts to Git operations. · `src/daemon`
- [Authorship](https://github.com/git-ai-project/git-ai/tree/main/src/authorship): Rust engine · Core attribution engine that turns change evidence into line-level ownership and survives history rewrites. · `src/authorship`
- [Git core](https://github.com/git-ai-project/git-ai/tree/main/src/git): Rust git · Repository inspection, refs, status, diffs, notes, and rewrite-log handling. · `src/git`
- [Streams](https://github.com/git-ai-project/git-ai/tree/main/src/streams): Rust parsers · Transcript and event parsers for agent and IDE telemetry formats. · `src/streams`
- [Notes store](https://github.com/git-ai-project/git-ai/tree/main/src/notes): Rust persistence · Git Notes storage, migration, and reference-server support for attribution metadata. · `src/notes`
- [Metrics](https://github.com/git-ai-project/git-ai/tree/main/src/metrics): Rust telemetry · Local event tracking and stats aggregation for usage and operational reporting. · `src/metrics`
- [Auth](https://github.com/git-ai-project/git-ai/tree/main/src/auth): Rust identity · Login, credentials, identity, and state management for optional remote workflows. · `src/auth`
- [Remote API](https://github.com/git-ai-project/git-ai/tree/main/src/api): Rust client · Remote notes, metrics, bundle, and CAS client surface. · `src/api`
- [CI flows](https://github.com/git-ai-project/git-ai/tree/main/src/ci): Rust ci · GitHub/GitLab CI context and workflow template generation for attribution-preserving hosted workflows. · `src/ci`
- [Installers](https://github.com/git-ai-project/git-ai/tree/main/src/mdm): Rust distribution · Hook installation, agent detection, editor setup, and managed deployment utilities. · `src/mdm`

### Adapters

Editor and agent integrations that feed checkpoints and session metadata into the Rust core.

- [VS Code](https://github.com/git-ai-project/git-ai/tree/main/agent-support/vscode): TS adapter · TypeScript extension that detects edits, tracks blame, and sends checkpoints to the core. · `agent-support/vscode`
- [OpenCode](https://github.com/git-ai-project/git-ai/tree/main/agent-support/opencode): TS adapter · TypeScript wrapper that bridges OpenCode activity into Git AI checkpoints. · `agent-support/opencode`
- [Pi wrapper](https://github.com/git-ai-project/git-ai/tree/main/agent-support/pi): TS adapter · Lightweight agent wrapper that forwards session activity to the Rust core. · `agent-support/pi`
- [IntelliJ](https://github.com/git-ai-project/git-ai/tree/main/agent-support/intellij): Kotlin plugin · JetBrains plugin that listens to document changes and emits checkpoint input. · `agent-support/intellij`
- [Visual Studio](https://github.com/git-ai-project/git-ai/tree/main/agent-support/visualstudio): C# extension · Visual Studio integration for document save and text-buffer tracking. · `agent-support/visualstudio`
- [Amp wrapper](https://github.com/git-ai-project/git-ai/tree/main/agent-support/amp): TS adapter · Agent wrapper for Amp-generated activity and checkpoint forwarding. · `agent-support/amp`

### Verification

Integration, compatibility, fixture, and workflow coverage for Git and agent scenarios.

- [Integration tests](https://github.com/git-ai-project/git-ai/tree/main/tests/integration): Rust tests · End-to-end Rust scenarios for blame, rebase, notes, daemon, agents, and Git compatibility. · `tests/integration`
- [Fixtures](https://github.com/git-ai-project/git-ai/tree/main/tests/fixtures): test data · Recorded agent transcripts, workspace snapshots, and Git compatibility fixtures. · `tests/fixtures`
- [Git compat](https://github.com/git-ai-project/git-ai/tree/main/tests/git-compat): test harness · Compatibility runner against core Git behavior and porcelain expectations. · `tests/git-compat`
- [Transcript fixtures](https://github.com/git-ai-project/git-ai/tree/main/tests/transcripts/fixtures): test data · Focused transcript samples used to validate parser and checkpoint behavior. · `tests/transcripts/fixtures`

## Connections

- CLI entry → Commands: dispatches · The binary enters through command parsing and subcommand dispatch.
- Commands → Daemon: controls · Commands start, stop, query, and feed the background daemon.
- Commands → Authorship: invokes · Blame, stats, checkpoint, and rewrite commands call the attribution engine.
- Commands → Git core: queries · Commands inspect repository state, diffs, refs, and notes.
- Commands → Notes store: reads/writes · Note migration, fetch, and display paths go through the note store.
- Daemon → Streams: ingests · The daemon consumes parsed agent and transcript event streams.
- Daemon → Authorship: reconstructs · Event normalization and checkpoint resolution feed attribution recomputation.
- Daemon → Git core: watches · Daemon reducers react to Git operations and repository state changes.
- Authorship → Git core: uses · Attribution depends on diffing, history traversal, status, and rewrite context.
- Authorship → Notes store: persists · Line-level provenance is stored durably in Git Notes and related local state.
- Authorship → Metrics: reports · Attribution and stats paths emit usage and operational metrics.
- Streams → Transcript fixtures: validated by · Transcript parsers are exercised by recorded agent fixtures.
- Git core → Git compat: verified by · Git wrapping and behavior are checked against compatibility tests.
- Notes store → Integration tests: exercised by · Note storage, migration, merge, and sync behavior are covered in integration tests.
- Metrics → Integration tests: exercised by · Stats aggregation and telemetry paths are validated in integration scenarios.
- Auth → Remote API: authenticates · Identity and credential state support optional remote operations.
- Remote API → Notes store: syncs · Remote note and bundle flows can exchange provenance data.
- CI flows → Git core: integrates with · CI helpers coordinate with GitHub/GitLab repository state and workflows.
- CI flows → Authorship: preserves · Hosted workflows help keep attribution intact across CI and PR operations.
- Installers → VS Code: installs · Managed deployment provisions editor integrations and hooks.
- Installers → IntelliJ: installs · Managed deployment provisions JetBrains plugin support.
- Installers → Visual Studio: installs · Managed deployment provisions Visual Studio extension support.
- Installers → OpenCode: installs · Managed deployment provisions OpenCode adapter support.
- Installers → Pi wrapper: installs · Managed deployment provisions Pi wrapper support.
- Installers → Amp wrapper: installs · Managed deployment provisions Amp wrapper support.
- Installers → VS Code: detects · Agent and editor detection selects the correct integration path.
- VS Code → Commands: feeds checkpoints · The extension sends change events and checkpoint data into the Rust command surface.
- IntelliJ → Commands: feeds checkpoints · The plugin emits document and save events that become checkpoint input.
- Visual Studio → Commands: feeds checkpoints · The extension converts buffer and save activity into checkpoint input.
- OpenCode → Streams: emits · Wrapper activity is normalized into transcript-like events.
- Pi wrapper → Streams: emits · Wrapper activity is normalized into transcript-like events.
- Amp wrapper → Streams: emits · Wrapper activity is normalized into transcript-like events.
- Integration tests → Commands: covers · End-to-end tests exercise the CLI command boundary.
- Integration tests → Daemon: covers · Daemon behavior is validated through integration scenarios.
- Integration tests → Authorship: covers · Attribution edge cases and rewrite behavior are heavily tested.
- Integration tests → Streams: covers · Agent transcript parsing and session extraction are covered end to end.
- Integration tests → Installers: covers · Installation and hook wiring are validated in platform scenarios.