Two small, unrelated CLI utilities in one repo: a code-change reasoning log, and a fixed-interval reminder scheduler for podcast notes.

Quick Start • Features • Examples • Contributing

What is this?

AgentTrace bundles two independent CLI utilities that share a click group and a JSON-file storage pattern, but no data model or workflow:

1. Change log — log-change / view-logs records a file, line number, and description for a code change to a JSON file, and lets you list them back.
2. Podcast note reminders — add-note / review-notes records a note with a timestamp and schedules a reminder on a fixed 1-day / 3-day / 1-week ladder (spaced_repetition.py), then lists notes that are due. This is a reminder scheduler, not adaptive spaced repetition (no SM-2 or difficulty-based interval adjustment) — every note gets the same fixed schedule regardless of how well you "know" it.

If you only need one of these, you can ignore the other command pair entirely; they don't interact.

Example Usage

$ python cli.py log-change --file main.py --line 10 --description "Fixed typo"
{"file": "main.py", "line": 10, "description": "Fixed typo"}

Problem

Developers struggle to understand why colleagues made certain code changes and often have nowhere lightweight to jot the "why." Separately, podcast/reading notes get made once and never revisited. These are two small, unrelated itches this repo scratches with two small tools.

Features

Feature	Description
Log Code Changes	Log the reasoning behind each code change with file name, line number, and a brief description.
View Logs	Print every logged code change back out, one JSON object per line.
Fixed-Ladder Podcast Note Reminders	Add a note with a timestamp and description; it's scheduled for review on a fixed 1 day / 3 day / 1 week ladder (not adaptive).
Review Due Notes	List notes whose next scheduled review has arrived.
Command Line Interface	Four click subcommands: log-change, view-logs, add-note, review-notes.
JSON Storage	Logs and notes are stored in separate flat JSON files (logs.json, notes.json by default).

There is no "view all active notes" command distinct from review-notes (which only shows notes that are currently due) and no date-range filtering — both were part of the original spec but were never implemented.

Quick Start

1. Clone the repository:

   git clone https://github.com/m2ai-portfolio/AgentTrace.git
   cd AgentTrace

2. Install dependencies:

   pip install -r requirements.txt

3. Run your first command:

   python cli.py log-change --file main.py --line 10 --description "Fixed typo"

Examples

Log a Code Change

Command:

python cli.py log-change --file main.py --line 10 --description "Fixed typo"

Output:

{"file": "main.py", "line": 10, "description": "Fixed typo"}

Add a Podcast Note

Command:

python cli.py add-note --timestamp "2023-10-01 12:00:00" --description "Key concept: Dijkstra's Algorithm"

Output:

{"timestamp": "2023-10-01 12:00:00", "description": "Key concept: Dijkstra's Algorithm", "next_review": "2023-10-02 12:00:00"}

Review Podcast Notes

Command:

python cli.py review-notes

Output:

{"timestamp": "2023-10-01 12:00:00", "description": "Key concept: Dijkstra's Algorithm"}

File Structure

AgentTrace/
├── agenttrace.py       # Facade used by the CLI (log_code_change, view_logs, add_note, review_notes)
├── cli.py              # click CLI entry point (log-change, view-logs, add-note, review-notes)
├── data.py             # CodeChange / PodcastNote dataclasses + JSON persistence
├── spaced_repetition.py  # Fixed 1/3/7-day review-interval scheduler
├── utils.py             # Timestamp parsing/formatting helpers
├── tests/               # Test suite
│   ├── __init__.py
│   ├── test_agenttrace.py
│   ├── test_cli.py
│   └── test_spaced_repetition.py
├── conftest.py
├── pytest.ini
├── requirements.txt
├── README.md
└── LICENSE

Tech Stack

Technology	Purpose
Python 3.11+	Core programming language
click	Command line interface library
pytest	Testing framework

Contributing

1. Fork the repository.
2. Create a new branch: git checkout -b feature/new-feature.
3. Make your changes and run tests.
4. Submit a pull request.

License

MIT

Author

Matthew Snow -- M2AI | @m2ai-portfolio