Skip to main content

agit commit

Create a neural commit that links reasoning to your code changes.

Usage​

agit commit -m <message>
agit commit --message <message>

Description​

Creates both a git commit and a neural commit:

  1. Reads all entries from the staging area
  2. Synthesizes a summary from intents and reasoning
  3. Creates a git commit from staged changes (if any)
  4. Creates a content-addressable neural commit object
  5. Links the neural commit to the git commit
  6. Clears the staging area

Options​

OptionRequiredDescription
-m, --messageYesCommit message
--amendNoAmend the previous neural commit
--edit-summaryNoEdit the synthesized summary before committing
--forceNoOverride semantic conflict detection

Examples​

Basic Commit​

agit commit -m "Add user authentication"

Output:

Created git commit:    e8d4f1a
Created neural commit: a3f7b2c

Summary: Intent: Add user authentication. Plan: Implement JWT-based auth with refresh tokens.

View Summary Before Committing​

agit commit -m "Refactor API" --edit-summary

This shows the synthesized summary and lets you modify it.

How Summaries Work​

AGIT synthesizes summaries from your staging area entries:

  1. Finds last user intent: The most recent user/intent entry
  2. Finds last AI reasoning: The most recent ai/reasoning entry
  3. Combines them: "Intent: X. Plan: Y."

Example​

Staging area:

[10:30] user/intent: Fix authentication bug
[10:31] ai/reasoning: Add null check before token validation
[10:35] user/intent: Also add rate limiting
[10:36] ai/reasoning: Use express-rate-limit middleware

Synthesized summary:

Intent: Also add rate limiting. Plan: Use express-rate-limit middleware.

(Uses the last intent and reasoning)

Semantic Conflict Detection​

AGIT protects against "hallucinated" commits by detecting conflicts between your pending thoughts and external changes.

How It Works​

Before committing, AGIT checks:

  1. Ghost commits: Git commits made outside AGIT since your last neural commit
  2. File references: Files mentioned in your pending thoughts
  3. Overlap: Whether ghost commits touched files in your thoughts

Safe vs Unsafe Scenarios​

Safe (proceeds automatically):

Ghost commit modified: README.md
Your thought mentions: src/auth.rs
→ No overlap, commit proceeds

Unsafe (blocks with warning):

Ghost commit modified: src/auth.rs
Your thought mentions: "fixing auth.rs"
→ File overlap detected

Override with --force​

If you're confident the conflict is fine:

agit commit -m "My changes" --force

Conflict Error​

Context conflict: external changes touched files in your pending thoughts.
Conflicting files: src/auth.rs
Use --force to commit anyway, or clear pending thoughts with 'agit reset'.

Solution: Review the conflict, then either use --force or clear your thoughts.

Commit Object Structure​

Neural commits are stored as JSON:

{
  "hash": "a3f7b2c...",
  "message": "Add user authentication",
  "summary": "Intent: Add auth. Plan: JWT with refresh tokens.",
  "git_commit": "e8d4f1a...",
  "parent": "previous-neural-hash",
  "trace_hash": "hash-of-full-trace",
  "timestamp": "2024-01-15T10:45:00Z"
}

Requirements​

  • AGIT must be initialized
  • Git repository must have at least one commit
  • Staging area should have entries (or use --amend)

Errors​

No Entries in Staging​

No thoughts recorded in staging area.
Use 'agit record' to add thoughts, or the MCP server will log them automatically.

Solution: Record some thoughts first with agit record or use an MCP-enabled editor.

Message Required​

Commit message required. Use -m or --message

Solution: Provide a message with -m "Your message".

Merge/Rebase in Progress​

⚠️  Merge in progress. Please resolve conflicts and finish the Merge before adding neural memories.

Solution: Complete the merge/rebase before committing to AGIT. See Git Resilience.

Best Practices​

  1. Commit after logical units: Use agit commit to create both git and neural commits in one step
  2. Use clear messages: The message helps find commits later
  3. Review before committing: Run agit status first to check entries
  4. Stage first: Run git add . before agit commit to include your changes

See Also​