"I'm in danger!" - Ralph Wiggum, every time you Ctrl+C a working AI loop too early

AI-Powered Code Automation with Structured Task Management

juno-code

The Ralph Method, but better. Controlled AI iteration loops with structured kanban task tracking, multi-backend support (Claude, Codex, Gemini), and full git traceability.

View on GitHub npm Package

MIT License

Multi-Backend

Kanban Tasks

Git Traceability

Iteration Control

Slack Integration

The Ralph Method: Where It All Started

Geoffrey Huntley's Ralph Method demonstrated something remarkable: AI can deliver production-quality software through iterative refinement. One engineer reportedly delivered a $50,000 project for $297 using this technique.

Ralph's Problems

One-time only - Shines for single big tasks, doesn't scale to iterative development

Overcooking - Loop runs too long, AI adds features nobody asked for

Undercooking - You Ctrl+C too early, work is incomplete

Fragile state - Markdown files as source of truth; LLMs can corrupt format

Vendor lock-in - Built for Claude Code only

No traceability - Changes blend together, hard to debug

juno-code Solutions

Iteration control - -i 5 for exact iterations, or "until tasks done"

Structured kanban - NDJSON format can't be corrupted by LLM formatting

Multi-backend - Claude, Codex, Gemini, Cursor with one flag

Full traceability - Every task links to a git commit

Hooks without lock-in - Works with ANY backend

Human-readable logs - -v gives structured output

Inspired by ghuntley.com/ralph/ - The $50K for $297 Technique

Get Started in Minutes

Install juno-code and start your first AI-powered coding session

Installation

npm install -g juno-code

Initialize Project

# Initialize in your project
juno-code init --task "Your task description" --subagent claude

Basic Usage

Multiple ways to run juno-code based on your workflow

Start Execution

# Start execution - uses .juno_task/init.md (initial task definition)
juno-code start -b shell -s claude -i 5 -v

# Default execution - uses .juno_task/prompt.md (optimized Ralph prompt)
juno-code -b shell -s claude -i 5 -v

# Or with a custom prompt
juno-code -b shell -s claude -i 5 -p "Fix the login bug"

# Quick subagent shortcuts
juno-code claude "your task"
juno-code codex "your task"
juno-code gemini "your task"

Key insight: Running juno-code start without -p uses.juno_task/init.md (your initial task definition). Running juno-code (without start and without -p) uses.juno_task/prompt.md—the production-ready prompt template that implements the Ralph method with guard rails.

Key Features

Everything you need for AI-powered iterative development

Iteration Control

No more overcooking or undercooking. Set exact iterations with -i 5 or run until all tasks complete.

Structured Kanban

NDJSON-based task tracking via juno-kanban. Strict format that can't be corrupted by LLM formatting errors.

Multi-Backend

Switch between Claude, Codex, Gemini, or Cursor with one flag. No vendor lock-in.

Full Traceability

Every task links to a git commit. Jump to any point in development history.

Lifecycle Hooks

Run scripts at START_ITERATION, END_ITERATION, and more. Works with ANY backend.

Real-time Feedback

Provide feedback while AI is running. Guide the development without stopping.

Backends & Services

Use any AI model with model shorthands for quick switching

Claude

Default: claude-sonnet-4-5-20250929

:haiku

:sonnet

:opus

Codex

Default: codex-5.2-max

:codex

:gpt-5

:mini

Gemini

Default: gemini-2.5-pro

:pro

:flash

:pro-3

:flash-3

Backend Switching Examples

# Stuck on a bug? Try different models

juno-code -b shell -s claude -m :opus -i 1 -v

juno-code -b shell -s codex -m :codex -i 1 -v

juno-code -b shell -s gemini -m :flash -i 1 -v

Kanban Task Management

Built-in structured task tracking via juno-kanban

Kanban Commands

# List tasks
./.juno_task/scripts/kanban.sh list --limit 5
./.juno_task/scripts/kanban.sh list --status backlog todo in_progress

# Get task details
./.juno_task/scripts/kanban.sh get TASK_ID

# Mark task status (backlog, todo, in_progress, done)
./.juno_task/scripts/kanban.sh mark in_progress --ID TASK_ID
./.juno_task/scripts/kanban.sh mark done --ID TASK_ID --response "Fixed auth, added tests"

# Update task with git commit reference
./.juno_task/scripts/kanban.sh update TASK_ID --commit abc123

Ralph vs juno-code

See why juno-code is the evolution of the Ralph Method

Feature	Ralph	juno-code
Design Focus	One-time tasks (migrations, rewrites)	Iterative development (scales to 1000s of tasks)
Core Loop	`while :; do claude; done`	Controlled iterations
Stopping	Ctrl+C (guesswork)	`-i N` or "until tasks done"
Source of Truth	Markdown files (TASKS.md, PLANNING.md)	Structured kanban over bash
Format Integrity	Relies on LLM instruction-following	Strict format, always parseable
Multiple AIs	Claude only	Claude, Codex, Gemini, Cursor
Traceability	None	Every task → git commit
Hooks	Claude-specific	Works with any backend
Verbose Output	Raw JSON	Human-readable + jq-friendly
Feedback	None	Real-time during execution

Advanced Features

Session management, real-time feedback, and lifecycle hooks

Session Management & Feedback

# Session management
juno-code session list           # View all sessions
juno-code session info abc123    # Session details
juno-code --resume abc123 -p "continue"  # Resume session
juno-code --continue -p "keep going"     # Continue most recent

# Real-time feedback while running
juno-code feedback "found a bug in the auth flow"
juno-code feedback --interactive

Lifecycle Hooks

// config.json - Hooks without lock-in
{
  "hooks": {
    "START_ITERATION": { "commands": ["./scripts/lint.sh"] },
    "END_ITERATION": { "commands": ["npm test"] }
  }
}

run_until_completion.sh

Continuously run juno-code until all kanban tasks are completed with pre-run commands and hooks

Usage with --pre-run and --pre-run-hook

# Run until all kanban tasks complete
./.juno_task/scripts/run_until_completion.sh -s claude -i 5 -v

# Execute commands before main loop (--pre-run)
./.juno_task/scripts/run_until_completion.sh \
  --pre-run "./scripts/sync.sh" \
  -s claude -i 5 -v

# Execute named hooks from config.json (--pre-run-hook)
./.juno_task/scripts/run_until_completion.sh \
  --pre-run-hook SLACK_SYNC \
  -s claude -i 5 -v

--pre-run Command

• Execute commands before the main loop starts
• Useful for syncing with external services, running linters
• Can specify multiple: --pre-run "cmd1" --pre-run "cmd2"
• Alternative: JUNO_PRE_RUN env var

--pre-run-hook Hook

• Execute named hooks from .juno_task/config.json
• Hooks group multiple commands that run together
• Can specify multiple: --pre-run-hook HOOK1 --pre-run-hook HOOK2
• Alternative: JUNO_PRE_RUN_HOOK env var

Slack Integration

Team collaboration via Slack channels - submit tasks and receive AI responses

1. Fetch

slack_fetch.sh monitors Slack and creates kanban tasks

2. Process

AI agent processes tasks and records responses

3. Respond

slack_respond.sh sends replies as threaded messages

Slack Commands

# Fetch messages from Slack and create tasks
./.juno_task/scripts/slack_fetch.sh --channel bug-reports

# Send completed task responses back to Slack
./.juno_task/scripts/slack_respond.sh --tag slack-input

# Automated workflow with hooks
./.juno_task/scripts/run_until_completion.sh \
  --pre-run "./.juno_task/scripts/slack_fetch.sh --channel bugs" \
  -s claude -i 5 -v

Configuration

# Environment setup (.env file)
SLACK_BOT_TOKEN=xoxb-your-token-here
SLACK_CHANNEL=bug-reports

# config.json hook for automated Slack sync
{
  "hooks": {
    "SLACK_SYNC": {
      "commands": [
        "./.juno_task/scripts/slack_fetch.sh --channel bugs",
        "./.juno_task/scripts/slack_respond.sh --tag slack-input"
      ]
    }
  }
}

Slack Bot Setup

Create app at api.slack.com/apps
Add scopes: channels:history, channels:read, groups:history, groups:read, users:read, chat:write
Install to workspace and copy the Bot User OAuth Token (xoxb-...)
Add token to .env file as SLACK_BOT_TOKEN

CLI Reference

Complete command-line options

Flag	Description
`-b, --backend <type>`	Backend: `mcp`, `shell`
`-s, --subagent <name>`	Service: `claude`, `codex`, `gemini`, `cursor`
`-m, --model <name>`	Model (supports shorthands like `:opus`, `:haiku`)
`-i, --max-iterations <n>`	Iteration limit (-1 for unlimited)
`-p, --prompt <text>`	Prompt text (`start` uses init.md, main command uses prompt.md)
`-v, --verbose`	Human-readable verbose output
`-r, --resume <id>`	Resume specific session
`--continue`	Continue most recent session

Project Structure

What gets created after juno-code init

your-project/
├── .juno_task/
│   ├── init.md           # Task breakdown (your input)
│   ├── prompt.md         # AI instructions (Ralph-style prompt)
│   ├── plan.md           # Progress tracking
│   ├── USER_FEEDBACK.md  # Issue tracking
│   ├── config.json       # Configuration
│   ├── scripts/          # Auto-installed utilities
│   │   ├── run_until_completion.sh
│   │   ├── kanban.sh
│   │   └── install_requirements.sh
│   └── tasks/            # Kanban tasks (ndjson)
├── CLAUDE.md             # Session learnings
└── AGENTS.md             # Agent performance

Environment Variables

Configure juno-code via environment

# Primary
export JUNO_CODE_BACKEND=shell
export JUNO_CODE_SUBAGENT=claude
export JUNO_CODE_MODEL=:sonnet
export JUNO_CODE_MAX_ITERATIONS=10

# Service-specific
export CODEX_HIDE_STREAM_TYPES="turn_diff,token_count"
export GEMINI_API_KEY=your-key
export CLAUDE_USER_MESSAGE_PRETTY_TRUNCATE=4

Ready to Try the Ralph Method, But Better?

Start building with controlled AI iterations, structured task tracking, and full git traceability.

Get Started on GitHub View on npm

Credits: Inspired by Geoffrey Huntley's Ralph Method