argus-code 0.2.0__tar.gz → 0.3.1__tar.gz

{argus_code-0.2.0 → argus_code-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: argus-code
-Version: 0.2.0
+Version: 0.3.1
 Summary: Local-first dashboard for Claude Code cost, token, tool-usage, and full-text search analytics
 Project-URL: Homepage, https://github.com/KrishBhimani/argus-code
 Project-URL: Repository, https://github.com/KrishBhimani/argus-code.git
@@ -106,11 +106,68 @@ argus                                   # top-level command group
 │     ├─ list                           # list templates (bundled + user)
 │     └─ create <name> [--path <dir>] [--all]
 │                                       # save a project's .claude/ as a template
+├─ daemon                               # argusd — background ingestion + detectors
+│  ├─ start                             # start argusd detached, write PID file
+│  ├─ stop                              # stop argusd gracefully
+│  ├─ restart                           # stop then start
+│  ├─ status                            # running? PID + uptime
+│  └─ logs [-n N] [-f]                  # tail ~/.argus/argusd.log
 └─ wipe                                 # delete ~/.argus/ entirely
 ```
 
 Run `--help` at any level for details — `argus --help`, `argus claude --help`,
-`argus claude template --help`.
+`argus claude template --help`, `argus daemon --help`.
+
+### `argus daemon` — background daemon (argusd)
+
+By default the watcher and the detector scheduler run *inside* `argus start` —
+close the dashboard and ingestion stops. `argusd` moves that work into a
+long-running background process so your data stays fresh and detectors keep
+running whether or not the dashboard is open. It does **not** serve the
+dashboard (port 4242 is still only bound by `argus start`).
+
+```sh
+argus daemon start      # run argusd in the background
+argus daemon status     # PID + uptime
+argus daemon logs -f    # follow the log (survives rotation)
+argus daemon stop
+```
+
+> **Autostart at login is coming separately.** For now, start argusd yourself
+> with `argus daemon start` (it survives closing the terminal). OS-native
+> autostart (`argus install` / `argus uninstall`) lands in a follow-up.
+
+**Coexistence.** When argusd is running, `argus start` notices its PID file and
+becomes a **read-only dashboard** — it skips its own watcher/scheduler and just
+views the database the daemon keeps fresh (the footer shows *"Powered by
+argusd"*). When argusd is **not** running, `argus start` ingests in-process
+exactly as before, so users who never touch the daemon see no change.
+
+> **Known limitation (v1):** if argusd dies while a read-only dashboard is open,
+> the footer keeps showing *"Powered by argusd"* and ingestion pauses until you
+> restart the dashboard (which then resumes ingesting in-process). The dashboard
+> does not re-check daemon liveness on every poll.
+
+**Running it long-term.** argusd is designed to stay up. Its idle cost is
+negligible — the watcher is event-driven (sleeps until a `~/.claude` file
+changes) and the detector scheduler wakes once every 10 minutes; expect ~40–70
+MB RAM and effectively no idle CPU. The log is capped at ~4 MB (1 MB × 3
+rotations). A few habits worth knowing:
+
+- **Restart after upgrading argus.** A running daemon holds the old code in
+  memory — run `argus daemon restart` after `uv sync` / `pip install -U` to pick
+  up changes.
+- **No auto-restart yet.** A daemon started with `argus daemon start` that
+  crashes stays down until you start it again (the stale PID file is cleaned up
+  automatically). OS-supervised restart arrives with autostart in a follow-up.
+- **Windows stop is a hard kill.** `argus daemon stop` terminates the process
+  directly on Windows, so no `argusd stopped.` line is written to the log (the
+  CLI still prints it). This is safe — there's no critical in-memory state.
+- **Toggling search:** the dashboard's "Enable indexing" button indexes
+  immediately; the CLI `argus search enable` only flips the flag and defers the
+  backfill to the next `argus start` / `argus daemon restart`.
+
+Logs live at `~/.argus/argusd.log` (plain text, rotated at ~1 MB × 3).
 
 ### `argus claude` — project scaffolding
 
@@ -176,6 +233,12 @@ For vulnerability reports, see [SECURITY.md](./SECURITY.md).
    Overview's "What needs attention" card reads these, and critical findings
    raise a browser notification. The v1 detector flags tools whose error rate
    spiked versus their preceding 4-week baseline.
+7. **Shared runtime + daemon.** The watcher, scheduler, and first-pass ingest
+   are owned by a single `CoreRuntime` that both `argus start` and `argusd`
+   construct. The optional `argusd` daemon (`argus daemon`) runs that runtime in
+   its own process; a live daemon flips `argus start`
+   into a read-only viewer so the two never double-ingest. See **`argus
+   daemon`** above.
 
 ## Configuration
 
@@ -216,7 +279,7 @@ set, Argus's own database keeps the data even after Claude rotates it out.
 git clone https://github.com/KrishBhimani/argus-code.git
 cd argus-code
 uv sync               # install deps + create venv
-uv run pytest         # ~215 tests, ~20s
+uv run pytest         # ~245 tests, ~20s
 uv run argus start    # dev — runs directly from source
 ```
 
@@ -231,6 +294,8 @@ python/argus/         Python ingest, store, server, CLI
   store/              SQLite schema + migrations + repo
   server/             FastAPI app + /api routes
   collector/          watcher + pipeline + first-run + search backfill + alert scheduler
+  core/               CoreRuntime — shared watcher+scheduler+ingest lifecycle
+  daemon/             argusd: pidfile, foreground service, process control, logging
   detectors/          alert detectors (pure reads) + @register registry
   scaffold/           `argus claude` template storage / init / snapshot
   pricing/            LiteLLM-derived price table + cost compute

{argus_code-0.2.0 → argus_code-0.3.1}/README.md

@@ -54,11 +54,68 @@ argus                                   # top-level command group
 │     ├─ list                           # list templates (bundled + user)
 │     └─ create <name> [--path <dir>] [--all]
 │                                       # save a project's .claude/ as a template
+├─ daemon                               # argusd — background ingestion + detectors
+│  ├─ start                             # start argusd detached, write PID file
+│  ├─ stop                              # stop argusd gracefully
+│  ├─ restart                           # stop then start
+│  ├─ status                            # running? PID + uptime
+│  └─ logs [-n N] [-f]                  # tail ~/.argus/argusd.log
 └─ wipe                                 # delete ~/.argus/ entirely
 ```
 
 Run `--help` at any level for details — `argus --help`, `argus claude --help`,
-`argus claude template --help`.
+`argus claude template --help`, `argus daemon --help`.
+
+### `argus daemon` — background daemon (argusd)
+
+By default the watcher and the detector scheduler run *inside* `argus start` —
+close the dashboard and ingestion stops. `argusd` moves that work into a
+long-running background process so your data stays fresh and detectors keep
+running whether or not the dashboard is open. It does **not** serve the
+dashboard (port 4242 is still only bound by `argus start`).
+
+```sh
+argus daemon start      # run argusd in the background
+argus daemon status     # PID + uptime
+argus daemon logs -f    # follow the log (survives rotation)
+argus daemon stop
+```
+
+> **Autostart at login is coming separately.** For now, start argusd yourself
+> with `argus daemon start` (it survives closing the terminal). OS-native
+> autostart (`argus install` / `argus uninstall`) lands in a follow-up.
+
+**Coexistence.** When argusd is running, `argus start` notices its PID file and
+becomes a **read-only dashboard** — it skips its own watcher/scheduler and just
+views the database the daemon keeps fresh (the footer shows *"Powered by
+argusd"*). When argusd is **not** running, `argus start` ingests in-process
+exactly as before, so users who never touch the daemon see no change.
+
+> **Known limitation (v1):** if argusd dies while a read-only dashboard is open,
+> the footer keeps showing *"Powered by argusd"* and ingestion pauses until you
+> restart the dashboard (which then resumes ingesting in-process). The dashboard
+> does not re-check daemon liveness on every poll.
+
+**Running it long-term.** argusd is designed to stay up. Its idle cost is
+negligible — the watcher is event-driven (sleeps until a `~/.claude` file
+changes) and the detector scheduler wakes once every 10 minutes; expect ~40–70
+MB RAM and effectively no idle CPU. The log is capped at ~4 MB (1 MB × 3
+rotations). A few habits worth knowing:
+
+- **Restart after upgrading argus.** A running daemon holds the old code in
+  memory — run `argus daemon restart` after `uv sync` / `pip install -U` to pick
+  up changes.
+- **No auto-restart yet.** A daemon started with `argus daemon start` that
+  crashes stays down until you start it again (the stale PID file is cleaned up
+  automatically). OS-supervised restart arrives with autostart in a follow-up.
+- **Windows stop is a hard kill.** `argus daemon stop` terminates the process
+  directly on Windows, so no `argusd stopped.` line is written to the log (the
+  CLI still prints it). This is safe — there's no critical in-memory state.
+- **Toggling search:** the dashboard's "Enable indexing" button indexes
+  immediately; the CLI `argus search enable` only flips the flag and defers the
+  backfill to the next `argus start` / `argus daemon restart`.
+
+Logs live at `~/.argus/argusd.log` (plain text, rotated at ~1 MB × 3).
 
 ### `argus claude` — project scaffolding
 
@@ -124,6 +181,12 @@ For vulnerability reports, see [SECURITY.md](./SECURITY.md).
    Overview's "What needs attention" card reads these, and critical findings
    raise a browser notification. The v1 detector flags tools whose error rate
    spiked versus their preceding 4-week baseline.
+7. **Shared runtime + daemon.** The watcher, scheduler, and first-pass ingest
+   are owned by a single `CoreRuntime` that both `argus start` and `argusd`
+   construct. The optional `argusd` daemon (`argus daemon`) runs that runtime in
+   its own process; a live daemon flips `argus start`
+   into a read-only viewer so the two never double-ingest. See **`argus
+   daemon`** above.
 
 ## Configuration
 
@@ -164,7 +227,7 @@ set, Argus's own database keeps the data even after Claude rotates it out.
 git clone https://github.com/KrishBhimani/argus-code.git
 cd argus-code
 uv sync               # install deps + create venv
-uv run pytest         # ~215 tests, ~20s
+uv run pytest         # ~245 tests, ~20s
 uv run argus start    # dev — runs directly from source
 ```
 
@@ -179,6 +242,8 @@ python/argus/         Python ingest, store, server, CLI
   store/              SQLite schema + migrations + repo
   server/             FastAPI app + /api routes
   collector/          watcher + pipeline + first-run + search backfill + alert scheduler
+  core/               CoreRuntime — shared watcher+scheduler+ingest lifecycle
+  daemon/             argusd: pidfile, foreground service, process control, logging
   detectors/          alert detectors (pure reads) + @register registry
   scaffold/           `argus claude` template storage / init / snapshot
   pricing/            LiteLLM-derived price table + cost compute

{argus_code-0.2.0 → argus_code-0.3.1}/dashboard/src/layouts/Default.astro

@@ -28,6 +28,7 @@ const path = Astro.url.pathname;
     <span class="status-pill" id="ingest-status">Loading…</span>
     <span style="margin: 0 0.8rem;">·</span>
     <span id="pricing-info">Pricing —</span>
+    <span id="daemon-status" style="margin-left: 0.8rem; display: none;" title="Ingestion is handled by the argusd background daemon">· Powered by argusd ●</span>
   </footer>
   <script>
     async function refresh() {
@@ -56,6 +57,8 @@ const path = Astro.url.pathname;
             ip.classList.add('busy');
           }
         }
+        const ds = document.getElementById('daemon-status');
+        if (ds) ds.style.display = s.daemon === true ? 'inline' : 'none';
       } catch (e) { /* server may not be live yet */ }
     }
     refresh();

{argus_code-0.2.0 → argus_code-0.3.1}/dashboard/src/pages/index.astro

@@ -29,7 +29,7 @@ import Default from '../layouts/Default.astro';
   </div>
 
   <div class="card" style="margin-bottom:1.2rem;">
-    <h3>Cost over time</h3>
+    <h3>Tokens over time</h3>
     <div id="line" class="chart"></div>
   </div>
 
@@ -39,7 +39,7 @@ import Default from '../layouts/Default.astro';
       <div id="heatmap" class="chart"></div>
     </div>
     <div class="card">
-      <h3>Top models by cost (window)</h3>
+      <h3>Top models by tokens (window)</h3>
       <div id="models" class="chart"></div>
     </div>
   </div>
@@ -52,7 +52,7 @@ import Default from '../layouts/Default.astro';
   <script>
     import { api } from '../scripts/api';
     import { usd, tok, num, shortDate, shortPath, escapeHtml } from '../scripts/format';
-    import { lineCost, calendarHeatmap, modelMix } from '../scripts/charts';
+    import { lineTokens, calendarHeatmap, modelMix } from '../scripts/charts';
     import { renderAlertCard, startNotificationPoll } from '../scripts/alerts';
 
     const $ = (s: string) => document.querySelector(s) as HTMLElement;
@@ -71,25 +71,23 @@ import Default from '../layouts/Default.astro';
       $('.hero-tokens')!.textContent = tok(overview.total_tokens);
       $('#hero-cost')!.textContent = usd(overview.total_cost_usd);
       $('#hero-sessions')!.textContent = num(overview.session_count);
-      const avg = overview.session_count ? overview.total_cost_usd / overview.session_count : 0;
-      $('#hero-avg')!.textContent = overview.session_count ? `· ~${usd(avg)} est/session` : '';
+      const avgTok = overview.session_count ? Math.round(overview.total_tokens / overview.session_count) : 0;
+      $('#hero-avg')!.textContent = overview.session_count ? `· ${tok(avgTok)} tok/session` : '';
 
-      const days = Object.entries(overview.cost_by_day).sort().map(([day, cost]) => ({ day, cost: cost as number }));
+      const days = Object.entries(overview.tokens_by_day).sort().map(([day, value]) => ({ day, value: value as number }));
       lineChart?.dispose();
-      if (days.length) lineChart = lineCost($('#line'), days);
-      else $('#line').innerHTML = '<p class="empty">No spend in this window.</p>';
+      if (days.length) lineChart = lineTokens($('#line'), days);
+      else $('#line').innerHTML = '<p class="empty">No activity in this window.</p>';
 
       const allOv = window === 'all' ? overview : await api.overview('all');
-      const allDays = Object.entries(allOv.cost_by_day).sort().map(([day, cost]) => ({ day, cost: cost as number }));
+      const allDays = Object.entries(allOv.tokens_by_day).sort().map(([day, value]) => ({ day, value: value as number }));
       heatChart?.dispose();
       heatChart = calendarHeatmap($('#heatmap'), allDays, 90);
 
-      // Models chart: read cost_by_model from /api/overview (window-bucketed).
-      // Previously summed s.total_cost_usd over inWindow sessions, which dumped
-      // a session's whole-lifetime cost onto whichever model was its primary_model.
-      const modelsList = Object.entries(overview.cost_by_model ?? {})
+      // Models chart: read tokens_by_model from /api/overview (window-bucketed).
+      const modelsList = Object.entries(overview.tokens_by_model ?? {})
         .sort((a, b) => (b[1] as number) - (a[1] as number))
-        .map(([name, cost]) => ({ name, cost: cost as number }));
+        .map(([name, value]) => ({ name, value: value as number }));
       modelsChart?.dispose();
       if (modelsList.length) modelsChart = modelMix($('#models'), modelsList);
       else $('#models').innerHTML = '<p class="empty">No data.</p>';

{argus_code-0.2.0 → argus_code-0.3.1}/dashboard/src/pages/session.astro

@@ -107,7 +107,7 @@ import Default from '../layouts/Default.astro';
 
         root.innerHTML = `
           <div class="grid-cards" style="margin-bottom:1.2rem;">
-            <div class="card kpi"><span class="kpi-label">Tokens</span><span class="kpi-value tokens">${tok(totalTokens)}</span><span class="kpi-sub">${num(totalTokens)} total</span></div>
+            <div class="card kpi"><span class="kpi-label">Tokens</span><span class="kpi-value tokens">${tok(totalTokens)}</span><span class="kpi-sub">${num(totalTokens)} total${subAgents?.length ? ` · incl. ${subAgents.length} sub-agent${subAgents.length === 1 ? '' : 's'}` : ''}</span></div>
             <div class="card kpi"><span class="kpi-label">Cost <span style="color:var(--text-2);font-weight:400;">(est.)</span></span><span class="kpi-value cost">~${usd(s.total_cost_usd)}</span><span class="kpi-sub">${reportedDelta}</span></div>
             <div class="card kpi"><span class="kpi-label">Turns</span><span class="kpi-value">${num(s.turn_count)}</span><span class="kpi-sub">${turns.length} loaded</span></div>
             <div class="card kpi"><span class="kpi-label">Duration</span><span class="kpi-value">${dur(s.duration_sec)}</span><span class="kpi-sub">started ${fmtLocalDateTime(s.started_at)}</span></div>

{argus_code-0.2.0 → argus_code-0.3.1}/dashboard/src/pages/settings.astro

@@ -212,6 +212,17 @@ import Default from '../layouts/Default.astro';
         progress.style.display = 'none';
       }
 
+      // When yielded to a running argusd the API is read-only — write
+      // controls would 409. Show a note instead of buttons that fail.
+      let daemon = false;
+      try {
+        daemon = (await fetch('/api/ingest/status').then(r => r.json())).daemon === true;
+      } catch { /* leave daemon=false */ }
+      if (daemon) {
+        actions.innerHTML = `<span style="color:var(--text-2);font-size:0.82rem;">Read-only while <code>argusd</code> is running — manage indexing from the CLI (<code>argus search enable</code>) or stop the daemon with <code>argus daemon stop</code>.</span>`;
+        return;
+      }
+
       // Action buttons reflect current state. Buttons that are
       // pointless in the current state are simply omitted instead of
       // disabled — fewer affordances to mis-click.

{argus_code-0.2.0 → argus_code-0.3.1}/dashboard/src/scripts/charts.ts

@@ -2,6 +2,7 @@ import * as echarts from 'echarts/core';
 import { LineChart, BarChart, HeatmapChart, PieChart } from 'echarts/charts';
 import { GridComponent, TooltipComponent, TitleComponent, LegendComponent, VisualMapComponent, MarkLineComponent } from 'echarts/components';
 import { CanvasRenderer } from 'echarts/renderers';
+import { tok } from './format';
 
 echarts.use([LineChart, BarChart, HeatmapChart, PieChart, GridComponent, TooltipComponent, TitleComponent, LegendComponent, VisualMapComponent, MarkLineComponent, CanvasRenderer]);
 
@@ -25,16 +26,16 @@ export function makeChart(el: HTMLElement) {
   return echarts.init(el, null, { renderer: 'canvas' });
 }
 
-export function lineCost(el: HTMLElement, days: { day: string; cost: number }[]) {
+export function lineTokens(el: HTMLElement, days: { day: string; value: number }[]) {
   const c = makeChart(el);
   c.setOption({
     ...THEME,
-    tooltip: { ...THEME.tooltip, trigger: 'axis', valueFormatter: (v: number) => '$' + v.toFixed(2) },
+    tooltip: { ...THEME.tooltip, trigger: 'axis', valueFormatter: (v: number) => tok(v) + ' tokens' },
     grid: { left: 50, right: 18, top: 18, bottom: 30 },
     xAxis: { type: 'category', data: days.map(d => d.day.slice(5)), ...AXIS },
-    yAxis: { type: 'value', axisLabel: { ...AXIS.axisLabel, formatter: '${value}' }, splitLine: AXIS.splitLine, axisLine: { show: false } },
+    yAxis: { type: 'value', axisLabel: { ...AXIS.axisLabel, formatter: (v: number) => tok(v) }, splitLine: AXIS.splitLine, axisLine: { show: false } },
     series: [{
-      type: 'line', data: days.map(d => +d.cost.toFixed(4)),
+      type: 'line', data: days.map(d => d.value),
       smooth: true, symbol: 'circle', symbolSize: 5,
       lineStyle: { color: '#f0883e', width: 2 },
       itemStyle: { color: '#f0883e' },
@@ -65,17 +66,17 @@ export function agentSplit(el: HTMLElement, split: Record<string, { cost: number
   return c;
 }
 
-export function modelMix(el: HTMLElement, models: { name: string; cost: number }[]) {
+export function modelMix(el: HTMLElement, models: { name: string; value: number }[]) {
   const c = makeChart(el);
   const top = models.slice(0, 8);
   c.setOption({
     ...THEME,
-    tooltip: { ...THEME.tooltip, valueFormatter: (v: number) => '$' + v.toFixed(2) },
+    tooltip: { ...THEME.tooltip, valueFormatter: (v: number) => tok(v) + ' tokens' },
     grid: { left: 140, right: 30, top: 8, bottom: 24 },
-    xAxis: { type: 'value', axisLabel: { ...AXIS.axisLabel, formatter: '${value}' }, splitLine: AXIS.splitLine, axisLine: { show: false } },
+    xAxis: { type: 'value', axisLabel: { ...AXIS.axisLabel, formatter: (v: number) => tok(v) }, splitLine: AXIS.splitLine, axisLine: { show: false } },
     yAxis: { type: 'category', data: top.map(m => m.name).reverse(), axisLabel: { ...AXIS.axisLabel, fontSize: 11 }, axisLine: { show: false }, axisTick: { show: false } },
     series: [{
-      type: 'bar', data: top.map(m => +m.cost.toFixed(4)).reverse(),
+      type: 'bar', data: top.map(m => m.value).reverse(),
       itemStyle: { color: '#f0883e', borderRadius: [0, 4, 4, 0] },
       barWidth: '60%',
     }],
@@ -83,9 +84,9 @@ export function modelMix(el: HTMLElement, models: { name: string; cost: number }
   return c;
 }
 
-export function calendarHeatmap(el: HTMLElement, days: { day: string; cost: number }[], lookbackDays = 90) {
+export function calendarHeatmap(el: HTMLElement, days: { day: string; value: number }[], lookbackDays = 90) {
   const c = makeChart(el);
-  const lookup = Object.fromEntries(days.map(d => [d.day, d.cost]));
+  const lookup = Object.fromEntries(days.map(d => [d.day, d.value]));
   // Anchor at UTC midnight so lookup keys align with the API's started_at.slice(0,10)
   // bucketing. Stepping by exactly 86400000 ms from a UTC-midnight anchor is robust against
   // local-timezone hour-of-day skew.
@@ -131,7 +132,7 @@ export function calendarHeatmap(el: HTMLElement, days: { day: string; cost: numb
     // ['Mon','Tue','Wed','Thu','Fri','Sat','Sun']: Sun→6, Mon→0, Tue→1, ..., Sat→5
     const rowIdx = (d.getUTCDay() + 6) % 7;
     const weekIdx = Math.round((monOfWeek(dayMs) - firstWeekMonMs) / (7 * 86_400_000));
-    cells.push([weekIdx, rowIdx, +v.toFixed(4)]);
+    cells.push([weekIdx, rowIdx, v]);
     cellDate.set(`${weekIdx}-${rowIdx}`, key);
   }
   // Total columns spans first calendar week containing oldest day through
@@ -146,7 +147,7 @@ export function calendarHeatmap(el: HTMLElement, days: { day: string; cost: numb
         const dow = p.data[1];
         const v = p.data[2];
         const key = cellDate.get(`${wk}-${dow}`) ?? '';
-        return `${key}<br>${v > 0 ? '~$' + v.toFixed(2) : '<span style="color:#6b7585;">no activity</span>'}`;
+        return `${key}<br>${v > 0 ? tok(v) + ' tokens' : '<span style="color:#6b7585;">no activity</span>'}`;
       },
     },
     grid: { left: 30, right: 10, top: 8, bottom: 22 },
@@ -162,7 +163,7 @@ export function calendarHeatmap(el: HTMLElement, days: { day: string; cost: numb
       splitArea: { show: false },
     },
     visualMap: {
-      min: 0, max: Math.max(0.01, max),
+      min: 0, max: Math.max(1, max),
       calculable: true, orient: 'horizontal', left: 'center', bottom: 0,
       inRange: { color: ['#1c222d', '#7a3e1e', '#c2622e', '#f0883e'] },
       textStyle: { color: '#6b7585', fontSize: 10 },