Cost Estimate Command

You are a senior software engineering consultant tasked with estimating the development cost of code in the current repository.

All tunable rates, ratios, and multipliers are defined in the Configuration section below. When performing calculations in later steps, always reference these values — do not use hardcoded numbers elsewhere. To customize the estimate for a different market, team structure, or role mix, edit only this section.

Configuration

All cost parameters in one place. Edit these to adjust the entire estimate.

Coding Productivity Rates (lines/hour, pure focused output)

Development Overhead Multipliers (% of base coding hours)

Total overhead range: ~68-93%

Hourly Market Rates by Role (USD, 2025 US market)

Role Ratios (hours as % of engineering hours, by company stage)

Organizational Efficiency (coding hours as % of 40-hr week)

Sanity Check Bounds

Claude ROI Constants

Helper Scripts

Three Python scripts in .claude/skills/cost-estimate/helpers/ automate the heavy lifting. Use these instead of manual find, wc -l, git log, and inline math. They work on any repo.

1. loc_counter.py — Count lines of code

# Full repo (respects .gitignore via git ls-files)
python3 .claude/skills/cost-estimate/helpers/loc_counter.py

# Branch diff (added lines only)
python3 .claude/skills/cost-estimate/helpers/loc_counter.py --branch feat/foo

# Branch diff against specific base
python3 .claude/skills/cost-estimate/helpers/loc_counter.py --branch feat/foo --base develop

# Single commit
python3 .claude/skills/cost-estimate/helpers/loc_counter.py --commit abc1234

Output (JSON): totals (lines, files, test/doc/config/source breakdown), by_language, by_directory, all_files (with path, lines, category, is_test, is_doc, is_config flags).

2. git_session_analyzer.py — Estimate Claude active hours

# All commits on current branch
python3 .claude/skills/cost-estimate/helpers/git_session_analyzer.py

# Specific branch
python3 .claude/skills/cost-estimate/helpers/git_session_analyzer.py --branch feat/foo

Output (JSON): total_commits, total_sessions, estimated_active_hours, sessions[] with date/start/end/commits/estimated_hours/subjects. Review the session estimates and adjust upward for large-scope commits (e.g. a single commit that adds 5000 lines should count as more than 1 hour).

3. cost_calculator.py — Calculate costs from categorized LOC

# Pipe categories as JSON
echo '{"audio_video_processing": 2000, "business_logic": 5000, ...}' | \
  python3 .claude/skills/cost-estimate/helpers/cost_calculator.py --rate 150 --claude-hours 29

Valid category keys: simple_crud_ui_boilerplate, standard_views, complex_ui, business_logic, database_persistence, audio_video_processing, gpu_shader, native_interop, system_extensions, on_device_ml, tests, config_build, documentation

Output (JSON): base_coding (rows with category/lines/rate/hours), overhead (rows), total_estimated_hours, sanity_check, calendar_time, engineering_cost, team_costs (per stage with role breakdowns), claude_roi (if --claude-hours given).

4. report_generator.py — Generate markdown report sections

# Full report from calculator + session data
python3 .claude/skills/cost-estimate/helpers/report_generator.py \
  --calc costs.json --sessions sessions.json --project "MyApp" --scope "Full codebase"

# Single section only
python3 .claude/skills/cost-estimate/helpers/report_generator.py \
  --calc costs.json --section executive_summary

# Pipe directly from calculator
echo '{"business_logic": 5000}' | python3 cost_calculator.py --rate 150 --claude-hours 29 | \
  python3 report_generator.py --project "MyApp"

Available sections: executive_summary, development_time, calendar_time, engineering_cost, team_cost, grand_total, claude_roi, assumptions

Output: Ready-to-paste markdown. Review, add complexity factors, market research rationale, and codebase metrics (which are project-specific and come from Step 1).

Recommended Workflow

# 1. Count LOC
python3 .claude/skills/cost-estimate/helpers/loc_counter.py > /tmp/loc.json

# 2. Analyze git sessions
python3 .claude/skills/cost-estimate/helpers/git_session_analyzer.py > /tmp/sessions.json

# 3. Classify files into categories (done manually from loc.json)
#    Then pipe to calculator:
echo '{"category": lines, ...}' | \
  python3 .claude/skills/cost-estimate/helpers/cost_calculator.py \
    --rate 150 --claude-hours 29 > /tmp/calc.json

# 4. Generate report sections
python3 .claude/skills/cost-estimate/helpers/report_generator.py \
  --calc /tmp/calc.json --sessions /tmp/sessions.json --project "MyApp"

The main job is: classify files into categories (the creative/judgment part) and add context (complexity factors, market research, codebase description). The math and formatting are handled by the scripts.

Step 0: Determine Scope

Check the user's input for scope specifiers:

• No arguments (default): Estimate the entire codebase.
• branch:<name>: Estimate only the diff introduced by that branch (added lines only).
• commit:<hash>: Estimate only the diff for that single commit (added lines only).

The loc_counter.py script handles all three modes via --branch and --commit flags.

Step 1: Analyze the Codebase

Run loc_counter.py to get a complete breakdown. Then review the output to:

1. Identify the primary languages from by_language
2. Understand the directory structure from by_directory
3. Note test/doc/config splits from totals
4. Identify complexity factors — scan the all_files list for signs of advanced work (GPU code, system extensions, audio/video pipelines, ML inference, native interop, complex UI, etc.)
5. Detect project name from the repo directory name or top-level config files

Step 2: Classify and Calculate Development Hours

Review the all_files output from Step 1 and classify each file (or group of files) into categories from the Coding Productivity Rates table. Build a JSON object mapping category keys to line counts, then pipe it to cost_calculator.py.

These rates represent pure focused coding output — fingers on keyboard, writing code with modern IDE autocomplete. All thinking, debugging, reviewing, and design time is captured by the overhead multipliers — do not bake overhead into rates or it will be double-counted.

The calculator handles: base hours, overhead multipliers, sanity check, calendar time, engineering cost, and full team costs. Review the sanity_check in the output — if it fails, adjust your category assignments.

Every source line must be assigned to exactly one category. Do not double-count.

Step 3: Research Market Rates

Start with the Hourly Market Rates by Role from the Configuration section as baseline defaults. Then use WebSearch to validate or adjust for:

• The specific tech stack detected in Step 1
• Geographic variations (US markets: SF Bay Area, NYC, Austin, Remote)
• Contractor vs. employee rates

Search queries to use:

• "senior full stack developer hourly rate 2025"
• "senior software engineer hourly rate United States 2025"
• "[detected language/platform] developer contractor rate 2025"

If web search results differ significantly from the config defaults, note the discrepancy and use the researched rates. Otherwise, use the config defaults to avoid slowing down the estimate.

Step 4: Calculate Organizational Overhead

Real companies don't have developers coding 40 hours/week. Account for typical organizational overhead to convert raw development hours into realistic calendar time.

Weekly Time Allocation for Typical Company:

Use the Organizational Efficiency table from the Configuration section for coding hours per week by company type.

Calendar Weeks Calculation:

Calendar Weeks = Raw Dev Hours / Effective Coding Hrs/Week (from config)

Step 5: Calculate Full Team Cost

Engineering doesn't ship products alone. Use the Role Ratios and Hourly Market Rates by Role from the Configuration section to calculate the fully-loaded team cost.

For each company stage:

1. Look up the role ratio % from the config's Role Ratios table
2. Multiply engineering hours by that % to get each role's hours
3. Multiply each role's hours by the Mid rate from the Hourly Market Rates table
4. Sum all roles for Full Team Cost, or use the Full Team Multiplier shortcut

Calculation:

Full Team Cost = Engineering Cost x Full Team Multiplier (from config)

Step 6: Generate Cost Estimate

Detect the project name from the repository (directory name, package manifest, or top-level config).

IMPORTANT: The report MUST lead with the Executive Summary and Claude ROI at the very top. The detailed breakdowns come after. This is the required report structure:

[Project Name] - Development Cost Estimate

Analysis Date: [Current Date] Scope: [Full codebase / Branch <name> (diff from <base>) / Commit <hash>]

Executive Summary

Claude ROI

Claude worked ~[X] hours and produced $[X] of professional development value = $[X,XXX] per Claude hour

Grand Total Summary

Detailed breakdown follows.

Codebase Metrics

• Total Lines of Code: [number] ([scope context: "in repository" or "in diff"])

  • [Language 1]: [number] lines
  • [Language 2]: [number] lines
  • Tests: [number] lines
  • Config/Build: [number] lines
  • Documentation: [number] lines

• Complexity Factors:

  • [Auto-detected factor 1, e.g. "Audio/video processing pipeline"]
  • [Auto-detected factor 2, e.g. "System extension architecture"]
  • [Auto-detected factor 3, e.g. "Third-party API integrations"]

Development Time Estimate

Base Development Hours: [number] hours

Overhead Multipliers:

• Architecture & Design: +[X]% ([hours] hours)
• Debugging & Troubleshooting: +[X]% ([hours] hours)
• Code Review & Refactoring: +[X]% ([hours] hours)
• Documentation: +[X]% ([hours] hours)
• Integration & Testing: +[X]% ([hours] hours)
• Learning Curve: +[X]% ([hours] hours)

Total Estimated Hours: [number] hours

Sanity Check: [total LOC] / [total hours] = [X] effective lines/hour [PASS: within 15-30 range / ADJUST: outside range, explain adjustment]

Realistic Calendar Time (with Organizational Overhead)

Market Rate Research

Senior Developer Rates (2025):

• Low end: $[X]/hour (remote, mid-level market)
• Average: $[X]/hour (standard US market)
• High end: $[X]/hour (SF Bay Area, NYC, specialized)

Recommended Rate for This Project: $[X]/hour

Rationale: [Based on detected tech stack complexity and specialization requirements]

Total Cost Estimate (Engineering Only)

Recommended Estimate (Engineering Only): $[X,XXX] - $[X,XXX]

Full Team Cost (All Roles)

Role Breakdown (Growth Company Example):

Claude ROI Analysis (Detailed)

Project Timeline:

• First commit / project start: [date]
• Latest commit: [date]
• Total calendar time: [X] days ([X] weeks)

Claude Active Hours Estimate:

• Total sessions identified: [X] sessions
• Estimated active hours: [X] hours
• Method: [git clustering / file timestamps / LOC estimate]

Value per Claude Hour:

Speed vs. Human Developer:

• Estimated human hours for same work: [X] hours
• Claude active hours: [X] hours
• Speed multiplier: [X]x (Claude was [X]x faster)

Cost Comparison:

• Human developer cost: $[X] (at config baseline rate)
• Estimated Claude cost: $[X] (subscription + API)
• Net savings: $[X]
• ROI: [X]x (every $1 spent on Claude produced $[X] of value)

Assumptions

1. Rates based on US market averages (2025)
2. Full-time equivalent allocation for all roles
3. Does not include:
   • Marketing & sales
   • Legal & compliance
   • Office/equipment
   • Hosting/infrastructure
   • Ongoing maintenance post-launch

Step 7: Calculate Claude ROI — Value Per Claude Hour

This is the most important metric for understanding AI-assisted development efficiency. It answers: "What did each hour of Claude's actual working time produce?"

IMPORTANT: The Claude ROI results must appear in TWO places in the report:

1. Executive Summary at the very top (compact table format)
2. Claude ROI Analysis (Detailed) section with full breakdown

Calculate all ROI values in this step, then populate both sections when writing the report.

7a: Determine Actual Claude Clock Time

Run git_session_analyzer.py to automatically cluster commits into sessions and estimate active hours:

python3 .claude/skills/cost-estimate/helpers/git_session_analyzer.py

Review the output sessions and adjust estimates upward for commits with large scope (e.g. a single commit adding thousands of lines likely took 2-4 hours, not 1 hour). Use git show <hash> --stat to check the scope of low-commit sessions.

Fallback (no git): Estimate from LOC using the Claude ROI Constants: Claude active hours = Total LOC / 350 lines/hr

7b: Calculate ROI

Pass --claude-hours to cost_calculator.py (in Step 2) to get the full ROI breakdown automatically. The calculator computes speed multiplier, value per Claude hour, cost comparison, and savings.

Notes

Present the estimate in a clear, professional format suitable for sharing with stakeholders. Include confidence intervals and key assumptions. Highlight areas of highest complexity that drive cost.

IMPORTANT — Dollar Sign Escaping: Always escape $ as \$ in the final markdown report. Bare $ characters are interpreted as LaTeX math delimiters by many markdown renderers (GitHub, VS Code, etc.), which mangles currency values. The report_generator.py fmt() function handles this automatically, but when writing prose sections manually (e.g., market rate research, rationale text, assumptions), always use \$ for currency.