Auto-tracking

Link a repo to a project with .frostbyte.json so your agent starts each session with the right task context.

Auto-tracking gives the plugin a project memory. Link a repo once, and each new Claude Code or Codex session starts with the Frostbyte project ID it should use before you paste task context or say "check Frostbyte".

From there, the agent uses the normal MCP tools to read the task list and keep it honest while it works. It can start the obvious task, suggest a new one when the work is large enough, add subtasks to work already in progress, and complete finished tasks with a short summary.

It requires the Agent Plugin v0.4.0 or newer.

One small file at your repo root connects the folder on disk to a Frostbyte project:

{ "projectId": "abc123XYZ" }

Commit it. The file contains no secrets, just the project ID, so the whole team can share the same link. There are three ways it gets created:

Your situation How the link gets made
Brand-new project The agent offers to create a Frostbyte project and writes the file
Existing project, already on Frostbyte The agent offers to match it to one of your projects and writes the file
You'd rather do it yourself Paste the project ID by hand (it's in the project's URL)

The first two paths use the plugin's onboarding flow. When the agent notices a repo with no link, it offers to set one up. It never creates a project or writes the file without your explicit yes.

How grounding works

On session start, a small hook checks for .frostbyte.json, walking up from the current directory like git does. If the repo is linked, it tells the agent which Frostbyte project it is in and to read that project's task context before starting work.

The hook only injects that instruction. It does not call Frostbyte, read your code, or see your token. The actual fetch goes through the MCP server with your existing API token. If the file is missing, malformed, disabled, or points to a project your token cannot access, the session is not blocked; the agent either starts normally or tells you the repo needs to be relinked.

What the agent does with it

Once grounded, the agent maintains the task list as it works:

  • Starts the matching task when you ask for work that's already tracked.
  • Proposes a new task when work is big enough: multi-step, multi-file, or framed as a deliverable. One-line fixes and chores do not get tasks.
  • Adds subtasks when work fits a task that's already in progress.
  • Completes tasks when the work is done, with a summary and the files touched.
  • Areas: new tasks go to the best-fitting existing area; a new area is created only when nothing fits.
  • Releases: never touched automatically — release moves happen only when you ask.

Creating anything, including a project, task, or area, is always an offer first. Your dashboard stays a record of work you approved, not a list of guesses.

Turning it off

  • Per repo: delete .frostbyte.json, or set { "projectId": "...", "grounding": false } to pause grounding while keeping the link.
  • Everywhere: disable the plugin in your agent client. For Codex, you can also remove the SessionStart hook from ~/.codex/hooks.json.

Setup

  • Claude Code: nothing to do — the hook ships with the plugin.
  • Codex: one config snippet — see the plugin README.
Last updated