# CareerPilot Agent

> Your personal AI CTO: Automates the journey from developer to intern by auditing code, suggesting gap-filling projects, and tracking 'Hirability Scores' through a modular agentic workflow.

- **Type:** MCP server
- **Install:** `agentstack add mcp-omerfarooq223-careerpilot-agent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [omerfarooq223](https://agentstack.voostack.com/s/omerfarooq223)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [omerfarooq223](https://github.com/omerfarooq223)
- **Source:** https://github.com/omerfarooq223/CareerPilot-Agent

## Install

```sh
agentstack add mcp-omerfarooq223-careerpilot-agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🤖 CareerPilot

> A fully autonomous AI agent that watches your GitHub, tracks your skill gaps and coaches you toward landing your target internship, week over week.

---

## Product Preview

The dashboard gives you one place to run skills, inspect generated outputs, and track your progress over time.

---

## The Problem

Most students send out applications without really knowing where they stand. Which skills are you actually missing? Which of your projects would make a recruiter scroll past? Probably hard to say.

CareerPilot reads your GitHub and tells you. It scores your profile against your target role, points at specific gaps and nudges you the following week to see if you moved on them.

---

## How It Works

CareerPilot runs a continuous agentic loop across five stages:

```
Observe → Analyze → Remember → Plan → Act
```

| Stage | What happens |
|---|---|
| **Observe** | Reads your entire GitHub profile via the REST API |
| **Analyze** | LLM compares your profile against your target role and produces a consistent readiness score |
| **Remember** | Saves progress snapshots to SQLite for week-over-week tracking |
| **Plan** | Agent autonomously decides what skill or gap to address next |
| **Act** | Executes a skill from the registry and saves output to `output/` |

---

## Quickstart

```bash
git clone https://github.com/omerfarooq223/CareerPilot-Agent
cd CareerPilot-Agent
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp config/.env.example config/.env   # fill in your API keys
```

**Run the CLI agent:**

```bash
python agent.py
```

**Run the web UI:**

```bash
uvicorn api.server:app --reload --port 8000
# Then open http://127.0.0.1:8000
```

The dashboard includes a **floating chat interface** where you can:
- Ask questions about your GitHub profile (e.g., "How many repos do I have?")
- Get real answers using your actual GitHub data
- Follow up with contextual questions (e.g., "Name them") — **the agent remembers previous messages**
- Trigger skills directly (e.g., "Audit my CareerPilot-Agent repo")

**Or try the live demo:** https://web-production-e1faa.up.railway.app

---

## Configuration

### `config/config.py`

Centralized configuration loader. Reads secrets from `config/.env` and defines app-wide constants.

### `config/goals.yaml`

```yaml
model_provider: "groq"
model_name: "llama-3.3-70b-versatile"
target_role: "AI/ML Intern"
target_timeline: "3 months"
target_companies:
  - "Arbisoft"
  - "Folio3"
preferred_stack:
  - "FastAPI"
  - "Django"
```

---

## Skills

| Skill | Description | Output |
|---|---|---|
| `suggest_project` | Suggests a mini-project targeting your biggest skill gap | `output/suggested_project.md` |
| `audit_repo` | Deep code audit via MCP if available, metadata fallback otherwise | `output/audit_.md` |
| `rewrite_readme` | Rewrites a repo's README to a professional standard | `output/readme_.md` |
| `generate_dev_card` | Generates a Markdown developer profile card | `output/developer_card.md` |
| `mock_interview_prep` | Produces role-specific interview questions | `output/mock_interview_prep.md` |
| `weekly_nudge` | Honest weekly progress report | `output/weekly_nudge.md` |
| `linkedin_writer` | LinkedIn post generator with post memory (HITL) | `output/linkedin__.md` |
| `update_goals` | Auto-syncs shipped projects and skills from GitHub | `config/goals.yaml` |

**Chat Features:**
- 💬 **Conversational Q&A** — Ask about your profile, repos, languages, score, and gaps
- 🧠 **Conversation Memory** — Each chat session remembers previous messages
- 🎯 **Real Data** — Answers use your actual GitHub profile, not generic advice

---

## Adding a New Skill

1. Create `skills/your_skill/your_skill.py`
2. Create `skills/your_skill/SKILL.md`
3. Register it in `actions/executor.py`:

```python
from skills.your_skill.your_skill import your_skill
registry.register("your_skill", "Description")(your_skill)
```

The planner and web UI pick it up automatically.

---

## Project Structure

```
CareerPilot-Agent/
├── agent.py                  # Main entrypoint: runs the agentic loop
├── AGENTS.md                 # AI assistant briefing and project rules
├── CLAUDE.md                 # AI assistant briefing and rules
├── LICENSE
├── Procfile                  # Railway deployment start command
├── README.md
├── pyproject.toml            # Python packaging and build config
├── railway.json              # Railway deployment config
├── requirements.txt
├── .gitignore
├── actions/                  # Action dispatcher and security
│   ├── error_handler.py      # Retry, timeout, fallback, rate limiting
│   ├── executor.py           # Skill dispatcher and output saving
│   └── security.py           # Input sanitization and path guards
├── api/                      # FastAPI backend
│   ├── server.py             # FastAPI app entrypoint
│   └── routes/
│       ├── __init__.py
│       ├── agent.py          # POST /api/run — loop execution, POST /api/ask — intent chat router
│       ├── dashboard.py      # GET /api/dashboard, history endpoints
│       └── skills.py         # POST /api/skills/{skill_name}
├── assets/
│   └── careerpilot-dashboard.png  # README product screenshot
├── config/
│   ├── .env                  # Environment variables (never committed)
│   ├── config.py             # Centralized config loader
│   └── goals.yaml            # Target role, skills, companies
├── credentials/              # Gmail API credentials (gitignored)
│   ├── credentials.json
│   └── token.json
├── database/
│   └── db_utils.py           # SQLite connection pooling
├── frontend/
│   └── index.html            # Single-page HTML UI
├── memory/
│   ├── careerpilot.db        # SQLite DB (gitignored)
│   ├── github_cache.json     # GitHub API cache (gitignored)
│   ├── latest_snapshot.json  # Last committed agent state
│   ├── long_term.py          # Long-term memory logic
│   └── short_term.py         # Short-term/session memory logic
├── planner/
│   └── reasoner.py           # Groq-powered planning logic
├── scripts/
│   ├── careerpilot_daemon.py # Local daemon for weekly email
│   ├── reminder_scheduler.py # FastAPI startup scheduler for weekly email
│   ├── send_gmail_api.py     # Sends email via Gmail API
│   └── weekly_reminder.py    # Email content builder and SMTP fallback
├── skills/
│   ├── registry.py           # Skill registration system
│   ├── audit_repo/
│   │   ├── SKILL.md
│   │   └── audit_repo.py
│   ├── dev_card/
│   │   ├── SKILL.md
│   │   └── dev_card.py
│   ├── gap_analyzer/
│   │   ├── SKILL.md
│   │   └── gap_analyzer.py
│   ├── github_observer/
│   │   ├── SKILL.md
│   │   └── github_observer.py
│   ├── goals_updater/
│   │   ├── SKILL.md
│   │   └── goals_updater.py
│   ├── interview_prep/
│   │   ├── SKILL.md
│   │   └── interview_prep.py
│   ├── linkedin_writer/
│   │   ├── SKILL.md
│   │   └── linkedin_writer.py
│   ├── nudge_writer/
│   │   ├── SKILL.md
│   │   └── nudge_writer.py
│   ├── project_suggester/
│   │   ├── SKILL.md
│   │   └── project_suggester.py
│   └── readme_writer/
│       ├── SKILL.md
│       └── readme_writer.py
└── tests/
    ├── test_memory.py
    ├── test_observer.py
    ├── test_planner.py
    └── test_weekly_email_schedule.py
```

---

## Stack

| Component | Technology |
|---|---|
| **LLM** | Groq API — LLaMA 3.3 70B |
| **GitHub data** | GitHub REST API + GitHub MCP (optional deep audits) |
| **Memory** | SQLite |
| **Data models** | Pydantic |
| **Web framework** | FastAPI |
| **Frontend** | Vanilla HTML/CSS/JS + marked.js (Premium Glassmorphism UI & Floating Chat) |
| **CLI** | Rich + Loguru |
| **Error handling** | Circuit breaker + custom retry/timeout/fallback |
| **Security** | Prompt injection guard, path traversal protection |
| **Testing** | pytest |
| **Scheduling** | Local cron job + FastAPI startup scheduler (weekly reminder) |
| **Deployment** | Railway (free tier) |
| **Caching** | Local JSON (1-hour GitHub cache) |
| **Connection pooling** | SQLite (5 connections) |

---

## Security

- API keys loaded via `python-dotenv` — never hardcoded
- Prompt injection detection on all inputs
- Path traversal protection on all file writes
- Secrets scrubbed before any LLM call
- Environment variable validation at boot
- Rate limiting on all Groq API calls

---

## Weekly Email Reminder

CareerPilot emails you every Friday at 6PM PKT with your current score, identified gaps, and a LinkedIn nudge — no manual check-in needed.

**Setup:**

1. Place your Gmail API credentials in `credentials/` (`credentials.json` and `token.json`)
2. Set `REMINDER_EMAIL_SENDER` and `REMINDER_EMAIL_RECEIVERS` in `config/.env`
3. Optional: set `REMINDER_TIMEZONE=Asia/Karachi` in `config/.env` (this is the default)
4. Test with: `python scripts/send_gmail_api.py`
5. Keep either the web app, daemon, or cron job running at the scheduled time

**Local cron job:**

Use absolute paths and write logs so failures are visible:

```
0 18 * * 5 cd "/absolute/path/to/CareerPilot Agent" && "/absolute/path/to/CareerPilot Agent/venv/bin/python" "/absolute/path/to/CareerPilot Agent/scripts/send_gmail_api.py" >> "/absolute/path/to/CareerPilot Agent/logs/weekly_email.log" 2>&1
```

For this machine, the installed cron path is:

```
0 18 * * 5 cd "/Users/muhammadomerfarooq/Desktop/GitHub Repositories/CareerPilot Agent" && "/Users/muhammadomerfarooq/Desktop/GitHub Repositories/CareerPilot Agent/venv/bin/python" "/Users/muhammadomerfarooq/Desktop/GitHub Repositories/CareerPilot Agent/scripts/send_gmail_api.py" >> "/Users/muhammadomerfarooq/Desktop/GitHub Repositories/CareerPilot Agent/logs/weekly_email.log" 2>&1
```

**Alternative schedulers:**

- FastAPI starts `scripts/reminder_scheduler.py` automatically and schedules the same Friday 6PM PKT email while the web process is alive.
- The standalone daemon can be run with: `python scripts/careerpilot_daemon.py`
- Set `CAREERPILOT_ENABLE_EMAIL_SCHEDULER=false` to disable the FastAPI startup scheduler.

**Troubleshooting:**

- Check `logs/weekly_email.log` after Friday 6PM PKT for cron output.
- Gmail API is the primary sender and uses `credentials/token.json`.
- `REMINDER_EMAIL_PASSWORD` is only needed for the SMTP fallback in `weekly_reminder.py`.
- If the token expires, `send_gmail_api.py` refreshes it when a refresh token is present.

---

## Testing & Debugging

**Run pytest tests:**
```bash
pytest tests/ -v
```

---

## License

[MIT](LICENSE)

Author: [](https://omerfarooq223.github.io)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [omerfarooq223](https://github.com/omerfarooq223)
- **Source:** [omerfarooq223/CareerPilot-Agent](https://github.com/omerfarooq223/CareerPilot-Agent)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-omerfarooq223-careerpilot-agent
- Seller: https://agentstack.voostack.com/s/omerfarooq223
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.