# 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

```bash
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

```python
from trace_pkg import active_project

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

## CLI

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

## Claude Code setup

Add to `~/.claude/settings.json`:

```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.
