argus-code 0.2.0__py3-none-any.whl

argus/templates/default/.claude/agents/code-reviewer.md

@@ -0,0 +1,27 @@
+---
+name: Code Reviewer
+description: Use when you need a thorough code review. Checks correctness, security, performance, and test coverage. Invoke for any non-trivial diff before merging.
+tools: Read, Grep, Glob, Bash
+---
+
+You are a senior engineer doing a thorough code review.
+
+## Behavior
+- Be direct and specific — point to exact lines
+- Explain *why* something is wrong, not just that it is
+- Distinguish: blocking issues vs suggestions vs nitpicks
+- Praise good patterns when you see them — not just criticism
+
+## Focus areas
+1. Correctness — does it do what it claims?
+2. Security — any injection, auth bypass, data exposure?
+3. Performance — any obvious bottlenecks?
+4. Maintainability — will the next developer understand this?
+5. Test coverage — are edge cases handled?
+
+## Output format
+```
+[BLOCKING] path/to/file.ts:42 — Token is logged in plaintext. Remove or mask before logging.
+[SUGGESTION] path/to/file.ts:88 — Extract this into a named function for readability.
+[NITPICK] path/to/file.ts:101 — Prefer `const` here.
+```

argus/templates/default/.claude/agents/security-auditor.md

@@ -0,0 +1,28 @@
+---
+name: Security Auditor
+description: Use when you need a dedicated security audit. Checks for OWASP top 10, injection flaws, auth issues, secrets in code, and insecure dependencies. Invoke before any security-sensitive release.
+tools: Read, Grep, Glob, Bash
+---
+
+You are a security engineer auditing code for vulnerabilities.
+
+## Behavior
+- Assume hostile input at every boundary
+- Flag anything suspicious even if not confirmed vulnerable
+- Reference OWASP categories where relevant
+- Never suggest security theater — only real mitigations
+
+## What to look for
+- Injection: SQL, command, LDAP, XPath
+- Auth issues: missing checks, insecure token handling, weak sessions
+- Sensitive data: secrets in code/logs, unencrypted storage
+- Insecure dependencies: known CVEs
+- Input validation: missing sanitization, unchecked file uploads
+- CORS/CSP misconfigurations
+
+## Output format
+```
+[CRITICAL] src/db.ts:14 — Raw user input interpolated into SQL query. Use parameterized queries.
+[HIGH] src/auth.ts:88 — JWT secret hardcoded. Move to environment variable.
+[MEDIUM] src/upload.ts:32 — File extension not validated. Restrict to allowed types.
+```

argus/templates/default/.claude/commands/commit.md

@@ -0,0 +1,38 @@
+---
+description: Stage and commit current changes
+---
+
+Stage and commit the current changes.
+
+## Steps
+1. Run `git status` — understand what changed
+2. Run `git diff` — read the actual changes
+3. Stage relevant files by name (never `git add -A` blindly)
+4. Write the commit message following the rules below
+5. Commit
+
+## Commit message rules
+- One sentence, imperative mood ("Add X", "Fix Y", "Remove Z")
+- Focus on the *why* or *what*, not the mechanics
+- No `Co-Authored-By` lines
+- No AI attribution ("Generated by", "Claude", etc.)
+- No trailing blank lines or extra metadata
+
+## Format
+Subject only when self-explanatory:
+```
+Add rate limiting to the auth endpoint
+```
+
+Subject + body when context is non-obvious:
+```
+Switch session store from memory to Redis
+
+Memory store resets on every deploy, logging out all active users.
+```
+
+## What NOT to do
+- No "Updated files" or "Made changes"
+- No listing every file touched
+- No referencing the task/ticket in the subject (put it in body if needed)
+- No co-author or AI attribution lines

argus/templates/default/.claude/commands/deploy.md

@@ -0,0 +1,13 @@
+---
+description: Run pre-deploy checklist before shipping
+---
+
+Prepare this branch for deployment.
+
+Run in order:
+1. `npm run lint` — fix any errors before continuing
+2. `npm test` — all tests must pass
+3. `npm run build` — build must succeed
+4. Summarize what's being deployed and flag anything risky
+
+Do not proceed past any failing step. Report the failure clearly.

argus/templates/default/.claude/commands/fix-issue.md

@@ -0,0 +1,15 @@
+---
+description: Fix a GitHub issue
+argument-hint: <issue-url-or-number>
+---
+
+Fix the GitHub issue described below.
+
+Steps:
+1. Read the issue carefully
+2. Find the relevant code
+3. Understand root cause before writing any fix
+4. Write the fix with a test that would have caught the bug
+5. Summarize what was wrong and what changed
+
+Issue: $ARGUMENTS

argus/templates/default/.claude/commands/pr.md

@@ -0,0 +1,38 @@
+---
+description: Create a pull request for the current branch
+---
+
+Create a pull request for the current branch.
+
+## Steps
+1. Run `git log main..HEAD` — understand what commits are included
+2. Run `git diff main..HEAD` — read all the changes
+3. Draft a PR title (under 70 characters, imperative mood)
+4. Write a PR body with:
+   - **What** changed and **why**
+   - Any important implementation decisions
+   - How to test it manually
+5. Run `gh pr create` with the title and body
+
+## PR title rules
+- Imperative mood: "Add X", "Fix Y", "Remove Z"
+- Under 70 characters
+- No issue numbers in the title (put them in the body)
+
+## PR body format
+```
+## What
+[1-3 sentences on what changed]
+
+## Why
+[The motivation — bug, feature request, tech debt]
+
+## Test plan
+- [ ] [Manual step to verify it works]
+- [ ] [Edge case to check]
+```
+
+## What NOT to do
+- No AI attribution in the PR body
+- No listing every file changed
+- No "as per your request" or similar filler

argus/templates/default/.claude/commands/review.md

@@ -0,0 +1,14 @@
+---
+description: Review staged changes before committing
+---
+
+Review the staged changes before I commit.
+
+Check for:
+- Bugs or logic errors
+- Security issues (injection, exposed secrets, unsafe input handling)
+- Missing edge cases
+- Code style inconsistencies with the rest of the project
+- Anything that should be tested but isn't
+
+Be specific. Point to line numbers. Don't summarize what the code does — I can read it.

argus/templates/default/.claude/rules/api-conventions.md

@@ -0,0 +1,27 @@
+# API Conventions
+
+<!-- Customize for your API style -->
+
+## REST
+- Plural nouns for resources: `/users`, `/posts`
+- HTTP verbs correctly: GET (read), POST (create), PUT (replace), PATCH (update), DELETE
+- 200 for success, 201 for created, 400 for bad input, 401 for unauth, 404 for not found, 500 for server error
+- Always return JSON, even for errors
+
+## Error responses
+```json
+{
+  "error": {
+    "code": "USER_NOT_FOUND",
+    "message": "No user with id 123"
+  }
+}
+```
+
+## Versioning
+- Version in URL path: `/v1/users`
+- Never break existing endpoints — add new ones instead
+
+## Auth
+- Bearer token in `Authorization` header
+- Never log tokens or passwords

argus/templates/default/.claude/rules/code-style.md

@@ -0,0 +1,25 @@
+# Code Style
+
+<!-- Customize these rules to match your project -->
+
+## General
+- Prefer explicit variable names over short ones
+- No magic numbers — use named constants
+- Max function length: ~40 lines. If longer, split it.
+- Delete dead code instead of commenting it out
+
+## TypeScript / JavaScript
+- `const` over `let`, never `var`
+- Arrow functions for callbacks
+- Async/await over `.then()` chains
+- No `any` types without a comment explaining why
+
+## Python
+- Type hints on all function signatures
+- f-strings over `.format()` or `%`
+- `pathlib` over `os.path`
+
+## CSS
+- BEM naming for class names
+- Variables in `:root` for all colors and spacing tokens
+- Mobile-first media queries

argus/templates/default/.claude/rules/testing.md

@@ -0,0 +1,19 @@
+# Testing
+
+## Rules
+- Every bug fix needs a test that would have caught it
+- Test behavior, not implementation details
+- One assertion per test where possible
+- Test names describe the scenario: `it('returns null when user not found')`
+
+## Structure
+- Unit tests live next to the code: `foo.ts` → `foo.test.ts`
+- Integration tests in `tests/integration/`
+- No mocking internal modules — only mock at system boundaries (HTTP, DB, filesystem)
+
+## Commands
+```bash
+npm test              # run all tests
+npm test -- --watch   # watch mode
+npm test -- --coverage
+```

argus/templates/default/.claude/settings.json

@@ -0,0 +1,28 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run *)",
+      "Bash(npx *)",
+      "Bash(node *)",
+      "Bash(git status)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git add *)",
+      "Bash(git commit*)",
+      "Bash(git branch*)",
+      "Bash(git checkout *)",
+      "Bash(git stash*)",
+      "Bash(ls *)",
+      "Bash(cat *)",
+      "Bash(echo *)"
+    ],
+    "deny": [
+      "Bash(rm -rf *)",
+      "Bash(git push --force*)",
+      "Bash(git reset --hard*)",
+      "Bash(chmod 777 *)",
+      "Bash(curl * | bash)",
+      "Bash(wget * | bash)"
+    ]
+  }
+}

argus/templates/default/.claude/skills/example/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: example
+description: Placeholder skill — replace with your own. Shows the .claude/skills/ layout.
+---
+
+# Example Skill
+
+This placeholder exists so the `skills/` directory ships reliably (empty
+directories don't survive packaging). Replace it with a real skill: set a
+clear `name` and `description` in the frontmatter above, then write the
+instructions Claude should follow when the skill is invoked.

argus/templates/default/CLAUDE.md

@@ -0,0 +1,57 @@
+# Project
+
+<!-- Replace with a 2-3 sentence description of your project -->
+A [type] application that [does what] for [who].
+Built with [stack]. Deployed on [platform].
+
+## Stack
+
+<!-- List your main technologies -->
+- Language:
+- Framework:
+- Database:
+- Hosting:
+
+## Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Run dev server
+npm run dev
+
+# Run tests
+npm test
+
+# Build for production
+npm run build
+
+# Lint
+npm run lint
+```
+
+## Project structure
+
+<!-- How this repo is organized -->
+- `src/` — application source
+- `tests/` — test files
+- `docs/` — documentation
+
+## Rules
+
+<!-- Non-obvious constraints Claude must follow -->
+- Follow existing code style — don't introduce new patterns without discussion
+- Write tests for all new functionality
+- Never modify generated files
+- Prefer explicit over clever
+
+## Important context
+
+<!-- Anything Claude needs to know that isn't obvious from the code -->
+- 
+
+## What NOT to do
+
+<!-- Guard rails — common mistakes to avoid in this codebase -->
+- 

argus_code-0.2.0.dist-info/METADATA

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: argus-code
+Version: 0.2.0
+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
+Project-URL: Issues, https://github.com/KrishBhimani/argus-code/issues
+Author: Krish Bhimani
+License: MIT License
+        
+        Copyright (c) 2026 Krish Bhimani
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+License-File: NOTICE
+Keywords: ai-tools,analytics,anthropic,claude,claude-code,cli,cost,dashboard,llm,local-first,tokens,usage
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.9
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn[standard]>=0.32
+Requires-Dist: watchdog>=5.0
+Description-Content-Type: text/markdown
+
+# Argus
+
+**Local-first analytics + persistent archive for Claude Code.** Argus reads
+your `~/.claude/` session logs, computes cost from a bundled pricing table,
+and serves a dashboard at `http://localhost:4242` that tells you exactly how,
+when, and how much you've been using Claude Code.
+
+Claude Code rotates its own session files (`cleanupPeriodDays` defaults to
+30). Once Argus ingests a session into `~/.argus/argus.db`, the row stays
+forever — so a few months in, Argus knows about sessions Claude has already
+deleted. Live tools like `ccusage` can only show what's currently on disk;
+Argus accumulates.
+
+Everything stays on your machine. No telemetry, no API calls, no
+embeddings — just SQLite and a static web UI.
+
+```sh
+pipx install argus-code     # or:  uv tool install argus-code
+argus start
+```
+
+That's it. Your default browser opens to the dashboard once the first-pass
+ingest finishes (~5–10s for a typical install).
+
+## What it shows you
+
+| Page | What it answers |
+|---|---|
+| **Overview** | How many tokens have I burned? How much would I have paid on the API? Where does my spend land each day? Plus a **"What needs attention"** card that surfaces detector findings (e.g. a tool whose error rate spiked this week). |
+| **Sessions** | Sortable table of every session — project, model, tokens, cost, duration. Click any row to drill in. |
+| **Tools** | Tool-call leaderboard (Bash vs Edit vs Read vs WebFetch…), error rates per tool, MCP server breakdown, sub-agent invocations. |
+| **Search** *(opt-in)* | Full-text search over every prompt you've typed AND every assistant response, your replies, and tool output. SQLite FTS5, sub-millisecond, no embeddings. |
+| **Trends** | Tokens and cost bucketed by day / week / month, grouped by model. |
+| **Models** | Per-model token mix and cost rollup. |
+| **Settings** | Search-indexing toggle, pricing version, parse errors, data export. |
+
+## CLI
+
+```sh
+argus                                   # top-level command group
+├─ start [--port 4242] [--host 127.0.0.1] [--data-dir <path>]
+│                                       # watcher + ingester + dashboard server
+├─ pricing
+│  └─ refresh                           # pull latest model prices from LiteLLM
+├─ search
+│  ├─ status                            # is transcript indexing on?
+│  ├─ enable                            # turn it on (next start backfills)
+│  ├─ disable                           # turn it off, keep data
+│  └─ clear                             # wipe all indexed segments + disable
+├─ claude                               # scaffold & manage .claude/ setups
+│  ├─ init [path] [--template <name>] [--force]
+│  │                                    # stamp CLAUDE.md + .claude/ into a project
+│  └─ template
+│     ├─ list                           # list templates (bundled + user)
+│     └─ create <name> [--path <dir>] [--all]
+│                                       # save a project's .claude/ as a template
+└─ wipe                                 # delete ~/.argus/ entirely
+```
+
+Run `--help` at any level for details — `argus --help`, `argus claude --help`,
+`argus claude template --help`.
+
+### `argus claude` — project scaffolding
+
+Set good agent config *before* you run, not just observe it after. `init`
+copies a template into a project: `CLAUDE.md` goes to the project root,
+everything else into `.claude/`. Existing files are skipped (use `--force`
+to overwrite) — but an existing `CLAUDE.md` is **never** overwritten, even
+with `--force`. The bundled `default` template ships a sensible
+`settings.json`, agents, commands, rules, and a placeholder skill. Save your
+own project's setup as a reusable template with `template create`; user
+templates live in `~/.argus/templates/` and take precedence over bundled ones.
+
+## Privacy & security
+
+Argus is built for one user on one machine. The defaults reflect that:
+
+- **Server binds to `127.0.0.1` only.** Nothing on your LAN/Wi-Fi/VPN can
+  reach the dashboard. Use `argus start --host 0.0.0.0` if you really
+  want LAN exposure — it prints a loud warning when you do.
+- **No external requests, ever**, except `argus pricing refresh` which
+  is a manual command that fetches one JSON file from LiteLLM's GitHub.
+  No telemetry, no analytics pings, no LLM calls.
+- **Transcript indexing is opt-in.** Cost-and-token analytics work out of
+  the box without indexing any text content. Full-text search across
+  prompts and transcripts requires explicit opt-in via Settings or
+  `argus search enable`. Opting out actually means out — the API
+  returns empty results, even if data is on disk.
+- **Cross-origin POSTs are rejected.** The state-changing endpoints
+  (`/api/search-index/*`) check the `Origin` header so a random tab in
+  your browser can't silently wipe your data while argus is running.
+- **No embeddings, no model weights.** Search uses SQLite FTS5 — pure
+  inverted-index lexical search. Lookups are deterministic and offline.
+
+Data lives at `~/.argus/argus.db`. Delete it any time with `argus wipe`
+(or just remove the file).
+
+For vulnerability reports, see [SECURITY.md](./SECURITY.md).
+
+## How it works
+
+1. **Ingest.** A `watchdog` observer tails every `~/.claude/projects/<project>/<session-id>.jsonl`
+   file. Lines are validated with `pydantic`, deduplicated by `message.id`,
+   and turned into normalized session/turn rows in SQLite (WAL mode).
+2. **Cost.** Per-turn cost comes from a bundled `pricing/<version>.json`
+   table sourced from [LiteLLM](https://github.com/BerriAI/litellm).
+   Tokens are exact; costs are estimates and the dashboard says so.
+3. **Tools.** Each `tool_use` block in the JSONL becomes a row in
+   `tool_calls`. Errors come from matching `tool_result.is_error` in the
+   next user message. MCP servers are extracted from tool names matching
+   `mcp__<server>__<tool>`.
+4. **Search (opt-in).** Two FTS5 virtual tables: one over `~/.claude/history.jsonl`
+   (every prompt you've ever typed, ~150 KB indexed for a heavy user),
+   one over assistant text + thinking blocks + user content + tool
+   output (~30–60 MB for hundreds of sessions). Indexing happens
+   incrementally during the normal ingest tick.
+5. **Dashboard.** Astro 5 + ECharts, statically built, served by the
+   FastAPI app (uvicorn). No server-side rendering, no Node code in the browser.
+6. **Detection (alerts).** A lightweight scheduler thread runs registered
+   *detectors* on a fixed cadence. Each detector reads the DB and returns
+   findings; the scheduler is the sole writer, upserting them into an
+   `alerts` table — idempotent, with a `resolved_at` lifecycle so an issue
+   that recovers then recurs fires again instead of staying silent. The
+   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.
+
+## Configuration
+
+| Where | Knob |
+|---|---|
+| `argus start --port <n>` | Pick a different port (default 4242). |
+| `argus start --host <h>` | Bind host (default `127.0.0.1`). Pass `0.0.0.0` for LAN exposure. |
+| `argus start --data-dir <path>` | Override `~/.argus/`. |
+| `pricing/*.json` | Bundled price tables. Refresh with `argus pricing refresh`. |
+
+## Requirements
+
+- **Python ≥ 3.11.** Argus uses the stdlib `sqlite3` module — make sure
+  your Python was built with FTS5 (the standard CPython distributions
+  for macOS, Linux, and Windows all are). Argus checks at startup and
+  fails with a clear error if FTS5 is missing.
+- A `~/.claude/` directory containing real session JSONL — i.e. you've
+  used Claude Code at least once. Argus exits with a friendly message
+  if it's missing.
+
+## Keep your history longer
+
+By default Claude Code deletes session files after 30 days. To extend the
+window, set `cleanupPeriodDays` in `~/.claude/settings.json`:
+
+```json
+{
+  "cleanupPeriodDays": 365
+}
+```
+
+The minimum is 1; there's no way to disable cleanup entirely. Whatever you
+set, Argus's own database keeps the data even after Claude rotates it out.
+
+## Development
+
+```sh
+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 argus start    # dev — runs directly from source
+```
+
+The dashboard is an Astro project under `dashboard/` and still builds via
+`npm` at release time only. End users never touch npm.
+
+Source layout:
+
+```
+python/argus/         Python ingest, store, server, CLI
+  adapters/           Claude Code JSONL parsers + adapter registry
+  store/              SQLite schema + migrations + repo
+  server/             FastAPI app + /api routes
+  collector/          watcher + pipeline + first-run + search backfill + alert scheduler
+  detectors/          alert detectors (pure reads) + @register registry
+  scaffold/           `argus claude` template storage / init / snapshot
+  pricing/            LiteLLM-derived price table + cost compute
+  schema/             pydantic data models
+dashboard/            Astro source
+dashboard-dist/       Astro build output (shipped in wheel as data)
+pricing/              Bundled pricing JSON (shipped in wheel as data)
+templates/            Bundled .claude/ scaffolding templates (shipped in wheel as data)
+tests/                pytest suite, mirrors python/argus/ layout
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).