CareerOS

A local-first, fork-friendly career operating system.

CareerOS is a small Python CLI plus a markdown workspace that helps you keep one canonical professional profile and reuse it everywhere — resumes, interview prep, applications, per-job portfolio sites. It is built in the spirit of Building a Second Brain: markdown + git is the system of record; SQLite is a disposable index; everything else is generated on demand.

It is forkable by design. All identity, paths, and deployment settings live in careeros.toml, so you can clone this repo, run careeros init, and have a working career OS scaffolded to your name within a minute.

Why?

• One canonical knowledge base for accomplishments, stories, skills, and experience — searchable with FTS5.
• Tailored evidence briefs that match a job posting to your strongest profile docs in seconds.
• Per-job ephemeral portfolio sites: turn a posting into a single-page, pre-signed S3 site you can share with the recruiter.
• LinkedIn / GitHub importers that fill the catalog from data you already have.
• Local-first. Markdown files are yours. No SaaS, no lock-in.

Quick start

# 1. Fork or clone
git clone https://github.com/yourusername/CareerOS.git my-career-os
cd my-career-os

# 2. Install
uv sync

# 3. Scaffold your workspace (interactive — asks for name, slug, links)
uv run careeros init

# 4. Drop your materials into db/<your-slug>/...
#    See examples/jane-doe/ for the recommended shape.

# 5. Index and use
uv run careeros career ingest
uv run careeros career list
uv run careeros career search "forecasting sql"

# 6. Apply to a job
uv run careeros career prepare db/jobs/Acme/posting.md
uv run careeros career brief    db/jobs/Acme/posting.md
uv run careeros career export   db/jobs/Acme/resume-tailored.md
uv run careeros career site preview db/jobs/Acme/posting.md

The cos command is an alias for careeros:

uv run cos career ingest

Workspace shape

CareerOS expects two top-level areas inside db/:

db/
├── <your-slug>/              # canonical profile materials
│   ├── profile.md
│   ├── positioning.md
│   ├── experience/
│   ├── accomplishments/
│   ├── stories/
│   ├── skills/
│   └── resumes/
└── jobs/
    └── <Company>/
        └── <Role>/
            ├── posting.md
            ├── application.md
            ├── resume.md
            ├── cover_letter.md
            └── notes.md

<your-slug> is whatever you put in careeros.toml (owner.slug). All generators, importers, and lenses read this from config — there is nothing hardcoded.

See examples/jane-doe/ for a fully-populated sample workspace.

Commands

Command	What it does
careeros init	Scaffold careeros.toml and db/ workspace
careeros career ingest	Re-index markdown into the SQLite catalog
careeros career list	List indexed documents (filter by kind/company)
careeros career search <q>	FTS5 search across the catalog
careeros career stats	Show catalog headline numbers
careeros career brief <target>	Generate a relevance brief for a job posting
careeros career prepare <posting>	Bootstrap application drafts beside a posting
careeros career review <jobdir>	Export .md → .docx for manual editing
careeros career rebuild <jobdir>	Re-render PDFs/HTML after editing
careeros career export <md>	Render any markdown to HTML + PDF
careeros career site generate <posting>	Build a per-job portfolio site
careeros career site preview <posting>	Generate + open in browser
careeros career site deploy <posting>	Deploy with pre-signed (TTL-capped) URL
careeros career site publish <posting>	Publish to a durable subdomain
careeros career find search	Discover jobs across configured ATS boards
careeros career find import-url	Pull job postings from a URL list file
careeros career github fetch/story/timeline/profile	GitHub importers + visualizations
careeros career linkedin import/compare/recommend	LinkedIn data integration
careeros career local upcoming/seed/check	Local meetup tracking
careeros career profiles generate	Render multi-lens profile variants

Configuration

Configuration is read in this order (later wins):

1. Built-in defaults
2. ~/.config/careeros/config.toml (or ~/.careeros/config.toml)
3. ./careeros.toml (project-local)
4. CAREEROS_* environment variables

See careeros.example.toml for the full schema and docs/configuration.md for a deeper guide, including how to wire up site deployment, GitHub auth, and finder sources.

How to fork

# 1. Fork on GitHub, then clone your fork
git clone git@github.com:youruser/your-fork.git
cd your-fork

# 2. Add the upstream so you can pull updates
git remote add upstream https://github.com/yourusername/CareerOS.git

# 3. Either keep the fork private (recommended — your career data is sensitive)
#    or commit only the code and gitignore db/ (the default).

# 4. Run init
uv run careeros init

# 5. Pull updates anytime
git fetch upstream && git merge upstream/main

The default .gitignore excludes db/ so you can safely use a public fork for code while keeping your career data local.

For the full step-by-step process — including the personal-branch pattern used by the maintainer's rarko branch — see docs/personalize.md.

Project status

CareerOS is alpha-quality. The core (parser, store, briefing, site generator) is solid; the ATS source list and lens definitions are biased toward the original author's role targets and will need tuning for yours. Contributions welcome — see CONTRIBUTING.md.

License

MIT — see LICENSE.

Acknowledgements

CareerOS was extracted from a personal career OS originally built around one author's job search, then generalized into a public template. If you have opinions about the workspace shape or the lens model, please open an issue.