Freelancer OS

Inspiration

Solo freelancers lose hours before paid work even begins: reviewing listings they have found, checking fit, estimating scope, pricing, drafting proposals, tracking approvals, and preserving enough context to deliver safely. Existing automation often optimizes for speed while hiding uncertainty or taking actions too early.

Freelancer OS was built around a different rule: the user chooses and imports job offers, while the system automates repetitive analysis and preparation but fails closed whenever evidence, approval, pricing, identity, or transport is uncertain.

What it does

Freelancer OS is a local-first operating system for the freelance workflow:

• the user selects job offers and imports their details into the local system;
• the application validates and deduplicates imported offers;
• it scores technical fit, economics, scope clarity, client risk, delivery feasibility, and portfolio value;
• it routes offers through specialized evaluator, planner, proposal, quality, and audit roles;
• it calculates bounded commercial terms from approved scope and hourly-rate rules;
• it generates implementation plans and client-ready proposals;
• it validates drafts for hallucinated claims, unsupported technology, unsafe commitments, secret requests, inconsistent pricing, and missing questions;
• it keeps every external action behind review, approval, snapshot-hash, draft-file, pricing, risk, and transport gates;
• it supports DRY_RUN, SHADOW_MODE, SUPERVISED_SEND, and AUTONOMOUS_SEND with evidence-based promotion between modes;
• it submits an approved Useme proposal only through an already-running authenticated Chrome session, never by launching a new profile or automating login;
• it stops on CAPTCHA, MFA, authentication ambiguity, closed listings, changed approvals, mismatched drafts, or uncertain delivery confirmation;
• it starts isolated Codex project work only after a signed contract;
• it tracks leads, projects, scope, conversations, costs, outcomes, backups, GDPR deletion, and append-only audit evidence in one local dashboard.

SQLite is the source of truth. The browser UI runs locally at 127.0.0.1, and runtime data stays on the user's machine. API keys and platform credentials are stored in Windows Credential Manager rather than SQLite, logs, reports, backups, or .env files.

How Codex and GPT-5.6 were used

Codex with GPT-5.6 served as the primary engineering collaborator across repository inspection, implementation, debugging, test generation, safety review, and long-running handoffs. Instead of treating the model as a one-shot code generator, the project used Codex as an auditable development loop:

1. inspect current code, SQLite state, logs, and frozen evidence;
2. identify the smallest shared root-cause fix;
3. implement a narrow change;
4. run focused regression tests, then the full suite;
5. record files, commands, decisions, blockers, and the next safe step in an append-only implementation log.

Codex accelerated difficult cross-cutting work such as approval-hash enforcement, fail-closed transport, autonomous pilot accounting, prompt calibration, Windows UI Automation repair, message correlation, secret-safe backups, and regression coverage. Human decisions remained authoritative for offer selection, labels, legal or data-processing risk, pricing exceptions, pilot promotion, and any ambiguous external action.

The runtime agent pipeline can use OpenRouter models for offer evaluation, planning, and proposal drafting. Availability errors such as quota limits are represented as WAITING_FOR_MODEL, not silently converted into approvals or negative model results.

How it was built

The application is intentionally dependency-light: Python 3.11 standard library, SQLite, a local ThreadingHTTPServer dashboard, HTML/CSS/JavaScript, PowerShell, Chrome DevTools Protocol, and optional Windows UI Automation.

Core architecture:

• SQLite-backed domain state and migrations;
• deterministic scoring, pricing, approval, hash, and audit gates;
• specialized agent roles with validated structured outputs;
• local workspace files for Codex task handoff;
• idempotent jobs and send attempts;
• frozen payloads and canonical label hashes for evaluation;
• secret scanning and sanitized backup creation;
• explicit contract, scope, cost, communication, and delivery state.

Safety and validation

Autonomy had to earn its permissions. The approved 50-offer dry-run cohort used offers imported and frozen by the owner, and achieved:

• 50/50 frozen extractions;
• 50/50 fail-closed decision safety;
• 0 unsafe approvals;
• 2/2 valid applicable plans;
• 0 prohibited external events.

A separate 20-offer calibration set reached 20/20 safety agreement, 18/20 exact decisions, 18/20 feasibility agreement, 0 unsafe approvals, and 0 availability failures. Shadow-mode trials produced two 100/100 drafts with zero send attempts. A supervised live proposal then proved the approval and transport chain before autonomous operation was enabled.

Latest full verification recorded 387 passing tests with one skipped test, plus successful compilation. Coverage includes migrations, imported-offer validation, scoring, model availability, prompt guardrails, approval hashes, draft-file integrity, pricing, pilot readiness, transport confirmation, closed listings, no-retry behavior, signed-contract gates, message routing, backups, GDPR deletion, and GUI workflows.

Challenges

The hardest problems were not generating text. They were proving when the system must refuse to act:

• incomplete or stale offer data supplied to the system;
• model hallucinations and malformed structured output;
• quota and provider availability;
• preventing benchmark leakage and optimistic retry scoring;
• ensuring approved price, timeline, and proposal text cannot change before submission;
• distinguishing a successful browser transition from a confirmed platform submission;
• reusing an authenticated session without automating credentials or login;
• preserving privacy while keeping enough audit evidence to debug failures.

Several fixes came from real fail-closed stops. For example, UI Automation once mistook ordinary offer text about login for an authentication challenge, and another proposal could not reach the summary because a required copyright choice was missing. Codex traced both root causes, added narrow guards, and left regression tests and audit evidence behind.

Accomplishments

• End-to-end workflow from a user-imported offer to guarded proposal submission and post-contract Codex handoff.
• Local-first data model with append-only audit history and secret-safe backups.
• Evidence-driven autonomy modes instead of a single unsafe on/off switch.
• Immutable approval provenance tying structured commercial terms to exact draft content.
• Fail-closed handling for model, browser, platform, pricing, legal, and authentication uncertainty.
• Measured calibration and pilot reports that preserve failures instead of hiding them.
• Runnable Windows CLI and local dashboard without a web framework or hosted backend.

Run locally

Requirements: Windows, Python 3.11+, and Git on PATH.

py -m freelance_os --help
py -m freelance_os gui

Open http://127.0.0.1:8787/.

Run verification:

py -m compileall freelance_os tests
py -m unittest discover -s tests -v

The dashboard works in manual mode without an API key. Model-backed features require an OpenRouter key. Live Useme transport additionally requires an already-running authenticated Chrome session and all safety gates to pass. Judges can import sample offer text themselves and test the dashboard, scoring, approvals, dry-run mode, reports, backups, and audit behavior without sending a proposal.

What we learned

Reliable agentic software needs explicit states for uncertainty, availability, approval, and evidence. A model response is not permission. A browser click is not proof of submission. A passing test suite is not enough when the specification or audit trail is incomplete.

Codex was most valuable when paired with user-selected inputs, durable local state, narrow tasks, executable checks, and persistent handoffs. That combination turned model assistance into a repeatable engineering process rather than a sequence of disconnected prompts.

What's next

• complete a real signed-contract-to-delivery cycle;
• add judge-friendly sample data and a scripted sandbox walkthrough;
• improve user-driven import formats while preserving validation and deduplication;
• improve model routing and cost analytics;
• validate live post-contract client/Codex question routing;
• package the local dashboard for simpler installation.

Built With

• chrome-devtools-protocol
• codex
• css
• gpt-5.6
• html
• javascript
• openrouter
• powershell
• python-3.11
• sqlite
• windows-credential-manager
• windows-ui-automation