Career-Terminal

Career-Terminal is a local-first job application operations toolkit powered by Ollama.

Fork Notice

This repository is a fork and has been modified from the upstream concept to run with a local Ollama stack.

Key fork changes:

• Ollama-first execution (ollama run) instead of hosted model tooling
• custom terminal entrypoint: career-terminal
• custom terminal panel/dashboard flow using the Go TUI in dashboard/
• updated docs and runbooks to reflect this local workflow

It focuses on one robust workflow:

• batch job evaluation from TSV input
• report generation
• ATS PDF generation
• tracker merge and integrity checks
• terminal dashboard for review and status updates

Right After Download (Do This First)

From a fresh clone, run these commands in order:

cd career-terminal
npm install
npx playwright install chromium
ollama pull gemma3:12b
ollama serve
./career-terminal

What happens on first run:

• career-terminal opens a terminal setup wizard
• it auto-creates missing required files (profile, portals config, CV scaffold, tracker, batch input)
• it asks for a resume file path or resume URL to populate cv.md
• it optionally lets you add your first job URL from terminal
• it does not ask for name/email/location prompts (resume-first workflow)

After setup, you can keep using just:

./career-terminal

Core Features

• Local LLM execution via ollama run (default model: gemma3:12b)
• Batch orchestration with retries, resumability, and per-offer logs
• Structured outputs:
  • markdown report in reports/
  • PDF in output/
  • tracker addition in batch/tracker-additions/
• Merge + verification pipeline:
  • merge-tracker.mjs
  • verify-pipeline.mjs
• Desktop terminal launcher on macOS: open-career-terminal.command
• Interactive Go dashboard in dashboard/

Deep Explanation (Non-Technical)

If you are new to software, think of this project as a personal "job-application assistant factory" that runs on your own computer.

You give it a list of job links. It reads each link, analyzes the job, creates files to help you apply, and keeps track of progress.

What problem this solves

Most job searches become messy fast:

• too many tabs
• unclear priorities
• hard to remember what you applied to
• difficult to tailor your CV repeatedly

Career-Terminal organizes that into one repeatable process.

What happens when you run it

When you run ./career-terminal, this is the full lifecycle:

1. It reads your input list from batch/batch-input.tsv.
2. It checks what was already processed in batch/batch-state.tsv.
3. For each pending job, it sends instructions to your local AI model (Ollama).
4. The AI produces a structured job evaluation report (reports/).
5. It generates a tailored PDF CV (output/).
6. It creates a tracker line in batch/tracker-additions/.
7. After all jobs finish, it merges tracker additions into your main tracker (data/applications.md).
8. It runs integrity checks to catch broken links, duplicates, or invalid states.

So you start with links, and end with organized outputs you can review and use.

The main folders in plain language

• career-terminal: The main command you run.
• batch/: The execution engine area; contains your input list, run state, worker prompt, logs, and pending tracker additions.
• config/: Your personal configuration template (name, profile settings, targeting preferences).
• templates/: Reusable blueprints, including the HTML CV layout and canonical status definitions.
• data/: Your long-term tracker source of truth (applications.md).
• reports/: One markdown report per evaluated job.
• output/: Generated PDF resumes.
• dashboard/: A terminal app (panel view) where you can browse jobs, sort/filter, open reports, and update statuses.
• docs/: Human-readable guides for setup, architecture, and system design.

What each core script does

• batch/batch-runner.sh: Orchestrates the whole batch run, including retries, resume, parallel workers, and end-of-run merging.
• batch/batch-prompt.md: Defines exactly how the AI worker should think and what files it should produce.
• generate-pdf.mjs: Turns prepared HTML into a polished PDF using Playwright.
• merge-tracker.mjs: Merges per-job tracker lines into one canonical tracker file.
• verify-pipeline.mjs: Checks consistency after processing.
• normalize-statuses.mjs: Standardizes status wording.
• dedup-tracker.mjs: Removes duplicate tracker entries.
• cv-sync-check.mjs: Validates that key setup files exist and look healthy.

Why there are multiple output files

Different files serve different review moments:

• report (reports/) for deep analysis and interview prep
• PDF (output/) for submission
• tracker (data/applications.md) for pipeline management

This separation makes the process safer and easier to audit.

Human control (important)

This system helps you prepare better applications; it does not replace your judgment. You review outputs and decide what to apply to.

What "local-first" means here

The AI inference is run with Ollama on your side. That means:

• you control model choice (gemma3:12b, gemma3:27b, etc.)
• you can keep the process private
• you are not locked into a hosted AI workflow

Typical day-to-day usage

1. Add new job links to batch/batch-input.tsv.
2. Run ./career-terminal.
3. Open generated report/PDF outputs.
4. Launch dashboard to review and update statuses.
5. Repeat with fresh links.

Quick Start

1) Install dependencies

npm install
npx playwright install chromium

2) Prepare configuration

cp config/profile.example.yml config/profile.yml
cp templates/portals.example.yml portals.yml

Add your CV as cv.md in the repository root.

3) Install and start Ollama

ollama pull gemma3:12b
ollama serve

4) Add batch input

Create or edit batch/batch-input.tsv:

id	url	source	notes
1	https://example.com/job-1	manual	Role @ Company | Match pending | https://example.com/job-1

5) Run locally

./career-terminal

On first run, career-terminal launches a terminal setup wizard and creates missing required files automatically (profile, portals config, CV scaffold, tracker, and batch input header). First-run prompts are intentionally minimal: resume path/URL first, then optional first job URL. During setup, type ? on any prompt to see examples before answering.

Terminal Usage

Main command

./career-terminal

Useful flags

./career-terminal --dry-run
./career-terminal --retry-failed
./career-terminal --parallel 2
./career-terminal --start-from 10
./career-terminal --max-retries 3

Change model

CAREER_TERMINAL_MODEL=gemma3:27b ./career-terminal

Remote Ollama host

OLLAMA_HOST=http://127.0.0.1:11434 ./career-terminal

Direct runner (advanced)

./batch/batch-runner.sh --model gemma3:12b --parallel 2

Dashboard

Build and run

cd dashboard
go build -o career-dashboard .
./career-dashboard --path ..

macOS launcher

Double-click open-career-terminal.command.

Project Structure

career-terminal/
├── career-terminal
├── batch/
│   ├── batch-input.tsv
│   ├── batch-state.tsv
│   ├── batch-prompt.md
│   ├── batch-runner.sh
│   ├── logs/
│   └── tracker-additions/
├── config/
│   └── profile.example.yml
├── templates/
│   ├── cv-template.html
│   ├── portals.example.yml
│   └── states.yml
├── data/
│   └── applications.md
├── reports/
├── output/
├── dashboard/
└── docs/

Validation Commands

node cv-sync-check.mjs
node verify-pipeline.mjs
node normalize-statuses.mjs
node dedup-tracker.mjs

Upcoming Features

Planned improvements for future releases:

• career-terminal add command to add new jobs from terminal without editing TSV manually
• career-terminal doctor command to run environment and config health checks in one step
• CSV import helper to convert spreadsheet exports into batch/batch-input.tsv
• Batch templates for common workflows (new applications, follow-ups, referral tracking)
• Job scoring and ranking output to prioritize highest-value opportunities first
• Company and role fit explanation block in each report for faster go/no-go decisions
• Re-apply detection to warn when a role or company was already processed
• Optional AI-generated interview prep pack per role (story prompts and likely questions)
• Dashboard shortcuts for common actions (mark applied, open report, open job URL)
• Resume version tracking so each submission can be traced to a specific PDF and model run
• Optional notifications when long runs finish (terminal, desktop, or webhook)
• Export utilities for tracker data (CSV/JSON) for analysis outside the repo
• Prompt profile presets (conservative, balanced, aggressive tailoring)
• Cost and runtime summary at end of run (tokens approximation, duration, failures, retries)
• Team mode foundations for shared tracker workflows while preserving local-first execution

Documentation

• docs/SETUP.md (includes step-by-step prompt walkthrough and full runtime process)
• docs/LOCAL_OLLAMA.md
• docs/CUSTOMIZATION.md
• docs/ARCHITECTURE.md
• docs/SYSTEM_DESIGN.md

License

MIT