Tracking modes

tl;dr

Crosslink enforces issue tracking at three levels. You set the mode once; agents are automatically held to it on every action.

 

How it works

You configure:

Set tracking_mode in .crosslink/hook-config.json to control how strictly agents must track their work.

→

Agents experience:

  • strict — blocked from editing without an active issue
  • normal — reminded but allowed to proceed
  • relaxed — no enforcement, only git mutation blocks

 

Mode comparison

Mode Hook Behavior Best For
strict Blocks Write/Edit/Bash without an active issue Teams that want every change tracked
normal Reminds but allows proceeding without an issue Balanced tracking without blocking quick fixes
relaxed No enforcement — only git mutation blocks Users who want tracking opt-in only

 

Setting the mode

Edit .crosslink/hook-config.json:

{
  "tracking_mode": "strict"
}

Changes take effect on the next prompt.

What’s always enforced

Regardless of tracking mode, these are always blocked:

  • Git mutations: git push, git merge, git rebase, git reset, git stash, git tag, etc.
  • These are human-only operations. Agents should never push code without explicit instruction.

Gated (require an active crosslink issue):

  • git commit — allowed only when the agent has an active work item via crosslink session work <id> or the /commit skill.

Read-only git commands (git status, git diff, git log, git show, git branch) are always allowed.

Strict mode

File: .crosslink/rules/tracking-strict.md

The hook checks if the agent has an active work item (crosslink session work <id>). If not, all Write, Edit, and Bash operations are blocked. The agent must create an issue first:

crosslink quick "describe the work" -p medium -l feature

This is the recommended mode for teams and production codebases.

Normal mode

File: .crosslink/rules/tracking-normal.md

Same check, but the hook reminds the agent instead of blocking. Operations proceed with a gentle nudge to create an issue. Good for solo developers who want tracking most of the time.

Relaxed mode

File: .crosslink/rules/tracking-relaxed.md

No issue-tracking enforcement. Only git mutations are blocked (same as all modes). Best for projects where crosslink is used occasionally.

 

Customizing mode rules

Each mode loads its instructions from .crosslink/rules/tracking-{mode}.md. Edit these files to customize wording or add project-specific rules.

To reset to defaults:

crosslink init --force