CareerPilot Agent

🤖 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

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:

python agent.py

Run the web UI:

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

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:

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:

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
• Source: omerfarooq223/CareerPilot-Agent
• License: MIT

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