AIGit

Git for files. AIGit for intent.

AI-native semantic version control that gives people, agents, and CI a shared, deterministic view of what a change means.

Alpha software. The semantic core is usable today; parser coverage and workflow ergonomics are actively evolving. Bring it to a real repository, inspect the output, and help shape the contract.

静けさ — clarity before automation

Why this exists

Code is no longer changed only by people. Agents can move quickly, but a line diff alone cannot answer the questions a team actually has:

• What capability changed?
• Did this refactor preserve its identity?
• Which agent produced this change, from which prompt and model?
• Where is the real merge risk?

AIGit keeps Git exactly as it is and adds a committed semantic layer beside it. No custom object store. No platform lock-in. No magic state that only one tool can read.

You need	AIGit gives you	So you can
review beyond line movement	deterministic semantic chunks and diffs	see intent-level change in pull requests
maintain context through refactors	stable IDs and lineage edges	trace a concept as it moves or changes shape
use agents responsibly	append-only provenance and commit trailers	audit generated work without guessing
merge agent work with confidence	semantic merge reports	surface conflict risk before the merge button
automate without surrendering control	a local API, CI checks, and an optional operator UI	keep humans in the loop

The quiet architecture

flowchart LR
    G["Git repository<br/>source of truth"] --> C["aigit chunk<br/>deterministic parsing"]
    C --> S[".semantic/<br/>committed semantic layer"]
    S --> R["semantic diff & merge<br/>reviewable intent"]
    S --> P["provenance<br/>who / model / prompt"]
    S --> A["local API & CI<br/>people, agents, automation"]

Loading

The contract is intentionally small:

• Git remains the source of truth.
• Semantic outputs live in .semantic/ and can be committed, reviewed, and regenerated.
• Normal GitHub and GitLab workflows continue to work.
• If AIGit is removed, the repository remains a normal Git repository.

Start in three breaths

Prerequisite: Python 3.10+ and Git. uv is the preferred environment manager; pip works too.

git clone https://github.com/jesusvilela/aigit.git
cd aigit
./scripts/bootstrap_uv.sh
uv run aigit chunk

Then ask a useful question of your repository:

# What changed in meaning between two refs?
uv run aigit semantic-diff --base main --head HEAD --output semantic_diff.md

# Where might two concurrent changes collide?
uv run aigit semantic-merge --base main --ours HEAD --theirs feature --output semantic_merge.json

Prefer pip?

python -m pip install -e ".[dev]"
aigit chunk

A practical loop

sequenceDiagram
    participant D as Developer or agent
    participant G as Git
    participant S as AIGit semantic layer
    participant CI as CI / reviewer

    D->>G: edit and commit
    D->>S: aigit chunk
    S-->>G: commit .semantic artifacts
    D->>S: semantic-diff / semantic-merge
    S-->>CI: intent, lineage, and provenance
    CI-->>D: review with evidence

Loading

For AI-assisted commits, attach the work context as you create the commit:

aigit commit -m "refactor parser" \
  --agent codex \
  --model gpt-5.2-codex \
  --prompt "extract parser helpers while preserving behavior"

What is ready now

Surface	Available today
Semantic core	deterministic chunking for Python, Markdown, JSON, YAML, TypeScript, and a safe file fallback
Identity and lineage	stable semantic IDs, conservative lineage edges, chunk_index.json
Review tooling	semantic diff and semantic merge reports
Provenance	append-only provenance log, signed records, commit trailers
Agent access	local HTTP API through aigit serve-api
Team automation	semantic freshness checks and PR-based maintenance workflow
Operator mode	optional DeerFlow harness and Gradio admin UI

Command map

Command	Use it when
aigit chunk	you need to rebuild semantic state
aigit validate-ruleset	you need to confirm the committed parser contract is valid
aigit eval-lineage --fixtures <file>	you need reproducible lineage precision and recall evidence
aigit semantic-diff --base <ref> --head <ref>	you want an intent-focused comparison
aigit semantic-merge --base <ref> --ours <ref> --theirs <ref>	you need early merge-risk signals
aigit record-provenance --agent … --model … --prompt …	you need an auditable record of AI context
aigit commit -m <message> --agent … --model … --prompt …	you want provenance attached to a commit
aigit install-merge-driver	concurrent branches keep colliding on .semantic/ files
aigit serve-api	an agent or tool needs semantic context locally
aigit improve	you want a concise local chunk-and-test cycle
aigit subagent-scout	you need a quick repository diagnosis
aigit up	you are running the optional DeerFlow operator stack

Run aigit --help for the full command reference.

Install profiles

Install	Includes
pip install aigit	pure-stdlib semantic core, diff/merge, provenance, and local API
pip install "aigit[ui]"	the Gradio observability UI (aigit admin-ui)
pip install "aigit[dev]"	test dependencies
aigit[deerflow] + Docker	optional DeerFlow harness; requires a DeerFlow checkout at runtime

The committed layer

.semantic/
  schema_version       # reproducibility contract
  ruleset.yaml         # parser and ruleset settings
  manifest.jsonl       # semantic chunks
  edges.jsonl          # identity and lineage links
  chunk_index.json     # fast lookup
  provenance.jsonl     # append-only AI work record
  cache/                # local-only, ignored by Git

Chunk artifacts are a function of the source, file by file, so they should not be merged line by line. aigit install-merge-driver registers a Git merge driver for this clone (the repository's .gitattributes already routes the artifacts to it; without the driver Git falls back to its text merge):

• manifest.jsonl and chunk_index.json merge per source file. A file changed on one side keeps that side's chunks. A file changed on both sides is re-chunked from the merged source, following a rename on either side as Git does, in a merge, rebase, cherry-pick, revert, stash or the git merge-tree --write-tree that merge queues run. Only a conflict in the source itself stops it -- or merge options that change how Git merges file content (-X, another strategy, merge.renormalize), which ask for aigit chunk rather than predict Git's result.
• edges.jsonl and provenance.jsonl hold immutable records and merge as sets, so two branches appending provenance no longer collide at end of file.

Every chunk carries its file's hash, so two versions of a file never share records. Given artifacts that are fresh on both sides, even a plain text merge -- a hosted merge button, a clone without the driver -- therefore either conflicts or produces exactly what aigit chunk would. No merge can repair artifacts that were already stale, or notice a merge with a branch that predates AIGit; aigit chunk --check in CI catches both. Octopus merges, artifacts that were already stale on either side, and .semantic/ deleted on one side stop for aigit chunk rather than guess. When a pull request conflicts with its base only in .semantic/, the Semantic Merge workflow merges the base in with the driver and pushes, so the hosted merge button works again.

Community: build the contract with us

This project needs skeptical builders: people who review AI-generated changes, maintain developer tools, build coding agents, or care about durable software history.

Good first contributions are deliberately small:

1. Try aigit chunk on a repository you know well.
2. Open an issue with a confusing chunk, missed lineage link, or workflow friction.
3. Pick a documented roadmap item, parser improvement, test, or documentation fix.
4. Send a focused pull request.

Please read Contributing, our Code of Conduct, and Security policy before participating. We are especially interested in real-world examples where semantic context would make review safer or faster.

For maintainers and operators

The optional DeerFlow stack is for long-running autonomous delivery with visibility and recovery controls. It is not required for the semantic core.

cp .deerflow/.env.example .deerflow/.env
aigit up
aigit admin-ui --host 127.0.0.1 --port 7860

Useful references:

• Beta readiness and release artifacts
• Development journal
• Evaluation program
• Changelog
• Release governance
• Roadmap
• DeerFlow recovery playbook
• Cycle 2 release charter
• Custom DeerFlow autopilot skill

Verify a checkout

uv sync --extra dev
pytest -q
./scripts/ci_refresh_semantics.sh
git diff --exit-code -- .semantic

The CI matrix tests Python 3.10–3.12, validates the lockfile, and rejects stale committed semantic artifacts.

License

Apache-2.0. See LICENSE.

Brand

The AIGit mark and its usage guidance live in Brand guidelines. The transparent PNG is ready for social posts, presentations, and repository use.