agent-usage-tracker 0.1.1__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (346) hide show
  1. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/CONTRACT.md +19 -0
  2. agent_usage_tracker-0.3.0/PKG-INFO +119 -0
  3. agent_usage_tracker-0.3.0/README.md +84 -0
  4. agent_usage_tracker-0.3.0/docs/assets/aut-local-setup.png +0 -0
  5. agent_usage_tracker-0.3.0/docs/assets/aut-workflow.png +0 -0
  6. agent_usage_tracker-0.3.0/docs/development.md +41 -0
  7. agent_usage_tracker-0.3.0/docs/evidence.md +181 -0
  8. agent_usage_tracker-0.3.0/docs/first-run.md +145 -0
  9. agent_usage_tracker-0.3.0/docs/improvement-studies.md +359 -0
  10. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/improvement.md +400 -14
  11. agent_usage_tracker-0.3.0/docs/quota.md +44 -0
  12. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/reference.md +35 -2
  13. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/packaging/launchd/aut-scan.sh +2 -0
  14. agent_usage_tracker-0.3.0/packaging/launchd/dev.aut.improve-draft.plist +31 -0
  15. agent_usage_tracker-0.3.0/packaging/windows/register-task.ps1 +50 -0
  16. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/pyproject.toml +13 -3
  17. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/__init__.py +1 -1
  18. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/backup.py +6 -1
  19. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/cli.py +44 -20
  20. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/_util.py +5 -1
  21. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/codex.py +3 -1
  22. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/cursor_cli.py +7 -5
  23. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/cursor_sdk.py +20 -1
  24. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/generic_sdk.py +3 -0
  25. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/coverage.py +6 -3
  26. agent_usage_tracker-0.3.0/src/agent_usage_tracker/demo.py +62 -0
  27. agent_usage_tracker-0.3.0/src/agent_usage_tracker/demo_cli.py +28 -0
  28. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/diagnostics.py +1 -1
  29. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/event.py +5 -1
  30. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/access.py +564 -0
  31. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/access_cli.py +180 -0
  32. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/access_mcp.py +75 -0
  33. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/case_view.py +76 -1
  34. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/cli.py +87 -1
  35. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/cursor_evidence.py +164 -0
  36. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/decide.py +423 -0
  37. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/draft.py +412 -0
  38. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/draft_adapters.py +258 -0
  39. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/draft_gguf.py +80 -0
  40. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/evidence.py +616 -0
  41. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/file_reads.py +93 -0
  42. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/inbox.py +199 -0
  43. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/judge.py +257 -56
  44. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/outputs.py +234 -0
  45. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/proposals.py +114 -0
  46. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/qualify.py +288 -0
  47. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/ranked_search.py +113 -0
  48. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/report_card.py +386 -0
  49. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/schedule.py +5 -1
  50. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/scores.py +75 -0
  51. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/setup_git.py +79 -0
  52. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/skill_proposals.py +83 -0
  53. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/store.py +99 -24
  54. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/studies.py +89 -7
  55. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/study_candidates.py +125 -0
  56. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/study_cli.py +135 -0
  57. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/study_decision.py +8 -3
  58. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/study_followup.py +6 -3
  59. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/study_independence.py +58 -0
  60. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/study_model_calls.py +97 -0
  61. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/study_observe.py +450 -0
  62. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/study_reviews.py +74 -0
  63. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/t3.py +176 -10
  64. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/trial.py +55 -18
  65. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve/turn_revisions.py +214 -0
  66. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/validation.py +78 -25
  67. agent_usage_tracker-0.3.0/src/agent_usage_tracker/improve_publish.py +110 -0
  68. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/gold.py +51 -17
  69. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/teach.py +9 -2
  70. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/local_page.py +2 -1
  71. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/net.py +11 -0
  72. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/observation_cli.py +2 -2
  73. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/observations.py +7 -2
  74. agent_usage_tracker-0.3.0/src/agent_usage_tracker/operational_status.py +270 -0
  75. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/outcome_git.py +6 -2
  76. agent_usage_tracker-0.3.0/src/agent_usage_tracker/overview.py +178 -0
  77. agent_usage_tracker-0.3.0/src/agent_usage_tracker/overview_cli.py +83 -0
  78. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/pricing.py +89 -22
  79. agent_usage_tracker-0.3.0/src/agent_usage_tracker/pricing_cli.py +31 -0
  80. agent_usage_tracker-0.3.0/src/agent_usage_tracker/quota.py +255 -0
  81. agent_usage_tracker-0.3.0/src/agent_usage_tracker/quota_cli.py +147 -0
  82. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/redact.py +21 -1
  83. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/scheduled.py +2 -0
  84. agent_usage_tracker-0.3.0/src/agent_usage_tracker/setup_cli.py +157 -0
  85. agent_usage_tracker-0.3.0/src/agent_usage_tracker/setup_schedule.py +164 -0
  86. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/sink_stack/README.md +6 -1
  87. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/sink_stack/grafana/dashboards/agents-effort.json +168 -4
  88. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/sink_stack/grafana/dashboards/agents-usage.json +99 -37
  89. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/sink_stack/sql/01_schema.sql +31 -0
  90. agent_usage_tracker-0.3.0/src/agent_usage_tracker/sink_stack/sql/02_price.sql +73 -0
  91. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/sink_stack/sql/03_effort.sql +9 -11
  92. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/sink_stack/sql/04_grants.sql +2 -0
  93. agent_usage_tracker-0.3.0/src/agent_usage_tracker/summary.py +363 -0
  94. agent_usage_tracker-0.3.0/src/agent_usage_tracker/summary_cli.py +34 -0
  95. agent_usage_tracker-0.3.0/src/agent_usage_tracker/usage_price.py +112 -0
  96. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_activitywatch.py +2 -1
  97. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_collectors.py +18 -0
  98. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_generic_sdk.py +18 -0
  99. agent_usage_tracker-0.3.0/tests/fixtures/claude-statusline-quota.json +10 -0
  100. agent_usage_tracker-0.3.0/tests/improve/test_case_context.py +88 -0
  101. agent_usage_tracker-0.3.0/tests/improve/test_count_evidence.py +171 -0
  102. agent_usage_tracker-0.3.0/tests/improve/test_decide.py +466 -0
  103. agent_usage_tracker-0.3.0/tests/improve/test_draft.py +314 -0
  104. agent_usage_tracker-0.3.0/tests/improve/test_draft_adapters.py +270 -0
  105. agent_usage_tracker-0.3.0/tests/improve/test_evidence_access.py +372 -0
  106. agent_usage_tracker-0.3.0/tests/improve/test_evidence_mcp.py +103 -0
  107. agent_usage_tracker-0.3.0/tests/improve/test_file_reads.py +48 -0
  108. agent_usage_tracker-0.3.0/tests/improve/test_inbox.py +158 -0
  109. agent_usage_tracker-0.3.0/tests/improve/test_judge_queue.py +134 -0
  110. agent_usage_tracker-0.3.0/tests/improve/test_native_evidence.py +179 -0
  111. agent_usage_tracker-0.3.0/tests/improve/test_outputs.py +464 -0
  112. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_proposals.py +30 -0
  113. agent_usage_tracker-0.3.0/tests/improve/test_qualify.py +365 -0
  114. agent_usage_tracker-0.3.0/tests/improve/test_ranked_evidence.py +124 -0
  115. agent_usage_tracker-0.3.0/tests/improve/test_report_card.py +291 -0
  116. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_schedule.py +23 -0
  117. agent_usage_tracker-0.3.0/tests/improve/test_scores.py +101 -0
  118. agent_usage_tracker-0.3.0/tests/improve/test_skill_proposals.py +70 -0
  119. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_store.py +24 -3
  120. agent_usage_tracker-0.3.0/tests/improve/test_studies.py +946 -0
  121. agent_usage_tracker-0.3.0/tests/improve/test_study_candidates.py +132 -0
  122. agent_usage_tracker-0.3.0/tests/improve/test_t3.py +518 -0
  123. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_trial.py +46 -0
  124. agent_usage_tracker-0.3.0/tests/improve/test_turn_provenance.py +105 -0
  125. agent_usage_tracker-0.3.0/tests/improve/test_turn_revisions.py +183 -0
  126. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_validation.py +93 -0
  127. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label.py +10 -1
  128. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label_models.py +2 -1
  129. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label_teach.py +10 -0
  130. agent_usage_tracker-0.3.0/tests/outcomes/conftest.py +25 -0
  131. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/outcomes/test_outcome_git.py +24 -21
  132. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/outcomes/test_outcomes.py +39 -39
  133. agent_usage_tracker-0.3.0/tests/pipeline/price_fixture.py +62 -0
  134. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_backup.py +1 -0
  135. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_coverage.py +2 -1
  136. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_coverage_scan.py +2 -1
  137. agent_usage_tracker-0.3.0/tests/pipeline/test_delivery_notices.py +124 -0
  138. agent_usage_tracker-0.3.0/tests/pipeline/test_demo.py +52 -0
  139. agent_usage_tracker-0.3.0/tests/pipeline/test_first_run.py +229 -0
  140. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_git_days.py +14 -5
  141. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_local_page.py +15 -0
  142. agent_usage_tracker-0.3.0/tests/pipeline/test_overview.py +101 -0
  143. agent_usage_tracker-0.3.0/tests/pipeline/test_overview_quota.py +82 -0
  144. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_pricing.py +87 -0
  145. agent_usage_tracker-0.3.0/tests/pipeline/test_publish_improve.py +190 -0
  146. agent_usage_tracker-0.3.0/tests/pipeline/test_quota.py +256 -0
  147. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_redact.py +33 -0
  148. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_scan_wrapper.py +19 -0
  149. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_sink.py +21 -1
  150. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_sink_sql.py +158 -1
  151. agent_usage_tracker-0.3.0/tests/pipeline/test_summary.py +208 -0
  152. agent_usage_tracker-0.3.0/tests/pipeline/test_summary_native_counts.py +93 -0
  153. agent_usage_tracker-0.3.0/tests/test_public_projection.py +32 -0
  154. agent_usage_tracker-0.1.1/PKG-INFO +0 -366
  155. agent_usage_tracker-0.1.1/README.md +0 -334
  156. agent_usage_tracker-0.1.1/docs/improvement-studies.md +0 -169
  157. agent_usage_tracker-0.1.1/packaging/windows/register-task.ps1 +0 -19
  158. agent_usage_tracker-0.1.1/src/agent_usage_tracker/improve/evidence.py +0 -322
  159. agent_usage_tracker-0.1.1/src/agent_usage_tracker/improve/inbox.py +0 -70
  160. agent_usage_tracker-0.1.1/src/agent_usage_tracker/improve/proposals.py +0 -72
  161. agent_usage_tracker-0.1.1/src/agent_usage_tracker/improve/study_cli.py +0 -46
  162. agent_usage_tracker-0.1.1/src/agent_usage_tracker/sink_stack/sql/02_price.sql +0 -60
  163. agent_usage_tracker-0.1.1/tests/improve/test_inbox.py +0 -76
  164. agent_usage_tracker-0.1.1/tests/improve/test_studies.py +0 -405
  165. agent_usage_tracker-0.1.1/tests/improve/test_t3.py +0 -294
  166. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/.gitignore +0 -0
  167. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/DEPLOY.md +0 -0
  168. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/LICENSE +0 -0
  169. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/config.example.toml +0 -0
  170. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/collectors-to-add.md +0 -0
  171. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/harness-coverage.md +0 -0
  172. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/human-html/2026-11-08-understanding-implicit-state-machines.html +0 -0
  173. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/human-html/2026-11-09-status-state-reliability-fixes.html +0 -0
  174. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/human-html/docs-index.json +0 -0
  175. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/human-html/index.html +0 -0
  176. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/local-labels.md +0 -0
  177. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/new-laptop.md +0 -0
  178. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/observations.md +0 -0
  179. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/research/codexbar-learnings.md +0 -0
  180. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/research/otel-lane.md +0 -0
  181. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/research/sdk-usage-capture.md +0 -0
  182. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/superpowers/plans/2026-07-22-aut-showcase-metrics.md +0 -0
  183. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/docs/superpowers/specs/2026-07-22-aut-showcase-metrics-design.md +0 -0
  184. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/packaging/README.md +0 -0
  185. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/packaging/claude/commands/outcome.md +0 -0
  186. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/packaging/launchd/dev.aut.backup.plist +0 -0
  187. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/packaging/launchd/dev.aut.improve-audit.plist +0 -0
  188. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/packaging/launchd/dev.aut.retry.plist +0 -0
  189. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/packaging/launchd/dev.aut.scan.plist +0 -0
  190. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/packaging/observations/Dockerfile +0 -0
  191. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/packaging/observations/Dockerfile.dockerignore +0 -0
  192. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/packaging/observations/README.md +0 -0
  193. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/packaging/observations/aut-observations.service +0 -0
  194. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/packaging/sql/turn-snapshot-grant.sql +0 -0
  195. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/packaging/systemd/agent-usage-tracker.service +0 -0
  196. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/packaging/systemd/agent-usage-tracker.timer +0 -0
  197. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/__init__.py +0 -0
  198. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/activity_common.py +0 -0
  199. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/activitywatch.py +0 -0
  200. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/claude_code.py +0 -0
  201. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/claude_code_activity.py +0 -0
  202. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/commits.py +0 -0
  203. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/cursor.py +0 -0
  204. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/cursor_api.py +0 -0
  205. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/pi.py +0 -0
  206. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/session_digest.py +0 -0
  207. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/collectors/t3.py +0 -0
  208. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/config.py +0 -0
  209. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/coverage_catalog.json +0 -0
  210. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/cursor_run.py +0 -0
  211. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/episode_store.py +0 -0
  212. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/git_day_cache.py +0 -0
  213. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/git_days.py +0 -0
  214. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/git_safe.py +0 -0
  215. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/harness_inventory.py +0 -0
  216. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/history_steers.py +0 -0
  217. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/__init__.py +0 -0
  218. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/desktop.py +0 -0
  219. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/groups.py +0 -0
  220. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/rubric.py +0 -0
  221. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/rubrics/avoidable_recovery.md +0 -0
  222. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/rubrics/code_quality.md +0 -0
  223. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/rubrics/completion_supported.md +0 -0
  224. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/rubrics/redundant_tests.md +0 -0
  225. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/rubrics/verbosity.md +0 -0
  226. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/runtime.py +0 -0
  227. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/improve/search_check.py +0 -0
  228. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/inspector.py +0 -0
  229. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/__init__.py +0 -0
  230. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/backends.py +0 -0
  231. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/bakeoff.py +0 -0
  232. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/baseline.py +0 -0
  233. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/clef.py +0 -0
  234. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/context.py +0 -0
  235. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/core.py +0 -0
  236. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/covered_run.py +0 -0
  237. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/evalset.py +0 -0
  238. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/local.py +0 -0
  239. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/local_parallel.py +0 -0
  240. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/merge.py +0 -0
  241. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/outcome_coverage.py +0 -0
  242. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/replay.py +0 -0
  243. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/run.py +0 -0
  244. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/label/tasks.py +0 -0
  245. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/manual_time.py +0 -0
  246. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/observation_report.py +0 -0
  247. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/observation_server.py +0 -0
  248. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/outcomes.py +0 -0
  249. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/push.py +0 -0
  250. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/repo_keys.py +0 -0
  251. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/review.py +0 -0
  252. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/scan.py +0 -0
  253. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/sdk.py +0 -0
  254. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/sink.py +0 -0
  255. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/sink_stack/apply.sh +0 -0
  256. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/sink_stack/compose.yaml +0 -0
  257. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/sink_stack/env.example +0 -0
  258. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/sink_stack/grafana/provisioning/dashboards/aut.yaml +0 -0
  259. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/sink_stack/grafana/provisioning/datasources/agents.yaml +0 -0
  260. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/sink_stack/sql/refresh.sql +0 -0
  261. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/sources.py +0 -0
  262. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/state.py +0 -0
  263. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/src/agent_usage_tracker/telemetry.py +0 -0
  264. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/codex_pi_helpers.py +0 -0
  265. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_activity.py +0 -0
  266. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_activitywatch_macos.py +0 -0
  267. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_claude_code.py +0 -0
  268. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_claude_profiles.py +0 -0
  269. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_codex.py +0 -0
  270. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_codex_pi.py +0 -0
  271. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_commits.py +0 -0
  272. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_cursor.py +0 -0
  273. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_cursor_api.py +0 -0
  274. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_cursor_cli.py +0 -0
  275. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_cursor_cli_cache.py +0 -0
  276. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_cursor_sdk.py +0 -0
  277. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_links.py +0 -0
  278. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_links_claude.py +0 -0
  279. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_pi.py +0 -0
  280. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_read_horizon.py +0 -0
  281. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_session_digest.py +0 -0
  282. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_source_registry.py +0 -0
  283. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/collectors/test_t3.py +0 -0
  284. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/conftest.py +0 -0
  285. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/__init__.py +0 -0
  286. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/conftest.py +0 -0
  287. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_case_view.py +0 -0
  288. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_cli.py +0 -0
  289. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_desktop.py +0 -0
  290. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_evidence.py +0 -0
  291. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_evidence_citations.py +0 -0
  292. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_groups.py +0 -0
  293. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_judge.py +0 -0
  294. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_judge_choices.py +0 -0
  295. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_judge_deadline.py +0 -0
  296. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_judge_native_deadline.py +0 -0
  297. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_judge_sampling.py +0 -0
  298. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_judge_stall.py +0 -0
  299. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_rubric.py +0 -0
  300. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_runtime.py +0 -0
  301. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_search_check.py +0 -0
  302. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/improve/test_studies_decision.py +0 -0
  303. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/label_helpers.py +0 -0
  304. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_context_paths.py +0 -0
  305. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_covered_run.py +0 -0
  306. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_cursor_origin.py +0 -0
  307. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_history_steers.py +0 -0
  308. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label_bakeoff.py +0 -0
  309. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label_baseline.py +0 -0
  310. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label_context.py +0 -0
  311. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label_core.py +0 -0
  312. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label_evalset.py +0 -0
  313. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label_gap.py +0 -0
  314. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label_gold.py +0 -0
  315. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label_local.py +0 -0
  316. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label_parallel.py +0 -0
  317. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label_reliability.py +0 -0
  318. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label_replay.py +0 -0
  319. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label_tasks.py +0 -0
  320. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_label_writing.py +0 -0
  321. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/label/test_outcome_coverage.py +0 -0
  322. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/outcomes/test_outcome_reliability.py +0 -0
  323. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/fake_psycopg.py +0 -0
  324. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_cli.py +0 -0
  325. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_coverage_diagnostics.py +0 -0
  326. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_cursor_run.py +0 -0
  327. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_delivery_cli.py +0 -0
  328. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_git_day_cache.py +0 -0
  329. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_harness_inventory.py +0 -0
  330. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_heartbeat.py +0 -0
  331. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_inspect.py +0 -0
  332. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_ledger_zone.py +0 -0
  333. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_net.py +0 -0
  334. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_push.py +0 -0
  335. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_push_outbox.py +0 -0
  336. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_push_snapshots.py +0 -0
  337. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_repo_keys.py +0 -0
  338. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_review.py +0 -0
  339. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_sessions.py +0 -0
  340. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/pipeline/test_state.py +0 -0
  341. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/test_observation_cli.py +0 -0
  342. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/test_observation_report.py +0 -0
  343. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/test_observation_server.py +0 -0
  344. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/test_observations.py +0 -0
  345. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/test_observe_entrypoint.py +0 -0
  346. {agent_usage_tracker-0.1.1 → agent_usage_tracker-0.3.0}/tests/test_telemetry.py +0 -0
@@ -935,3 +935,22 @@ People can change coding tools without assuming that a successful collector capt
935
935
  Doctor does not fetch a website or manufacture a publisher receipt.
936
936
 
937
937
  The [coverage guide](docs/harness-coverage.md) defines the registry, limits and supported fields.
938
+
939
+ ### Advisory improvement scores
940
+
941
+ `aut publish-improve` sends sampled verdict counts and human adoption metadata to the private sink.
942
+ It sends no evidence text, paths, case identifiers, session identifiers, rationale or commit SHAs.
943
+
944
+ `agents.improve_score_daily` is append-only, keyed by
945
+ `(day, rubric_id, rubric_version, harness, trigger, pushed_at)`.
946
+ Counts are `passed`, `failed`, `unknown` (nonnegative integers), with a boolean `qualified`.
947
+ `day` is the work date in the configured ledger time zone.
948
+ Triggers are `control`, `error_result`, or `merge`; versions are nonnegative integers.
949
+ `agents.improve_score_latest` exposes the latest push for each key without `pushed_at`.
950
+ A zero row clears a key removed inside the publisher's recomputed date window.
951
+
952
+ `agents.improve_adoption` holds `adoption_id` (first 16 hex of the private record key),
953
+ `adopted_at` (local noon), operator-written `title` (1..120 characters),
954
+ `kind` (`instruction`, `skill`, `config`, `code`), `rubric_ids` (text array), and optional integer `pr`.
955
+ Adoptions use `ON CONFLICT (adoption_id) DO NOTHING`. They do not claim a benefit.
956
+ The writer can select and insert both tables. Grafana reads only the latest score view and adoption table.
@@ -0,0 +1,119 @@
1
+ Metadata-Version: 2.5
2
+ Name: agent-usage-tracker
3
+ Version: 0.3.0
4
+ Summary: Track coding-agent usage and outcomes from local logs, find recurring problems, and test proposed fixes before adopting them.
5
+ Project-URL: Homepage, https://github.com/rhnfzl/agent-usage-tracker
6
+ Project-URL: Issues, https://github.com/rhnfzl/agent-usage-tracker/issues
7
+ License: MIT
8
+ License-File: LICENSE
9
+ Keywords: claude-code,codex,coding-agent,cursor,observability,pi,tokens,usage
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Environment :: Console
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Software Development
15
+ Requires-Python: >=3.11
16
+ Requires-Dist: tzdata; sys_platform == 'win32'
17
+ Provides-Extra: label
18
+ Requires-Dist: huggingface-hub>=1.3; (sys_platform == 'darwin' and platform_machine == 'arm64') and extra == 'label'
19
+ Requires-Dist: mlx-lm<0.33,>=0.32.2; (sys_platform == 'darwin' and platform_machine == 'arm64') and extra == 'label'
20
+ Requires-Dist: mlx>=0.31.2; (sys_platform == 'darwin' and platform_machine == 'arm64') and extra == 'label'
21
+ Requires-Dist: psycopg[binary]>=3.1; extra == 'label'
22
+ Provides-Extra: mcp
23
+ Requires-Dist: mcp<2,>=1.30; extra == 'mcp'
24
+ Provides-Extra: merge
25
+ Requires-Dist: huggingface-hub>=1.3; extra == 'merge'
26
+ Requires-Dist: peft>=0.21; extra == 'merge'
27
+ Requires-Dist: torch>=2.14; extra == 'merge'
28
+ Requires-Dist: transformers>=5.17; extra == 'merge'
29
+ Provides-Extra: postgres
30
+ Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
31
+ Provides-Extra: test
32
+ Requires-Dist: pytest; extra == 'test'
33
+ Requires-Dist: pytest-xdist==3.8.0; extra == 'test'
34
+ Description-Content-Type: text/markdown
35
+
36
+ # Agent Usage Tracker (`aut`)
37
+
38
+ [![CI](https://github.com/rhnfzl/agent-usage-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/rhnfzl/agent-usage-tracker/actions/workflows/ci.yml)
39
+ [![PyPI](https://img.shields.io/pypi/v/agent-usage-tracker)](https://pypi.org/project/agent-usage-tracker/)
40
+ [![MIT license](https://img.shields.io/badge/license-MIT-green)](https://github.com/rhnfzl/agent-usage-tracker/blob/main/LICENSE)
41
+
42
+ **See where your coding agents spend tokens, how the work ends, and what keeps going wrong.**
43
+
44
+ AUT reads the logs Claude Code, Codex, Cursor, and Pi already save. Start with a local usage report or CSV. Add your own database for session history across machines. The optional improvement workflow links recurring problems to the evidence and drafts changes you can review.
45
+
46
+ ## Quick start
47
+
48
+ With [uv](https://docs.astral.sh/uv/getting-started/installation/) installed, try the demo with synthetic logs:
49
+
50
+ ```sh
51
+ uvx agent-usage-tracker demo
52
+ ```
53
+
54
+ The demo finds two agent records totaling **1,140 tokens**. It shows input, output and cache separately, and reports missing model prices as unknown. Try the same report with your own logs, or export them as a CSV:
55
+
56
+ ```sh
57
+ uvx agent-usage-tracker summary --period week --group-by agent
58
+ uvx agent-usage-tracker --agents claude_code,codex,cursor_cli,pi export --out usage.csv
59
+ ```
60
+
61
+ Local reporting runs without a database, a provider account, or a model. The CLI runs on macOS, Linux, and Windows with Python 3.11 to 3.15. See [first run](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/first-run.md) for installation, source checks, and the private browser overview.
62
+
63
+ ## What you can track
64
+
65
+ | Question | Where to start |
66
+ |---|---|
67
+ | Which agents and models am I using? How much is cached? | Local summary and CSV export. |
68
+ | Which sessions belong to the same work? What happened to their commits? | Your own TimescaleDB and Grafana stack, with Git outcome tracking. |
69
+ | How much of my work is building, debugging, planning, or review? | Optional local models estimate work categories and leave uncertain cases unknown. |
70
+ | What if I lose this laptop? | Optional encrypted backups of agent logs and AUT settings with restic. |
71
+
72
+ ## From a repeated problem to a fix you can review
73
+
74
+ ![AUT reads agent logs for a local report or self-hosted history. A separate optional workflow checks local evidence, groups recurring problems, and drafts a fix for approval.](https://raw.githubusercontent.com/rhnfzl/agent-usage-tracker/main/docs/assets/aut-workflow.png)
75
+
76
+ For example, an agent says the tests passed. AUT can surface the tool result behind that claim. If the result is missing, the judgment can stay unknown. When judgments identify the same problem across distinct tasks, AUT can group those cases and draft a small instruction or config change in an isolated copy. Run a check you trust against the original and the candidate, then decide whether to adopt it.
77
+
78
+ Start by freezing a small sample of recent sessions. This step runs locally without a model:
79
+
80
+ ```sh
81
+ uvx agent-usage-tracker improve audit --days 7 --limit 30
82
+ ```
83
+
84
+ The [improvement guide](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/improvement.md) covers private evidence, advisory judgments, drafts, and the review inbox. The [study guide](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/improvement-studies.md) explains how to test a candidate. Source edits require an explicit decision. A passing check supports the tested change; measuring an improvement in real work requires comparable follow-up.
85
+
86
+ You can also ask a coding agent to explore that evidence directly. Run `aut evidence capture` for a private full-text audit, then search and compare runs through the CLI or MCP. Choose what the client can read and link useful findings to a repair you can test. See the [agent evidence guide](docs/evidence.md).
87
+
88
+ ## How I run AUT
89
+
90
+ I run AUT on an Apple silicon Mac to track agent usage, classify work, and find recurring problems. AUT sends usage metadata to a self-hosted database. The local labeler combines that metadata with request and reply text on the Mac.
91
+
92
+ ![Agent logs feed usage reporting, local decision models for provisional labels, and private evidence review. Inkling drafts proposals for recurring problems, then a person reviews them.](https://raw.githubusercontent.com/rhnfzl/agent-usage-tracker/main/docs/assets/aut-local-setup.png)
93
+
94
+ | Job | Models I use | Method |
95
+ | --- | --- | --- |
96
+ | What my message is doing | Elephant 1, PPLX Decider Flash, Kev 4B | Weighted scores |
97
+ | What kind of work I’m doing | PPLX Decider Flash, Elephant 1, Clef Flash | Majority vote |
98
+ | Where work with no code changes stands | Elephant 1, Kev 4B, Clef Flash | Weighted scores |
99
+ | Draft a fix for a recurring problem | Inkling 2 Mini via llama.cpp | Low reasoning effort, then human review |
100
+
101
+ The label recipes leave uncertain cases unknown. I run the larger Inkling model only when a recurring problem is eligible for a draft. Each proposal goes to a private inbox for review.
102
+
103
+ You can adapt this setup by starting with one [local decision model](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/local-labels.md#ongoing-local-estimates) per job and checking it against examples you’ve reviewed. Add [offline drafting](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/improvement.md#drafted-proposals) when you have a recurring problem worth testing a fix for.
104
+
105
+ ## Collectors
106
+
107
+ Claude Code, Codex, and Pi supply native token records. Cursor CLI supplies prompts and activity. For Cursor token totals, choose one of the IDE, API, or SDK sources to avoid double-counting. T3 Code activity and ActivityWatch are optional. See the [collector matrix](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/reference.md#collectors) and [coverage guide](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/harness-coverage.md).
108
+
109
+ ## Privacy model
110
+
111
+ Normal collection works from existing logs. If you configure a sink, it receives usage and activity metadata such as counts, project basenames, and commit IDs. Prompt text and tool output stay off that path. Optional remote drafting sends selected file text and review summaries after redaction. Remote drafting requires a separate opt-in for conversation excerpts. Evidence access uses the content mode you choose for that connection or export. See the [privacy and network-call reference](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/reference.md#privacy-model) and [drafting guide](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/improvement.md#drafted-proposals).
112
+
113
+ Usage is measured in tokens. Dollar estimates apply API list rates and are separate from subscription billing. AUT is a CLI with an optional self-hosted dashboard.
114
+
115
+ ## Documentation
116
+
117
+ - **Set up:** [First run](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/first-run.md) · [Self-hosted stack](https://github.com/rhnfzl/agent-usage-tracker/blob/main/src/agent_usage_tracker/sink_stack/README.md) · [Deploy runbook](https://github.com/rhnfzl/agent-usage-tracker/blob/main/DEPLOY.md) · [Timers](https://github.com/rhnfzl/agent-usage-tracker/blob/main/packaging/README.md)
118
+ - **Use it:** [Command and configuration reference](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/reference.md) · [Local labels](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/local-labels.md) · [Quota and statusline](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/quota.md) · [Backup and recovery](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/new-laptop.md)
119
+ - **Improve it:** [Private improvement](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/improvement.md) · [Controlled studies](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/improvement-studies.md) · [Observation imports](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/observations.md) · [Development](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/development.md) · [Data contract](https://github.com/rhnfzl/agent-usage-tracker/blob/main/CONTRACT.md)
@@ -0,0 +1,84 @@
1
+ # Agent Usage Tracker (`aut`)
2
+
3
+ [![CI](https://github.com/rhnfzl/agent-usage-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/rhnfzl/agent-usage-tracker/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/agent-usage-tracker)](https://pypi.org/project/agent-usage-tracker/)
5
+ [![MIT license](https://img.shields.io/badge/license-MIT-green)](https://github.com/rhnfzl/agent-usage-tracker/blob/main/LICENSE)
6
+
7
+ **See where your coding agents spend tokens, how the work ends, and what keeps going wrong.**
8
+
9
+ AUT reads the logs Claude Code, Codex, Cursor, and Pi already save. Start with a local usage report or CSV. Add your own database for session history across machines. The optional improvement workflow links recurring problems to the evidence and drafts changes you can review.
10
+
11
+ ## Quick start
12
+
13
+ With [uv](https://docs.astral.sh/uv/getting-started/installation/) installed, try the demo with synthetic logs:
14
+
15
+ ```sh
16
+ uvx agent-usage-tracker demo
17
+ ```
18
+
19
+ The demo finds two agent records totaling **1,140 tokens**. It shows input, output and cache separately, and reports missing model prices as unknown. Try the same report with your own logs, or export them as a CSV:
20
+
21
+ ```sh
22
+ uvx agent-usage-tracker summary --period week --group-by agent
23
+ uvx agent-usage-tracker --agents claude_code,codex,cursor_cli,pi export --out usage.csv
24
+ ```
25
+
26
+ Local reporting runs without a database, a provider account, or a model. The CLI runs on macOS, Linux, and Windows with Python 3.11 to 3.15. See [first run](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/first-run.md) for installation, source checks, and the private browser overview.
27
+
28
+ ## What you can track
29
+
30
+ | Question | Where to start |
31
+ |---|---|
32
+ | Which agents and models am I using? How much is cached? | Local summary and CSV export. |
33
+ | Which sessions belong to the same work? What happened to their commits? | Your own TimescaleDB and Grafana stack, with Git outcome tracking. |
34
+ | How much of my work is building, debugging, planning, or review? | Optional local models estimate work categories and leave uncertain cases unknown. |
35
+ | What if I lose this laptop? | Optional encrypted backups of agent logs and AUT settings with restic. |
36
+
37
+ ## From a repeated problem to a fix you can review
38
+
39
+ ![AUT reads agent logs for a local report or self-hosted history. A separate optional workflow checks local evidence, groups recurring problems, and drafts a fix for approval.](https://raw.githubusercontent.com/rhnfzl/agent-usage-tracker/main/docs/assets/aut-workflow.png)
40
+
41
+ For example, an agent says the tests passed. AUT can surface the tool result behind that claim. If the result is missing, the judgment can stay unknown. When judgments identify the same problem across distinct tasks, AUT can group those cases and draft a small instruction or config change in an isolated copy. Run a check you trust against the original and the candidate, then decide whether to adopt it.
42
+
43
+ Start by freezing a small sample of recent sessions. This step runs locally without a model:
44
+
45
+ ```sh
46
+ uvx agent-usage-tracker improve audit --days 7 --limit 30
47
+ ```
48
+
49
+ The [improvement guide](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/improvement.md) covers private evidence, advisory judgments, drafts, and the review inbox. The [study guide](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/improvement-studies.md) explains how to test a candidate. Source edits require an explicit decision. A passing check supports the tested change; measuring an improvement in real work requires comparable follow-up.
50
+
51
+ You can also ask a coding agent to explore that evidence directly. Run `aut evidence capture` for a private full-text audit, then search and compare runs through the CLI or MCP. Choose what the client can read and link useful findings to a repair you can test. See the [agent evidence guide](docs/evidence.md).
52
+
53
+ ## How I run AUT
54
+
55
+ I run AUT on an Apple silicon Mac to track agent usage, classify work, and find recurring problems. AUT sends usage metadata to a self-hosted database. The local labeler combines that metadata with request and reply text on the Mac.
56
+
57
+ ![Agent logs feed usage reporting, local decision models for provisional labels, and private evidence review. Inkling drafts proposals for recurring problems, then a person reviews them.](https://raw.githubusercontent.com/rhnfzl/agent-usage-tracker/main/docs/assets/aut-local-setup.png)
58
+
59
+ | Job | Models I use | Method |
60
+ | --- | --- | --- |
61
+ | What my message is doing | Elephant 1, PPLX Decider Flash, Kev 4B | Weighted scores |
62
+ | What kind of work I’m doing | PPLX Decider Flash, Elephant 1, Clef Flash | Majority vote |
63
+ | Where work with no code changes stands | Elephant 1, Kev 4B, Clef Flash | Weighted scores |
64
+ | Draft a fix for a recurring problem | Inkling 2 Mini via llama.cpp | Low reasoning effort, then human review |
65
+
66
+ The label recipes leave uncertain cases unknown. I run the larger Inkling model only when a recurring problem is eligible for a draft. Each proposal goes to a private inbox for review.
67
+
68
+ You can adapt this setup by starting with one [local decision model](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/local-labels.md#ongoing-local-estimates) per job and checking it against examples you’ve reviewed. Add [offline drafting](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/improvement.md#drafted-proposals) when you have a recurring problem worth testing a fix for.
69
+
70
+ ## Collectors
71
+
72
+ Claude Code, Codex, and Pi supply native token records. Cursor CLI supplies prompts and activity. For Cursor token totals, choose one of the IDE, API, or SDK sources to avoid double-counting. T3 Code activity and ActivityWatch are optional. See the [collector matrix](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/reference.md#collectors) and [coverage guide](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/harness-coverage.md).
73
+
74
+ ## Privacy model
75
+
76
+ Normal collection works from existing logs. If you configure a sink, it receives usage and activity metadata such as counts, project basenames, and commit IDs. Prompt text and tool output stay off that path. Optional remote drafting sends selected file text and review summaries after redaction. Remote drafting requires a separate opt-in for conversation excerpts. Evidence access uses the content mode you choose for that connection or export. See the [privacy and network-call reference](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/reference.md#privacy-model) and [drafting guide](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/improvement.md#drafted-proposals).
77
+
78
+ Usage is measured in tokens. Dollar estimates apply API list rates and are separate from subscription billing. AUT is a CLI with an optional self-hosted dashboard.
79
+
80
+ ## Documentation
81
+
82
+ - **Set up:** [First run](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/first-run.md) · [Self-hosted stack](https://github.com/rhnfzl/agent-usage-tracker/blob/main/src/agent_usage_tracker/sink_stack/README.md) · [Deploy runbook](https://github.com/rhnfzl/agent-usage-tracker/blob/main/DEPLOY.md) · [Timers](https://github.com/rhnfzl/agent-usage-tracker/blob/main/packaging/README.md)
83
+ - **Use it:** [Command and configuration reference](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/reference.md) · [Local labels](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/local-labels.md) · [Quota and statusline](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/quota.md) · [Backup and recovery](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/new-laptop.md)
84
+ - **Improve it:** [Private improvement](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/improvement.md) · [Controlled studies](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/improvement-studies.md) · [Observation imports](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/observations.md) · [Development](https://github.com/rhnfzl/agent-usage-tracker/blob/main/docs/development.md) · [Data contract](https://github.com/rhnfzl/agent-usage-tracker/blob/main/CONTRACT.md)
@@ -0,0 +1,41 @@
1
+ # Development
2
+
3
+ From a checkout:
4
+
5
+ In restricted agent sessions, keep uv's cache inside the checkout before running these commands:
6
+
7
+ ```bash
8
+ export UV_CACHE_DIR="$PWD/.agent-harness/uv-cache"
9
+ ```
10
+
11
+ ```bash
12
+ uv venv
13
+ uv pip install -e ".[test,postgres]" ruff==0.15.11 mypy==2.4.1
14
+ uv run --no-sync pytest -q
15
+ uv run --no-sync ruff check .
16
+ uv run --no-sync mypy
17
+ ```
18
+
19
+ For feedback before committing, run the same Ruff and mypy commands as CI:
20
+
21
+ ```bash
22
+ uv run --no-sync ruff check . && uv run --no-sync mypy
23
+ ```
24
+
25
+ You can add that line to your existing pre-commit hook. It checks the working tree.
26
+ For a full test run with the same three workers as CI:
27
+
28
+ ```bash
29
+ uv run --no-sync pytest -q -n 3 --dist worksteal --max-worker-restart=0 --durations=15
30
+ ```
31
+
32
+ The [CI workflow](../.github/workflows/ci.yml) tests Linux, macOS, and Windows across supported Python versions.
33
+ It also checks Ruff, mypy, the sink SQL, and the Compose configuration.
34
+ The `CI required` check passes once all validation jobs succeed.
35
+ In GitHub's branch protection for `main`, require a pull request and the `CI required` check from GitHub Actions.
36
+ Require branches to be up to date before merging, and apply the rule to administrators.
37
+ CI also runs on `main` to verify the landed commit.
38
+ SQL integration tests require a scratch database on a TimescaleDB server and `psql`, through `AUT_TEST_PG_DSN` with a literal IP address and port; otherwise those tests skip.
39
+ To release, raise `__version__` in `src/agent_usage_tracker/__init__.py`, merge, and push the tag `v<version>`.
40
+ The [release workflow](../.github/workflows/release.yml) builds it and publishes it to PyPI through trusted publishing.
41
+ Use synthetic fixtures in public contributions. Keep session logs, personal labels, and private benchmarks out of commits.
@@ -0,0 +1,181 @@
1
+ # Investigate coding-agent sessions with AUT
2
+
3
+ Search across agent sessions, cite captured events, and compare a failed attempt with a clean one.
4
+ Use the CLI from a shell or give an agent the same operations through MCP. Both read a selected
5
+ audit or a portable evidence bundle.
6
+
7
+ ## Capture a project
8
+
9
+ ```sh
10
+ aut evidence capture --project /path/to/repo --days 7 --limit 20
11
+ aut evidence --audit AUDIT_ID describe
12
+ aut evidence --audit AUDIT_ID search --status error
13
+ aut evidence --audit AUDIT_ID search --query "Operation not permitted"
14
+ aut evidence --audit AUDIT_ID search --mode ranked --query "permissions cache"
15
+ aut evidence --audit AUDIT_ID session SESSION_ID
16
+ aut evidence --audit AUDIT_ID event SESSION_ID EVENT_ID
17
+ aut evidence --audit AUDIT_ID commits COMMIT_SHA
18
+ aut evidence --audit AUDIT_ID compare FAILED_SESSION_ID CLEAN_SESSION_ID
19
+ ```
20
+
21
+ Exact mode is the default. It matches literal substrings. Ranked mode uses SQLite FTS5 to match words
22
+ in any order and puts exact phrases first. A running MCP server reuses an in-memory index for
23
+ queries and pages that use the same filters. It rebuilds the index when the filters or source
24
+ files change. Each CLI invocation builds a fresh index. Narrow the filters if the index would
25
+ exceed 50,000 events or 64 MiB. Metadata-only scope supports filters without text search.
26
+
27
+ Copy the full audit, session, and event IDs from the JSON results. Follow search's `next_cursor`
28
+ with the same filters. An empty search page can still have a cursor when the scan budget runs out.
29
+ Session results list event references. Supported native Codex turns link the completed turn to its
30
+ recorded model and workspace. Metadata-only clients can see the status and source location.
31
+ Read a referenced event and follow `next_offset` to read its
32
+ remaining text. Commit lookup cites a matched Git call and result. A short recorded prefix can
33
+ match more than one commit. AUT reports the prefix as captured. Redacted and metadata scopes omit
34
+ command-derived IDs that match a redaction rule. Comparison shows event counts and the first difference in the observed tool
35
+ sequence. A missing result stays unknown. The comparison does not infer why two runs differed.
36
+
37
+ For a completed T3 run with a ready workspace checkpoint, AUT resolves its local Git ref
38
+ when it captures the audit. Open the boundary event to see the checkpoint time and, with
39
+ full or redacted access, the ref and commit. This is the workspace state saved by T3 after a run.
40
+ Ordinary-work studies still verify turn-start setup from the evidence recorded for that turn.
41
+ If you already have a checkpoint SHA, use
42
+ `aut evidence --audit AUDIT_ID commits CHECKPOINT_SHA --source checkpoint` to find its run.
43
+ MCP accepts the same `source` option.
44
+
45
+ The project filter includes its Git worktrees and excludes sessions with recorded directories in
46
+ other repositories. T3 applies the thread limit within that project.
47
+ The filter cannot infer where unrecorded tool activity took place. Select explicit
48
+ sessions before sharing externally. Use `--workspace` or `--tool` to filter on recorded labels. Capture uses AUT's existing Claude Code, Codex, Pi,
49
+ Cursor CLI, and T3 Code sources and preserves their coverage limits. It skips recently active
50
+ sources by default. Session and event IDs refer to frozen evidence. A fresh capture can include
51
+ new events and produce a new ID.
52
+
53
+ If a session reports a byte cap, capture the project again with a larger per-source budget.
54
+ For example, use `aut evidence --content redacted capture --project /path/to/repo --max-mib 64`.
55
+ The default is 16 MiB. The audit records the budget and reports any remaining capture gaps.
56
+
57
+ ## Choose what the client can read
58
+
59
+ Put `--content` before the operation, for example
60
+ `aut evidence --audit AUDIT_ID --content redacted event SESSION_ID EVENT_ID`.
61
+
62
+ | Mode | Result |
63
+ | --- | --- |
64
+ | `full` (default) | Unredacted text available from the selected capture. |
65
+ | `redacted` | Text with recognized secrets and identifiers masked. Review it before sharing. |
66
+ | `metadata` | Event references, kinds, counts, and coverage. Text search is unavailable. |
67
+
68
+ Running `aut evidence capture` authorizes a new private copy of available text in the AUT improvement
69
+ store. It retains normalized text, subject to each source's capture budget and exclusions.
70
+ Existing audits may contain only clipped, redacted text. Such events report `snapshot_redacted`
71
+ when the client requests their text. This includes a restored snapshot without its full-text record.
72
+ Capture the source again if it is still available.
73
+
74
+ Full text lives in separate private records. Existing judges, drafts, and the usage sink still
75
+ receive their existing inputs. Default restic backups exclude these records in the standard store
76
+ and the store named by `AUT_IMPROVE_ROOT`. Add the full-content directory to `backup_excludes`
77
+ when a different `--root` sits inside a backed-up path. Use `aut evidence --content redacted capture` to save only the
78
+ standard redacted snapshots. Bundles and MCP clients can narrow their content mode; they cannot
79
+ recover text omitted at capture or export. A local process can still pass a response to a hosted
80
+ model through its client. Choose the content mode and client together.
81
+
82
+ ## Connect a local MCP client
83
+
84
+ Install the optional MCP extra in the environment that supplies `aut`.
85
+
86
+ ```sh
87
+ pip install 'agent-usage-tracker[mcp]'
88
+ ```
89
+
90
+ Set the client's MCP command to the absolute path to `aut`. Pass these arguments:
91
+
92
+ ```json
93
+ ["evidence", "--audit", "AUDIT_ID", "mcp"]
94
+ ```
95
+
96
+ Use the same `--root` as capture if you use a custom store. Add `--content redacted` before
97
+ `mcp` to mask text. The server exposes `describe`, `search`, `session`, `event`, `compare`,
98
+ `commits`, `case`, and `ordinary_work` with the same scope and results as the CLI.
99
+ It provides read operations only.
100
+
101
+ An example prompt for the connected agent:
102
+
103
+ > Find recent setup failures and a comparable successful attempt. Cite the failed call and its
104
+ > result, list the differences you can observe, and propose one change we can test. State any
105
+ > missing context that affects the diagnosis.
106
+
107
+ ## Read the evidence from another machine
108
+
109
+ Export the exact sessions you want to share:
110
+
111
+ ```sh
112
+ aut evidence --audit AUDIT_ID --content redacted export investigation.json SESSION_ID OTHER_SESSION_ID
113
+ aut evidence --bundle investigation.json search --status error
114
+ ```
115
+
116
+ Transfer the file through a channel you choose. A bundle is private plain JSON with an integrity
117
+ checksum. It can be opened without the original logs or store. AUT refuses to overwrite an existing
118
+ bundle. Treat a bundle as saved data. Revoke client access by stopping the server or replacing its
119
+ token. Copies recipients already have remain readable.
120
+
121
+ On a private host, load a bundle or use an audit already on that host. Supply a unique random
122
+ URL-safe token of 32 to 128 characters through `AUT_EVIDENCE_TOKEN`. For example, generate it with
123
+ `python -c 'import secrets; print(secrets.token_urlsafe(32))'` and store it with the service's secrets.
124
+
125
+ ```sh
126
+ aut evidence --bundle investigation.json mcp --transport http --port 8765
127
+ ssh -N -L 8765:127.0.0.1:8765 user@host
128
+ ```
129
+
130
+ Run the first command on the evidence host and the second on the client machine. Configure a client
131
+ that supports custom bearer headers to use `http://127.0.0.1:8765/mcp` with that token. The service
132
+ binds to loopback and scopes one token to the selected evidence. It supports explicit bearer
133
+ credentials over the tunnel. It does not run an OAuth authorization server or a multi-tenant
134
+ service. The host's normal AUT usage sink does not provide transcript access.
135
+
136
+ ## Turn an observation into a repair
137
+
138
+ Freeze selected attempts in the private store. This creates the same type of case AUT uses for
139
+ proposals and studies. It does not run a judge.
140
+
141
+ ```sh
142
+ aut evidence --audit AUDIT_ID freeze-case FAILED_SESSION_ID FAILED_EVENT_ID
143
+ aut evidence --audit AUDIT_ID freeze-case CLEAN_SESSION_ID CLEAN_EVENT_ID
144
+ aut evidence --audit AUDIT_ID compare FAILED_CASE_ID CLEAN_CASE_ID --cases
145
+ ```
146
+
147
+ A case from a successful run can preserve a workflow worth reusing. Case results list commit IDs
148
+ observed in matched Git tool results when the capture contains them. Use the failing case when
149
+ drafting a repair. Set an explicit scope and target for the proposed change.
150
+
151
+ ```sh
152
+ aut improve propose --case FAILED_CASE_ID --scope /path/to/repo \
153
+ --target /path/to/repo/AGENTS.md --before-file before.txt --after-file after.txt
154
+ ```
155
+
156
+ Use the same improvement root for both commands. The
157
+ [study workflow](improvement-studies.md) links the candidate to the original evidence. Test an
158
+ isolated baseline and candidate with the same acceptance check. Record the result and compare
159
+ fresh eligible work before claiming a lasting benefit. The source configuration changes only
160
+ through the existing review and adoption process.
161
+
162
+ ## Propose a project skill from successful work
163
+
164
+ Open the successful attempts and freeze their case IDs. Ask the reviewing agent to write a draft
165
+ `SKILL.md` with a matching `name`, a `description`, and the instructions. Cite at least two independent
166
+ sessions from the same project. Each citation identifies a successful result matched to a captured
167
+ call. AUT records the supporting cases and any observed commit IDs.
168
+
169
+ ```sh
170
+ aut evidence --audit AUDIT_ID propose-skill --scope /path/to/repo \
171
+ --target .agents/skills/check-setup/SKILL.md --draft-file draft.md \
172
+ --proof CASE_ID:EVENT_ID --proof OTHER_CASE_ID:OTHER_EVENT_ID \
173
+ --candidate /path/outside/the/repo
174
+ ```
175
+
176
+ Review the proposal with `aut improve inbox list` and the existing review workflow. AUT can prepare
177
+ an addition or update, and stage it in the independent candidate. A new file has a null baseline
178
+ hash. To trial the addition, explicitly list the file with a null value in `files.baseline`. List its
179
+ SHA-256 hash in `files.candidate`. This binds the trial to the absence of the skill before the change.
180
+ A successful tool result is evidence for the cited step. Review whether the proposed instructions
181
+ apply to the whole workflow before you adopt the skill.
@@ -0,0 +1,145 @@
1
+ # First run
2
+
3
+ AUT reads the logs your coding agents already save. You can try it and check local coverage before
4
+ you choose a database or send any data.
5
+
6
+ ## Start with a local report
7
+
8
+ With [uv](https://docs.astral.sh/uv/getting-started/installation/) installed, install the
9
+ latest release to get the `aut` command:
10
+
11
+ ```sh
12
+ uv tool install agent-usage-tracker
13
+ ```
14
+
15
+ Install from `git+https://github.com/rhnfzl/agent-usage-tracker` when you need a change on
16
+ `main` before the next release.
17
+
18
+ ```sh
19
+ aut setup
20
+ aut demo
21
+ aut setup --apply
22
+ aut summary
23
+ aut overview
24
+ ```
25
+
26
+ `aut setup` previews the config path and checks local source metadata. Use `--json` for a
27
+ receipt with separate settings, source observations and delivery state. A scan receipt
28
+ describes locally emitted rows. The local queue can show pending rows, while delivery remains
29
+ unverified until you check the sink. A missing source can mean that the agent has yet to log
30
+ any work. Run `aut doctor --json` for the full private coverage report.
31
+
32
+ `aut setup --apply` creates the starter config only when the file is missing. The starter
33
+ uses local logs and leaves delivery off. The [config example](../config.example.toml) describes
34
+ optional sources and transport settings. The demo uses sample logs in a temporary directory.
35
+ It needs no provider account, database or previous setup.
36
+
37
+ The overview opens a private loopback page. Choose a date range and group by agent, model
38
+ or project. It shows when usage was last seen and whether scan evidence is fresh. If an
39
+ improvement store exists, the page links to its private report card. Use
40
+ `aut overview --no-browser` to get the local URL and Ctrl-C to close the page.
41
+ Quota appears after a [local capture](quota.md). The overview reads the cache for each page
42
+ request and shows freshness, the reset time and any supported pace estimate.
43
+
44
+ Use `aut improve inspect --case CASE_ID` to review the private context for a saved case.
45
+ The view links text sizes, exact repeat reads and observed compactions to their frozen events.
46
+ Captured text sizes use UTF-8 bytes and can be clipped. Actual model context tokens are unknown.
47
+
48
+ ## Export usage and compare models
49
+
50
+ ```sh
51
+ aut --agents claude_code,codex,cursor_cli,pi export --out usage.csv
52
+ aut summary --period week --group-by model
53
+ aut summary --since 2026-06-01 --until 2026-07-01 --group-by project --json
54
+ ```
55
+
56
+ Local export needs neither a config file nor a database. Cursor CLI contributes prompt rows. For Cursor
57
+ token counts, choose one source from the [collector reference](reference.md#collectors).
58
+ An unreadable source makes export exit nonzero. Check the exit code before treating a CSV as complete.
59
+
60
+ Dates use the configured ledger time zone. The end date is exclusive. JSON reports unknown counts as
61
+ `null` and lists records with missing values in `unknown_events`. Project summaries can contain names.
62
+
63
+ `aut sync-prices` refreshes local API list rates. The summary shows the known estimated subtotal, the
64
+ total estimate when coverage allows it, and any costs recorded in the logs.
65
+ Use `aut summary --compare-prices MODEL_A MODEL_B` to price the same observed token mix at two rates.
66
+
67
+ Use `aut statusline` for cached quota, reset times, and scan freshness. See the [quota guide](quota.md)
68
+ for Claude Code statusline input and optional local notices.
69
+
70
+ ## Keep history in your own database
71
+
72
+ Install the PostgreSQL extra:
73
+
74
+ ```bash
75
+ uv tool install "agent-usage-tracker[postgres]"
76
+ ```
77
+
78
+ Create `~/.config/agent-usage-tracker/config.toml` with your machine label and database connection:
79
+
80
+ ```toml
81
+ machine = "laptop"
82
+ agents = ["claude_code", "codex", "cursor_cli", "pi"]
83
+
84
+ [transport]
85
+ pg_dsn = "env:AUT_PG_DSN"
86
+ ```
87
+
88
+ Set `AUT_PG_DSN` to your provisioned database connection.
89
+ The database needs AUT's tables and views. The [sink stack](../src/agent_usage_tracker/sink_stack/README.md) provides them with one `docker compose up`;
90
+ the [deploy runbook](../DEPLOY.md) describes the sink contract.
91
+ Set `ledger_timezone` to the sink's `AUT_TZ`.
92
+ On macOS and Linux, protect the configuration with `chmod 600`.
93
+ On Windows, restrict its directory permissions to your account.
94
+
95
+ ```bash
96
+ aut status
97
+ aut scan --dry-run
98
+ aut scan
99
+ ```
100
+
101
+ The dry run parses logs and reports totals without sending rows.
102
+ Real scans advance their watermark only after delivery succeeds.
103
+ Repeated delivery is safe because the sink deduplicates event IDs.
104
+ Native JSONL collection drains a finite file snapshot, including all capped chunks present when each file is admitted.
105
+ Later appends, new files and replaced files wait for the next run.
106
+ On POSIX, acknowledged closed Cursor CLI stores skip SQLite reads while database and WAL metadata stay unchanged.
107
+
108
+ Webhook-only scans keep session, activity, and time rows in a private local delivery queue.
109
+ `aut status` shows pending rows. After configuring PostgreSQL, scans replay them automatically;
110
+ `aut retry-delivery` also retries the queue directly. Keep the state directory in your backups.
111
+
112
+ For a full configuration, start from [`config.example.toml`](../config.example.toml).
113
+ Put secrets in your local configuration or environment, never in this repository.
114
+ Scheduled jobs do not inherit your shell environment; configure their secrets separately.
115
+
116
+ See the [configuration reference](reference.md#configuration) for default paths. Keep the same
117
+ `repo_key_salt` across machines when you want their repository identities to match. Back up that salt.
118
+
119
+ ## Schedule delivery to your own sink
120
+
121
+ Set the transport in your local config. The scheduled job needs access to any environment
122
+ variables that the config names. AUT leaves credentials out of scheduler entries. Use a stable
123
+ `aut` executable, such as one from `uv tool install agent-usage-tracker`.
124
+
125
+ ```sh
126
+ aut setup --schedule
127
+ aut setup --apply --schedule
128
+ ```
129
+
130
+ The first command previews. The second enables a per-user scan timer, which can start a scan
131
+ as soon as the scheduler loads it. It uses launchd on macOS, a systemd user timer on Linux,
132
+ and a scheduled task for the current interactive user on Windows. It keeps existing config and
133
+ refuses to replace a schedule created outside guided setup. On macOS the scheduled logs are
134
+ under `~/Library/Logs`. Linux uses the user journal and Windows uses Task Scheduler history.
135
+
136
+ On Windows, setup uses a process-local execution policy for the packaged script. Group Policy
137
+ can still block it. Use Task Scheduler to run `aut scan` if your administrator permits it.
138
+
139
+ The guided timer uses the default AUT config and state paths. For a custom setup, an existing
140
+ manual timer, or a system without a supported user scheduler, see
141
+ [the scheduler templates](../packaging/README.md). Use `aut summary` for local reporting on demand.
142
+
143
+ `aut setup --uninstall` removes only the scan entry created by guided setup. It keeps config,
144
+ scan state and logs. It can remove the managed entry when the config is unreadable.
145
+ Custom daily jobs and manual scan timers have their own removal procedures.