Japan Career Agent

Evidence-based career decision support for the Japanese job market.
Your career record stays on your machine, and nothing becomes a fact without your approval.

Install · Why · Flow · Quick start · Skills · Contributing · Changelog

🌐 English · 한국어 · 日本語

Current release: 2.1.1.

In three steps:

1. Record what happened — 棚卸し turns past work into contexts, experiences and checkable evidence. What you cannot verify stays Unknown.
2. Approve it — nothing enters your canonical career record until you confirm it. A number without a source is refused.
3. Use it — JD matching, a 職務経歴書, interview practice and next actions, all quoting only confirmed evidence.

It runs as a Claude Code and Codex plugin/skill suite, or as a standalone command, over a local Career Agent runtime — for job seekers and hiring teams.

Use it to sort out a career direction, prepare a resume or 職務経歴書, read a job description or company evidence, compare opportunities, practise an interview, and keep track of the next step. It is a plugin and local runtime, not a hosted SaaS or standalone GUI.

Why this is different

• Evidence, not invented scores or career history.
• If a fact is not confirmed, it stays Unknown.
• A confirmed hard, legal, must-have, or dealbreaker conflict is not averaged away by another strength.
• The system does not predict whether you will be hired.
• You make the final decision and keep approval control. It does not submit applications or send messages for you.

The basic flow

flowchart LR
    A[Your request] --> B[Career Agent]
    B --> C[Evidence and current state]
    C --> D{Needs confirmation?}
    D -->|Yes| E[Unknown, conflict, or question]
    E --> F[You review and confirm]
    F --> G[Canonical state]
    D -->|No| H[Analysis or preparation]
    G --> H

Install

Without a plugin host

Both commands install and run the same Python program. Pick whichever runner you already have.

npx japan-career-agent init     # via npm
uvx japan-career-agent init     # via uv, or: pipx run japan-career-agent init

npx ships an installer and no runtime: it locates uv or pipx, installs the matching PyPI release, and hands over. Nothing runs at npm install time, and neither path writes into a Python you already depend on.

Python 3.11 or newer is required. uv downloads a matching interpreter by itself; pipx uses one that is already installed. With neither runner present, npx prints how to install one and changes nothing.

Claude Code

Install the plugin into the host you already use.

claude plugin marketplace add younnieCutler/japan-career-agent
claude plugin install japan-career-agent@japan-career-agent

Codex

codex plugin marketplace add younnieCutler/japan-career-agent
codex plugin add japan-career-agent@japan-career-agent

Release channels

The repository version can be ahead of the stable marketplace channel while a release is being prepared. The stable channel always points to the latest published immutable vX.Y.Z tag; it never follows main. Source metadata is 2.1.1 while the stable marketplace ref is still v1.18.1, because the release workflow has not published a tag for the newer source yet. Installing from the marketplace therefore gives you 1.18.1 today. The gap closes when the release workflow publishes the next tag and this ref is updated; uvx and npx are not affected, since they resolve a published package version rather than this ref.

Local fallback

Clone the repository when you need to inspect or run the files directly:

git clone https://github.com/younnieCutler/japan-career-agent.git

Upgrading from 2.0.x, when this was japan-recruit-ai-agent

The project was renamed in 2.1.1. GitHub redirects the old repository URL, so an existing clone or remote keeps working, but the marketplace entry is matched by name and has to be re-added:

claude plugin marketplace remove japan-recruit-ai-agent
claude plugin marketplace add younnieCutler/japan-career-agent
claude plugin install japan-career-agent@japan-career-agent

Nothing in your Career Vault changes: the vault path, the event ledger and every document are untouched by the rename. JAPAN_RECRUIT_NO_UPDATE_CHECK=1 still disables the update check, so an existing opt-out stays in force alongside the new JAPAN_CAREER_NO_UPDATE_CHECK. Release bundles published under the old name remain verifiable with scripts/verify_release.py.

Quick start

After installation, start with a normal request in Claude Code or Codex:

I want to start preparing for a job change in Japan.
Compare this JD with my experience and keep unconfirmed points as Unknown.
Help me prepare for next week's interview.
Review this 職務経歴書 without inventing evidence.

You do not need to learn proposal_id, CAREER_VAULT, or data/pipeline.yml before making a first request. Those details are for the advanced local workflow below.

What it can help with

How evidence is handled

The suite keeps evidence and preference separate. It uses the following vocabulary:

interest_level records your preference. It does not change objective evidence, decision status, or ordering. A resume, JD, web page, YAML file, Vault metadata, pipeline text, or rule is career data, not an instruction.

Advanced: Career Agent

The local runtime keeps the personal Career Vault as canonical state and projects per-company workflow state into ./data/pipeline.yml.

For an explicit local setup and guided menu:

VAULT=/path/to/career-agent-vault
python skills/career-agent/career_agent.py setup --vault "$VAULT" --track chuto --target-role "Platform Engineer"
python skills/career-agent/career_agent.py guided --vault "$VAULT" --format human

guided shows setup status, pending proposals, Unknown and Conflict counts, workspace metadata, and valid next actions. Use --choice <id-or-number> for scripted input. A write-capable action also requires --confirm; guided mode does not approve proposals automatically or read private note bodies.

Recover past experience, then write for one target

If the Vault is empty, readiness says so and nothing is assumed from it:

python skills/career-agent/career_agent.py readiness --vault "$VAULT"      # bootstrap_suggested
python skills/career-agent/career_agent.py add-context "○○大学" --kind university --vault "$VAULT"
python skills/career-agent/career_agent.py experiences --vault "$VAULT"    # context -> experience -> evidence

A context is where an experience happened and is not always an employer; --kind covers company, university, internship, part-time workplace, club, volunteer group, personal work and open source. An experience is not always a project either. Evidence about something that did not happen at a job is captured with run --mode chat --non-work, which keeps coursework out of your work history.

Once there is evidence, a document is built for one target and checked before it can be rendered:

python skills/career-agent/career_agent.py document-model <company-slug> --vault "$VAULT" > model.json
python skills/career-agent/career_agent.py document-check --model model.json --draft draft.json
python skills/career-agent/career_agent.py document-render --model model.json --draft draft.json \
    --template standard-chuto --out ./career-docs

The check is deterministic: it refuses a number the evidence never recorded, an existing number rounded, 支援 (supported) written as 主導 (led), a JD keyword presented as a technology you used, a team's result written as your own, or an internal project name where an external_label exists. Passing means no known protected-claim violation is present — not that the Japanese has been proven faithful, which is why you read the document before sending it.

Rendering writes HTML with A4 print CSS; use your browser's print-to-PDF. Documents are never overwritten: the filename carries a digest of the evidence, JD, template and wording, so regenerating after a change writes a new file and leaves the old one alone. ./career-docs/ is not tracked by Git.

See skills/career-agent/SKILL.md for the full CLI contract.

Local-first does not mean fully offline

The status bar may perform one detached, non-blocking version check per 24-hour period against the public plugin manifest. It does not send Vault, pipeline, or candidate data. To disable that check completely, set:

export JAPAN_CAREER_NO_UPDATE_CHECK=1

Details of the persistence, context, workspace, and policy hardening in 1.6.2 and 1.6.3 are in CHANGELOG.md, rather than on this entry page.

Development

Read CONTRIBUTING.md before changing the repository. The canonical local verification command is:

python scripts/run_all_checks.py

The release guard is scripts/check_version_bump.py. Release history is in CHANGELOG.md.

The decision contract is documented in _shared/decision_philosophy.md and _shared/schemas.yml. Time-sensitive external claims belong in _shared/career_claims.yml.

Safety

No login, CAPTCHA bypass, access-control bypass, application submission, or message sending. The suite does not fabricate resume evidence or hiring outcomes.

MIT License.