What is NextRole?

Preparing for an interview takes hours of tedious resume tailoring and company research. NextRole automates the heavy lifting. Hand it your current CV and a target Job Description (or just a JD URL) — whether you're applying externally or angling for an internal move — and a team of specialized AI agents researches the company, rewrites your resume to fit, coaches you round-by-round, and prints a cheat sheet for the day of.

• 📄 Tailored resume → PDF — your experience rewritten against the exact JD + company research, rendered with rendercv (editable & re-renderable).
• 🔍 Deep company & role recon — live web research distilled into a match analysis.
• 🎯 Structured interview prep — a self-introduction plus per-round STAR stories mapped to the role.
• ⚡ Day-of battlecard — a one-page-per-round PDF cheat sheet for the final high-pressure review.
• 🗓️ Time-boxed prep plans — a study plan that fits 1 month, 2 weeks, or just 3 hours.
• 🔗 Paste a JD URL — point it at a careers page; it extracts and processes the posting for you.
• 💬 Iterate by chatting — "add a 4th round", "add React to my skills" — streaming multi-turn edits, with the right agent owning each file.
• 🗂️ Built-in workspace — upload, preview (PDF / MD / YAML / JSON / code), print-to-PDF, and swap the LLM at runtime.

Demo

▶️ Watch the full walkthrough in HD on YouTube »

Quick Start

The whole stack — frontend, backend, Postgres, Redis — runs in Docker.

# 1. Clone & configure
git clone https://github.com/tam159/next-role.git
cd next-role
cp .env.example .env          # then fill in your API keys (see table below)

# 2. Launch everything
docker compose up -d

# 3. Find your host ports (set in .env, vary per machine)
docker ps                     # read the 0.0.0.0:<host>->... mappings

# 4. Open the app
#    Frontend UI      →  http://localhost:<FRONTEND_LOCAL_PORT>/
#    Backend API docs →  http://localhost:<LANGGRAPH_LOCAL_PORT>/docs

💡 Pick your LLM in the app. Open the in-app Configuration dialog to set the main agent and subagent models — no rebuild needed. See LLM configuration below for recommended models and free / local options.

Architecture

NextRole is a supervisor agent orchestrating three specialist subagents on LangGraph + DeepAgents. The main agent handles intake, document processing, and the final battlecard; it delegates research, resume tailoring, and interview coaching to declarative subagents (defined in subagents.yaml, each with its own model, tools, and skills).

How It Works

A five-stage pipeline. Stage 4 runs the resume tailor and interview coach in parallel; Stage 6 routes follow-up edits to whichever agent owns the target file.

flowchart LR
    Agent["Agent filesystem tools<br/>read_file · write_file · edit_file<br/>ls · glob · grep · execute"]
    CB{{"CompositeBackend<br/>routes virtual paths"}}
    Agent --> CB
    subgraph Shell["VirtualPathShellBackend · default route"]
        SH["rewrites /virtual/path → on-disk path<br/>before subprocess.run<br/>(e.g. rendercv render /tailored_resume/...)"]
    end
    subgraph Store["StoreBackend · Postgres + pgvector"]
        ST["/memory/ · /processed/ · /research/<br/>/interview_coach/<br/>/large_tool_results/ · /workspace/"]
    end
    subgraph Disk["FilesystemBackend · disk (binaries + renders)"]
        DK["/upload/ · /tailored_resume/<br/>/render_intermediate/<br/>/interview_battlecard/"]
    end
    CB -->|default| Shell
    CB -->|KV routes| Store
    CB -->|binary + PDF routes| Disk
    Sem["Semantic memory · AGENTS.md"] -. loaded into system prompt .-> Agent
    Proc["Procedural memory · skills/*/SKILL.md"] -. loaded on demand .-> Agent
    Work["Working memory · LangGraph thread"] -. drives .-> Agent
    Store --- Epi["Episodic memory · persisted artifacts<br/>(incl. /memory/ auto-memory)"]
    Disk --- Epi

Roadmap

• 💤 "Auto-dream" consolidation — sleep-time compaction that prunes stale notes and merges insights into durable memory.
• 📦 Remote sandboxes — swap LocalShellBackend for an isolated remote sandbox (e.g. Daytona) so render/shell steps are safe for multi-tenant use.
• 📊 Agent evaluation — LangSmith evals over the workflow (the @pytest.mark.eval marker is already reserved).
• 🎨 Enhanced UI — richer artifact editing, diff views, and inline regeneration.
• 🔌 MCP / A2A examples — sample integrations driving career_agent from external agents and IDEs.
• 🧵 Per-thread / multi-user scoping — namespace artifacts per user instead of the current global layout.
• 🌐 More sources & ATS-aware tailoring — pluggable retrievers + keyword/ATS optimization passes.

Limitations

NextRole is built for local, single-user, trusted use today.

• 🔒 Local shell execution — VirtualPathShellBackend runs render commands via subprocess on the host. Safe locally; not hardened for multi-tenant production (needs sandboxing — see roadmap).
• 👤 Global file scoping — uploads and artifacts share one filesystem layout; re-uploading a filename overwrites. No per-user isolation yet.
• 🧪 LLM evals deferred — current tests are unit + local-DB integration; automated quality evals aren't wired up yet.
• 🧠 Personalization is preferences-only — the agent persists and auto-applies the preferences you state across sessions, but doesn't yet infer your style/history on its own or consolidate memory over time (see roadmap).
• ⏱️ Latency — a full run makes several LLM and tool calls across multiple agents; expect minutes, not seconds.

Contributing

PRs and issues are welcome! Start with CONTRIBUTING.md — it walks through the fork → PR workflow, local setup, the CI quality gate (pre-commit + backend tests), testing, and conventions. Stack-specific details live in backend/CLAUDE.md and frontend/CLAUDE.md; commits follow Conventional Commits.

New here? Issues labelled good first issue are a gentle place to start, and questions are welcome in Discussions.

License

MIT © 2026 Tam Nguyen

Acknowledgements

Built on DeepAgents, LangChain / LangGraph / LangSmith, rendercv, WeasyPrint, Tavily, and LlamaIndex / LlamaParse.