Git Mode

Git Mode lets you use Intent alongside Git in existing repositories. Instead of Intent managing file content, Git remains the source of truth while Intent tracks provenance—which AI exchanges produced which lines of code.

When to Use Git Mode

Use Git Mode when:

• You have an existing Git repository with established workflows
• Your team uses Git for version control and you want to layer Intent on top
• You want provenance tracking without changing how you manage files

Initializing Git Mode

For an existing Git repository:

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

This creates the .intent/ directory but configures Intent to let Git manage file content. The key difference: Intent's materializer is disabled, so it tracks changes without writing files.

What Changes in Git Mode

Cloning with Intent

To clone a repository that already has Intent provenance:

intent git clone <git-url> <intent-url> [target-dir]

Example:

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

This:

1. Clones the Git repository
2. Fetches Intent provenance notes from the remote
3. Initializes Intent in Git Mode automatically
4. Configures remote sync

The Git Workflow

Committing Changes

After working with AI coding tools, sync your changes to Git:

intent git commit

This:

1. Queries Intent's journal for unsynced file changes
2. Groups changes by AI exchange and manual edits
3. Auto-generates a commit message with rich metadata
4. Attaches provenance data as Git notes

Preview before committing:

intent git commit --dry-run

Override the message:

intent git commit -m "Custom commit message"

Pushing and Pulling

Push code and provenance to your remote:

intent git push [remote] [branch]

This pushes both the branch and Intent's provenance refs (refs/notes/intent/*).

Pull code and provenance from your remote:

intent git pull [remote] [branch]

This fetches both the branch and Intent notes, giving you the full history of who (or what AI) wrote each piece of code.

Provenance Queries

Git Mode enables powerful provenance queries with blame and trace.

Blame: Who Wrote This Line?

intent blame <file> [line]

Shows which AI exchange authored each line of code, combining Git blame with Intent provenance.

Example:

intent blame src/auth/middleware.ts
intent blame src/auth/middleware.ts 42
intent blame src/auth/middleware.ts --json

Output includes:

• Commit SHA and author (from Git)
• Exchange ID and session (from Intent)
• Agent type and model
• User prompt that triggered the change

Trace: What Did This Exchange Write?

intent trace <exchange-id>

The inverse of blame—shows all files and lines produced by a specific exchange.

Example:

intent trace 1ea90095:0
intent trace 1ea90095:0 --json

Output includes:

• All files modified by the exchange
• Line ranges in current positions
• Session context and user prompt

How Provenance Is Stored

Intent stores provenance as Git notes attached to commits:

• refs/notes/intent/exchanges — Exchange metadata (user prompts, agent replies, enrichment)
• refs/notes/intent/metadata — Additional provenance information

These notes travel with push/pull, so your entire team gets full provenance history.

Typical Workflow

# 1. Clone a repo with Intent
intent git clone git@github.com:myorg/project.git intent://sync.intent.build/project

# 2. Work with AI tools (Claude Code, Cursor, etc.)
# Intent automatically captures sessions

# 3. Review what was captured
intent timeline
intent -i  # Launch TUI

# 4. Commit with provenance
intent git commit

# 5. Push to share with team
intent git push

# 6. Query provenance
intent blame src/feature.ts 42  # Who wrote this line?
intent trace abc123:0           # What did this exchange produce?

What's Next