diff --git a/plans/2026-01-01-usage-tracking-design.md b/plans/2026-01-01-usage-tracking-design.md index cfd2f50..5a6c690 100644 --- a/plans/2026-01-01-usage-tracking-design.md +++ b/plans/2026-01-01-usage-tracking-design.md @@ -1,8 +1,8 @@ # Model Usage & Cost Tracking Design **Date:** 2026-01-01 -**Status:** Approved -**FC Reference:** fc-005 +**Status:** Implemented +**FC Reference:** fc-005 (resolved) ## Overview @@ -187,9 +187,9 @@ Tokens (est): ~125K input, ~42K output ## Implementation Checklist -- [ ] Create `~/.claude/state/usage/config.json` -- [ ] Create `~/.claude/skills/usage/SKILL.md` -- [ ] Create `~/.claude/commands/usage.md` -- [ ] Implement history parsing logic -- [ ] Test with existing session data -- [ ] Update fc-005 status to resolved +- [x] Create `~/.claude/state/usage/config.json` +- [x] Create `~/.claude/skills/usage/SKILL.md` +- [x] Create `~/.claude/commands/usage.md` +- [x] Implement history parsing logic +- [x] Test with existing session data +- [x] Update fc-005 status to resolved diff --git a/state/future-considerations.json b/state/future-considerations.json index 95f6ec8..7fd288f 100644 --- a/state/future-considerations.json +++ b/state/future-considerations.json @@ -1 +1 @@ -{"version":"1.0.0","description":"Deferred features and decisions for future implementation","items":[{"id":"fc-001","category":"infrastructure","title":"Workstation monitoring with Prometheus","description":"Deploy node_exporter and Alertmanager for workstation metrics and alerting","priority":"medium","status":"deferred","created":"2024-12-28","notes":"Would enable proactive alerting for disk, memory, CPU issues"},{"id":"fc-002","category":"agent","title":"Network admin agent","description":"Agent for network configuration, firewall rules, VPN management","priority":"medium","status":"deferred","created":"2024-12-28","notes":"Would manage iptables/nftables, NetworkManager, WireGuard"},{"id":"fc-003","category":"agent","title":"Personal assistant agent","description":"Agent for personal tasks, reminders, scheduling","priority":"medium","status":"deferred","created":"2024-12-28","notes":"Integration with calendar, task management"},{"id":"fc-004","category":"integration","title":"External LLM integration","description":"Support for non-Claude models in the agent system","priority":"low","status":"deferred","created":"2024-12-28","notes":"For specialized tasks or cost optimization"},{"id":"fc-005","category":"optimization","title":"Model usage logging and cost tracking","description":"Track model usage across agents for cost analysis","priority":"medium","status":"deferred","created":"2024-12-28","notes":"Would help optimize model selection policy"},{"id":"fc-006","category":"design","title":"Slash commands redesign","description":"Revisit slash command architecture and user experience","priority":"low","status":"deferred","created":"2024-12-28","notes":"Current design may need refinement"},{"id":"fc-007","category":"optimization","title":"Document structure optimization","description":"Optimize agent document format for efficiency","priority":"low","status":"deferred","created":"2024-12-28","notes":"Balance between clarity and token usage"},{"id":"fc-008","category":"infrastructure","title":"ArgoCD CLI authentication","description":"Configure argocd CLI with proper authentication","priority":"medium","status":"resolved","created":"2025-12-28","resolved":"2025-12-28","notes":"Using 10-year API token (expires 2035-12-26). Token ID: e3980c6a-1c4e-4f1a-8459-a120a5c60cc5. Stored in ~/.config/argocd/config. No renewal automation needed."},{"id":"fc-009","category":"infrastructure","title":"Prometheus local port-forward","description":"Document Prometheus access patterns for agents","priority":"low","status":"identified","created":"2025-12-28","notes":"Prometheus not accessible on localhost:9090. Options: (1) use kubectl exec to query, (2) set up port-forward, (3) use ingress. Currently works via pod exec."},{"id":"fc-010","category":"infrastructure","title":"Clone homelab gitops repo locally","description":"Clone git@github.com:will666/homelab.git for git-operator access","priority":"low","status":"resolved","created":"2025-12-28","resolved":"2025-12-28","notes":"Cloned to ~/.claude/repos/homelab"},{"id":"fc-011","category":"k8s-health","title":"Address OutOfSync ArgoCD apps","description":"5 apps OutOfSync, 1 Degraded (porthole)","priority":"medium","status":"identified","created":"2025-12-28","notes":"OutOfSync: adopt-a-street, ai-stack, gitea, home-assistant, kubernetes-dashboard, speetest-tracker. Degraded: porthole"},{"id":"fc-012","category":"agent-memory","title":"PA knowledge base with session caching","description":"Local KB for infrastructure facts with lazy-load and in-session caching","priority":"medium","status":"resolved","created":"2025-12-28","resolved":"2025-12-28","notes":"Implemented. KB files at state/kb.json (shared) and state/personal-assistant/kb.json (private). PA agent updated with lazy-load behavior."},{"id":"fc-013","category":"agent-memory","title":"Vector database for agent long-term memory","description":"Semantic search over agent knowledge using embeddings","priority":"low","status":"deferred","created":"2025-12-28","notes":"Would enable fuzzy matching, semantic queries, and scalable knowledge storage. Consider: ChromaDB, Qdrant, or pgvector."},{"id":"fc-014","category":"observability","title":"Grafana predefined reports","description":"Slash command like /grafana-report services to get standard metrics from known dashboards","priority":"low","status":"deferred","created":"2025-12-29","notes":"Requires comprehensive dashboard coverage first. Revisit when observability matures."},{"id":"fc-015","category":"observability","title":"Grafana integration in diagnostics","description":"Auto-pull Grafana dashboard data during /k8s:diagnose or health checks","priority":"low","status":"deferred","created":"2025-12-29","notes":"Would make Grafana the first troubleshooting tool. Depends on fc-016 and mature observability setup."},{"id":"fc-016","category":"observability","title":"Extend prometheus-analyst with Grafana API","description":"Add Grafana API query capability to existing prometheus-analyst agent","priority":"low","status":"deferred","created":"2025-12-29","notes":"Preferred approach over creating new agent/skill. Natural extension when dashboards are comprehensive. Prerequisite for fc-014 and fc-015."},{"id":"fc-017","category":"optimization","title":"Subagent spawning for skill delegation","description":"Implement Task tool or similar mechanism to spawn lower-tier models for specific operations","priority":"medium","status":"resolved","created":"2025-12-31","resolved":"2025-12-31","notes":"Implemented via Claude CLI subprocess. Helper at ~/.claude/mcp/delegation/gmail_delegate.py. Uses tiered delegation: fetch/list (no LLM), Sonnet for summarize/triage (via 'claude --print --model sonnet'). Uses subscription, no API key needed."},{"id":"fc-018","category":"gcal","title":"Custom date range query","description":"Support querying arbitrary date ranges like 'jan 2026' or 'next month'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Currently only supports today/tomorrow/week/next. Would need new subcommand or natural language parsing."},{"id":"fc-019","category":"gcal","title":"Natural language date parsing","description":"Parse dates like 'next monday', 'jan 2026', 'next week' into calendar queries","priority":"medium","status":"identified","created":"2026-01-01","notes":"Could use dateparser library or LLM-based parsing. Would enhance hybrid command interface."},{"id":"fc-020","category":"gcal","title":"Configurable timezone","description":"Allow user to configure display timezone instead of hardcoded America/Los_Angeles","priority":"low","status":"identified","created":"2026-01-01","notes":"Could read from personal-assistant-preferences.json or detect from system."},{"id":"fc-021","category":"gcal","title":"Month subcommand","description":"Add /gcal month for current month overview","priority":"low","status":"identified","created":"2026-01-01","notes":"Would complement week view for longer-range planning."},{"id":"fc-022","category":"gcal","title":"Free/busy check","description":"Check availability like 'am I free Tuesday at 2pm?'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Useful for scheduling. Could use Google Calendar freeBusy API or query events in time range."},{"id":"fc-023","category":"gcal","title":"Write operations","description":"Create, modify, delete calendar events","priority":"low","status":"deferred","created":"2026-01-01","notes":"Would change read-only policy. Requires careful consideration of autonomy levels and confirmation flows."},{"id":"fc-024","category":"gmail","title":"Date range search","description":"Search emails by date range like 'last week', 'in December', 'past 30 days'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Currently uses newer_than:Nd. Could add natural language date parsing or explicit date range subcommand."},{"id":"fc-025","category":"gmail","title":"Label and folder filtering","description":"Filter by Gmail labels: starred, important, promotions, specific labels","priority":"medium","status":"identified","created":"2026-01-01","notes":"Gmail API supports label filtering. Would enable '/gmail starred' or '/gmail label:work'."},{"id":"fc-026","category":"gmail","title":"Thread view","description":"Show full email conversation thread instead of individual messages","priority":"medium","status":"identified","created":"2026-01-01","notes":"Gmail API returns threadId. Could fetch all messages in thread for context."},{"id":"fc-027","category":"gmail","title":"Attachment detection and listing","description":"List emails with attachments, show attachment names and sizes","priority":"low","status":"identified","created":"2026-01-01","notes":"Useful for finding documents. API provides attachment metadata in message payload."},{"id":"fc-028","category":"gmail","title":"Full email body view","description":"Read complete email content on demand, not just snippets","priority":"medium","status":"identified","created":"2026-01-01","notes":"Currently shows snippets. Could add '/gmail read ' or expand specific emails."},{"id":"fc-029","category":"gmail","title":"Sender statistics","description":"Show who emails you most, email volume by sender","priority":"low","status":"identified","created":"2026-01-01","notes":"Aggregate sender data over time period. Useful for identifying noise vs signal."},{"id":"fc-030","category":"gmail","title":"Natural language search","description":"Parse queries like 'emails from John about the project last month'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Could use LLM to translate natural language to Gmail search syntax."},{"id":"fc-031","category":"gmail","title":"Configurable urgency keywords","description":"Customize what keywords/senders trigger urgent classification","priority":"low","status":"identified","created":"2026-01-01","notes":"Currently hardcoded. Could store in personal-assistant-preferences.json."},{"id":"fc-032","category":"gmail","title":"Mark as read","description":"Mark emails as read after viewing","priority":"low","status":"deferred","created":"2026-01-01","notes":"Write operation. Would need gmail.modify scope and autonomy consideration."},{"id":"fc-033","category":"gmail","title":"Archive emails","description":"Archive emails from Claude interface","priority":"low","status":"deferred","created":"2026-01-01","notes":"Write operation. Requires gmail.modify scope. Consider batch operations."},{"id":"fc-034","category":"gmail","title":"Reply and compose","description":"Send emails and replies from Claude interface","priority":"low","status":"deferred","created":"2026-01-01","notes":"Write operation. Requires gmail.send scope. Significant policy change - needs careful autonomy controls."},{"id":"fc-035","category":"gmail","title":"Unsubscribe detection","description":"Identify subscription/newsletter emails, suggest unsubscribe","priority":"low","status":"identified","created":"2026-01-01","notes":"Parse List-Unsubscribe headers. Could help with inbox cleanup."},{"id":"fc-036","category":"optimization","title":"API token billing support","description":"Track actual API costs when using Anthropic API instead of subscription","priority":"low","status":"deferred","created":"2026-01-01","notes":"Currently on Pro subscription. When/if using API, add token-based cost calculation using Anthropic pricing."},{"id":"fc-037","category":"optimization","title":"Automatic usage summary","description":"PA mentions usage stats at session end or provides weekly digest","priority":"low","status":"identified","created":"2026-01-01","notes":"Depends on fc-005 (usage logging). Could be opt-in via preferences."},{"id":"fc-038","category":"optimization","title":"Usage dashboard file","description":"Generate Markdown/JSON usage report updated periodically","priority":"low","status":"identified","created":"2026-01-01","notes":"Depends on fc-005 (usage logging). Could be daily/weekly cron or on-demand generation."}]} +{"version":"1.0.0","description":"Deferred features and decisions for future implementation","items":[{"id":"fc-001","category":"infrastructure","title":"Workstation monitoring with Prometheus","description":"Deploy node_exporter and Alertmanager for workstation metrics and alerting","priority":"medium","status":"deferred","created":"2024-12-28","notes":"Would enable proactive alerting for disk, memory, CPU issues"},{"id":"fc-002","category":"agent","title":"Network admin agent","description":"Agent for network configuration, firewall rules, VPN management","priority":"medium","status":"deferred","created":"2024-12-28","notes":"Would manage iptables/nftables, NetworkManager, WireGuard"},{"id":"fc-003","category":"agent","title":"Personal assistant agent","description":"Agent for personal tasks, reminders, scheduling","priority":"medium","status":"deferred","created":"2024-12-28","notes":"Integration with calendar, task management"},{"id":"fc-004","category":"integration","title":"External LLM integration","description":"Support for non-Claude models in the agent system","priority":"low","status":"deferred","created":"2024-12-28","notes":"For specialized tasks or cost optimization"},{"id":"fc-005","category":"optimization","title":"Model usage logging and cost tracking","description":"Track model usage across agents for cost analysis","priority":"medium","status":"resolved","created":"2024-12-28","resolved":"2026-01-01","notes":"Implemented /usage command. Parses history/index.json for session data. Extensible for detailed metrics when session content logging is available."},{"id":"fc-006","category":"design","title":"Slash commands redesign","description":"Revisit slash command architecture and user experience","priority":"low","status":"deferred","created":"2024-12-28","notes":"Current design may need refinement"},{"id":"fc-007","category":"optimization","title":"Document structure optimization","description":"Optimize agent document format for efficiency","priority":"low","status":"deferred","created":"2024-12-28","notes":"Balance between clarity and token usage"},{"id":"fc-008","category":"infrastructure","title":"ArgoCD CLI authentication","description":"Configure argocd CLI with proper authentication","priority":"medium","status":"resolved","created":"2025-12-28","resolved":"2025-12-28","notes":"Using 10-year API token (expires 2035-12-26). Token ID: e3980c6a-1c4e-4f1a-8459-a120a5c60cc5. Stored in ~/.config/argocd/config. No renewal automation needed."},{"id":"fc-009","category":"infrastructure","title":"Prometheus local port-forward","description":"Document Prometheus access patterns for agents","priority":"low","status":"identified","created":"2025-12-28","notes":"Prometheus not accessible on localhost:9090. Options: (1) use kubectl exec to query, (2) set up port-forward, (3) use ingress. Currently works via pod exec."},{"id":"fc-010","category":"infrastructure","title":"Clone homelab gitops repo locally","description":"Clone git@github.com:will666/homelab.git for git-operator access","priority":"low","status":"resolved","created":"2025-12-28","resolved":"2025-12-28","notes":"Cloned to ~/.claude/repos/homelab"},{"id":"fc-011","category":"k8s-health","title":"Address OutOfSync ArgoCD apps","description":"5 apps OutOfSync, 1 Degraded (porthole)","priority":"medium","status":"identified","created":"2025-12-28","notes":"OutOfSync: adopt-a-street, ai-stack, gitea, home-assistant, kubernetes-dashboard, speetest-tracker. Degraded: porthole"},{"id":"fc-012","category":"agent-memory","title":"PA knowledge base with session caching","description":"Local KB for infrastructure facts with lazy-load and in-session caching","priority":"medium","status":"resolved","created":"2025-12-28","resolved":"2025-12-28","notes":"Implemented. KB files at state/kb.json (shared) and state/personal-assistant/kb.json (private). PA agent updated with lazy-load behavior."},{"id":"fc-013","category":"agent-memory","title":"Vector database for agent long-term memory","description":"Semantic search over agent knowledge using embeddings","priority":"low","status":"deferred","created":"2025-12-28","notes":"Would enable fuzzy matching, semantic queries, and scalable knowledge storage. Consider: ChromaDB, Qdrant, or pgvector."},{"id":"fc-014","category":"observability","title":"Grafana predefined reports","description":"Slash command like /grafana-report services to get standard metrics from known dashboards","priority":"low","status":"deferred","created":"2025-12-29","notes":"Requires comprehensive dashboard coverage first. Revisit when observability matures."},{"id":"fc-015","category":"observability","title":"Grafana integration in diagnostics","description":"Auto-pull Grafana dashboard data during /k8s:diagnose or health checks","priority":"low","status":"deferred","created":"2025-12-29","notes":"Would make Grafana the first troubleshooting tool. Depends on fc-016 and mature observability setup."},{"id":"fc-016","category":"observability","title":"Extend prometheus-analyst with Grafana API","description":"Add Grafana API query capability to existing prometheus-analyst agent","priority":"low","status":"deferred","created":"2025-12-29","notes":"Preferred approach over creating new agent/skill. Natural extension when dashboards are comprehensive. Prerequisite for fc-014 and fc-015."},{"id":"fc-017","category":"optimization","title":"Subagent spawning for skill delegation","description":"Implement Task tool or similar mechanism to spawn lower-tier models for specific operations","priority":"medium","status":"resolved","created":"2025-12-31","resolved":"2025-12-31","notes":"Implemented via Claude CLI subprocess. Helper at ~/.claude/mcp/delegation/gmail_delegate.py. Uses tiered delegation: fetch/list (no LLM), Sonnet for summarize/triage (via 'claude --print --model sonnet'). Uses subscription, no API key needed."},{"id":"fc-018","category":"gcal","title":"Custom date range query","description":"Support querying arbitrary date ranges like 'jan 2026' or 'next month'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Currently only supports today/tomorrow/week/next. Would need new subcommand or natural language parsing."},{"id":"fc-019","category":"gcal","title":"Natural language date parsing","description":"Parse dates like 'next monday', 'jan 2026', 'next week' into calendar queries","priority":"medium","status":"identified","created":"2026-01-01","notes":"Could use dateparser library or LLM-based parsing. Would enhance hybrid command interface."},{"id":"fc-020","category":"gcal","title":"Configurable timezone","description":"Allow user to configure display timezone instead of hardcoded America/Los_Angeles","priority":"low","status":"identified","created":"2026-01-01","notes":"Could read from personal-assistant-preferences.json or detect from system."},{"id":"fc-021","category":"gcal","title":"Month subcommand","description":"Add /gcal month for current month overview","priority":"low","status":"identified","created":"2026-01-01","notes":"Would complement week view for longer-range planning."},{"id":"fc-022","category":"gcal","title":"Free/busy check","description":"Check availability like 'am I free Tuesday at 2pm?'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Useful for scheduling. Could use Google Calendar freeBusy API or query events in time range."},{"id":"fc-023","category":"gcal","title":"Write operations","description":"Create, modify, delete calendar events","priority":"low","status":"deferred","created":"2026-01-01","notes":"Would change read-only policy. Requires careful consideration of autonomy levels and confirmation flows."},{"id":"fc-024","category":"gmail","title":"Date range search","description":"Search emails by date range like 'last week', 'in December', 'past 30 days'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Currently uses newer_than:Nd. Could add natural language date parsing or explicit date range subcommand."},{"id":"fc-025","category":"gmail","title":"Label and folder filtering","description":"Filter by Gmail labels: starred, important, promotions, specific labels","priority":"medium","status":"identified","created":"2026-01-01","notes":"Gmail API supports label filtering. Would enable '/gmail starred' or '/gmail label:work'."},{"id":"fc-026","category":"gmail","title":"Thread view","description":"Show full email conversation thread instead of individual messages","priority":"medium","status":"identified","created":"2026-01-01","notes":"Gmail API returns threadId. Could fetch all messages in thread for context."},{"id":"fc-027","category":"gmail","title":"Attachment detection and listing","description":"List emails with attachments, show attachment names and sizes","priority":"low","status":"identified","created":"2026-01-01","notes":"Useful for finding documents. API provides attachment metadata in message payload."},{"id":"fc-028","category":"gmail","title":"Full email body view","description":"Read complete email content on demand, not just snippets","priority":"medium","status":"identified","created":"2026-01-01","notes":"Currently shows snippets. Could add '/gmail read ' or expand specific emails."},{"id":"fc-029","category":"gmail","title":"Sender statistics","description":"Show who emails you most, email volume by sender","priority":"low","status":"identified","created":"2026-01-01","notes":"Aggregate sender data over time period. Useful for identifying noise vs signal."},{"id":"fc-030","category":"gmail","title":"Natural language search","description":"Parse queries like 'emails from John about the project last month'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Could use LLM to translate natural language to Gmail search syntax."},{"id":"fc-031","category":"gmail","title":"Configurable urgency keywords","description":"Customize what keywords/senders trigger urgent classification","priority":"low","status":"identified","created":"2026-01-01","notes":"Currently hardcoded. Could store in personal-assistant-preferences.json."},{"id":"fc-032","category":"gmail","title":"Mark as read","description":"Mark emails as read after viewing","priority":"low","status":"deferred","created":"2026-01-01","notes":"Write operation. Would need gmail.modify scope and autonomy consideration."},{"id":"fc-033","category":"gmail","title":"Archive emails","description":"Archive emails from Claude interface","priority":"low","status":"deferred","created":"2026-01-01","notes":"Write operation. Requires gmail.modify scope. Consider batch operations."},{"id":"fc-034","category":"gmail","title":"Reply and compose","description":"Send emails and replies from Claude interface","priority":"low","status":"deferred","created":"2026-01-01","notes":"Write operation. Requires gmail.send scope. Significant policy change - needs careful autonomy controls."},{"id":"fc-035","category":"gmail","title":"Unsubscribe detection","description":"Identify subscription/newsletter emails, suggest unsubscribe","priority":"low","status":"identified","created":"2026-01-01","notes":"Parse List-Unsubscribe headers. Could help with inbox cleanup."},{"id":"fc-036","category":"optimization","title":"API token billing support","description":"Track actual API costs when using Anthropic API instead of subscription","priority":"low","status":"deferred","created":"2026-01-01","notes":"Currently on Pro subscription. When/if using API, add token-based cost calculation using Anthropic pricing."},{"id":"fc-037","category":"optimization","title":"Automatic usage summary","description":"PA mentions usage stats at session end or provides weekly digest","priority":"low","status":"identified","created":"2026-01-01","notes":"Depends on fc-005 (usage logging). Could be opt-in via preferences."},{"id":"fc-038","category":"optimization","title":"Usage dashboard file","description":"Generate Markdown/JSON usage report updated periodically","priority":"low","status":"identified","created":"2026-01-01","notes":"Depends on fc-005 (usage logging). Could be daily/weekly cron or on-demand generation."}]}