Skip to content

docs: add --json-stream to commit, finish, and rebase patterns #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
helixclaw wants to merge 1 commit into from
Closed

docs: add --json-stream to commit, finish, and rebase patterns #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions openclaw-skill/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,8 @@ For anything non-trivial, use the **plan → review → start → spin** workflo

5. **Finish:** Merge and clean up
```bash
bash pty:true command:"il finish --force --cleanup --no-browser --json"
bash pty:true background:true command:"il finish --force --cleanup --no-browser --json --json-stream"
# Monitor: process action:poll sessionId:XXX
```

### Small Changes (single issue, quick fix)
Expand All @@ -130,7 +131,8 @@ bash pty:true command:"il list --json"
### Commit with AI-generated message

```bash
bash pty:true command:"il commit --no-review --json"
bash pty:true background:true command:"il commit --no-review --json --json-stream"
# Monitor: process action:poll sessionId:XXX
```

## Ideation and Planning
Expand All @@ -145,7 +147,7 @@ bash pty:true background:true command:"il plan --yolo --print --json-stream"

`il plan` launches an autonomous AI planning session that reads the codebase and creates structured issues with dependencies. Always prefer this over manually creating issues.

**Important:** Both `plan` and `spin` should always be run in **background mode** (`background:true`) with `--print --json-stream`. These commands can run for several minutes (especially with Opus) as they analyze the codebase, and foreground timeouts will kill them. The `--json-stream` flag ensures incremental output is visible via `process action:poll`.
**Important:** Commands that can run for extended periods — `plan`, `spin`, `commit`, `finish`, and `rebase` — should be run in **background mode** (`background:true`) with `--json-stream` (and `--print` for plan/spin). The `--json-stream` flag streams JSONL incrementally so you can monitor progress via `process action:poll`. Without it, you get zero visibility until the command completes.

## References

Expand All @@ -159,7 +161,7 @@ bash pty:true background:true command:"il plan --yolo --print --json-stream"
## Safety Rules

1. **Always use `pty:true`** for every iloom command.
2. **Use `background:true`** for commands that launch Claude: `start`, `spin`, `plan`.
2. **Use `background:true`** for commands that launch Claude or run extended operations: `start`, `spin`, `plan`, `commit`, `finish`, `rebase`.
3. **Never run `il finish` without `--force`** in autonomous mode — it will hang on confirmation prompts.
4. **Always pass explicit flags** to avoid interactive prompts. See `{baseDir}/references/non-interactive-patterns.md` for the complete decision bypass map.
5. **Use `--json`** when you need to parse command output programmatically.
Expand Down
7 changes: 4 additions & 3 deletions openclaw-skill/references/core-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,18 +129,19 @@ Validate, commit, merge, and clean up a loom workspace.
| `--no-browser` | boolean | `false` | Skip opening PR in browser |
| `--cleanup` / `--no-cleanup` | boolean | — | Explicit cleanup decision (skips prompt) |
| `--json` | boolean | `false` | Output result as JSON |
| `--json-stream` | boolean | `false` | Stream JSONL progress output |

### Examples

```bash
# Fully autonomous finish from within a loom directory
bash pty:true command:"il finish --force --cleanup --no-browser --json"
# Fully autonomous finish from within a loom directory (background recommended — can take 1-2+ min)
bash pty:true background:true command:"il finish --force --cleanup --no-browser --json --json-stream"

# Dry run to preview what would happen
bash pty:true command:"il finish --dry-run"

# Finish a specific issue
bash pty:true command:"il finish 42 --force --cleanup --no-browser --json"
bash pty:true background:true command:"il finish 42 --force --cleanup --no-browser --json --json-stream"
```

### Interactive Prompts and Bypasses
Expand Down
12 changes: 7 additions & 5 deletions openclaw-skill/references/development-commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,13 +54,14 @@ Commit all uncommitted files with issue reference trailer.
| `--fixes` | boolean | `false` | Use "Fixes #N" trailer instead of "Refs #N" |
| `--no-review` | boolean | `false` | Skip commit message review prompt |
| `--json` | boolean | `false` | Output result as JSON (implies `--no-review`) |
| `--json-stream` | boolean | `false` | Stream JSONL progress output |
| `--wip-commit` | boolean | `false` | Quick WIP commit: skip validations and pre-commit hooks |

### Examples

```bash
# Non-interactive commit with AI-generated message
bash pty:true command:"il commit --no-review --json"
# Non-interactive commit with AI-generated message (background recommended — Claude generates message)
bash pty:true background:true command:"il commit --no-review --json --json-stream"

# Commit with custom message
bash pty:true command:"il commit -m 'fix: resolve auth timeout' --json"
Expand Down Expand Up @@ -103,12 +104,13 @@ Rebase current loom branch on main with AI-assisted conflict resolution.
|------|------|---------|-------------|
| `-f, --force` | boolean | `false` | Force rebase even in edge cases |
| `-n, --dry-run` | boolean | `false` | Simulate rebase without changes |
| `--json-stream` | boolean | `false` | Stream JSONL progress output |

### Examples

```bash
# Rebase with force (skip edge case checks)
bash pty:true command:"il rebase --force"
# Rebase with force and progress streaming (background recommended — Claude may resolve conflicts)
bash pty:true background:true command:"il rebase --force --json-stream"

# Dry run
bash pty:true command:"il rebase --dry-run"
Expand All @@ -119,7 +121,7 @@ bash pty:true command:"il rebase --dry-run"
- Detects uncommitted changes and throws if found (commit first)
- Claude assists with conflict resolution if conflicts arise
- Post-rebase: installs dependencies and runs build (non-blocking)
- No JSON output mode
- Use `--json-stream` for incremental progress visibility

---

Expand Down
42 changes: 35 additions & 7 deletions openclaw-skill/references/non-interactive-patterns.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,15 +36,28 @@ These commands launch Claude Code and run for extended periods. **Always run in
- Without `--json-stream`, `--print` buffers ALL output until completion (no visibility into what Claude is doing)
- These commands can easily run 3-10+ minutes with Opus analyzing a codebase — foreground timeouts will kill them

### Background Commands — Extended Operations

These commands use Claude for message generation, conflict resolution, or merge validation and support `--json-stream` for progress monitoring:

| Command | Recommended Invocation |
|---------|----------------------|
| `il commit` | `bash pty:true background:true command:"il commit --no-review --json --json-stream"` |
| `il finish` | `bash pty:true background:true command:"il finish --force --cleanup --no-browser --json --json-stream"` |
| `il rebase` | `bash pty:true background:true command:"il rebase --force --json-stream"` |

**Why `--json-stream` for these commands?**
- `commit` uses Claude to generate commit messages — can take 10-30s
- `finish` validates, commits, merges, and may trigger builds — can take 1-2+ minutes
- `rebase` may invoke Claude for conflict resolution — duration is unpredictable

### Foreground Commands (no `background:true`)

These commands complete quickly and return structured output:

| Command | Recommended Invocation |
|---------|----------------------|
| `il list` | `bash pty:true command:"il list --json"` |
| `il commit` | `bash pty:true command:"il commit --no-review --json"` |
| `il finish` | `bash pty:true command:"il finish --force --cleanup --no-browser --json"` |
| `il cleanup` | `bash pty:true command:"il cleanup --issue 42 --force --json"` |
| `il build` | `bash pty:true command:"il build"` |
| `il test` | `bash pty:true command:"il test"` |
Expand All @@ -61,7 +74,6 @@ These commands complete quickly and return structured output:
| Command | Note |
|---------|------|
| `il init` | Interactive wizard, must run foreground. **Not recommended for AI agents** — use manual setup instead (see `{baseDir}/references/initialization.md`) |
| `il rebase` | May need Claude for conflict resolution |
| `il shell` | Opens interactive subshell |

---
Expand Down Expand Up @@ -134,13 +146,16 @@ bash pty:true background:true command:"il start <issue> --yolo --no-code --no-te
### Full Autonomous Finish (merge and cleanup)

```bash
bash pty:true command:"il finish --force --cleanup --no-browser --json"
bash pty:true background:true command:"il finish --force --cleanup --no-browser --json --json-stream"
# Monitor: process action:poll sessionId:XXX
```

- `--force`: skip all confirmations
- `--cleanup`: auto-cleanup worktree
- `--no-browser`: don't open browser
- `--json`: structured output
- `--json-stream`: stream progress incrementally
- `background:true`: finish can take 1-2+ minutes (commit, merge, build verification)

### Headless Planning

Expand All @@ -158,11 +173,23 @@ bash pty:true background:true command:"il plan --yolo --print --json-stream"
### Non-Interactive Commit

```bash
bash pty:true command:"il commit --no-review --json"
bash pty:true background:true command:"il commit --no-review --json --json-stream"
# Monitor: process action:poll sessionId:XXX
```

- `--no-review`: skip message review
- `--json`: structured output (also implies `--no-review`)
- `--json-stream`: stream progress (Claude generates commit message)

### Non-Interactive Rebase

```bash
bash pty:true background:true command:"il rebase --force --json-stream"
# Monitor: process action:poll sessionId:XXX
```

- `--force`: force rebase even in edge cases
- `--json-stream`: stream progress (Claude assists with conflict resolution if needed)

### Quick Cleanup

Expand All @@ -182,17 +209,18 @@ Commands that support `--json` for machine-parseable output:
| Command | JSON Flag | Notes |
|---------|-----------|-------|
| `il start` | `--json` | Returns workspace metadata |
| `il finish` | `--json` | Returns operation results |
| `il finish` | `--json`, `--json-stream` | Returns operation results. `--json-stream` for progress |
| `il cleanup` | `--json` | Returns cleanup results |
| `il list` | `--json` | Returns array of loom objects |
| `il commit` | `--json` | Returns commit details (implies `--no-review`) |
| `il commit` | `--json`, `--json-stream` | Returns commit details (implies `--no-review`). `--json-stream` for progress |
| `il issues` | `--json` | Returns array of issues/PRs |
| `il add-issue` | `--json` | Returns created issue |
| `il enhance` | `--json` | Returns enhancement result |
| `il summary` | `--json` | Returns summary text and metadata |
| `il recap` | `--json` | Returns recap data |
| `il dev-server` | `--json` | Returns server status |
| `il projects` | `--json` | Returns project list |
| `il rebase` | `--json-stream` | Stream progress during rebase |
| `il plan` | `--json` | Returns planning result (requires `--print`) |
| `il spin` | `--json` | Returns result (requires `--print`) |

Expand Down