How git-ai-project/git-ai works
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: commands Commands · mdm Installers · integration Integration tests · authorship Authorship
Components 22
Rust core
Authoritative CLI, daemon, attribution engine, and persistence layers.
- CLI entry · Primary executable entry point and command dispatch.
src/main.rs - Commands · User-facing commands for blame, stats, checkpointing, hooks, login, daemon control, and Git helpers.
src/commands - Daemon · Long-lived orchestration process that ingests events, tracks repo activity, and reacts to Git operations.
src/daemon - Authorship · Core attribution engine that turns change evidence into line-level ownership and survives history rewrites.
src/authorship - Git core · Repository inspection, refs, status, diffs, notes, and rewrite-log handling.
src/git - Streams · Transcript and event parsers for agent and IDE telemetry formats.
src/streams - Notes store · Git Notes storage, migration, and reference-server support for attribution metadata.
src/notes - Metrics · Local event tracking and stats aggregation for usage and operational reporting.
src/metrics - Auth · Login, credentials, identity, and state management for optional remote workflows.
src/auth - Remote API · Remote notes, metrics, bundle, and CAS client surface.
src/api - CI flows · GitHub/GitLab CI context and workflow template generation for attribution-preserving hosted workflows.
src/ci - Installers · 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 · TypeScript extension that detects edits, tracks blame, and sends checkpoints to the core.
agent-support/vscode - OpenCode · TypeScript wrapper that bridges OpenCode activity into Git AI checkpoints.
agent-support/opencode - Pi wrapper · Lightweight agent wrapper that forwards session activity to the Rust core.
agent-support/pi - IntelliJ · JetBrains plugin that listens to document changes and emits checkpoint input.
agent-support/intellij - Visual Studio · Visual Studio integration for document save and text-buffer tracking.
agent-support/visualstudio - Amp wrapper · 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 · End-to-end Rust scenarios for blame, rebase, notes, daemon, agents, and Git compatibility.
tests/integration - Fixtures · Recorded agent transcripts, workspace snapshots, and Git compatibility fixtures.
tests/fixtures - Git compat · Compatibility runner against core Git behavior and porcelain expectations.
tests/git-compat - Transcript fixtures · Focused transcript samples used to validate parser and checkpoint behavior.
tests/transcripts/fixtures
Connections 37
- 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.