trace

Universal agent context tracking.

When an AI agent works on code, trace records which project it's in. Any tool — MCP servers, hooks, scripts — can read ~/.trace/active_project to know the current context.

Install

pip install trace

How it works

A Claude Code hook fires on every file operation (Read, Edit, Write). It extracts the git root from the file path and writes it to ~/.trace/active_project. That's it.

Any tool can read this file. No coordination needed.

Python API

from trace_pkg import active_project

project = active_project()  # Path("/Users/you/your-project") or None

CLI

trace          # print active project
trace set .    # manually set active project

Claude Code setup

Add to ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Read|Edit|Write|Glob|Grep",
        "hooks": [
          {
            "type": "command",
            "command": "trace-hook",
            "async": true
          }
        ]
      }
    ]
  }
}

Why

MCP servers need to know what project the agent is working in. Without trace, each server has to guess from cwd, env vars, or explicit configuration. With trace, there's one source of truth that updates automatically.