Git Mode

Add decision tracking to an existing Git repo without changing your workflow. If you already have a Git repository with established workflows, you probably don't want another tool trying to manage your files. Git Mode is designed for exactly this situation.

With Git Mode, Git stays in charge of your files. Stoa sits alongside it and passively tracks which AI sessions produced which lines of code. You keep using git add, git commit, and git push exactly as before. It just adds a layer of provenance on top.

When you'd use this

Git Mode makes sense when:

• You have a repo that your team already works in
• You want to know which AI exchange wrote a specific line, without changing anything about how you manage files
• You want decision context to travel with your commits so teammates can see it too

If you're starting a brand new project and don't have existing Git workflows, you might prefer the default mode instead (just run intent init without the flag).

Getting started

Navigate to your Git repo and initialize with the --git-mode flag:

cd your-git-repo
intent init --git-mode

This creates the .intent/ directory, but with the materializer disabled. That means the system will never write to your working tree. It only watches and records.

How it compares to default mode

Cloning a repo with provenance

If a teammate already set up Stoa on a repo, you can clone it and get the full provenance history in one step:

intent git clone git@github.com:myorg/myrepo.git intent://sync.intent.build/myrepo ./myrepo

This does four things: clones the Git repo, pulls down provenance notes, sets up Git Mode, and configures remote sync. You're ready to go.

The Git workflow

Once Git Mode is set up, you work normally with your AI coding tools. The CLI captures everything in the background. When you're ready to commit, you have two options.

Committing with provenance

Instead of git commit, use intent git commit. This does everything a normal commit does, but also attaches provenance data as Git notes: which exchanges produced which changes, what you asked the AI, and the AI-generated decision summaries.

# See what would be committed before doing it
intent git commit --dry-run

# Commit with an auto-generated message based on the exchanges
intent git commit

# Or write your own message
intent git commit -m "Add auth middleware"

You can also keep using regular git commit if you prefer. The provenance data will still be in your .intent/ directory, it just won't be attached to the Git commit as notes.

Pushing and pulling

When you push, provenance travels with the code:

intent git push origin main

When a teammate pulls, they get the provenance too:

intent git pull origin main

The provenance is stored as Git notes, so it moves with standard push/pull operations. No extra setup needed on the receiving end.

Querying provenance

This is where Git Mode really pays off. Once you have provenance data, you can ask questions about your code.

Who wrote this line?

intent blame works like git blame, but instead of showing you which commit changed a line, it shows you which AI exchange wrote it and what the user asked.

# See provenance for every line in a file
intent blame src/auth/middleware.ts

# Focus on a specific line
intent blame src/auth/middleware.ts 42

# Get machine-readable output
intent blame src/auth/middleware.ts --json

The output shows the commit SHA, the exchange ID, the agent that wrote it, and the prompt that triggered the change.

What did this exchange change?

intent trace goes the other direction. Given an exchange ID, it shows you every file that exchange touched.

intent trace 1ea90095:0

You'll see the files modified, the line ranges, and the full session context.

Where provenance lives

Provenance is stored as Git notes under two refs:

• refs/notes/intent/exchanges for exchange metadata and decision enrichments
• refs/notes/intent/metadata for additional context

These are standard Git notes. They travel with push and pull, they're stored in the Git object database, and they don't affect your working tree or your regular commit history.

Day-to-day workflow

Here's what using Git Mode looks like in practice:

1. Clone the repo with intent git clone (or run intent init --git-mode on an existing checkout)
2. Code with your AI tools as you normally would (Claude Code, Cursor, etc.)
3. Review what was captured with intent timeline or intent -i
4. Commit with intent git commit to attach provenance to the commit
5. Push with intent git push so your team gets the context
6. Query later with intent blame or intent trace when you need to understand why code looks the way it does

What to read next