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.
- Discover — live search against the Freelancer.com REST API.
- Research is scoped to your stacks —
ffetches for the stacks on your profile, and thesmenu offers exactly those to filter by (Spacetoggles,Enterapplies; 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+Ssaves to the DB,Esccancels. - Steer the AI —
Ggenerates with a custom instruction you type ("keep it under 3 sentences", "emphasize my fintech work");lpicks the proposal language (English, French, Arabic, …). Language + instruction apply to the LLM path (the template fallback stays English). - Override the price —
psets the bid manually asamount,amount/daysoramount/days/milestone%(e.g.450,450/7,450/7/30), overriding the recommendation. - A profile you fill in from inside the app — press
Pto view it, theneto 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+Swrites it back tojobwatcher.toml(keeping a.bak) and hands it to the running engine — no restart. Your savedstacksare pre-selected in the filter and auto-fetched on launch. - Pre-fill it from the platform —
iin 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/nconfirmation 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 withm, scan now withM, 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.Hhides the terminal and keeps the monitor running behind the icon, andmonitor.start_hidden = trueboots 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-checkverifies it. - Persist & measure — jobs and proposals stored in SQLite; a pipeline/analytics view (drafts → submitted → interviewing → won/lost, win rate).
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
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_onlyadapters (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.
cp .env.example .env
# edit .env: set FREELANCER_OAUTH_TOKEN (required) and OPENROUTER_API_KEY (optional)
cargo run --releaseThere'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 workedOn 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.
| 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.
- 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.
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/napproval — 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_minutesand can spend LLM credits on each auto-draft. Both are capped and configurable; pause it withmor setmonitor.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.
New platforms are just adapters — implement adapters::PlatformAdapter and advertise honest
Capabilities. Issues and PRs welcome.
Licensed under the MIT License.