feat: add project attribution

Author: douglasmonsky

AGENTS.md

@@ -59,6 +59,7 @@ codex-usage-tracker dashboard --output /tmp/codex-usage-dashboard.html
 codex-usage-tracker serve-dashboard --help
 codex-usage-tracker init-allowance --output /tmp/codex-usage-allowance.json
 codex-usage-tracker init-thresholds --output /tmp/codex-usage-thresholds.json
+codex-usage-tracker init-projects --output /tmp/codex-usage-projects.json
 codex-usage-tracker support-bundle --output /tmp/codex-usage-support.json
 codex-usage-tracker pricing-coverage
 codex-usage-tracker summary --preset by-subagent-role

README.md

@@ -30,7 +30,7 @@ Use this when you want to answer questions like:
 - Do long-running chats get more expensive over time?
 - Are subagents, auto-reviews, or review passes attached to the right parent work?
 - Which calls have low cache reuse, high context-window pressure, or large reasoning output?
-- Which active project directories are consuming the most usage?
+- Which projects, project tags, or active directories are consuming the most usage?
 - Did a change in workflow, model choice, or reasoning mode improve efficiency?
 
 The dashboard is intentionally split into three views:
@@ -241,6 +241,8 @@ Show a summary:
 
 ```bash
 codex-usage-tracker summary --group-by model
+codex-usage-tracker summary --group-by project
+codex-usage-tracker summary --group-by project_tag
 codex-usage-tracker summary --group-by thread --limit 20
 codex-usage-tracker summary --preset today
 codex-usage-tracker summary --preset last-7-days
@@ -303,6 +305,14 @@ codex-usage-tracker init-thresholds
 
 Edit `~/.codex-usage-tracker/thresholds.json` to adjust the aggregate-only thresholds used for low cache reuse, high context pressure, high uncached input, large cumulative threads, reasoning-output spikes, large low-output calls, and high estimated cost. The dashboard uses these values for presets, insight cards, row recommendations, and thread lifecycle summaries.
 
+Enable optional project aliases, ignored paths, and tags:
+
+```bash
+codex-usage-tracker init-projects
+```
+
+Edit `~/.codex-usage-tracker/projects.json` to map stable project hashes, repo roots, or project names to friendlier aliases, ignored paths, and tags. The tracker derives project identity from `cwd` and local Git metadata when available: repo root, repo name, current branch, and a hashed remote origin. It does not store or display the full remote URL.
+
 Credit usage estimates are calculated from Codex's aggregate input, cached-input, and output token counters using the bundled OpenAI Codex rate-card snapshot from `https://help.openai.com/en/articles/20001106-codex-rate-card` and `https://developers.openai.com/codex/pricing`. Direct model matches are marked exact. Local aliases and inferred labels, such as code-review usage mapped to GPT-5.3-Codex, are marked estimated. Normal reports do not contact the network for allowance or credit estimates.
 
 ### Usage And Allowance Accuracy

docs/dashboard-guide.md

@@ -22,6 +22,8 @@ codex-usage-tracker init-allowance
 
 To tune review thresholds locally, run `codex-usage-tracker init-thresholds` and edit `~/.codex-usage-tracker/thresholds.json`. These thresholds control low-cache, high-context, high-uncached-input, large-thread, reasoning-spike, low-output, and high-cost recommendations.
 
+To tune project attribution locally, run `codex-usage-tracker init-projects` and edit `~/.codex-usage-tracker/projects.json`. The dashboard derives project name, relative cwd, branch, tags, and a hashed remote origin from aggregate `cwd` and local Git metadata when available.
+
 The server keeps the HTML aggregate-only and enables two live features:
 
 - `Refresh` rescans local Codex logs and updates the dashboard rows.
@@ -59,6 +61,7 @@ Use `Calls` view when you want to inspect individual model calls.
 - The top cards include cached input, uncached input, Codex credit usage, and optional usage remaining instead of estimated-token, unpriced-token, and price-coverage counters.
 - A `Parser warnings` chip appears only when the latest refresh reports skipped token events, missing expected token fields, invalid counters, duplicate cumulative snapshots, or unknown event shapes. Use `codex-usage-tracker inspect-log <path>` to inspect a suspect log without writing to SQLite.
 - Search matches thread, cwd, model, session id, turn id, subagent role, and parent thread fields.
+- Search also matches derived project names, project-relative cwd values, tags, branch names, and redacted remote labels.
 - The cards summarize only the currently visible filtered rows.
 - Time values are shown in your browser's local date/time format while sorting still uses the logged timestamp.
 - Click a column header like `Time`, `Thread`, `Tokens`, `Cost`, or `Cache` to sort. Use the sort menu for `Highest Codex credits`. Click the same header again to reverse the direction.

src/codex_usage_tracker/cli.py

@@ -25,11 +25,13 @@
     DEFAULT_MARKETPLACE_PATH,
     DEFAULT_PLUGIN_LINK,
     DEFAULT_PRICING_PATH,
+    DEFAULT_PROJECTS_PATH,
     DEFAULT_SUPPORT_BUNDLE_PATH,
     DEFAULT_THRESHOLDS_PATH,
 )
 from codex_usage_tracker.parser import inspect_log, load_session_index
 from codex_usage_tracker.plugin_installer import install_plugin, uninstall_plugin
+from codex_usage_tracker.projects import write_project_template
 from codex_usage_tracker.pricing import (
     OPENAI_PRICING_MD_URL,
     VALID_PRICING_TIERS,
@@ -83,6 +85,7 @@ def _build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--pricing", type=Path, default=DEFAULT_PRICING_PATH)
     parser.add_argument("--allowance", type=Path, default=DEFAULT_ALLOWANCE_PATH)
     parser.add_argument("--thresholds", type=Path, default=DEFAULT_THRESHOLDS_PATH)
+    parser.add_argument("--projects", type=Path, default=DEFAULT_PROJECTS_PATH)
     subparsers = parser.add_subparsers(dest="command", required=True)
     _add_setup_parser(subparsers)
     _add_doctor_parser(subparsers)
@@ -103,6 +106,7 @@ def _build_parser() -> argparse.ArgumentParser:
     _add_pricing_parsers(subparsers)
     _add_allowance_parser(subparsers)
     _add_threshold_parser(subparsers)
+    _add_project_parser(subparsers)
     _add_support_bundle_parser(subparsers)
     return parser
 
@@ -403,6 +407,17 @@ def _add_threshold_parser(
     thresholds.add_argument("--force", action="store_true")
 
 
+def _add_project_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    projects = subparsers.add_parser(
+        "init-projects",
+        help="Write a local template for project aliases, ignored paths, and tags",
+    )
+    projects.add_argument("--output", type=Path, default=None)
+    projects.add_argument("--force", action="store_true")
+
+
 def _add_support_bundle_parser(
     subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
 ) -> None:
@@ -609,6 +624,7 @@ def _run_summary(args: argparse.Namespace) -> int:
         preset=args.preset,
         since=args.since,
         limit=args.limit,
+        projects_path=args.projects,
     )
     print(report.render())
     return 0
@@ -640,6 +656,7 @@ def _run_dashboard(args: argparse.Namespace) -> int:
         allowance_path=args.allowance,
         since=args.since,
         thresholds_path=args.thresholds,
+        projects_path=args.projects,
     )
     print(f"Wrote dashboard to {output}")
     if args.open:
@@ -658,6 +675,7 @@ def _run_open_dashboard(args: argparse.Namespace) -> int:
         allowance_path=args.allowance,
         since=args.since,
         thresholds_path=args.thresholds,
+        projects_path=args.projects,
     )
     print(f"Opening dashboard at {output}")
     webbrowser.open(output.resolve().as_uri())
@@ -686,6 +704,7 @@ def _run_serve_dashboard(args: argparse.Namespace) -> int:
         include_archived=args.include_archived,
         context_api="disabled" if args.no_context_api else args.context_api,
         thresholds_path=args.thresholds,
+        projects_path=args.projects,
     )
     return 0
 
@@ -758,6 +777,12 @@ def _run_init_thresholds(args: argparse.Namespace) -> int:
     return 0
 
 
+def _run_init_projects(args: argparse.Namespace) -> int:
+    output = write_project_template(args.output or args.projects, force=args.force)
+    print(f"Wrote project attribution template to {output}")
+    return 0
+
+
 def _run_support_bundle(args: argparse.Namespace) -> int:
     output = build_support_bundle(
         output_path=args.output,
@@ -766,6 +791,7 @@ def _run_support_bundle(args: argparse.Namespace) -> int:
         pricing_path=args.pricing,
         allowance_path=args.allowance,
         thresholds_path=args.thresholds,
+        projects_path=args.projects,
     )
     print(f"Wrote privacy-preserving support bundle to {output}")
     print("Bundle excludes raw logs, prompts, assistant messages, tool output, and context text.")
@@ -795,6 +821,7 @@ def _run_support_bundle(args: argparse.Namespace) -> int:
     "update-pricing": _run_update_pricing,
     "init-allowance": _run_init_allowance,
     "init-thresholds": _run_init_thresholds,
+    "init-projects": _run_init_projects,
     "support-bundle": _run_support_bundle,
 }
 

src/codex_usage_tracker/dashboard.py

@@ -20,9 +20,11 @@
     DEFAULT_ALLOWANCE_PATH,
     DEFAULT_DASHBOARD_PATH,
     DEFAULT_PRICING_PATH,
+    DEFAULT_PROJECTS_PATH,
     DEFAULT_THRESHOLDS_PATH,
 )
 from codex_usage_tracker.pricing import annotate_rows_with_efficiency, load_pricing_config
+from codex_usage_tracker.projects import annotate_rows_with_project_identity, load_project_config
 from codex_usage_tracker.recommendations import (
     annotate_rows_with_recommendations,
     load_threshold_config,
@@ -44,6 +46,7 @@ def dashboard_payload(
     api_token: str | None = None,
     context_api_enabled: bool = False,
     thresholds_path: Path = DEFAULT_THRESHOLDS_PATH,
+    projects_path: Path = DEFAULT_PROJECTS_PATH,
 ) -> dict[str, object]:
     """Return aggregate-only dashboard data without rendering HTML."""
 
@@ -53,11 +56,13 @@ def dashboard_payload(
     pricing = load_pricing_config(pricing_path)
     allowance = load_allowance_config(allowance_path)
     thresholds = load_threshold_config(thresholds_path)
+    projects = load_project_config(projects_path)
     annotated_rows = annotate_rows_with_allowance(
         annotate_rows_with_efficiency(rows, pricing),
         allowance,
     )
     annotated_rows = annotate_rows_with_recommendations(annotated_rows, thresholds)
+    annotated_rows = annotate_rows_with_project_identity(annotated_rows, projects)
     allowance_summary = summarize_allowance_usage(annotated_rows, allowance)
     normalized_limit = _normalize_limit(limit)
     metadata = refresh_metadata(db_path)
@@ -85,6 +90,8 @@ def dashboard_payload(
         "action_thresholds": thresholds.thresholds,
         "thresholds_configured": thresholds.loaded and not thresholds.error,
         "thresholds_error": thresholds.error,
+        "project_configured": projects.loaded and not projects.error,
+        "project_config_error": projects.error,
     }
 
 
@@ -98,6 +105,7 @@ def generate_dashboard(
     api_token: str | None = None,
     context_api_enabled: bool = False,
     thresholds_path: Path = DEFAULT_THRESHOLDS_PATH,
+    projects_path: Path = DEFAULT_PROJECTS_PATH,
 ) -> Path:
     output_path.parent.mkdir(parents=True, exist_ok=True)
     guide_href = _dashboard_guide_href(output_path)
@@ -114,6 +122,7 @@ def generate_dashboard(
             api_token=api_token,
             context_api_enabled=context_api_enabled,
             thresholds_path=thresholds_path,
+            projects_path=projects_path,
         ),
         ensure_ascii=True,
     ).replace("</", "<\\/")

src/codex_usage_tracker/paths.py

@@ -12,6 +12,7 @@
 DEFAULT_PRICING_PATH = APP_DIR / "pricing.json"
 DEFAULT_ALLOWANCE_PATH = APP_DIR / "allowance.json"
 DEFAULT_THRESHOLDS_PATH = APP_DIR / "thresholds.json"
+DEFAULT_PROJECTS_PATH = APP_DIR / "projects.json"
 DEFAULT_CODEX_HOME = Path.home() / ".codex"
 DEFAULT_PLUGIN_LINK = Path.home() / "plugins" / "codex-usage-tracker"
 DEFAULT_MARKETPLACE_PATH = Path.home() / ".agents" / "plugins" / "marketplace.json"

src/codex_usage_tracker/plugin_data/dashboard/dashboard.js

@@ -427,6 +427,11 @@ const initialPayload = JSON.parse(document.getElementById('usage-data').textCont
         const haystack = [
           rowThreadLabel(row),
           row.cwd,
+          row.project_name,
+          row.project_relative_cwd,
+          Array.isArray(row.project_tags) ? row.project_tags.join(' ') : '',
+          row.git_branch,
+          row.git_remote_label,
           row.model,
           row.effort,
           row.session_id,
@@ -1341,6 +1346,8 @@ const initialPayload = JSON.parse(document.getElementById('usage-data').textCont
             <h3>Thread narrative</h3>
             ${fieldsList([
               ['Thread', attachment.label],
+              ['Project', row.project_name || 'Unknown project'],
+              ['Project tags', Array.isArray(row.project_tags) && row.project_tags.length ? row.project_tags.join(', ') : 'None'],
               ['Thread attachment', attachment.relation],
               ['Source', sourceLabel(row)],
               ['Parent thread', resolvedParentThreadName(row) || 'None'],
@@ -1373,6 +1380,10 @@ const initialPayload = JSON.parse(document.getElementById('usage-data').textCont
               ['Parent session', row.parent_session_id || 'None'],
             ['Parent updated', resolvedParentSessionUpdatedAt(row) ? formatTimestamp(resolvedParentSessionUpdatedAt(row)) : 'None'],
             ['Cwd', row.cwd],
+            ['Project cwd', row.project_relative_cwd || '.'],
+            ['Git branch', row.git_branch || 'Unknown'],
+            ['Remote label', row.git_remote_label || 'None'],
+            ['Remote hash', row.git_remote_hash || 'None'],
           ])}
           ${detailCollapse('Source file and line', [
             ['Source line', `${row.source_file}:${row.line_number}`],

src/codex_usage_tracker/plugin_data/docs/dashboard-guide.html

@@ -83,6 +83,7 @@ <h2>Open The Dashboard</h2>
 codex-usage-tracker serve-dashboard --open</code></pre>
     <p>For optional allowance context, run <code>codex-usage-tracker init-allowance</code> and copy current 5-hour or weekly remaining usage from Codex Usage or <code>/status</code> into the local template.</p>
     <p>To tune review thresholds locally, run <code>codex-usage-tracker init-thresholds</code> and edit <code>~/.codex-usage-tracker/thresholds.json</code>. These thresholds control low-cache, high-context, high-uncached-input, large-thread, reasoning-spike, low-output, and high-cost recommendations.</p>
+    <p>To tune project attribution locally, run <code>codex-usage-tracker init-projects</code> and edit <code>~/.codex-usage-tracker/projects.json</code>. The dashboard derives project name, relative cwd, branch, tags, and a hashed remote origin from aggregate <code>cwd</code> and local Git metadata when available.</p>
     <p>The server enables live aggregate refresh and on-demand context loading. Static file mode can still filter, sort, and inspect aggregate fields, but cannot refresh logs or load context.</p>
     <p>The localhost server uses a random per-server token for refresh and context API calls, validates loopback <code>Host</code> and <code>Origin</code> headers, and can run as aggregate-only with <code>codex-usage-tracker serve-dashboard --no-context-api</code>.</p>
 
@@ -104,6 +105,7 @@ <h2>Calls View</h2>
       <li><code>Cached input</code> and <code>Uncached input</code> make cache behavior visible without storing transcript text.</li>
       <li>A cost with <code>*</code> means the pricing row is a marked best-guess estimate.</li>
       <li>Codex credits are estimated from aggregate input, cached-input, and output counters using bundled or locally configured rate-card values.</li>
+      <li>Search matches derived project names, project-relative cwd values, tags, branch names, and redacted remote labels.</li>
       <li><code>Usage Remaining</code> is not read from the logged-in account plan. Configure <code>~/.codex-usage-tracker/allowance.json</code> with values copied from Codex Settings &gt; Usage, the Codex Usage dashboard, or <code>/status</code> when you want current remaining allowance context.</li>
       <li>Call details include a recommended action and a "why flagged" explanation derived only from aggregate counters and pricing/allowance metadata.</li>
       <li>Raw aggregate identifiers and source file metadata are collapsed until you need them.</li>