DevHQ Documentation

Everything you need to know about protecting your time and getting paid properly.

📖 Overview

DevHQ is the financial and technical guardrail for developers. It automates retainer monitoring and git access control to ensure you get paid for your work.

💡 Core Philosophy

DevHQ acts as an impartial enforcer between you and your client. When the retainer runs dry, commit access stops automatically. No more awkward conversations about unpaid invoices.

How It Works

  1. Connect Repository: Link your GitHub/GitLab repository and set your hourly rate
  2. Invite Client: Client adds their payment method and makes an initial retainer deposit
  3. Start Coding: Work as usual - time is tracked automatically via CLI or manual entries
  4. Auto-Protection: If funds run out, the repository locks automatically until replenishment

🚀 Quick Start

1. Create Your Account

Sign up at devhq.site and complete your profile setup.

2. Create a Project

  1. Go to Projects → New Project
  2. Enter project details and set your hourly rate
  3. Add a project prefix (e.g., "WEB" for tracking codes)
  4. Connect your Git repository

3. Invite Your Client

  1. Add client details in the Clients section
  2. Send them a contract via DevHQ
  3. Client signs contract and adds payment method
  4. Initial retainer is charged automatically

4. Start Tracking Time

# Install the CLI curl -fsSL https://www.devhq.site/cli/install.sh | sh # Configure your API token devhq config set api-token YOUR_TOKEN # Start tracking devhq start WEB-001

🎯 Key Concepts

Retainer-Based Billing

DevHQ uses a retainer model where clients pre-fund work. As you log hours, the retainer depletes. When it reaches a threshold (default 20%), clients are automatically charged to refill it.

Tracking Codes

Each deliverable gets a unique tracking code (e.g., WEB-001, API-042). Use these codes in:

  • Git branch names: deliverable/WEB-001-feature
  • Commit messages: [WEB-001] Implement feature
  • CLI commands: devhq start WEB-001

Auto-Pause Protection

When budget falls below the threshold or runs out completely:

  • Repository access is automatically revoked
  • Client receives notification to refill retainer
  • Access restores automatically upon payment
  • No manual intervention required

🔒 Git Access Control

DevHQ's signature feature - automatic repository access management based on budget status.

How It Works

  1. Integration: Connect your GitHub/GitLab account via OAuth
  2. Repository Link: Associate a repository with your project
  3. Client Access: Client is added as a collaborator automatically
  4. Budget Monitoring: System tracks budget in real-time
  5. Auto-Lock: When budget hits threshold, client access is revoked
  6. Auto-Unlock: Access restores when payment is received
⚠️ Important

You maintain full repository access at all times. Only client access is controlled by budget status.

Supported Platforms

🐙
GitHub
Full support for public and private repositories
🦊
GitLab
Self-hosted and GitLab.com supported

💳 Auto-Refill Retainers

Never wait for checks. Clients are automatically charged when hours run low.

Configuration

  • Threshold: Set when auto-refill triggers (default: 20% remaining)
  • Refill Amount: How much to charge (default: initial retainer amount)
  • Payment Method: Client's saved card is charged automatically

Notification Flow

  1. Budget reaches threshold → Client receives warning email
  2. Auto-charge is attempted
  3. Success → Budget replenished, work continues
  4. Failure → Repository locked, client notified to update payment

⏱️ Time Tracking

Track time manually via the web app or automatically via the CLI tool.

Manual Time Tracking

  1. Go to Time Tracker in the web app
  2. Select a deliverable
  3. Click "Start Session"
  4. Work on your task
  5. Click "Stop" when done

CLI Time Tracking (Recommended)

The CLI tool provides seamless time tracking from your terminal:

# Start tracking devhq start WEB-001 # Check status devhq status # Pause session devhq pause # Resume session devhq resume # Stop session devhq stop

Git-Based Time Tracking

DevHQ can automatically calculate time from your Git commits:

  • Detects commits with tracking codes
  • Groups commits into work sessions
  • Calculates time based on commit timestamps
  • Creates pending time entries for review
  • You approve or adjust before finalizing
💡 Smart Time Calculation

Sessions are grouped with a 2-hour max gap. Minimum commit time is 15 minutes, maximum session time is 8 hours per day.

👥 Client Portal

Give clients transparency into where their money is going.

Features

  • Budget Overview: See remaining balance and burn rate
  • Time Entries: View all logged hours with descriptions
  • Deliverables: Track progress on each deliverable
  • Invoices: Access all invoices and payment history
  • Change Requests: Submit and approve scope changes

Access

Clients receive a magic link via email after contract signing. No password required - just click the link to access their portal.

🛠️ CLI Installation

macOS / Linux

curl -fsSL https://www.devhq.site/cli/install.sh | sh

Windows

curl -fsSL https://www.devhq.site/cli/install-windows.ps1 | powershell

Verify Installation

devhq --version

Configuration

  1. Get your API token from Settings → CLI Tokens in the web app
  2. Configure the CLI:
devhq config set api-token YOUR_TOKEN_HERE devhq config set api-url https://api.devhq.site

📝 CLI Commands

Session Management

# Start a new session devhq start <tracking-code> # Stop active session devhq stop # Pause session devhq pause [tracking-code] # Resume paused session devhq resume [tracking-code] # View all active sessions devhq status # Sync with backend devhq sync

Configuration

# Set API token devhq config set api-token <token> # Set API URL devhq config set api-url <url> # View current config devhq config list # Show version devhq version

🔄 CLI Workflow

Typical Development Session

# 1. Start tracking for a deliverable devhq start WEB-001 # 2. Create a branch with the tracking code git checkout -b deliverable/WEB-001-auth-feature # 3. Work on your feature # ... code, code, code ... # 4. Commit with tracking code git commit -m "[WEB-001] Implement login form" # 5. More work and commits git commit -m "[WEB-001] Add validation" # 6. Stop tracking when done devhq stop # Time is automatically synced to DevHQ

Multi-Tasking

# Start session for WEB-001 devhq start WEB-001 # Need to switch to urgent task devhq pause WEB-001 devhq start WEB-002 # Work on WEB-002 # ... # Back to WEB-001 devhq stop devhq resume WEB-001

🔗 Git Integration

Setup

  1. Go to Integrations in the web app
  2. Click "Connect GitHub" or "Connect GitLab"
  3. Authorize DevHQ to access your repositories
  4. Select repositories to link with projects

Tracking Code Patterns

DevHQ recognizes tracking codes in:

Branch Names

deliverable/WEB-001-feature-name feature/WEB-001-description WEB-001-anything

Commit Messages

[WEB-001] Implement feature WEB-001: Fix bug feat(WEB-001): Add component

Automatic Time Calculation

When you push commits with tracking codes:

  1. DevHQ detects the commits via webhook
  2. Extracts tracking codes from branches/messages
  3. Groups commits into work sessions
  4. Calculates time based on commit timestamps
  5. Creates pending time entries
  6. You review and approve in the web app

🔔 Webhooks & Events

DevHQ uses webhooks and real-time events to keep everything in sync.

Webhook Events

  • contract.signed - Contract signed by client
  • contract.declined - Contract declined by client
  • payment.received - Payment successfully processed
  • payment.failed - Payment failed
  • budget.low - Budget below threshold
  • budget.depleted - Budget completely used
  • repository.locked - Access revoked
  • repository.unlocked - Access restored

Real-Time Updates

The web app uses WebSocket connections for instant updates:

  • Time session changes
  • Budget updates
  • Contract status changes
  • Payment notifications

🔌 API Reference

DevHQ provides a REST API for integrations.

Authentication

All API requests require a Bearer token:

Authorization: Bearer YOUR_API_TOKEN

Base URL

https://api.devhq.site

Common Endpoints

Projects

GET /api/projects # List all projects POST /api/projects # Create project GET /api/projects/:id # Get project details PATCH /api/projects/:id # Update project DELETE /api/projects/:id # Delete project

Time Sessions

GET /api/time-sessions # List sessions POST /api/time-sessions # Create session POST /api/time-sessions/:id/stop # Stop session POST /api/time-sessions/:id/pause # Pause session

Deliverables

GET /api/projects/:id/deliverables # List deliverables POST /api/projects/:id/deliverables # Create deliverable PATCH /api/deliverables/:id # Update deliverable DELETE /api/deliverables/:id # Delete deliverable
✅ Ready to Get Started?

Head over to devhq.site to join the waitlist and be among the first to stop chasing invoices!

💬 Support

Need help? We're here for you:

  • Email: support@devhq.site
  • Documentation: docs.devhq.site
  • Status: status.devhq.site