Metadata-Version: 2.4
Name: afterlight
Version: 0.1.0
Summary: Universal agent context tracking. Know what codebase the agent is working in.
Author: Andrew Park
License-Expression: MIT
Project-URL: Homepage, https://github.com/aardpark/trace
Keywords: ai,agent,context,mcp,claude
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

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