@candelahq/opencode

OpenCode plugin for Candela — real-time AI cost tracking, budget guardrails, and spending intelligence.

@candelahq/opencode connects your OpenCode coding agent to Candela, providing live spending visibility, proactive budget warnings, cost-aware model routing, and rich analytics — all inside your terminal.

---

⚡ Features

• 💰 Real-Time Cost Tracking — Per-response cost deltas, session totals, and 24h spend in your status bar and sidebar
• 📊 Budget Monitoring — Threshold toasts at 80/90/100%, budget pacing forecast, reset countdown
• 🔀 Smart Model Routing — Opt-in suggestions to swap to cheaper models when budget is tight
• 📏 Context Window Gauge — Token usage tracking with compaction warnings at 80%+
• 🎯 Daily Cost Goals — Set spending targets, track progress with visual pacing
• 🛑 Session Cost Caps — Per-session spending limits with 80%/100% warnings
• 📈 Cost Forecasting — Extrapolate session cost based on current call rate
• 🔇 Quiet Mode — Suppress info toasts, keep warnings and errors
• 🏷️ Session Tagging — Tag sessions by activity (auto-detects git branch)
• 📂 Repo Attribution — Auto-tracks costs per git repository
• 📜 Session History — Browse past sessions with cost, duration, and tool usage
• ⏰ Time-of-Day Patterns — Discover when you spend the most
• 🛠️ Tool Cost Breakdown — See which tools cost the most per call
• 📝 Git Commit Annotation — Embed cost metadata in commit messages
• 📦 Export — JSON + CSV export of session data
• 🗄️ Local Analytics — JSONL event log with 90-day auto-rotation and 10MB cap

---

📦 Installation

npm install @candelahq/opencode

Add to your OpenCode config (~/.config/opencode/config.json):

{
  "plugins": ["@candelahq/opencode"]
}

---

🚀 Quick Start

1. Start Candela: candela start
2. Add the plugin to your OpenCode config (see above)
3. Open OpenCode — look for 🕯️ in your status bar
4. Type /cost to see your first spending report

⚙️ Configuration

Zero-config when running Candela locally. All settings support environment variable overrides.

Environment Variables

Variable	Type	Default	Description
CANDELA_PROXY_URL	String	http://localhost:8181	Candela proxy URL
CANDELA_CONFIG	String	—	Path to Candela config YAML (for port discovery)
CANDELA_SMART_ROUTING	Boolean	false	Enable cost-conscious model routing
CANDELA_ROUTING_THRESHOLD	Float (0–1)	0.7	Budget fraction to trigger routing
CANDELA_ROUTING_SAVINGS_THRESHOLD	Float (0–1)	0.5	Min savings to suggest model swap
CANDELA_DAILY_GOAL	Number (USD)	—	Daily spending target
CANDELA_QUIET	Boolean	false	Suppress info-level toasts
CANDELA_SESSION_CAP	Number (USD)	—	Per-session cost alert threshold

Settings File

Persistent settings at ~/.config/opencode/candela-settings.json.

Resolution priority: env vars > settings file > defaults.

---

💻 Slash Commands

Command	Aliases	Description
/cost	/spend	Session cost + 24h total breakdown
/budget	/remaining	Budget remaining, grants, reset time
/models	—	Top models by spend and call count
/dashboard	/dash	Open Candela web dashboard
/export	/dump	Export session data to JSON + CSV
/goal	—	Set or view daily cost goal
/quiet	/shh	Toggle quiet mode
/tag	/label	Tag session for cost attribution
/cap	—	Set per-session cost cap
/history	/sessions	Browse recent sessions
/patterns	/when	Time-of-day cost analysis
/annotate	/commit-cost	Git commit cost metadata
/tools	/tool-cost	Tool cost breakdown

---

🖥️ Sidebar

The sidebar dashboard shows:

📊 $4.20 · 24h
🗄️ Cache hit rate: 72%
🏷️ feat/context-gauge
⚡ Session: $1.80 · 12 calls
📈 Forecast: ~$3.30 if 10 more calls
📏 Context: 45k tokens 🟩 ~35%
🎯 Goal: $4.20/$20 🟩 21%
⏱️ Budget exhausted by 4:30 PM
  claude-sonnet: $2.10 (8 calls)
  gpt-4o: $1.30 (4 calls)

---

📊 Intelligence Layer

• Cost Streaks — Track consecutive under-budget days
• Anomaly Detection — Alert when session cost is 2x+ your average
• Budget Pacing — Estimate budget exhaustion time from hourly burn rate
• Model Efficiency — Score models by cost-per-call vs effectiveness
• Weekly Digest — Week-over-week spending comparison
• Time Patterns — Morning vs afternoon vs evening vs night cost analysis

---

🛠️ Requirements

• OpenCode with @opencode-ai/plugin support
• Candela proxy running (default: http://localhost:8181)

---

📄 License

Apache-2.0