Your frontier model asks. Junior reads the code, checks the risks, drafts the plan, and comes back with options and its understanding of the job. You pick. It ships—locally or through an operator-controlled remote worker.
Keep your senior on the hard decisions. Let your junior do the legwork.
Your frontier model frames the problem and sets the acceptance bar. Junior reads the code, researches the options, sets up the work, and checks back with its understanding before it commits to an approach. The senior still decides.
JUNIOR · RESEARCH, SETUP & EXECUTION
The legwork, done and checkable
Searching the scoped codebase, reading the surrounding code, gathering options with their tradeoffs, preparing the environment, and executing the chosen plan. Bounded reconnaissance returns evidence, not just an answer. When something is genuinely ambiguous, it checks back instead of guessing.
SENIOR · JUDGMENT & ACCEPTANCE
The judgment stays with you
Framing the deliverable, choosing between the options Junior brings back, weighing architectural tradeoffs, and giving final acceptance. Unclear requirements, failures spanning several systems, and decisions that are expensive to reverse still deserve experienced attention.
“Junior” describes a role and a spending budget, not low intelligence. Commodity means economical to use repeatedly; it does not necessarily mean small, open-source, or less capable on every task.
When the contract leaves something to decide, Junior reads the code, states its understanding, and brings back options instead of guessing. You pick one; your correction becomes a constraint.
Illustrative briefneeds_choice
understanding:
U1scope: add retry handling to the webhook sender
A1guess: retries happen in-process, not through a queue
A2verified:src/webhooks/sender.ts:42
options:
A · in-process backoff
Simplest to ship; depends on A1 and only survives the process.
B · durable outbox
Survives restarts; adds a table and a migration to review.
recommendation:
B, if retries must survive a deploy; otherwise A.
reply:
junior handoff task.json --choose B --correct A1="retries go through the outbox"
It only checks back when there is something to decide; a trivial change goes straight through. Planned contracts get the same care: when Jev judges one unclear, the run stops with numbered questions before any worker starts, and your answers become constraints on the workflow you chose.
The Manager-Junior dynamic
You define the scope. The junior executes. You review the handoff. Clear scope. Clear accountability.
1. Plan
Write a clear prompt detailing the specific deliverable. Treat it like assigning a ticket to a junior developer.
2. Delegate
Junior creates a clean Git worktree and delegates execution to a commodity model, bounded by explicit acceptance criteria, runtime budgets and recorded consent for any external context handoff.
3. Review
Get a compact receipt. Review the generated code and independent test results before accepting changes into your branch.
NEW IN 0.20
Run lanes in parallel.
Fan a plan out to many lanes on one machine, then integrate them with one build instead of one per lane.
Share the machine
Every worker and check takes a slot shared by all Junior runs on the machine, and nothing starts while memory is low or swap is busy. Per-command pools cap heavy builds.
Start warm
isolationSetup.warmFrom copies build caches into each new worktree, so a lane does not compile from cold. It never symlinks into your tree.
Land once
junior land applies the reviewed lanes, reuses each lane check whose evidence identity is unchanged on the final tree, and runs one compile for the batch.
A CHECK BEFORE EXECUTION
When the handoff needs senior attention.
Jev assesses whether the deliverable needs frontier attention, whether its contract is clear, and whether unresolved assumptions could change the implementation. Junior returns a compact recommendation so the manager can clarify, re-scope, or take over.
Enforce
A frontier-required, blocked, or uncertain preflight returns needs_review before the commodity worker starts.
Shadow
Records the assessment and continues. It is advisory, not a blocking filter.
Manager decides
The receipt reports frontier_required, delegate, clarify, or uncertain with a reason and probability. No frontier model is called automatically. Jev is optional; it defaults to off.
Enable the frontier-attention and readiness filter in the task contract with "jev": {"mode": "enforce"}. After execution, a completion gate can flag acceptance gaps against check results and change evidence. Classification supports review; it does not guarantee correctness.
COMMODITY MODELS ONLY
One cheap default. Changes need your sign-off.
Junior never runs a deliverable on a frontier model. It executes only on commodity or open-weight models, and it stays on the cheapest capable default unless a human approves a different one.
Commodity-only execution
DeepSeek, Moonshot, Z.ai, Qwen, MiniMax, Meta Llama and openai/gpt-oss*. A frontier or unknown vendor is refused before any paid call.
DeepSeek V4.1 Flash by default
Contracts and plans are shaped so the cheapest model can finish the work. A deliverable that needs more is a signal to re-scope, not to spend more.
Approval, not assumption
Another profile needs a human's approval per run, plan or project, with a rationale and the price change. A routing pick never counts as consent.
Junior's built-in commodity model roster and each profile's intended use.
Profile
Model
Use it for
general (default)
deepseek/deepseek-v4.1-flash
Bounded implementation: bug fixes, tests, small multi-file changes, docs and setup. Lowest cost; use unless the task clearly needs another profile.
deep-reasoning
deepseek/deepseek-v4-pro-0813
Subtle debugging, concurrency, algorithms, performance work, or refactors whose correctness depends on careful analysis.
long-horizon
moonshotai/kimi-k2.7-code
Long autonomous coding sessions with many tool calls, large-codebase navigation, and front-end or UI implementation.
agentic-tools
z-ai/glm-5.3
Tool-heavy work: shell, build, CI and environment setup, scripting, and many small command steps.
fast-mechanical
qwen/qwen3.7-flash
Cheap mechanical edits: renames, formatting, boilerplate and small summaries.
Routing, price-gated upgrades, roster overrides, Jev gateways and LiteLLM proxies are covered in the Junior models reference.
MORE THAN A CODING PROMPT
The Junior toolbelt.
Plan the deliverable, examine the risks, and preserve the reasoning that shaped it. The manager and worker can work from shared, saved evidence.
Failure modes & criticality
FMECA
Identify how a deliverable or handoff could fail, rank the risks, and record mitigations before execution.
Jobs, journeys, code, risks, plans and ADRs tied together in one committed graph that stays in sync as they change, so a feature can be traced to its code and tests.
Committed .crossmatrix/ store · stays in sync with your repository
Explore technical or physical contradictions using a catalog of inventive principles. Jev classification suggests applicable conflicts; the catalog provides structured options.
Optional separate CLI · repository access required
Explore, replay and regression-check real user journeys in a browser, gate CI on the result, and turn a journey into a narrated demo. A pass/fail jevitate check can verify a delivered change.
npm @jevitate/cli · ships its own agent skills and MCP server
Requirements interviews that treat every claim as a hypothesis: probe it, mark it verified or a guess, and surface the assumptions a deliverable rests on before work starts.
Requirements interviews · claims are hypotheses
Managed by Junior setup
Investigations
Scientific process
Run a hypothesis → experiment → verdict investigation: state the claim, design the cheapest test that could disprove it, run it, and record the verdict as evidence.
The manager plans in CPM and weighs risks in FMECA. CPM leases the ready, non-conflicting deliverables; each becomes a bounded Junior contract on a commodity model; the manager reviews the receipt, applies it with junior apply and marks it done. Every call goes through junior tools call, so plan, risk and trace state are saved as evidence, with no MCP setup.
junior init installs every tool and its agent skills, checksum-verified, and junior update keeps them current. See the tools reference and planning guide.
Delegate deliberately.
Choose a commodity worker when…
You can specify what must be delivered, constrain the files and tools, and check the result. There is enough implementation work to justify a handoff, and failures are recoverable.
Keep it with the senior when…
The hard part is deciding what to build, diagnosing an unclear system failure, or making a consequential tradeoff. Tiny edits may cost more to delegate than to finish directly.
Escalate when…
The bounded attempts run out, checks keep failing, assumptions break, or scope grows. Return the evidence and unfinished work so the manager can choose the next step.
Why open weights?
Junior executes only on commodity or open-weight models, and a frontier or unknown provider is refused before any spend. Within that policy, open-weight models can offer a choice of hosts, inspectable weights, and self-hosting under their license. Openness, price, and capability are separate choices, and the default stays on the cheapest capable commodity model until a human approves another.
A hosted open-weight API still sends data to its provider. Self-hosting requires hardware and operations; large models are not automatically cheap to run locally. Check the model license and your provider’s data terms. Example open-weight license.
Junior makes the handoff manageable.
A defined deliverable. A bounded worker run. Independent checks. A compact receipt with changes, usage, and unresolved work. You keep the planning context small and reserve frontier attention for decisions and review.
Built for clean handoffs
Junior Agent is a CLI tool designed for precise, recoverable task delegation. Define the deliverable, run independent checks, and keep the evidence you need to review the result.
Git Worktrees
Executes in an isolated worktree. Your current branch remains untouched until you approve, then junior apply brings the reviewed change in. By default the worker gets only the contract and four tools (read, bash, edit, write): no skills, extensions, MCP servers or context files from your machine.
Independent Checks
Runs designated linters and tests. It verifies the work before handing it back.
Recoverable handoff
Provides changed files, check results, model usage, and cost when pricing is available.
Consent-gated context
Before project context is sent to an external provider, Junior records the destination, model and file scope and requires your run or project consent. Clarification stays local to the decision before execution begins.
Controlled remote compute
For work that needs a remote runner, Junior can use bounded Pi transport and a safely reconciled Hetzner pool. Provisioning, scaling and release remain explicit operator actions.
↳
Bounded execution
Hard deadlines and bounded repair attempts. Partial changes and diagnostics are preserved when execution stops.
Illustrative receiptready_for_review
task:"Implement JWT refresh token rotation"
model:"commodity model"
status:"ready_for_review"
files_changed:
M src/auth/jwt.ts
M src/routes/auth.ts
A tests/auth.test.ts
cost:unavailable without provider pricing
> Worktree preserved at /tmp/jr-auth-123 > Manager review required before acceptance
ONE PROMPT TO YOUR CODING AGENT
Give your agent a junior.
Paste this into Cursor, Codex, Claude Code, GitHub Copilot, Gemini CLI, or another coding agent with terminal access. The guide installs Junior, wires up the delegation skill, and checks your project’s readiness. Provider login stays with you.
Agent setup prompt
Help me set up Junior for this project. Read https://junioragent.dev/INSTALL.md and follow the setup steps. Install the manager skill, verify readiness, and report any missing prerequisites before delegating work.
junior doctor is read-only and reports what is ready and what is missing, including a stale Junior skill. junior setup previews the repair plan, asks before it changes anything, then applies it — registering Junior through claude/codex mcp add or Cursor’s mcp.json. Junior also notices newer releases, and junior update adopts them. Before a paid run, junior model status shows the commodity roster and junior plan check lints a plan into bounded handoffs.
Prefer to install it yourself?
Requires Node.js 24+, npm, and Git. Install (or upgrade) the CLI from npm, then run project init inside the project you want your agent to manage.
npm uninstall -g @matthew-cochran/junior && npm install -g @matthew-cochran/junior@latest --prefer-online && junior --version
junior init --target both
junior doctor --check-updates
The public-domain commands require the site to be deployed. For this local preview, use its origin instead. Init installs project-local Codex and Claude Code skills, the tested Pi dependency, the prebuilt FMECA, CPM, Crossmatrix, scientific-process and elicitation tools, and the npm companions fmeca, cpm, crossmatrix, scientific-process, elicitation, jevitate and triz with their skills. It stays on the commodity default, DeepSeek V4.1 Flash, unless a human approves another model; junior model status reports the roster and junior update adopts newer releases. The setup guide adds a managed AGENTS.md entry for other agents and a small adapter when your IDE needs its own instruction file. Follow the guide for authentication and unresolved prerequisites.
Junior is MIT licensed. Open-source CLI repository. Initialization preserves existing configuration; live model calls require your authorization.