DevSpecDevSpec
Sign In
All Docs/Commit tracking

Commit tracking

Commit tracking keeps your project's record complete when work lands without a task, such as a quick fix someone pushed without planning it first. Commits link to the work they belong to. If a commit lands on a tracked branch without an item, DevSpec writes up the change so it can be reviewed. There's nothing to set up: it works for every GitHub repository connected to a project.

Tagged and untagged commits

A commit is tagged when its message names a task, like this:

Fix the retry banner on slow connections [devspec:<id>]

<id> is the item's ID, in full or its first eight characters, and one commit can name several items. A tagged commit links to its item on any branch and shows up in the item's Linked activity without needing an AI write-up. Linking it costs nothing. The tag stays with the commit's message, so the link survives a rebase or squash that gives the commit a new ID.

A commit is untagged when its message names no item. What happens depends on where it lands:

  • On a tracked branch, if the commit isn't linked to a task shortly after being pushed, DevSpec writes up an Auto-tracked task for the change.
  • On an experiment's branch, the work remains accountable to the experiment and its decisions.
  • On other untracked branches, no item is created.

A repository's tracked branches are its Tracking branch plus any other branches you choose to Track, both on the repository's card in Project settings → Repositories. Merge commits are skipped: their work is already covered by the commits they bring in.

Commits your coding agent makes

When a coding agent works through the DevSpec plugin for Claude Code, Antigravity or Pi, DevSpec sees each commit the agent makes. It records that agent as the commit's author, and when the agent records its work, DevSpec links the agent's commits to the task. Nobody needs to copy commit IDs.

Full commit tracking — every commit reported to DevSpec and tagged with its task automatically — works on macOS, Linux, and Windows through WSL. On native Windows, without WSL, it depends on the agent:

  • Pi: full tracking on native Windows too, through Git Bash.
  • Claude Code: full tracking on native Windows once Claude Code's PowerShell tool is turned off, with this entry in its settings.json: "env": { "CLAUDE_CODE_USE_POWERSHELL_TOOL": "0" }. With the PowerShell tool on, only plain single-line commits made through the Bash tool are caught.
  • Antigravity: use WSL. On native Windows, only plain single-line commits are caught, in a folder linked to a DevSpec project.

Most DevSpec plugins also add the tag to the agent's commit message, when the plugin recognizes the repository as part of your project and the agent is working on exactly one task. The tag still has to be written into the message, by the agent or by you, when:

  • the agent is working on more than one task at once, so the plugin can't tell which one a commit belongs to
  • the plugin doesn't recognize the repository as part of your project, or doesn't add tags
  • you commit yourself, from your own terminal or editor

Your agent knows this: when its plugin adds the tag, the plugin says so, and otherwise the agent writes the tag itself.

What an auto-tracked item looks like

An item DevSpec creates from a commit:

  • starts at Implemented, because the work has already landed;
  • carries the Auto-tracked chip, which says which commit it came from;
  • has a title, type, description, intent, testing notes and acceptance criteria written from the commit's changes and message;
  • lists the files the commit changed, and shows the commit under Commits in the item's Linked activity;
  • carries relevant topic tags from your project's vocabulary.

DevSpec asks the recognized author to confirm the intent of work that landed without an item (or asks the project's Maintainers if the author isn't matched to a project member).

Work recorded after it lands is checked for conflicts and duplicates too. Recording a commit does not approve a change to someone else's decision. See Review.

Because it's Implemented, an auto-tracked item waits under Implemented on the Tasks page for someone to check. It reaches Done the same way as any other item: when someone verifies it, or once every acceptance criterion is settled with evidence. See Tasks.

When an auto-tracked item duplicates existing work

Open the auto-tracked item. If DevSpec has found matching work, choose Move commit here beside the item it belongs to. You can also use Move commit to item and enter the existing item's ID.

DevSpec links the commit to that item and closes the auto-tracked item as a duplicate. This preserves the work's history instead of treating it as work that was never done. Keep both items when they describe separate outcomes.

The simplest way to avoid duplicates is to tag commits with the item they belong to.

Take ownership of work recorded from a commit

Choose Take ownership of this on the auto-tracked item. Confirm or correct why the change was made, then choose Confirm ownership. That intent becomes your decision, so future work can be checked against it.

If the commit belongs to an existing item, move it there instead of adopting a second description of the same work.

Set up commit tracking

There's nothing to switch on. Commit tracking works for every GitHub repository connected to a project, on the branches it tracks, from the moment the repository is connected. You don't need a deployment target.

What you can control is which branches count, on the repository's card in Project settings → Repositories: change the Tracking branch, or Track another branch under the repository's branches list. Ordinary untracked branches are left out; experiment branches remain linked to the work they are testing.

DevSpec learns about commits when you push them to GitHub. If the repository card says Pushes aren't arriving, updates may appear late. Use Fix on the repository card to restore normal delivery; see Repositories and GitHub.

If commit tracking can't write up a commit

If a commit can't be analyzed automatically after retrying, DevSpec creates a placeholder item from the commit message so the change still appears in the project's record, where you can edit or dismiss it.

The project's Maintainers get a Commit tracking needs attention alert when a noticeable share of recent commits needed to be written up after the fact instead of arriving tagged. Have your agent work from the matching task, so its commits are tagged and linked for it, and add [devspec:<id>] to commits you make yourself, so commits link cleanly without extra background write-ups.

What commit tracking costs

Linking tagged commits is free.

Writing up an untagged commit is AI work, charged to your organization's balance as background work. It appears on Settings → Billing → Transactions as Running your project. A busy repository where most commits are untagged is charged for each of them, continuously.

There's no per-project switch to turn this off. To keep the cost down, tag your commits: a tagged commit does not need a separate AI write-up. While the project is paused, for example because your organization's balance reached $0, this work waits, and catches up once the project starts again. See Billing, usage and limits.