Metadata-Version: 2.4
Name: applyr
Version: 0.5.1
Summary: CLI job application tracker designed for AI coding agents
Author-email: Deiby Gorrin <deibygorrin@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Deiby Gorrin
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/DeibyGS/applyr
Project-URL: Repository, https://github.com/DeibyGS/applyr
Project-URL: Issues, https://github.com/DeibyGS/applyr/issues
Keywords: job,tracker,cli,ai,career,applications,job-search,job-tracker,developer-tools,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: colorama>=0.4.6
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# applyr

[![PyPI version](https://img.shields.io/pypi/v/applyr)](https://pypi.org/project/applyr/)
[![PyPI downloads](https://img.shields.io/pypi/dm/applyr)](https://pypi.org/project/applyr/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![CI](https://github.com/DeibyGS/applyr/actions/workflows/python-package.yml/badge.svg)](https://github.com/DeibyGS/applyr/actions)
[![Tests: 54 passed](https://img.shields.io/badge/tests-54%20passed-brightgreen)](https://github.com/DeibyGS/applyr)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/DeibyGS/applyr/pulls)

**Your AI agent's job application tracker.** Score offers, detect duplicates, generate ATS-safe CVs — all from the terminal.

```bash
pip install applyr && applyr init && applyr setup-agent
```

> **Requires:** Python 3.12+ and an AI coding agent ([Claude Code](https://claude.ai/claude-code), [Cursor](https://cursor.sh), [OpenCode](https://opencode.ai), or any agent that reads instruction files).

---

## How it works

```
You: paste a job offer into your AI agent

         |
         v

Agent: reads cv-master.md + evaluates 6 topics
       runs  applyr add '<json>'

         |
         v

applyr:  74% compatibility (>= 65% threshold)
         >> RECOMMENDATION: APPLY
         Skill gaps: English, Experience

         |  (you confirm)
         v

Agent: generates tailored CV from cv-master.md
       runs recruiter review (ATS score: 87/100)
       delivers PDF ready to send
```

applyr is the **storage layer**. Your AI agent is the **brain**.

---

## Features

- **Weighted scoring** — 6 configurable topics (tech stack 30%, projects 20%, experience 15%, education 15%, english 10%, cultural fit 10%)
- **Threshold gate** — automatic APPLY/SKIP based on your minimum score (default: 65%)
- **Duplicate detection** — same company+title? applyr catches it before you waste time
- **ATS-safe CVs** — locked single-column CSS, standard fonts, no images. Your agent fills content, never touches structure
- **Recruiter review** — built-in prompt scores your CV 0-100 with specific improvements
- **21 commands** — pipeline, stats, gaps, trends, salary insights, follow-ups, compare, export, and more
- **Local and private** — SQLite on your machine. No API keys, no subscriptions, nothing leaves your system
- **Agent-native** — ships with `AGENT_INSTRUCTIONS.md` that tells Claude/Cursor/OpenCode exactly what to do

---

## Quick start

### 1. Install and initialize

```bash
pip install applyr
applyr init
```

This creates `~/.applyr/` with config, database, CV template, and agent instructions.

### 2. Fill your profile

Edit `~/.applyr/cv-master.md` with your complete professional profile. This is the only source of truth — the agent reads it to score offers and write CVs.

### 3. Connect your agent

```bash
applyr setup-agent                       # Auto-detects Claude/Cursor/OpenCode
applyr setup-agent --agent claude        # Or specify: claude | cursor | opencode | generic
```

**Done.** Paste a job offer into your agent and say "analyze this".

---

## What your agent sees

```
You:   "Analyze this AI Engineer posting at Acme Corp"

Agent: Checks duplicates → none found
       Scores: tech_stack 85%, experience 40%, projects 90%...
       applyr add '<json>'
       → "74% match. APPLY recommended. Generate CV?"

You:   "Yes"

Agent: applyr cv generate 1 → fills from cv-master.md
       applyr cv review → ATS score: 87/100, READY TO SEND
       applyr cv pdf → delivers PDF

You:   "Analyze this Data Analyst role at SmallCo"

Agent: applyr add '<json>'
       → "42% match. SKIP recommended. Gaps: no R/Tableau, 0 data roles."

You:   "What should I learn?"

Agent: applyr gaps → "Experience: seen in 15 offers, avg gap 20%"
```

---

## Commands

### Tracking

```bash
applyr add '<json>'                # Register offer (agent builds the JSON)
applyr list [--status S]           # All offers or filtered
applyr show <id>                   # Full detail + topic scores
applyr pipeline                    # Grouped by status
applyr update <id> <status>        # Change status, add notes
applyr delete <id>                 # Remove an offer
applyr search <keyword>            # Search by company/title/tech
```

### Analytics

```bash
applyr stats                       # Conversion funnel + metrics
applyr gaps                        # Skills to improve (by frequency)
applyr trends                      # Applications per week
applyr summary --json              # Weekly summary for LLM
applyr compare 1 3 4               # Side-by-side offers
applyr plan                        # Learning priorities
applyr salary [--seniority mid]    # Salary insights
applyr followups                   # Overdue + upcoming
```

### CV pipeline

```bash
applyr cv generate <id>            # ATS HTML skeleton
applyr cv review <file.html>       # Recruiter review prompt
applyr cv pdf <file.html>          # Chrome headless → PDF
```

### System

```bash
applyr doctor                      # Health check
applyr export --format json        # Export everything
applyr version                     # Show version
```

<details>
<summary><strong>Aliases and flags</strong></summary>

| Alias | Command | | Flag | Effect |
|-------|---------|-|------|--------|
| `ls` | `list` | | `--json` | Structured JSON output |
| `st` | `stats` | | `--no-color` | Disable colors (also respects `NO_COLOR`) |
| `fu` | `followups` | | | |
| `cmp` | `compare` | | | |
| `sal` | `salary` | | | |

</details>

---

## Scoring

Each topic is scored 0-100 by the AI agent, then weighted:

| Topic | Weight | What it measures |
|-------|:------:|-----------------|
| `tech_stack` | 30% | Required technologies vs. your skills |
| `projects` | 20% | Portfolio relevance to the role |
| `experience` | 15% | Years, seniority, industry match |
| `education` | 15% | Degree level and field |
| `english` | 10% | Language level vs. requirement |
| `cultural_fit` | 10% | Work mode, location, values |

**Formula:** `sum(score * weight) / sum(weights)` — configurable in `~/.applyr/applyr.toml`.

**Threshold:** score >= 65% → APPLY. Below → SKIP. Configurable.

---

## Status flow

```
pending ──> applied ──> waiting ──> in_process ──> offer
               |            |           |
               v            v           v
           discarded    rejected    rejected
```

---

## Configuration

```toml
# ~/.applyr/applyr.toml

[general]
threshold = 65          # Min % to recommend applying
followup_days = 10      # Days before follow-up reminder

[weights]               # Auto-normalized, no need to sum to 1.0
tech_stack = 30
education = 15
experience = 15
projects = 20
english = 10
cultural_fit = 10
```

---

<details>
<summary><strong>Offer fields reference</strong></summary>

| Field | Type | Valid values | Required |
|-------|------|-------------|:--------:|
| `title` | string | Any | Yes |
| `company` | string | Any | No |
| `summary` | string | Any | No |
| `date_received` | string | `YYYY-MM-DD` | No |
| `date_applied` | string | `YYYY-MM-DD` | No |
| `status` | string | `pending` `applied` `waiting` `in_process` `rejected` `discarded` `offer` | No |
| `canal` | string | `linkedin_easy` `linkedin_direct` `email` `portal` `referral` `other` | No |
| `work_mode` | string | `remote` `hybrid` `onsite` | No |
| `location` | string | Any | No |
| `salary_min` / `salary_max` | integer | Amount | No |
| `salary_period` | string | `annual` `monthly` `hourly` | No |
| `seniority_level` | string | `trainee` `entry_level` `junior` `mid` `senior` `lead` `director` | No |
| `role_category` | string | `backend` `frontend` `fullstack` `ai` `devops` `data` `mobile` `qa` `other` | No |
| `tech_stack` | string | Comma-separated | No |
| `job_url` | string | URL | No |
| `contact_name` / `contact_role` | string | Any | No |
| `cover_letter` | integer | `0` or `1` | No |
| `notes` | string | Any | No |
| `topics` | object | See Scoring section | No |

</details>

---

## Project structure

```
applyr/
  cli.py                 # Entry point
  config.py              # TOML config
  db.py                  # SQLite schema (28 columns)
  scoring.py             # Weighted scoring engine
  cv.py                  # ATS CV + Chrome PDF + recruiter review
  commands/
    core.py              # add, list, show, update, delete, search, init, setup-agent
    analytics.py         # stats, gaps, trends, pipeline, compare, plan, salary
    workflow.py          # export, doctor
  templates/
    AGENT_INSTRUCTIONS.md
tests/
  test_scoring.py        # 54 unit tests
  test_config.py
  test_db.py
  test_validators.py
```

## Development

```bash
git clone https://github.com/DeibyGS/applyr.git
cd applyr
pip install -e ".[dev]"
pytest                             # 54 tests, ~0.1s
```

---

## Built with AI

applyr was designed to work **for** AI agents — it made sense to build it *with* one, as a pair programming partner.

| Human-owned | AI-assisted (human-reviewed) |
|-------------|------------------------------|
| Domain model & 28-column schema | Python implementation |
| Scoring engine & threshold logic | CLI scaffolding |
| ATS CV template & locked CSS | Test suite (54 tests) |
| Architecture & code review | Module split & CI |

**Process:** `Spec (SDD) → AI implementation → Human review → Test → Merge`

<details>
<summary><strong>Principles & metrics</strong></summary>

**Principles:**
1. AI never made product decisions — domain model and UX flow are human-designed.
2. Every feature started from a written spec (SDD) before any code.
3. `AGENT_INSTRUCTIONS.md` is a contract, not a suggestion.
4. PRs follow a 400-line budget with work-unit commits.

**Metrics:**

| | |
|---|---|
| PRs | 17 (all human-reviewed) |
| Tests | 54 unit (scoring, config, db, validators) |
| Commands | 21 + 5 aliases |
| Schema | 28 columns, 3 tables, migration system |
| Models | Claude Opus 4.6, DeepSeek V4 Flash |

_Measured with [ClaudeStat](https://github.com/DeibyGS/claudestat)._

</details>

---

## License

[MIT](LICENSE) — use it, fork it, improve it.
