Tools

Gtw

Name: Gtw
Rating: 3.5 (1 reviews)
Author: cnlangzi

By cnlangzi ⭐ 4 stars 👁 17 views ▲ 0 votes

GitHub team workflow automation - an openclaw plugin session-based issue generation, git operations, and PR review coordination.

GitHub

Install

openclaw plugins install ~/code/plugins/gtw

Configuration Example

{
  "model": "github/gpt-4o",
  "watchList": ["owner/repo1", "owner/repo2"],
  "maxReviewRounds": 5
}

README

# gtw — GitHub Team Workflow (OpenClaw Plugin)

> GitHub team workflow automation — session-based issue generation, git operations, and PR review coordination via slash command.

## Features

- **Session-based workflow** — Draft in `wip.json`, confirm when ready. No accidental API calls.
- **AI-assisted issue creation** — `/gtw new` reads the parent session history and auto-generates a structured issue draft (title + body) with no manual input required.
- **Git operations** — `fix`, `push`, and `pr` commands wrap standard git workflows.
- **Emoji review protocol** — eyes claim → checklist → approved/changes verdict.
- **GitHub CLI integration** — Uses `gh` for auth; no manual token config needed.

## Installation

```bash
openclaw plugins install ~/code/plugins/gtw -l --dangerously-force-unsafe-install
openclaw gateway restart
```

- `-l` (link mode): changes to the source directory take effect immediately without reinstalling.
- `--dangerously-force-unsafe-install`: the dangerous-code scanner flags `child_process` calls used to invoke `git`/`gh` CLI. These are intentional — gtw is a GitHub workflow tool that wraps these CLIs. Use this flag to skip the false-positive scan result.
- Gateway auto-reloads the plugin; `openclaw gateway restart` ensures a clean start.

## Usage

```
/gtw <command> [args]
```

### Setup

```
/gtw on <workdir>       Set working directory (resolves git remote)
```

### Issue Management

```
/gtw new                Read conversation history, auto-generate issue draft (title + body) via AI, save to wip.json
/gtw update #<id>       Update issue draft
/gtw confirm            Execute all pending operations (create issue/branch/PR)
/gtw issue              List open issues
/gtw show #<id>         Show issue details
/gtw poll              List open issues and PRs
```

### Git Operations

```
/gtw fix <issue_id>     Claim issue (add gtw/wip label), fetch issue, derive branch name, create branch,
                          inject directive to trigger subagent, subagent fixes automatically, creates
                          pendingCommit, requires /gtw confirm to push, then unclaims (removes label)
/gtw push               Stage → auto-commit (conventional format) → generate commit draft → save as pendingCommit
                          (two-step: run /gtw confirm to actually push)
/gtw rebase [branch]    Sync current branch with remote — 有分支名：fetch → checkout → rebase 远程分支
                          — 无分支名：git pull --rebase origin <当前分支>
/gtw pr [issue_id]      Generate PR title/body via LLM from commit diff, save as pendingPr draft
                          — /gtw pr (no args): uses current branch; never reads wip.json
                          — /gtw pr <issue_id>: derives branch from issue title (same as /gtw fix)
                            If remote branch exists → checks out and hard-resets to it.
                            If local branch exists but remote missing → checks out and prompts to run /gtw push.
                            If neither exists → uses current branch.
                          (two-step: run /gtw confirm to actually create the PR)
```

### Review

```
/gtw review             Claim earliest PR with gtw/ready label from watch list
/gtw review <pr>       Claim/review specific PR in current repo
/gtw watch add <owner>/<repo>   Add repo to watch list
/gtw watch rm <owner>/<repo>    Remove repo from watch list
/gtw watch list         Show watched repos
```

### Config

```
/gtw config             Show current config and wip.json
/gtw model              Show current AI model (gtw-specific or session default)
/gtw model <model>      Set custom AI model (e.g. github/gpt-4o)
/gtw model off          Clear custom model, use session default
/gtw login              Interactive OAuth login (device code flow)
/gtw login --pat <token>  Register a Personal Access Token directly
```

## Configuration

### Authentication

`gtw` supports multiple authentication methods:

**Method 1: Personal Access Token (PAT) - Recommended for CI**

**Option A: Direct PAT input**
```
/gtw login --pat ghp_your_token_here
```
Validates the token via GitHub API and caches it to `~/.gtw/token.json`.

**Option B: Environment variable**
```bash
export GITHUB_TOKEN=ghp_your_token_here
/gtw login --pat
```
Uses and validates `GITHUB_TOKEN`, then caches it.

**Option C: Cached PAT from previous login**
Automatically used if you previously ran `/gtw login --pat`.

Generate a PAT at: https://github.com/settings/tokens (requires `repo` and `workflow` scopes)

**Method 2: Interactive OAuth Login**

Use the device code flow for interactive login:

```
/gtw login
```

This will:
1. **If GITHUB_CLIENT_ID is set**: Use custom OAuth app with device code flow
2. **If GITHUB_CLIENT_ID is NOT set** (default): Fall back to `gh auth login` using GitHub CLI's built-in OAuth app
   - Opens browser for device code authentication
   - Caches the token from gh CLI for gtw use
   - No need to configure client ID/secret manually

**Method 3: GitHub CLI Integration**

`gtw` automatically uses `gh` CLI token if available. Make sure `gh auth login` has been run with `repo` scope:

```bash
gh auth login --hostname github.com --scopes repo,workflow
gh auth status
```

**Token Priority:**
1. `GITHUB_TOKEN` environment variable (PAT)
2. Cached token in `~/.gtw/token.json` (PAT or OAuth)
3. `gh auth token` (validated before use)

Check auth status anytime:

```
/gtw config
```

### Configuration Items

`~/.gtw/config.json` stores gtw-specific settings:

```json
{
  "model": "github/gpt-4o",
  "watchList": ["owner/repo1", "owner/repo2"],
  "maxReviewRounds": 5
}
```

| Field | Default | Description |
|-------|---------|-------------|
| `model` | session default | AI model used for issue/PR generation and review. Use `github/<model>` for Copilot models, `minimax/<model>` for MiniMax, etc. |
| `watchList` | `[]` | Watch list of repos scanned by `/gtw review` (no-arg) for `gtw/ready` PRs. |
| `maxReviewRounds` | `5` | Maximum review rounds before a PR is marked `gtw/stuck`. Set to `0` to disable. |
| `llmTimeoutSeconds` | `60` | Timeout in seconds for LLM API calls. If a request times out, it is retried once. If both attempts time out, a `TimeoutError` is thrown. Can be overridden with the `GTW_LLM_TIMEOUT_SECONDS` environment variable (takes precedence). |

View/edit via:

```
/gtw model <provider/model-id>   # set custom AI model
/gtw model                      # show current model
/gtw model off                  # clear custom model
/gtw watch add <owner>/<repo>   # add to watch list
/gtw watch list                 # show watch list
```

## Standard Workflow

```
You: /gtw on ~/code/myproject
→ ✅ Switched to owner/repo
   📁 Workdir: /home/user/code/myproject
   Let's discuss the requirements first — no code yet.

You: /gtw new
→ Draft saved:
   Title: fix: handle null pointer in auth
   Body:
   ## Background
   ...
   ## Acceptance Criteria
   ...

You: /gtw fix 42
→ 🌿 Fix workflow started
   Issue: #42
   Title: fix: handle null pointer in auth
   Branch: fix/handle-null-pointer
   ⏳ Subagent spawned — the main session will now:
   1. Spawn coding subagent to fix the issue
   2. Wait for subagent to finish
   3. Run push + confirm automatically
   (gtw/wip label is applied to issue #42)

You: /gtw push
→ 🔍 Commit draft — run /gtw confirm to push
   📝 Commit Message: fix(auth): handle null pointer in auth
   📊 Changes: +10 -2
   Run /gtw confirm to commit and push.

You: /gtw confirm
→ 📦 Committed and pushed
   Branch: fix/handle-null-pointer
   (gtw/wip label removed from issue #42)

You: /gtw pr
→ 🔍 PR draft — run /gtw confirm to create PR
   📝 Title: fix: handle null pointer in auth
   🌿 Branch: fix/handle-null-pointer → main

You: /gtw confirm
→ ✅ PR #42 created
   URL: https://github.com/owner/repo/pull/42
```

### PR Workflow (with issue)

```
You: /gtw pr 13
→ 🔍 PR draft for issue #13 — run /gtw confirm to create PR
   📝 Title: fix: handle null pointer in auth
   🌿 Branch: fix/handle-null-pointer
   ⚠️  Remote branch missing — please run /gtw push to publish this branch
   Issue: #13 — handle null pointer in auth

You: /gtw push
→ 🔍 Commit draft — run /gtw confirm to push
   📝 Commit Message: fix(auth): handle null pointer in auth
   Run /gtw confirm to commit and push.

You: /gtw confirm
→ 📦 Committed and pushed
   Branch: fix/handle-null-pointer

You: /gtw pr 13
→ 🔍 PR draft for issue #13 — run /gtw confirm to create PR
   📝 Title: fix: handle null pointer in auth
   🌿 Branch: fix/handle-null-pointer → main
   Issue: #13 — handle null pointer in auth

You: /gtw confirm
→ ✅ PR #42 created
   URL: https://github.com/owner/repo/pull/42
```

### Review Workflow

```
You: /gtw watch add owner/repo
→ ✅ Now watching: owner/repo

You: /gtw review
→ eyes Claimed PR #23: fix: handle null pointer
   Linked Issue: #12 — handle null pointer in auth
   Files changed (3):
     - src/auth.js: +10 -2
     - tests/auth.test.js: +5 -0
   Review [Round 1/5]
     - [ ] Destructive
     - [ ] Out-of-scope
   Review the diff against the issue requirements.
   Run /gtw review 23 again after resolving items.

You: /gtw review 23
→ eyes PR #23 re-review (Round 2/5)
   [Items still unresolved kept as unchecked]
   Review the diff and update checklist.
```

**Review protocol:**
- `/gtw review` (no-arg): Scans watch list for PRs labeled `gtw/ready`, picks the oldest by `updated_at`, claims it (`gtw/wip`), creates a Round 1 checklist.
- `/gtw review <pr>`: Reviews specific PR in the current repo (from `wip.json`). If a checklist exists, increments the round and updates the same comment.
- Checklist items (always two): **Destructive** and **Out-of-scope** — the canonical checks to prevent AI-caused unplanned or out-of-scope modifications.
- Each invocation increments the round number. Unresolved items remain unchecked.
- When all checkboxes are resolved (all items checked): checklist comment is deleted, approved comment posted, `gtw/lgtm` labe

... (truncated)

tools