{ "schemaVersion": "1.0", "item": { "slug": "codesession", "name": "Codesession", "source": "tencent", "type": "skill", "category": "开发巄具", "sourceUrl": "https://clawhub.ai/brian-mwirigi/codesession", "canonicalUrl": "https://clawhub.ai/brian-mwirigi/codesession", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/codesession", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=codesession", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "slug": "codesession", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-05-01T22:22:11.173Z", "expiresAt": "2026-05-08T22:22:11.173Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=codesession", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=codesession", "contentDisposition": "attachment; filename=\"codesession-2.5.1.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "codesession" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/codesession" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/codesession", "agentPageUrl": "https://openagent3.xyz/skills/codesession/agent", "manifestUrl": "https://openagent3.xyz/skills/codesession/agent.json", "briefUrl": "https://openagent3.xyz/skills/codesession/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "Session Cost Tracking (codesession-cli)", "body": "Track agent session costs, file changes, and git commits. Enforces budget limits and provides detailed session analytics with a full web dashboard.\n\nLatest: v2.5.1 - cs run wraps everything in one step (session + proxy + run + cost summary). cs today for multi-project context. Dashboard Help tab, Codex pricing, security fixes.\n\nšŸ“¦ npm ā€¢ ā­ GitHub ā€¢ šŸ“ Changelog" }, { "title": "Installation", "body": "# 1. Install the CLI globally from npm\nnpm install -g codesession-cli\n\n# 2. Install the OpenClaw skill\nclawhub install codesession\n\nAfter installing, the cs command is available globally. The OpenClaw agent will automatically use it to track sessions.\n\nRequirements: Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).\nOSInstall build toolsUbuntu/Debiansudo apt-get install -y build-essential python3macOSxcode-select --installWindowsnpm install -g windows-build-tools or install Visual Studio Build ToolsAlpineapk add build-base python3\nData is stored locally at ~/.codesession/sessions.db." }, { "title": "When to use", "body": "Always start a tracked session at the beginning of a multi-step task\nAlways log AI usage after each API call you make\nAlways end the session when the task is complete\nCheck budget before expensive operations\nUse cs dashboard to review session data in a browser" }, { "title": "Start tracking", "body": "# Agent mode (always use --json for structured output):\ncs start \"task description\" --json --close-stale\n\n# Resume if a session was left open (e.g. after a crash):\ncs start \"task description\" --json --resume\n\n# Human/interactive mode (stays running with live file watcher):\ncs start \"task description\"\n\nAgent mode vs interactive mode: With --json, the session is created in the database, JSON is printed, and the process exits immediately -- the session stays \"active\" and tracks git changes when you run cs end. Without --json, the process stays running with a live file watcher and git commit poller until you press Ctrl+C or run cs end in another terminal." }, { "title": "Log AI usage (after each API call)", "body": "# With granular tokens (cost auto-calculated from built-in pricing):\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json\n\n# With agent name tracking (NEW in v1.9.1):\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Code Review Bot\" --json\n\n# With manual cost:\ncs log-ai -p anthropic -m claude-opus-4-6 -t 15000 -c 0.30 --json\n\n# With all fields:\ncs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent \"Research Agent\" --json\n\nProviders: anthropic, openai, google, mistral, deepseek\nCost is auto-calculated from a configurable pricing table (21+ built-in models including Codex). Use cs pricing list --json to see known models. If a model is unknown, provide -c manually.\n\nAgent Name (optional): Use --agent \"Agent Name\" to track which agent performed the work. Perfect for multi-agent systems, A/B testing, and cost attribution. Agent names appear in the dashboard and can be used to filter/analyze costs per agent." }, { "title": "Check current status", "body": "cs status --json\n\nReturns JSON with current session cost, tokens, files changed, duration. All JSON responses include schemaVersion and codesessionVersion fields." }, { "title": "End session and get summary", "body": "cs end -n \"completion notes\" --json\n\nWhen ending, codesession automatically scans git for all files changed and commits made since the session started -- even if --json mode was used (no live watcher needed)." }, { "title": "Web Dashboard", "body": "cs dashboard\n# Opens http://localhost:3737 with full analytics UI\n\ncs dashboard --port 4000 # custom port\ncs dashboard --no-open # don't auto-open browser\n\nThe dashboard shows:\n\nOverview ā€” KPIs, daily cost/token trends, spend projections, cost velocity\nSessions ā€” searchable/sortable table, per-session detail with timeline, files, commits, AI calls, notes\nModels ā€” per-model & per-provider cost breakdown, token ratios, usage charts\nInsights ā€” file hotspots, activity heatmap, project breakdown, pricing table\nAlerts ā€” set daily/total/per-session cost thresholds with alarm mode (sound + browser notifications)\nStart Fresh ā€” reset all session data from the sidebar" }, { "title": "View session details", "body": "cs show --json --files --commits" }, { "title": "View historical stats", "body": "cs stats --json" }, { "title": "Export sessions", "body": "cs export --format json --limit 10\ncs export --format csv" }, { "title": "Add notes / annotations", "body": "cs note \"Starting refactor phase\"\ncs note \"Tests passing, moving to cleanup\"\n\nTimestamped annotations appear in cs show --json under annotations." }, { "title": "Recover stale sessions", "body": "cs recover --max-age 12\n\nAuto-ends any active sessions older than 12 hours." }, { "title": "Agent Workflow", "body": "Agents should always use --json on every command for structured, parseable output.\n\nAt task start: cs start \"Fix authentication bug\" --json --close-stale\nAdd context notes: cs note \"analyzing auth flow\" --json\nAfter each AI call: cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Bug Fixer\" --json\nCheck spend: cs status --json -- read aiCost field\nAt task end: cs end -n \"Fixed the auth bug, added tests\" --json\nReview past sessions: cs dashboard\n\nTip: Use the --agent flag to identify your agent's work, especially useful in multi-agent systems where different agents handle different tasks (e.g., \"Code Review Bot\", \"Test Writer\", \"Documentation Agent\")." }, { "title": "Pricing", "body": "Pricing is configurable. Run cs pricing list to see all known model prices. Override or add models:\n\n# Plain model key\ncs pricing set my-model 5.00 15.00\n\n# Provider-namespaced key (avoids collisions)\ncs pricing set gpt-4o 2.50 10.00 --provider openai\n\nIf the model isn't in the pricing table, you must provide -c when logging." }, { "title": "Proxy mode & cs run (v2.5.0)", "body": "The fastest way to track any agent run:\n\ncs run python my_agent.py\n# or: cs run --name \"fix auth\" node agent.js\n\nThis starts a session, launches the proxy, runs your command, then ends the session and prints a cost summary. No extra terminals, no env vars to export.\n\nIf you prefer manual control, start the proxy in one terminal and set env vars:\n\ncs proxy --session \"my task\" # auto-starts a session too\n# then in your agent shell:\nexport ANTHROPIC_BASE_URL=http://127.0.0.1:3739\nexport OPENAI_BASE_URL=http://127.0.0.1:3739/v1\n\nThe proxy binds to 127.0.0.1 only. It never stores prompt text or API keys ā€” only token counts are written to the session." }, { "title": "Budget awareness", "body": "If the user has set a budget or you detect high spending:\n\nCheck cs status --json before expensive operations\nWarn the user if aiCost exceeds $5.00 in a single session\nSuggest cheaper models if costs are escalating" }, { "title": "Important", "body": "Use --close-stale on cs start to avoid \"session_active\" errors from prior crashes\nIf cs is not installed, skip session tracking ā€” don't block the user's task\nAlways use --json on every command ā€” agents must use structured output\nWith --json, cs start creates the session and exits (no long-running process needed)\nSessions are scoped by git root ā€” running from a subdirectory still matches the repo-level session\nOn errors in --json mode, exit code is always 1 and the response has { \"error\": { \"code\": \"...\", \"message\": \"...\" } }\nCheck schemaVersion in JSON responses to detect breaking changes" }, { "title": "Update check", "body": "Periodically check if the CLI is up to date (e.g. at session start or once per day):\n\n# Compare installed version to latest on npm:\ncs --version # installed version\nnpm view codesession-cli version # latest on npm\n\nIf the installed version is behind, notify the user:\n\n\"codesession-cli update available: v1.9.4 -> v2.0.0. Run npm install -g codesession-cli to update.\"\n\nDon't block the workflow for an update ā€” just inform and continue." }, { "title": "JSON output", "body": "All commands support --json for machine-readable output. Use this when you need to parse session data programmatically." } ], "body": "Session Cost Tracking (codesession-cli)\n\nTrack agent session costs, file changes, and git commits. Enforces budget limits and provides detailed session analytics with a full web dashboard.\n\nLatest: v2.5.1 - cs run wraps everything in one step (session + proxy + run + cost summary). cs today for multi-project context. Dashboard Help tab, Codex pricing, security fixes.\n\nšŸ“¦ npm ā€¢ ā­ GitHub ā€¢ šŸ“ Changelog\n\nInstallation\n# 1. Install the CLI globally from npm\nnpm install -g codesession-cli\n\n# 2. Install the OpenClaw skill\nclawhub install codesession\n\n\nAfter installing, the cs command is available globally. The OpenClaw agent will automatically use it to track sessions.\n\nRequirements: Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).\n\nOS\tInstall build tools\nUbuntu/Debian\tsudo apt-get install -y build-essential python3\nmacOS\txcode-select --install\nWindows\tnpm install -g windows-build-tools or install Visual Studio Build Tools\nAlpine\tapk add build-base python3\n\nData is stored locally at ~/.codesession/sessions.db.\n\nWhen to use\nAlways start a tracked session at the beginning of a multi-step task\nAlways log AI usage after each API call you make\nAlways end the session when the task is complete\nCheck budget before expensive operations\nUse cs dashboard to review session data in a browser\nCommands\nStart tracking\n# Agent mode (always use --json for structured output):\ncs start \"task description\" --json --close-stale\n\n# Resume if a session was left open (e.g. after a crash):\ncs start \"task description\" --json --resume\n\n# Human/interactive mode (stays running with live file watcher):\ncs start \"task description\"\n\n\nAgent mode vs interactive mode: With --json, the session is created in the database, JSON is printed, and the process exits immediately -- the session stays \"active\" and tracks git changes when you run cs end. Without --json, the process stays running with a live file watcher and git commit poller until you press Ctrl+C or run cs end in another terminal.\n\nLog AI usage (after each API call)\n# With granular tokens (cost auto-calculated from built-in pricing):\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json\n\n# With agent name tracking (NEW in v1.9.1):\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Code Review Bot\" --json\n\n# With manual cost:\ncs log-ai -p anthropic -m claude-opus-4-6 -t 15000 -c 0.30 --json\n\n# With all fields:\ncs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent \"Research Agent\" --json\n\n\nProviders: anthropic, openai, google, mistral, deepseek Cost is auto-calculated from a configurable pricing table (21+ built-in models including Codex). Use cs pricing list --json to see known models. If a model is unknown, provide -c manually.\n\nAgent Name (optional): Use --agent \"Agent Name\" to track which agent performed the work. Perfect for multi-agent systems, A/B testing, and cost attribution. Agent names appear in the dashboard and can be used to filter/analyze costs per agent.\n\nCheck current status\ncs status --json\n\n\nReturns JSON with current session cost, tokens, files changed, duration. All JSON responses include schemaVersion and codesessionVersion fields.\n\nEnd session and get summary\ncs end -n \"completion notes\" --json\n\n\nWhen ending, codesession automatically scans git for all files changed and commits made since the session started -- even if --json mode was used (no live watcher needed).\n\nWeb Dashboard\ncs dashboard\n# Opens http://localhost:3737 with full analytics UI\n\ncs dashboard --port 4000 # custom port\ncs dashboard --no-open # don't auto-open browser\n\n\nThe dashboard shows:\n\nOverview ā€” KPIs, daily cost/token trends, spend projections, cost velocity\nSessions ā€” searchable/sortable table, per-session detail with timeline, files, commits, AI calls, notes\nModels ā€” per-model & per-provider cost breakdown, token ratios, usage charts\nInsights ā€” file hotspots, activity heatmap, project breakdown, pricing table\nAlerts ā€” set daily/total/per-session cost thresholds with alarm mode (sound + browser notifications)\nStart Fresh ā€” reset all session data from the sidebar\nView session details\ncs show --json --files --commits\n\nView historical stats\ncs stats --json\n\nExport sessions\ncs export --format json --limit 10\ncs export --format csv\n\nAdd notes / annotations\ncs note \"Starting refactor phase\"\ncs note \"Tests passing, moving to cleanup\"\n\n\nTimestamped annotations appear in cs show --json under annotations.\n\nRecover stale sessions\ncs recover --max-age 12\n\n\nAuto-ends any active sessions older than 12 hours.\n\nAgent Workflow\n\nAgents should always use --json on every command for structured, parseable output.\n\nAt task start: cs start \"Fix authentication bug\" --json --close-stale\nAdd context notes: cs note \"analyzing auth flow\" --json\nAfter each AI call: cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Bug Fixer\" --json\nCheck spend: cs status --json -- read aiCost field\nAt task end: cs end -n \"Fixed the auth bug, added tests\" --json\nReview past sessions: cs dashboard\n\nTip: Use the --agent flag to identify your agent's work, especially useful in multi-agent systems where different agents handle different tasks (e.g., \"Code Review Bot\", \"Test Writer\", \"Documentation Agent\").\n\nPricing\n\nPricing is configurable. Run cs pricing list to see all known model prices. Override or add models:\n\n# Plain model key\ncs pricing set my-model 5.00 15.00\n\n# Provider-namespaced key (avoids collisions)\ncs pricing set gpt-4o 2.50 10.00 --provider openai\n\n\nIf the model isn't in the pricing table, you must provide -c when logging.\n\nProxy mode & cs run (v2.5.0)\n\nThe fastest way to track any agent run:\n\ncs run python my_agent.py\n# or: cs run --name \"fix auth\" node agent.js\n\n\nThis starts a session, launches the proxy, runs your command, then ends the session and prints a cost summary. No extra terminals, no env vars to export.\n\nIf you prefer manual control, start the proxy in one terminal and set env vars:\n\ncs proxy --session \"my task\" # auto-starts a session too\n# then in your agent shell:\nexport ANTHROPIC_BASE_URL=http://127.0.0.1:3739\nexport OPENAI_BASE_URL=http://127.0.0.1:3739/v1\n\n\nThe proxy binds to 127.0.0.1 only. It never stores prompt text or API keys ā€” only token counts are written to the session.\n\nBudget awareness\n\nIf the user has set a budget or you detect high spending:\n\nCheck cs status --json before expensive operations\nWarn the user if aiCost exceeds $5.00 in a single session\nSuggest cheaper models if costs are escalating\nImportant\nUse --close-stale on cs start to avoid \"session_active\" errors from prior crashes\nIf cs is not installed, skip session tracking ā€” don't block the user's task\nAlways use --json on every command ā€” agents must use structured output\nWith --json, cs start creates the session and exits (no long-running process needed)\nSessions are scoped by git root ā€” running from a subdirectory still matches the repo-level session\nOn errors in --json mode, exit code is always 1 and the response has { \"error\": { \"code\": \"...\", \"message\": \"...\" } }\nCheck schemaVersion in JSON responses to detect breaking changes\nUpdate check\n\nPeriodically check if the CLI is up to date (e.g. at session start or once per day):\n\n# Compare installed version to latest on npm:\ncs --version # installed version\nnpm view codesession-cli version # latest on npm\n\n\nIf the installed version is behind, notify the user:\n\n\"codesession-cli update available: v1.9.4 -> v2.0.0. Run npm install -g codesession-cli to update.\"\n\nDon't block the workflow for an update ā€” just inform and continue.\n\nJSON output\n\nAll commands support --json for machine-readable output. Use this when you need to parse session data programmatically." }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/brian-mwirigi/codesession", "publisherUrl": "https://clawhub.ai/brian-mwirigi/codesession", "owner": "brian-mwirigi", "version": "2.5.1", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/codesession", "downloadUrl": "https://openagent3.xyz/downloads/codesession", "agentUrl": "https://openagent3.xyz/skills/codesession/agent", "manifestUrl": "https://openagent3.xyz/skills/codesession/agent.json", "briefUrl": "https://openagent3.xyz/skills/codesession/agent.md" } }