agent-trace: Instructions file for Codex

AGENTS.md — agent-strace development guide

This file tells AI coding agents how to work with the agent-strace repository.

Project layout

src/agent_trace/    Core library — one module per feature
tests/              One test file per module (test_<module>.py)
ADRs/               Architecture Decision Records — read before adding dependencies
docs/               User-facing documentation (setup, commands, production, integrations, security)
examples/           Usage examples for each integration
pyproject.toml      Package config and optional extras

Constraints

• Zero runtime dependencies in src/agent_trace/. Use Python stdlib only. If a feature requires a third-party package, it must be an optional extra in pyproject.toml under [project.optional-dependencies], imported lazily inside the function with a clear ImportError message. See ADR-0003.
• Never change the .agent-traces/ storage format in a way that breaks existing sessions. Adding new fields is fine. Removing or renaming existing fields requires a major version bump and human approval.
• Every new CLI command must be registered in cli.py following the existing subparser pattern.
• Every new feature must have tests in tests/test_<module>.py. Run python -m unittest discover -s tests -v to verify.
• OTLP export uses HTTP/JSON only — no gRPC. See ADR-0006.

Development workflow

# Install in editable mode
pip install -e .

# Run tests
python -m unittest discover -s tests -v

# Run a single test file
python -m unittest discover -s tests -p 'test_watch.py' -v

Adding a new feature

1. Create src/agent_trace/<feature>.py
2. Add a cmd_<feature> function following the pattern in existing modules
3. Import and register it in cli.py
4. Add new EventType values to models.py if needed
5. Write tests in tests/test_<feature>.py
6. Add the command to the appropriate table in README.md (one line, linked to docs/)
7. Add full flag reference to docs/commands.md
8. If the feature involves production export, update docs/production.md
9. If the feature involves a new integration, update docs/integrations.md