juggle

KO | EN

gitlite — search

#javascript #android #machine-learning #linux #docker #nodejs #macos #java #windows #awesome-list #vue #security #ios #open-source

(★ 15)

CLI Ralph Loops with Good UX

juggle Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Juggle

Unopinionated Ralph Loop runner. Runs an AI coding agent in a loop with fresh context per iteration.

## What is a Ralph Loop?

A Ralph Loop runs an AI agent repeatedly, each iteration starting a new session with fresh context. The agent reads its own previous output from files and git history rather than relying on conversation memory. The pattern is named after Ralph Wiggum.

## Why juggle?

- **Unopinionated.** No conventions about what files your agent reads or writes, what task system you use, or how you track progress. Juggle runs the loop. You bring the workflow.
- **Fresh context per iteration.** Each loop starts a new agent session. State lives in git, not LLM memory.
- **Cost-aware.** Built for overnight runs with `--max-cost`, `--max-failures`, and automatic quota backoff.
- **Composable.** Shell hooks (`--cmd-after`, `--stop-when`), phase agents (`--agent-before`, `--agent-after`), and environment variables let you wire in verification gates without juggle imposing a workflow.

I kept running into the same problem: I wanted to run different kinds of agent loops -- overnight "find a problem and fix it" runs, trigger-based loops that watch a file for updates, and Ralph Loops that work through a list of tasks. None of the existing tools did all of these. My own scripts were too rigid. The Claude Code `/loop` command builds up context instead of starting fresh. And none of them let me reuse prompt templates.

Juggle exists to solve all of this in one tool -- strong enough to trust with your workflow, flexible enough to fit any workflow.

</details>

## Quick start

```bash
# Run 3 iterations on a task
juggle loop "fix the failing tests" -n 3
```

```bash
# Leave it running overnight -- find and fix issues autonomously
juggle loop "Find one issue to fix or improvement to make. Check git log to avoid repeating past work." -n 20 --max-cost 10
```

```bash
# Work through a todo list while you sleep
juggle loop "Read TODO.md and implement the next unchecked item. Mark it done when complete." -n 0 --max-cost 20
```

```bash
# @file reads a file's contents into the prompt
juggle loop @task.md -n 5
```

```bash
# Mix and match -- all positional args join into one prompt
juggle loop @tdd @fix "the login form rejects valid emails" -n 5
```

```bash
# Point JUGGLE_PROMPTS at a library of reusable prompts
export JUGGLE_PROMPTS=~/prompts
juggle loop @tdd @fix "broken email validation" -n 5
```

[prompt-lego](https://github.com/jeprecated/prompt-lego) is a starter kit of reusable prompt files that work out of the box.

```bash
# Add a test gate -- stop when tests pass
juggle loop @tdd @fix "broken email validation" --cmd-after "make test" --stop-when "make test" -n 10
```

```bash
# Run a code review agent after each iteration
juggle loop @fix "broken email validation" --agent-after @code-review -n 5
```

```bash
# Watch a directory -- agents pick up tasks as they appear
juggle queue @tdd --watch tasks/ready/
```

`juggle queue --watch` runs a fresh agent session for each file in a directory, and waits for new files to appear. That pairs naturally with a task queue like [frontloop](https://github.com/jeprecated/frontloop), which stores tasks as markdown files in `.frontloop/ready/` -- you plan tasks while a background juggle loop works through them. But juggle doesn't care where tasks come from -- a directory of markdown files, a script that dumps issues, or anything else that puts files in a folder.

All positional args are prompt content -- strings and `@file` references join into the final prompt. Point `JUGGLE_PROMPTS` at a directory of reusable prompts and compose them like lego pieces.

## Prompt library

Set `JUGGLE_PROMPTS` to a directory of reusable prompt files. Reference any file with `@name` — no path needed:

```bash
export JUGGLE_PROMPTS=~/prompts
juggle loop @tdd @fix "broken email validation" -n 5
```

**Resolution order** for a bare `@name` (no `/`):

1. Literal path — `name` read as-is from disk
2. `$JUGGLE_PROMPTS/name`
3. `$JUGGLE_PROMPTS/name.md` (only when `name` has no extension)
4. Alias scan — all files in `$JUGGLE_PROMPTS` checked for a matching `aliases` frontmatter entry
5. Error

Names containing `/` (like `@./local/task.md`) skip steps 2–4 and are treated as literal paths only. Frontmatter is stripped from every file resolved via `$JUGGLE_PROMPTS`.

**Aliases** let a single file answer to multiple names. Add YAML frontmatter:

```markdown
---
aliases: [fix, fixer, bugfix]
---

You are a careful bug-fixing agent...
```

`@fix`, `@fixer`, and `@bugfix` all resolve to that file. Base name (filename without extension) always wins over an alias — `fix.md` is found at step 2 before aliases are checked. Two files declaring the same alias is an error.

**Organizing prompts** — bare-name resolution only searches the top level of `$JUGGLE_PROMPTS`. Subdirectories are for grouping; files in them must be referenced by full path.

```
~/prompts/
├── tdd.md           # @tdd
├── fix.md           # @fix
├── review.md        # @review
└── roles/
    └── senior.md    # @/home/you/prompts/roles/senior.md
```

**Autocomplete** — `juggle completion bash|zsh|fish|nushell|powershell` generates a shell completion script. When enabled, pressing tab after `@` suggests prompt names and aliases from `$JUGGLE_PROMPTS`. Run `juggle completion --help` for setup instructions.

## Install

**macOS (Homebrew):**

```bash
brew tap jeprecated/tap && brew install juggle
```

**Windows (Scoop):**

```bash
scoop bucket add jeprecated https://github.com/jeprecated/scoop && scoop install juggle
```

**Linux:**

```bash
curl -sSL https://raw.githubusercontent.com/jeprecated/juggle/main/install.sh | bash
```

**Go:**

```bash
go install github.com/jeprecated/juggle/cmd/juggle@latest
```

## Features

- **Loop control** -- iterations, delay with jitter, per-iteration timeout, resume after crash
- **Queue mode** -- wait for triggers: watch directories, fixed intervals, or HTTP endpoints (`juggle queue @worker-rules.md --watch tasks/ready/`)
- **Lifecycle hooks** -- run shell commands before/after each iteration, stop on a condition
- **Phase agents** -- run separate agent sessions before/after the main loop or each iteration
- **Pipeline** -- define ordered `agent` and `cmd` nodes with events, dependencies, conditions, and failure policies (`juggle pipeline --file pipeline.toml`)
- **Config file** -- `juggle.toml` for project-level defaults
- **JSONL logging** -- per-iteration token counts, cost estimates, and run summary
- **Failure handling** -- stop, continue, or retry with backoff on agent failures

Run `juggle --help` for the full flag reference.

## Providers

Juggle wraps AI coding CLIs. Supported providers:

| Provider | Binary | Flag |
|----------|--------|------|
| Claude Code (default) | `claude` | `--provider claude` |
| OpenCode | `opencode` | `--provider opencode` |
| OpenAI Codex | `codex` | `--provider codex` |
| Gemini CLI | `gemini` | `--provider gemini` |
| Custom | any | `--agent-cmd "your-cli"` |

Some juggle flags map to provider-native equivalents automatically. Flags marked `--` emit a warning and are skipped — use passthrough flags instead.

| Flag | Claude | Codex | Copilot | Gemini | OpenCode |
|------|--------|-------|---------|--------|----------|
| `--allowed-tools` | yes | -- | yes | -- | -- |
| `--disallowed-tools` | yes | -- | yes | -- | -- |
| `--max-turns` | yes | -- | yes | -- | -- |
| `--mcp-config` | yes | -- | -- | -- | -- |
| `--hooks-file` | yes | -- | -- | -- | -- |

## Passthrough flags

Pass provider-native flags directly to the agent CLI with `-X` (repeatable) or `--` (everything after):

```bash
# -X appends one arg at a time
juggle loop -X "--json" "summarise this repo" --provider codex

# -- passes everything after it verbatim
juggle loop "fix tests" -- --max-turns 50 --allowedTools Bash,Read
```

Both forms are equivalent. `-X` is useful in config files and scripts where `--` can be awkward.

**Codex examples** — Codex uses `-c` for runtime config overrides:

```bash
# Override the model
juggle loop --provider codex -X "-c" -X 'model="o3"' "refactor auth"

# Get structured JSON output
juggle loop --provider codex -X "--json" -X "-o" -X "result.txt" "extract API endpoints"

# Set sandbox policy
juggle loop --provider codex "fix tests" -- -c 'sandbox_permissions=["disk-full-read-access"]'
```

**Claude examples:**

```bash
# Limit tools and turns via passthrough (equivalent to juggle's --allowed-tools and --max-turns)
juggle loop "fix tests" -- --allowedTools Bash,Read --max-turns 50

# Pass a custom MCP config
juggle loop -X "--mcp-config" -X "./mcp.json" "check the database"
```

## Environment variables

Juggle exposes loop state to every spawned agent process. Prompts, skills, and MCP servers can read these.

| Variable | Description |
|----------|-------------|
| `JUGGLE_ITERATION` | Current iteration number (1-indexed) |
| `JUGGLE_MAX_ITERATIONS` | Total planned iterations (`0` = unlimited) |
| `JUGGLE_RUN_ID` | Stable UUID for the entire run |
| `JUGGLE_MODEL` | Model name passed to the agent |
| `JUGGLE_PROVIDER` | Provider name (`claude`, `opencode`, ...) |
| `JUGGLE_LABEL` | Run label if `--label` was set (omitted otherwise) |
| `JUGGLE_TASK_FILE` | *(queue --watch)* Absolute path to the current task file |
| `JUGGLE_WORKER_ID` | *(queue --watch)* 0-indexed worker number |

## Prerequisites

One of the supported AI coding CLIs installed and authenticated:
[Claude Code](https://claude.ai/code),
[OpenCode](https://opencode.ai/),
[Codex](https://github.com/openai/codex),
[Gemini CLI](https://github.com/google-gemini/gemini-cli),
or any CLI via `--agent-cmd`.

## License

MIT

juggle

juggle Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

juggle

juggle Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README