turnlog 0.1.0

Lightweight local provenance recorder for agent sessions and turns
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

# turnlog

A lightweight, Git-compatible agent trace recorder.

`turnlog` records agent sessions and turns, then links them to tickets and the current VCS state. If `jj` is available in a colocated repo, it records `jj` change/operation metadata; otherwise it falls back to Git metadata.

## Goal

Connect:

```text
ticket → agent session → agent turn → jj change or git commit
```

without becoming a VCS.

## Install

From crates.io, after publication:

```bash
cargo install turnlog
```

From source:

```bash
cargo build --release
```

## Use

```bash
turnlog init
turnlog start --ticket AUTH-123 --goal "Fix auth token validation"
turnlog current
turnlog use <session-id>
turnlog record --model claude-sonnet-4-5 --summary "Updated token validation" --verification "cargo test auth"
turnlog record --attach-diff --summary "Record with patch snapshot"
turnlog record --session <session-id> --summary "Explicit session record"
turnlog status
turnlog --cwd /path/to/repo status
turnlog -C /path/to/repo record --summary "Record a different repo"
turnlog log
turnlog log --ticket AUTH-123
turnlog log --session <session-id>
turnlog log --changed src/auth.rs
turnlog log --grep validation
turnlog show <session-or-turn-id>
turnlog show <session-or-turn-id> --json
turnlog report <session-id>
turnlog report <session-id> --stdout
turnlog grep "cargo test"
```

## Storage

`turnlog --cwd DIR` (or `-C DIR`) runs against `DIR` instead of the process current directory, which is useful when an agent process is launched from one directory while editing another repository.

`turnlog init` adds `.turnlog/` to `.gitignore` when missing, keeping local provenance out of GitHub by default. Treat turnlog as local-only provenance unless a repo explicitly opts into sharing it. If shared provenance is needed, commit a curated report or summary intentionally.

`turnlog` writes human-reviewable files under `.turnlog/`:

```text
.turnlog/
  index.jsonl
  sessions/
  turns/
  attachments/
```

`index.jsonl` is the append-only canonical event log. JSON snapshots and Markdown reports are written for sessions and turns.