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 start and end dates, 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.

Start and end dates

Every project can carry an optional start date and end date. The end date is the deadline: it shows as a chip on the project card, turns amber within 7 days and red when overdue, and lands on the calendar. Set both at creation or later from Client Actions, then Budgets & dates.

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.

Completed projects keep their full card. Everything the project tracked stays browsable in place: sessions, invoices, notes, and files. Only controls that create new work or new charges are hidden. If work resumes, click Reopen Project on the completed banner: the project moves back to the active list so you can log time and bill again, and nothing is deleted. You don't need to reopen just to look around.

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 linked to this project, split into Upcoming and Past, with an Add to calendar form for quick all-day entries (pushed to Google when your calendar is 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, disconnect Google Calendar 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: Let the client approve more (recommended)

You don't raise the budget request yourself, and there's no button for it. Once billable work passes 80% of the cap, the portal creates the request and emails the client, and the project's Approval Status section shows it sitting with them.

The client types in how much extra spending they're approving, so they can approve less than you hoped for. Whatever they approve is added on top of the original budget, which is never edited, and billable work resumes as soon as there's room under the new cap. When the approved extra gets used up, the request goes back to pending and the client gets a fresh email.

If what you need is extra hours rather than extra dollars, open the client's page, click Client Actions, then Request hours.

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 from the client page: open Client Actions, then Budgets & dates, and edit the project's budget (the same modal also edits start and end dates). 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

Every session records the admin who started it. The project's Team on Project section in the admin workspace lists those admins with their session counts and total time.

Only one session can be open on a project at a time, whoever started it. If a teammate has one running and you click Start Work on that same project, the portal blocks it with "A session is already running on this project." Two admins can be on the clock at the same moment, just not on the same project.

Any admin with write access can stop an open session, including one a teammate started, so a session left running by mistake never blocks the rest of the team.