Skip to content
Junior 0.20.0 · concurrent runs share the machine, warm worktrees, and reused lane evidence →
Small tasks. Big ideas.

Big plans.
Meet your junior.

(It already did the homework.)

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.

A little developer wearing headphones at a warmly lit coding workstation
A baby agent wearing sunglasses at a command-center laptop
A tiny agent suspended in a laser vault, working on a laptop
A baby agent in sunglasses and a trench coat beside a London streetlamp at night
A baby agent monitoring a tablet inside a rainy command van
A baby agent operating a drone above a nighttime city
A baby agent in a hood using a radio in a safehouse
A baby agent with glasses examining documents in an archive
A baby agent reviewing a tablet at a harbor command center
A baby agent studying a tablet in a car on a rainy night
A baby agent working at a railway station with a satellite dish
A baby agent controlling a drone on a nighttime rooftop
Illustrative execution
> Preparing worktree...
> Analyzing scope...
> Commodity model writing changes...
> Running tests...
Ready for review

THE CASE FOR A JUNIOR TEAM

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.

Explore sourced costs and capability gaps →

A BRIEF BEFORE THE WORK

It checks back before it acts.

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:

  • U1 scope: add retry handling to the webhook sender
  • A1 guess: retries happen in-process, not through a queue
  • A2 verified: 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.
ProfileModelUse it for
general (default)deepseek/deepseek-v4.1-flashBounded implementation: bug fixes, tests, small multi-file changes, docs and setup. Lowest cost; use unless the task clearly needs another profile.
deep-reasoningdeepseek/deepseek-v4-pro-0813Subtle debugging, concurrency, algorithms, performance work, or refactors whose correctness depends on careful analysis.
long-horizonmoonshotai/kimi-k2.7-codeLong autonomous coding sessions with many tool calls, large-codebase navigation, and front-end or UI implementation.
agentic-toolsz-ai/glm-5.3Tool-heavy work: shell, build, CI and environment setup, scripting, and many small command steps.
fast-mechanicalqwen/qwen3.7-flashCheap 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.

Native persisted analysis state

Explore FMECA on GitHub ↗

Critical path & dependencies

CPM Planner

Break a plan into defined deliverables, track dependencies, and identify the work that determines the finish date.

Persistent project database

Explore CPM Planner on GitHub ↗

Connected state graph

Crossmatrix

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 Crossmatrix on GitHub ↗

Contradictions & solution strategies

TRIZ

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 TRIZ on GitHub ↗

Browser testing & demos

Jevitate

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

Explore Jevitate ↗

Hypothesis interviews

Elicitation

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.

npm @matthew-cochran/scientific-process · hypothesis → experiment → verdict

Managed by Junior setup

Frontier plans, Junior executes

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.

READY IN ONE COMMAND

Check readiness, then let setup fix the rest.

junior doctor
junior setup

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.