Jonggrang

AI agents write code fast. Too fast. Jonggrang makes sure they don't make a mess while doing it.

Jonggrang is a CLI tool that puts AI coding agents through a Plan → Implement → Simplify → Test → Review pipeline. It breaks features into atomic tasks, runs each one with a fresh agent, and refuses to let anything through until the quality gates are green.

Works with four AI backends: OpenCode, Claude Code, OpenAI Codex CLI, and Jonggrang (built on Pi SDK). Pick your poison.

---

What Makes It Different

AI agents write code fast. Too fast. The bottleneck isn't speed — it's knowing when to stop and clean up.

Jonggrang enforces a pipeline where every feature passes through the same gates: Plan → Implement → Simplify → Test → Review. Not because every step is always necessary, but because skipping steps is how complexity accumulates silently.

Fresh context per task. Each task starts with a clean agent instance. No stale assumptions carrying forward. Hooks police in real-time — secrets blocked, context overload prevented, exit refused until quality gates pass. Simplify phase revisits every changed file to reduce complexity before the PR opens.

Left unchecked, an AI agent will always take the shortest path — even if that path goes through a minefield. Jonggrang puts up the guardrails.

→ Read the full philosophy & architecture

---

🚀 I Just Want to Use It

Five commands. That's all you need.

# In your project directory:
jonggrang init
jonggrang plan "what you want to build"    # AI writes a plan — you review it
jonggrang approve                          # Decompose plan into tasks
jonggrang work                             # Execute tasks one by one
jonggrang review                           # Comprehensive code review

One-shot shortcut:

jonggrang work "REST API for todo management" --yes

Interactive chat:

jonggrang agent    # Full TUI chat with /plan, /work, /review, etc.

→ Step-by-step guide for beginners

---

🔧 I Want to Hack on It

Come on in. The water's fine.

git clone <repo-url> && cd jonggrang
make install
make build

Project entry points: CLI binary, Pi TUI extension, web dashboard server. Hooks live in hooks/, skills in skills/, orchestration engine reads MANIFEST.yaml.

→ Full development setup guide

---

Commands at a Glance

Command	What it does
jonggrang init	Interactive wizard — sets up .jonggrang/, AGENTS.md, hooks, skills
jonggrang plan "desc"	AI analyzes the goal, asks clarifying questions if anything is ambiguous, then writes a draft plan to .jonggrang/.drafts/<session>/plan.md — human reviews before code
jonggrang plan --append <id> "desc"	Extend an existing approved plan: generate a delta draft for the additional scope only; on approve the new tasks are appended to that feature (numbering continues, completed tasks untouched)
jonggrang approve	Decomposes the most-recent draft (or --session <id>) into .jonggrang/.output/features/<id>/jonggrang-tasks.json. With --feature <id> (or a draft carrying append_to:) it decomposes into an existing feature instead of minting a new one
jonggrang work	Executes task queue with fresh context per task
jonggrang status	Shows task board
jonggrang review	Comprehensive code review → markdown report
jonggrang agent	Full TUI chat session with /plan, /work, /review commands
jonggrang web	Visual Kanban dashboard with real-time logs + parallel run (one worktree/branch per plan, review & push per branch)
jonggrang issues list	List GitHub/GitLab issues from configured sources (or --repo owner/repo)
jonggrang issues pickup <p> <repo> <n>	Generate a plan in this project from a GitHub/GitLab issue
jonggrang manifest	Inspect output files tracked per phase (list, show [id], add)
jonggrang memory	Read, recall, stage fragments, compact feature memory, and promote stable project lessons
jonggrang codemap	Show/refresh deterministic codebase map (LLM-free, cached at .jonggrang/codemap/codemap.json)

# Quick flags
jonggrang plan "feature" --yes       # Skip review, auto-approve
jonggrang work "feature" --yes       # Full pipeline in one command
jonggrang plan "feature" --src docs/brd.md  # Reference source document for the agent to read
jonggrang plan "feature" --deep      # 3-phase deep analysis (risks, alternatives)
jonggrang plan "feature" --base develop  # Cut the worktree from a chosen branch (fetched fresh from origin)
jonggrang plan "feature" --no-ask    # Skip the agent's clarifying-questions step
jonggrang plan --append feat-abc123 "also add rate limiting"  # Extend an approved plan (tasks appended, numbering continues)
jonggrang plan --append feat-abc123 "..." --deep  # Deep analysis on the added scope (Affected Areas / Risks)
jonggrang approve --session draft-abc123  # Approve a specific pending draft
jonggrang approve --feature feat-abc123    # Decompose the draft into an EXISTING feature (append)
jonggrang work --mode autonomous     # Override autonomy mode
jonggrang work --task task-003       # Execute specific task only
jonggrang work --feature feat-abc123 # Target a specific approved feature (multi-feature projects)

When the request is ambiguous, plan first asks you a few clarifying questions (pick an option — each carries its rationale — or type your own answer) so the agent plans from real intent instead of guessing. The Q&A is saved with the plan and reused on plan --revise. The web dashboard shows the same questions as a form.

---

Requirements

• Node.js (latest LTS)
• An AI agent — pick one:
  • OpenCode → curl -fsSL https://opencode.ai/install | bash
  • Claude Code → npm install -g @anthropic-ai/claude-code
  • OpenAI Codex CLI → npm install -g @openai/codex
  • Jonggrang (Pi SDK) → npm install -g @earendil-works/pi-coding-agent
• jq → brew install jq
• git

---

Configuration

// .jonggrang/jonggrang.json (after init)
{
  "tool": "opencode",          // opencode | claude | jonggrang | codex
  "mode": { "autonomy": "balanced" },
  "work": { "max_iterations": 0 }   // 0 = unlimited (run until all tasks complete)
}

Two-layer config: ~/.jonggrang/settings.json (your defaults) → .jonggrang/jonggrang.json (this project's quirks).

→ Full config reference

---

📚 More Reading

Doc	When you want to...
QUICKSTART.md	Get building in 5 minutes
QUICKSETUP.md	Set up your dev environment
PHILOSOPHY.md	Understand why this thing exists
JONGGRANG.md	Read the full blueprint
WORKFLOW.md	Grok the 16-phase pipeline
SKILLS.md	Teach the agents new tricks
CONFIG.md	Tweak every knob
COMMIT-CONVENTION.md	Write agent-readable commit messages

---

Contributors

• Eka Irawan (Ibnu) + Ahmad Anshorimuslim Syuhada (Ans)

→ Full credits & backstory

---

License

MIT © Porcupine Team

See LICENSE for full text. TL;DR: free to use for anything, including commercial, with no warranty. Contributors are protected from liability.