feat(usage): Claude/Codex usage monitoring via ccusage sidecar

.gitignore

@@ -31,3 +31,7 @@ build/
 
 # ts-rs generated TypeScript bindings (build artifact)
 crates/api/bindings/
+crates/usage/bindings/
+
+# ccusage sidecar binaries — fetched at build time by src-tauri/build.rs
+crates/desktop/src-tauri/binaries/

Cargo.toml

@@ -11,6 +11,7 @@ members = [
 	"crates/markdown",
 	"crates/inference",
 	"crates/cc-plugins",
+	"crates/usage",
 	"crates/desktop/src-tauri",
 ]
 resolver = "2"

crates/api/Cargo.toml

@@ -20,11 +20,12 @@ aghub-core = { path = "../core" }
 aghub-git = { path = "../git" }
 aghub-inference = { path = "../inference" }
 aghub-cc-plugins = { path = "../cc-plugins" }
+aghub-usage = { path = "../usage" }
 skill = { path = "../skill" }
 skills-sh = { path = "../skills-sh" }
 rocket = { version = "0.5", features = [ "json" ] }
 rocket_cors = "0.6.0"
-tokio = { workspace = true, features = [ "rt-multi-thread", "macros", "process" ] }
+tokio = { workspace = true, features = [ "rt-multi-thread", "macros", "process", "time" ] }
 serde = { workspace = true }
 serde_json = { workspace = true }
 thiserror = { workspace = true }
@@ -37,4 +38,5 @@ keyring = { workspace = true }
 uuid = { workspace = true }
 log = { workspace = true }
 reqwest = { workspace = true }
+chrono = { workspace = true }
 url = { workspace = true }

crates/api/src/bin/export-dto.rs

@@ -70,6 +70,10 @@ use aghub_api::dto::{
 		TransferRequest,
 	},
 };
+use aghub_usage::{
+	AgentLimitsDto, AgentUsageDto, LimitWindowDto, UsageDayDto,
+	UsageLimitsReportDto, UsageModelDto, UsageReportDto, UsageTotalsDto,
+};
 use ts_rs::{Config, TS};
 
 fn workspace_root() -> PathBuf {
@@ -247,6 +251,16 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 	export_type::<CCPluginValidateRequest>(&cfg)?;
 	export_type::<CCPluginValidateResponse>(&cfg)?;
 
+	export_type::<UsageModelDto>(&cfg)?;
+	export_type::<UsageDayDto>(&cfg)?;
+	export_type::<UsageTotalsDto>(&cfg)?;
+	export_type::<AgentUsageDto>(&cfg)?;
+	export_type::<UsageReportDto>(&cfg)?;
+
+	export_type::<LimitWindowDto>(&cfg)?;
+	export_type::<AgentLimitsDto>(&cfg)?;
+	export_type::<UsageLimitsReportDto>(&cfg)?;
+
 	write_index_file(&out_dir)?;
 
 	if disallowed_dir.exists() {

crates/api/src/lib.rs

@@ -23,6 +23,8 @@ pub(crate) const CREATE_NO_WINDOW: u32 = 0x0800_0000;
 pub struct ApiOptions {
 	pub port: u16,
 	pub app_data_dir: Option<PathBuf>,
+	/// Path to the bundled `ccusage` sidecar; `None` falls back to env/PATH.
+	pub ccusage_bin: Option<PathBuf>,
 	pub auth_token: Option<String>,
 	pub allowed_origins: Vec<String>,
 	pub allowed_origin_regexes: Vec<String>,
@@ -33,6 +35,7 @@ impl ApiOptions {
 		Self {
 			port,
 			app_data_dir: None,
+			ccusage_bin: None,
 			auth_token: None,
 			allowed_origins: default_allowed_origins(),
 			allowed_origin_regexes: default_allowed_origin_regexes(),
@@ -58,6 +61,7 @@ impl ApiOptions {
 			app_data_dir: self
 				.app_data_dir
 				.unwrap_or_else(default_app_data_dir),
+			ccusage_bin: self.ccusage_bin,
 			auth_token,
 			token_was_generated,
 			allowed_origins: self.allowed_origins,
@@ -87,6 +91,7 @@ fn default_allowed_origin_regexes() -> Vec<String> {
 struct ResolvedApiOptions {
 	port: u16,
 	app_data_dir: PathBuf,
+	ccusage_bin: Option<PathBuf>,
 	auth_token: String,
 	token_was_generated: bool,
 	allowed_origins: Vec<String>,
@@ -183,6 +188,9 @@ fn build_rocket(
 		.manage(crate::state::InferenceProviderState {
 			app_data_dir: options.app_data_dir,
 		})
+		.manage(crate::state::UsageState {
+			ccusage_bin: options.ccusage_bin,
+		})
 		.manage(crate::auth::ApiAuthState {
 			token: options.auth_token,
 		})
@@ -286,6 +294,8 @@ fn build_rocket(
 				routes::plugins::cli_status,
 				routes::plugins::prune_plugins,
 				routes::plugins::validate_plugin,
+				routes::usage::usage_summary,
+				routes::usage::usage_limits,
 			],
 		)
 		.register(

crates/api/src/routes/mod.rs

@@ -8,6 +8,7 @@ pub mod mcps;
 pub mod plugins;
 pub mod skills;
 pub mod sub_agents;
+pub mod usage;
 
 use aghub_core::{
 	create_adapter, manager::ConfigManager, models::ResourceScope,

crates/api/src/routes/usage.rs

@@ -0,0 +1,27 @@
+//! Usage routes: thin handlers over the `aghub-usage` crate, which owns the
+//! ccusage shell-out, normalization, and vendor limit-endpoint logic.
+
+use rocket::serde::json::Json;
+use rocket::State;
+
+use aghub_usage::{UsageLimitsReportDto, UsageReportDto};
+
+use crate::state::UsageState;
+
+/// `GET /api/v1/usage/summary` — daily token/cost usage for Claude and Codex.
+#[get("/usage/summary?<since>&<until>&<timezone>")]
+pub async fn usage_summary(
+	usage: &State<UsageState>,
+	since: Option<String>,
+	until: Option<String>,
+	timezone: Option<String>,
+) -> Json<UsageReportDto> {
+	let bin = aghub_usage::resolve_ccusage_bin(usage.ccusage_bin.clone());
+	Json(aghub_usage::summary(&bin, since, until, timezone).await)
+}
+
+/// `GET /api/v1/usage/limits` — remaining rate-limit quota for Claude and Codex.
+#[get("/usage/limits")]
+pub async fn usage_limits() -> Json<UsageLimitsReportDto> {
+	Json(aghub_usage::limits().await)
+}

crates/api/src/state.rs

@@ -26,3 +26,10 @@ pub struct GitCloneSessions {
 pub struct InferenceProviderState {
 	pub app_data_dir: PathBuf,
 }
+
+/// Path to the bundled `ccusage` sidecar binary, injected by the desktop shell.
+/// `None` in dev / standalone server: usage routes fall back to the
+/// `AGHUB_CCUSAGE_BIN` env var, then to `ccusage` on `PATH`.
+pub struct UsageState {
+	pub ccusage_bin: Option<PathBuf>,
+}

crates/cli/Cargo.toml

@@ -14,6 +14,7 @@ path = "src/main.rs"
 aghub-core = { path = "../core" }
 aghub-agents = { path = "../agents" }
 aghub-cc-plugins = { path = "../cc-plugins" }
+aghub-usage = { path = "../usage" }
 skill = { path = "../skill" }
 
 clap = { workspace = true }

crates/cli/src/commands/mod.rs

@@ -5,6 +5,7 @@ pub mod enable;
 pub mod get;
 pub mod plugin;
 pub mod update;
+pub mod usage;
 
 use aghub_core::models::McpTransport;
 use anyhow::{bail, Result};

crates/cli/src/commands/usage.rs

@@ -0,0 +1,54 @@
+//! `aghub-cli usage ...` subcommands.
+//!
+//! Thin CLI surface over the `aghub_usage` crate. Both subcommands print the
+//! same JSON the desktop app consumes; the CLI does not bundle the ccusage
+//! sidecar, so `summary` resolves it from `AGHUB_CCUSAGE_BIN` or `PATH`.
+
+use anyhow::{Context, Result};
+use clap::Subcommand;
+
+#[derive(Subcommand)]
+pub enum UsageAction {
+	/// Daily token and cost usage for Claude and Codex from local ccusage data
+	Summary {
+		/// Start date, YYYY-MM-DD (passed through to ccusage)
+		#[arg(long)]
+		since: Option<String>,
+		/// End date, YYYY-MM-DD (passed through to ccusage)
+		#[arg(long)]
+		until: Option<String>,
+		/// IANA timezone for day bucketing (passed through to ccusage)
+		#[arg(long)]
+		timezone: Option<String>,
+	},
+	/// Remaining rate-limit quota for Claude and Codex from each vendor endpoint
+	Limits,
+}
+
+pub fn execute(action: UsageAction) -> Result<()> {
+	let runtime = tokio::runtime::Builder::new_current_thread()
+		.enable_all()
+		.build()
+		.context("Failed to build tokio runtime")?;
+	runtime.block_on(dispatch(action))
+}
+
+async fn dispatch(action: UsageAction) -> Result<()> {
+	match action {
+		UsageAction::Summary {
+			since,
+			until,
+			timezone,
+		} => {
+			let bin = aghub_usage::resolve_ccusage_bin(None);
+			let report =
+				aghub_usage::summary(&bin, since, until, timezone).await;
+			println!("{}", serde_json::to_string_pretty(&report)?);
+		}
+		UsageAction::Limits => {
+			let report = aghub_usage::limits().await;
+			println!("{}", serde_json::to_string_pretty(&report)?);
+		}
+	}
+	Ok(())
+}

crates/cli/src/main.rs

@@ -13,7 +13,7 @@ use aghub_core::{
 
 mod commands;
 
-use commands::{add, delete, disable, enable, get, plugin, update};
+use commands::{add, delete, disable, enable, get, plugin, update, usage};
 
 /// Global verbose flag used by the eprintln_verbose macro
 static VERBOSE: AtomicBool = AtomicBool::new(false);
@@ -205,6 +205,11 @@ enum Commands {
 		#[command(subcommand)]
 		action: plugin::PluginAction,
 	},
+	/// Report token usage and rate-limit quota for Claude and Codex
+	Usage {
+		#[command(subcommand)]
+		action: usage::UsageAction,
+	},
 }
 
 #[derive(ValueEnum, Clone, Copy, Debug)]
@@ -221,6 +226,12 @@ fn main() -> Result<()> {
 	// Set global verbose flag
 	set_verbose(cli.verbose);
 
+	// Usage reporting is agent-agnostic: it reads each vendor's own data, so it
+	// runs before agent/scope resolution and config loading.
+	if let Commands::Usage { action } = cli.command {
+		return usage::execute(action);
+	}
+
 	// Handle --agent all: iterate all registered agents
 	if cli.agent == "all" {
 		return handle_all_agents(&cli);
@@ -380,6 +391,9 @@ fn main() -> Result<()> {
 			}
 			plugin::execute(action)
 		}
+		Commands::Usage { .. } => {
+			unreachable!("usage is dispatched before agent resolution")
+		}
 	}
 }