junai — Let AI Think. Let Code Route.
25 specialised AI agents. A 9-stage deterministic pipeline. Zero hallucinated routing.
"Trust the LLM to pick the right agent" — worked great, right up until it didn't.
junai is Un-AI routing with full AI power.
Your agents stay smart. Your pipeline stays predictable.
- No hallucinated routing — a Python state machine owns all transitions; git-blameable, auditable
- Deterministic gates — key decisions require explicit approval; the pipeline cannot guess past them
- Predictable output — 9 stages, 23 agents, 0 surprises
What It Is
junai is a portable agent framework for VS Code + GitHub Copilot. It gives you:
- 25 specialised agents — Architect, Implement, Tester, Code Reviewer, Debug, Security Analyst, Anchor, and more
- A deterministic pipeline — a Python state machine owns all routing logic; the LLM cannot hallucinate the wrong next step
- Three pipeline modes — supervised (you approve everything), assisted (agents route, you approve gates), and autopilot ⚠️ (beta — agents route, smart gates, only intent requires approval)
- 121 reusable skills, 30 prompts, 24 instruction files — loaded dynamically by agents as needed
- Chat-first UX — init, reset, mode switch, gate approval all from the Copilot chat window
Prerequisites
| Requirement | Notes |
|---|
| VS Code | Any recent version |
| GitHub Copilot | Agent mode must be enabled in Copilot Chat settings |
| Python 3.11+ | Must be on PATH |
| Git | For pipeline commits |
| PowerShell 5.1+ | Windows built-in; required for sync.ps1 |
Setup — Path A: New Project (Fastest) ⚡
Fastest of all: Install the junai — Agent Pipeline VS Code extension, open any project, run junai: Initialize Agent Pipeline from the command palette, and skip straight to step 3 below. No cloning, no PowerShell needed.
- Click "Use this template" → "Create a new repository" on this page
- Clone your new repo, open it in VS Code
- One-time venv setup (30 seconds — we timed it):
python -m venv .venv
.venv\Scripts\pip install -r .github/tools/mcp-server/requirements.txt -r .github/tools/pipeline-runner/requirements.txt
- Reload VS Code — the 8 junai MCP tools appear in the Copilot Chat tools icon (⚙)
- Edit
.github/project-config.md — set your project name and stack
- Edit
.github/copilot-instructions.md — the extension creates this with a managed section; add your architecture overview, DB names, and key file paths outside the <!-- junai:start --> markers
- Open Copilot Chat → select Orchestrator from the agent dropdown → describe what you want to build
VS Code note: Custom agents aren't invoked via @AgentName mentions in chat. Click the agent icon in Copilot Chat and select Orchestrator from the list to activate it.
Setup — Path B: Existing Project
- Clone junai anywhere on your machine:
git clone https://github.com/saajunaid/junai
- Add to your PowerShell
$PROFILE (once per machine):
. 'C:\Path\To\junai\sync.ps1'
- From your existing project root:
junai-pull
Deploys .github/ (agents, skills, prompts, instructions, diagrams, tools) into your project.
- Create venv (same as Path A step 3), reload VS Code
- Configure
project-config.md and add your project context to copilot-instructions.md (outside the <!-- junai:start --> managed section), then open Copilot Chat → select Orchestrator from the agent dropdown
Your First Pipeline — Chat Commands
No terminal needed after setup. Everything runs from Copilot Chat (with Orchestrator selected):
| Say this | What happens |
|---|
| "Start a new pipeline for feature: dark mode" | pipeline_init creates state, Orchestrator classifies and routes |
| "Switch to assisted mode" | Agents route automatically, gates still require your approval |
| "Switch to autopilot mode" | Agents route + gates auto-satisfied (beta) |
| "Approve plan_approved" | Satisfies a gate — gates are never bypassed in any mode |
| "What stage are we at?" | Returns current stage, mode, blocked_by |
| "Reset pipeline for next feature: X" | Wipes state and starts fresh |
Pipeline stages
intent → prd → architect → plan → implement → tester → review → closed
Hotfix fast-track: intent → implement → tester → closed
Pipeline Modes
