Skip to content

About

AI Freelance Agent — a Rust TUI that discovers, ranks, and drafts proposals for freelance projects. Freelancer.com adapter, OpenRouter, SQLite. You approve every bid.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

jobwatcher — AI Freelance Agent

Rust License: MIT Platform

A terminal AI agent that discovers freelance projects, ranks them against your profile, drafts personalized proposals, and — only after you approve — submits bids through a platform's official API.

This repo is the vertical slice: one platform working end-to-end, proving the whole pipeline before breadth. Stack: Rust + ratatui TUI + OpenRouter, SQLite for state.

What works today

  • Discover — live search against the Freelancer.com REST API.
  • Research is scoped to your stacks — f fetches for the stacks on your profile, and the s menu offers exactly those to filter by (Space toggles, Enter applies; results across several stacks are merged, deduped and co-ranked, matching any selected one). The full catalog only appears in the profile editor, where you choose which stacks are yours. A profile that names none narrows nothing, so everything is back in scope.
  • Rank — deterministic skills-based scoring (overlap · budget fit · competition · recency).
  • Draft — proposal generation via OpenRouter (any model), with a solid template fallback when no key is set.
  • Edit — revise any proposal by hand in a built-in multi-line editor (e): full cursor movement, insert/delete, line splitting, UTF-8 safe; Ctrl+S saves to the DB, Esc cancels.
  • Steer the AI — G generates with a custom instruction you type ("keep it under 3 sentences", "emphasize my fintech work"); l picks the proposal language (English, French, Arabic, …). Language + instruction apply to the LLM path (the template fallback stays English).
  • Override the price — p sets the bid manually as amount, amount/days or amount/days/milestone% (e.g. 450, 450/7, 450/7/30), overriding the recommendation.
  • A profile you fill in from inside the app — press P to view it, then e to edit it in place: identity, years of experience, location, timezone, availability, rate, minimum budget, bio, core skills, tools, industries, spoken languages, certifications, education, differentiators, client feedback, links, roles held (with highlights and the tech used) and portfolio entries (with role, year, outcome, link and tech). Ctrl+S writes it back to jobwatcher.toml (keeping a .bak) and hands it to the running engine — no restart. Your saved stacks are pre-selected in the filter and auto-fetched on launch.
  • Pre-fill it from the platform — i in the profile editor reads your freelancer.com profile (name, bio, years of experience parsed from it, location, timezone, rate, currency, language, skills, and your portfolio entries) and shows a preview of every field it would change before touching anything. The merge never deletes: absent fields are left alone, lists are unioned with what you typed, and portfolio entries are matched by title, so re-running it later is safe.
  • Everything you enter reaches the AI — the whole profile is formatted into a dossier for the proposal prompt, with the roles and portfolio entries most relevant to this job picked by skill overlap, and the model told to ground every claim in it and invent nothing. Skills named only inside a role or portfolio entry also count in job matching, so filling in real experience changes which jobs surface.
  • Price — bid amount + delivery estimate from the job budget and your profile.
  • Access gates & verification — detects project gates from the platform (NDA, IP agreement, Preferred-Freelancer-only, required qualifications, sealed) and your account's verification status (payment / email / phone / identity). Gated jobs stay visible with red badges, but auto-bid is blocked with the reason. The agent never signs an NDA or IP agreement — those are deferred to you on the platform.
  • Approve → Submit — a y/n confirmation gates every bid; on approval the adapter places the bid via the official API. Nothing is ever sent silently.
  • Milestones that actually land — every bid carries a first-milestone share (your profile default, overridable per bid with p), always sent as a whole number in 1–100. After submitting, the agent reads the bid back from the platform and reports the milestone the platform actually stored; if it came back empty it retries via the bid update endpoint and tells you plainly when it still couldn't set it.
  • Watch in the background — a monitor polls your saved stacks on an interval (default every 10 min), scores each posting against your profile and experience, and flags the ones at or above your threshold (default 75) with a ★. Postings already in your database are never announced as new, so you only see what actually just appeared.
  • Auto-drafted proposals — every flagged job gets a proposal written for it automatically (marked ✎), capped per scan so a busy hour can't run up your LLM bill. It only ever drafts — bidding still needs your y/n. Pause with m, scan now with M, tune the interval/threshold/cap in the profile editor.
  • Lives in the tray — hover the icon for the countdown to the next scan (next scan in 7m, scanning now…, writing 2 proposal(s)…) plus how many finds and drafts are waiting; it turns amber when something needs review. The menu shows/hides the window, scans now, pauses the monitor or quits. H hides the terminal and keeps the monitor running behind the icon, and monitor.start_hidden = true boots straight into the tray (ignored unless an icon exists, so you can't end up with no way back). Windows only — elsewhere the app just runs without an icon; jobwatcher tray-check verifies it.
  • Persist & measure — jobs and proposals stored in SQLite; a pipeline/analytics view (drafts → submitted → interviewing → won/lost, win rate).

Architecture

Every platform is an adapter implementing one trait (adapters::PlatformAdapter) and advertising honest capabilities (can_search / can_submit / read_only). The core engine only talks to the trait, so new platforms never touch ranking/proposal/pricing.

src/
  domain.rs      platform-neutral types (Job, Proposal, Profile, …)
  adapters/      the trait + capability flags
    freelancer.rs  live search + bid submission
  ranking.rs     skills-based scoring
  pricing.rs     bid + delivery recommendation
  proposal.rs    LLM proposal generation (+ template fallback)
  llm.rs         OpenRouter client
  store.rs       SQLite persistence + analytics
  engine.rs      async worker (network/LLM) + background monitor, behind channels
  tui.rs         ratatui UI + approval flow
  profile_edit.rs the in-app profile/monitor form
  tray.rs        system-tray icon + hide-to-tray (Windows)
  config.rs      config file + env secrets

On the other platforms

The adapter interface is designed for all of Upwork, Contra, Toptal, Guru, Wellfound, LinkedIn, RemoteOK, We Work Remotely, Arc.dev, Braintrust, and FlexJobs — but they differ sharply in what they permit:

  • Official API incl. bidding: Freelancer.com (done), Upwork (needs an approved app + client OAuth).
  • Read-only public feeds: RemoteOK, We Work Remotely, Wellfound, Arc.dev — these get read_only adapters (search + draft, submit manually).
  • No usable/permitted API: Toptal, Braintrust, FlexJobs, Contra, LinkedIn Jobs. Scraping these violates their ToS, so no scraper adapters ship without an explicit agreement.

Setup

cp .env.example .env
# edit .env: set FREELANCER_OAUTH_TOKEN (required) and OPENROUTER_API_KEY (optional)
cargo run --release

There's also a headless mode (handy for scripting / verifying without the TUI):

cargo run -- search rust        # fetch + rank + print
cargo run -- stack laravel      # search by a stack term, filter to its keywords
cargo run -- stack react,rust   # multiple stacks: merge searches, match any
cargo run -- stacks             # list configured stacks
cargo run -- tray-check         # put a tray icon up for 5s and report what worked

On first run a jobwatcher.toml config is written. Fill in your profile from inside the app (P, then e) — that's the single biggest lever on proposal quality — or edit the file by hand; every [profile] key is optional, so a partial file loads fine. The [[stacks]] list lives there too. The LLM model defaults to anthropic/claude-sonnet-5 via OpenRouter — change llm.model to any OpenRouter slug. Without an OPENROUTER_API_KEY, proposals fall back to the (English-only) template.

The config lives at ./jobwatcher.toml if present, otherwise in your platform config dir (%APPDATA%\jobwatcher\jobwatcher\config\ on Windows, ~/.config/jobwatcher/ on Linux). The profile editor reports the exact path when it saves.

Set freelancer.sandbox = true in the config to target Freelancer's sandbox host while testing bids.

Keys

key action
f fetch jobs for the stacks on your profile
/ search with a text query
s filter by your stacks (multi-select: Space toggle, Enter apply)
j/k or ↑/↓ move selection
o open the selected job in your browser
g generate a proposal for the selected job
G generate with a custom AI instruction you type
l choose the proposal language
e edit the proposal by hand (Ctrl+S save · Esc cancel)
p set the bid (amount, amount/days, amount/days/milestone%)
b bid — approve the proposal, then submit (with confirmation)
P view your profile — then e to edit it
m pause / resume the background monitor
M scan for new jobs right now
H hide to the tray (the monitor keeps running)
t analytics / pipeline stats
? help
q / Esc quit

In the job list, ★ marks something the monitor just found and you haven't looked at yet, and ✎ marks a proposal it drafted for you. While the AI is actually writing, that row turns magenta and the status bar counts the drafts in flight (✎2) — next to the countdown to the next scan (●7m≥75).

Inside the profile editor: j/k move · Enter edits a field, opens an entry or adds one · i pre-fills from your platform profile (with a preview) · d deletes the highlighted entry · Ctrl+S saves to jobwatcher.toml · Esc steps out of an entry, then closes (asking first if there's unsaved work). Short fields open a one-line prompt; the bio and every list (skills, tools, highlights…) open the multi-line editor, one item per line.

New platforms get profile import for free by implementing the optional PlatformAdapter::fetch_profile; adapters that don't just return None.

Not built yet (next milestones)

  • Additional adapters (Upwork write path; read-only feeds).
  • Learning loop: feed won/lost outcomes back into ranking and pricing.
  • Interview/contract/invoice tracking beyond the proposal lifecycle.

Disclaimer

This is an assistant, not an auto-bidder-at-any-cost. Use it responsibly:

  • Respect platform Terms of Service. Only adapters using official, permitted APIs are included. No scrapers ship for platforms that forbid automated access.
  • You are in control. Nothing is ever submitted without your explicit y/n approval — the background monitor writes drafts and nothing else — and the agent never signs an NDA or IP agreement; those are deferred to you.
  • Mind the polling. The monitor calls the platform API every interval_minutes and can spend LLM credits on each auto-draft. Both are capped and configurable; pause it with m or set monitor.enabled = false.
  • Bring your own keys. You supply your own Freelancer OAuth token and (optional) OpenRouter key via environment variables. No credentials are bundled.
  • Provided "as is", without warranty. You are responsible for what you submit.

Contributing

New platforms are just adapters — implement adapters::PlatformAdapter and advertise honest Capabilities. Issues and PRs welcome.

License

Licensed under the MIT License.

About

AI Freelance Agent — a Rust TUI that discovers, ranks, and drafts proposals for freelance projects. Freelancer.com adapter, OpenRouter, SQLite. You approve every bid.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages