Tracking time and managing projects

Every project in The Contractor Codex has a budget, a pricing profile, and a set of work sessions logged against it. This page covers the day-to-day flow.

Where projects come from

Three sources:

Auto-created from a quote — when a client accepts a quote, a project spawns with budget = quote total and the quote's title as the project name (default; configurable per org).
Manually created — from a client's workspace, click New Project. Set name, description, pricing profile, optional deadline, and budget.
Imported — not currently supported in the UI; contact support for bulk imports.

Pricing profiles

Each project has a pricing profile that controls how billable time is priced. Pick one when creating the project:

Hourly — flat hourly rate. Set rate at creation.
Block — fixed-fee package (e.g., "Logo Design Package, $1500"). Time tracked is informational.
Retainer — fixed monthly fee with included hours. Overage hours bill at a per-hour overage rate.
General Services — flat or range-bounded fee for service work.

Pricing rates are locked at project creation — they don't change if your org-level pricing catalog changes later. This is intentional: the agreed price stays the agreed price.

Manage your org-wide pricing catalog at /admin/pricing.

Starting and stopping work

From the admin project view, click the green Start Work button. A session begins, the timer runs in the background, and the project shows a "Live now" pill.

When you're done, click Stop Work. You'll be prompted for a work note (required) — a short description of what you accomplished. This note goes to the client in their notification email so they know what they're paying for.

You can also:

Mark a session non-billable at start time — billable work time is what shows on invoices; non-billable is internal.
Override the rate multiplier on a session — e.g., 1.5x for overtime, 0.5x for a discount. Multiplier shows on the session card and is applied when calculating invoice values.
Set start/stop times manually — if you forgot to start the timer, you can backdate the session.

What clients see

Clients see their projects in the /dashboard/projects tab with:

Billable hours tracked — total billable time across all sessions.
Total hours — billable + non-billable.
Session list — each session with start/end, billable status, rate multiplier (if any), the work note, and any feedback they left.

Clients can leave a 1–5 star rating + comment on each session for feedback purposes. These show up on your admin view too.

Project deadlines

Set a deadline at creation or later. The portal:

Shows the deadline as a chip on the project card.
Color-codes it red when overdue, amber within 7 days.
Auto-creates a calendar event on the project's calendar feed (if you connected Google Calendar).

Budget tracking

If you set a budget on the project, the portal tracks tracked billable value (hours × rate, accounting for multipliers and pricing profile) against the budget cap and shows:

A progress bar at the top of the project card
A green/amber/red status based on % used
A warning when you exceed 80%
An "Over budget" alert when you cross 100%

Once a project crosses 100%, billable work stops until the client approves additional spending. See Approvals and surcharges.

Non-billable work continues — you can still log time, it just doesn't accumulate against the budget.

Project status

Three states, all derived from data (no manual status):

Active — completedAt = null, the customer isn't archived.
In Progress — Active AND has a currently-running work session.
Completed — completedAt != null. Mark this from the project actions menu when work is done.

Completing a project:

Sets completedAt to now.
Prompts you for a completion note (the deliverable summary) — saved on the project and surfaced on the client's completed-project card.
For projects in draft for completion or deposit + draft billing mode, this is when you'd click Finalize & send on the balance invoice.

Project sections in the workspace

Open a project in the admin client workspace and you'll see collapsible sections:

Pricing & Metrics — billing profile, total billed, paid, outstanding, billable hours.
Approval Status — any blocking approvals.
Work Session — start/stop controls + open session.
Client Notes — threaded conversation with the client about this project.
Requests — delivery requests / change orders against the project.
Invoices — every invoice tied to this project.
Documents — files uploaded to this project specifically.
Recurring Product Costs — heads-up disclosure of ongoing third-party costs the client will pay directly (cloud, AI APIs, SaaS, hosting). Not billed through you.
Surcharges — one-off or recurring extras.
Discounts — applied discounts (off the project total).
Recent Sessions — last 6 work sessions with notes + feedback.
Team on Project — admins who logged time on this project.
Calendar — events tied to this project (if connected).

Each section auto-expands when it has something needing attention.

Dictation for work notes

The work note field (required when stopping a session) supports voice dictation via the browser's Web Speech Recognition API. Click the microphone icon next to the field and speak your note — the transcript is filled in as you talk.

You can also use the "Organize with AI" button to take a raw rambling transcript and structure it into a clean, professional work note. The button calls the platform's AI dictation endpoint and replaces the raw text with a cleaned-up version. Undo restores the original if you don't like the AI's pass.

This is useful when you stop work between jobs (driving back from a site, walking between meetings) and want to capture what happened without typing.

Manual session corrections

If you forgot to start a session, or the system clocked the wrong stop time, you can correct it after the fact:

Open the project in the admin workspace.
Find the session in the Recent Sessions list.
Click Edit on the session.
Adjust startedAt, endedAt, isBillable, or the rate override.
Save.

The audit log records every edit, including who made it and the previous values. Clients see the corrected session next time they refresh their portal — they don't get a notification about the edit unless you tell them.

For complex corrections (e.g., you logged a 4-hour session that should have been split into two 2-hour sessions on different projects), the cleanest path is:

Delete the misattributed session.
Manually create two new sessions with the correct start/stop times via the Add Session button on each project.

Live session indicator

When a session is running, the portal shows several visual cues:

A green pulsing dot on the project card.
A "Live now" pill in the session list.
A ticker at the top of the customer's portal saying "Work in progress on [Project Name]".
A counter in the customer's dashboard showing "1 session running".

These all update in real time via the /api/session-status poll (the customer's portal polls every few seconds). If you stop a session, the indicators clear within a few seconds.

Calendar push

If you've connected Google Calendar (see Calendar and client visibility), every work session you log is automatically pushed to your calendar as a timed event. The event:

Title: "Work session — [Project Name]"
Time: matches your session's start + stop.
Description: includes the work note.
Calendar: whichever calendar you selected during integration setup (default: your primary).

You can edit the calendar event in Google Calendar — those edits don't flow back to the portal (one-way sync). To fix the work session itself, edit it in the portal.

To stop calendar push for work sessions specifically, untick the toggle in Settings → Calendar.

Rate multiplier overrides

Each session can have a custom rate multiplier applied at start time:

1.0x (default) — normal billing rate from the pricing profile.
1.5x — typical "overtime" rate.
2.0x — emergency/rush work.
0.5x — half-rate discount.
0.0x — non-billable (equivalent to ticking the non-billable box).

The multiplier applies to that session's billable value when calculating invoice amounts. It shows up:

As a pill on the session card ("1.5x rate")
In the line item description on the invoice ("Consulting at 1.5x rate")
In the work-stopped notification email to the client

Use this for transparently billing premium time without changing the project's base rate.

Budget extensions in practice

When a project crosses 100% of its budget, billable work is paused. To resume:

Option A: Request an extension from the client (recommended)

From the project's Approval Status section, click Request approval.
Pick Budget extension and enter the extra dollars you need.
Add a message explaining why.
The client gets an email + sees the request in their portal.
When they approve, the project's effective budget grows by the approved amount and billable work resumes.

Option B: Override the budget yourself

If you have a verbal agreement with the client and don't want to send a formal approval request, you can directly increase the budget in the project's settings. The audit log records the override with a note that no client approval was attached, which protects you and the client if there's ever a dispute.

Use Option A whenever you can — it's a paper trail that protects you legally.

Time tracking for retainer projects

Retainer-style projects (with included hours + an overage rate) work slightly differently:

The first N hours are "included" — they count toward the retainer fee, no per-hour billing.
Hours beyond N bill at the overage rate.

The portal tracks both separately:

Included used / remaining — shows on the project card.
Overage hours + value — appears once you cross the included threshold.

For a 10-hour retainer at $100/hr base + $150/hr overage:

Hours 1–10: counted against the retainer (no per-hour charge; the retainer fee already covers them).
Hours 11+: $150/hr, accruing against the overage sub-total.

You bill the retainer fee separately (via recurring invoice) and bill overage hours at month-end via a manual invoice.

Active session safety

Only one work session can be running per project at a time. If you click Start Work while a session is already open, the portal blocks it with an error.

If you have a stuck session (e.g., the browser tab crashed before you could stop it), open the project and click Stop Work — even days later. The portal lets you set a stop time manually, so you can backdate to when you actually stopped working.

Time tracking across multiple admins

If multiple admins work on the same project, each session records createdByClerkId — the admin who logged it. The project's Team on Project section in the admin workspace shows distinct admins with session counts and total time.

There's no enforcement that "only one admin can have a live session" — two admins can both be working on the same project at the same time. Their sessions are tracked independently.