Nightgauge 发布开源本地优先的 issue 到 PR 流水线

Work the day shift. Ship the night shift.

An open-source, local-first issue-to-PR pipeline for AI coding agents,
with a quality gate at every stage between the issue and the merge.

Website · Quick start · How it works · Adapters · Docs · Releases · Contributing

What you get

Open-source and local-first

Everything in this repository is Apache-2.0 licensed. The VS Code extension, SDK, portable skills, Claude plugin, and Go binary run locally using model and forge credentials you control. No Nightgauge account or hosted service is required, and cloud connectivity is disabled by default: nothing about your work is sent until you turn it on. With it on, run telemetry is opt-out (on by default, disclosed on first run, one line of config to stop — see docs/TELEMETRY_PRIVACY.md for what is sent, when and why).

Optional services may integrate through public contracts, but their private implementations and commercial plans are outside this repository. See VISION.md and docs/PRODUCT_OVERVIEW.md.

Prerequisites

Have these in place before installing — the pipeline orchestrates tools you already use rather than replacing them:

Platform support: macOS is the primary end-to-end tested platform. Packaged Linux amd64 CLI and VSIX binaries are tested on Debian and Alpine; live provider-driven Linux pipelines still have less coverage. Windows is not currently supported; use WSL2.

Install from Source

git clone https://github.com/nightgauge/nightgauge.git
cd nightgauge
go install ./cmd/nightgauge

Signed release binaries, checksums, and the Homebrew cask are available from GitHub Releases. See docs/GO_BINARY.md for the full install matrix.

Quick Start

VSCode Extension (Recommended UI)

The full Nightgauge experience with visual dashboard, project board integration, batch processing, and one-click pipeline execution.

Install Nightgauge from Open VSX, which selects the build for your platform automatically and is the default registry in VSCodium, Cursor, Windsurf and Gitpod. In VS Code itself, install the .vsix for your platform from the latest release with code --install-extension <file>.vsix. Target-specific VSIXs are also available from the GitHub Release; Extensions → … → Install from VSIX installs one manually. Building locally or running dev-install.sh is for extension development and intentionally produces a non-release build.

Features:

• Visual pipeline status with real-time progress
• GitHub Project board integration (Ready/In Progress/In Review views)
• Batch pipeline execution for multiple issues
• Token usage tracking and cost analytics
• Configurable notifications and sounds — live-updating pipeline status in Discord, Slack or Mattermost

Other ways to run it: Claude Code CLI, Grok Build, Codex CLI, Copilot CLI, local models

Claude Code CLI (Alternative)

For terminal-based workflows, install the Nightgauge plugin:

# Add the marketplace
claude plugin marketplace add https://github.com/nightgauge/nightgauge.git

# Install the Nightgauge plugin
claude plugin install nightgauge@nightgauge-plugins

# Start the pipeline
/nightgauge:issue-pickup

Grok Build TUI

# Home copy (~/.grok/skills) plus grok plugin install
./scripts/install-agent-skills.sh --grok-only

Skills then resolve as /nightgauge-issue-create (canonical names) or /issue-create when loaded via the plugin. dev-install.sh and the VS Code extension activate path install the same tree.

OpenAI Codex CLI (Beta Adapter)

Codex support is available through both slash commands and the unified stage runner.

Install Codex assets (commands + skills):

./scripts/install-agent-skills.sh --codex-only

Slash commands are defined in .codex/commands/ and invoked as /<name>:

/nightgauge-issue-pickup 42
/nightgauge-feature-planning 42
/nightgauge-feature-dev 42
/nightgauge-feature-validate 42
/nightgauge-pr-create 42
/nightgauge-pr-merge 42

Run stages directly with the unified stage runner:

# Build the SDK CLI once (from repo root)
npm run -w @nightgauge/sdk build

# Run core pipeline stages — scripts/run-stage.sh <adapter> <stage> <issue>
scripts/run-stage.sh codex issue-pickup 42
scripts/run-stage.sh codex feature-planning 42
scripts/run-stage.sh codex feature-dev 42
scripts/run-stage.sh codex feature-validate 42
scripts/run-stage.sh codex pr-create 42
scripts/run-stage.sh codex pr-merge 42

Migration note:

• The per-tool wrapper scripts under configs/codex/commands/*.sh were removed. scripts/run-stage.sh <adapter> <stage> <issue> is the single supported entry point for non-Claude adapters.
• See docs/MIGRATION.md for the removal history and adapter mapping.

Codex CLI Beta Scope

• All six pipeline stage entry points are available via scripts/run-stage.sh codex <stage> <issue>; Codex remains beta while the complete live-provider matrix is expanded
• Matching Codex slash commands are available via .codex/commands/*.md
• Queue/project-sync and some plugin-level automations remain Claude-first
• The Codex adapter depends on built SDK output: npm run -w @nightgauge/sdk build

Adapter Switching Workflow (Claude <-> Codex)

Both paths use the same stage contract and context artifacts. Mid-issue switching is a supported beta workflow; inspect the handoff files before continuing because it has less live coverage than a single-provider run.

1. Run a stage in Claude or Codex.
2. Confirm handoff files in nightgauge layout path pipeline and plans in nightgauge layout path plans (per-clone, in the git directory).
3. Continue with the next stage in the other adapter.

Example:

# Start in Codex
scripts/run-stage.sh codex issue-pickup 42
scripts/run-stage.sh codex feature-planning 42

# Continue in Claude (same issue + branch)
/nightgauge:feature-dev
/nightgauge:pr-create

If a Codex stage fails, rebuild the SDK output and retry:

# Restore the SDK CLI runtime
npm run -w @nightgauge/sdk build

Then continue in Claude commands if needed and finish the pipeline.

GitHub Copilot CLI (Experimental Adapter)

Copilot is available as an experimental agentic execution adapter via the VSCode extension and SDK. It routes pipeline stages through the copilot CLI subprocess, but it has not completed Nightgauge's live six-stage provider verification matrix. Keep a proven Claude or Codex adapter available as a fallback.

Prerequisites:

npm install -g @github/copilot-cli
gh auth login  # or set GH_TOKEN env var

Configure in .nightgauge/config.yaml:

ui:
  core:
    adapter: copilot
copilot:
  # model: "provider-model-id" # optional; omit to use the CLI default

Cost model: Copilot plans and premium-request multipliers change over time. Check your current GitHub plan and the Copilot CLI's usage reporting. See docs/CONFIGURATION.md for all configuration options.

Local models

Local models run through the OpenCode adapter against any OpenAI-compatible server (LM Studio, Ollama, oMLX, MTPLX, …). The chat-only openai-compatible backend serves evaluation, judging and summarization on the same kind of server. See docs/MULTI_BACKEND_SETUP.md for setup and docs/CONFIGURATION.md for the judge's configuration.

Adapter Scope (verified July 22, 2026)

Standalone Skills (Advanced)

Skills work with any AI tool supporting the Agent Skills specification:

Adapters

Nightgauge includes 8 provider adapters across three categories. Five have agentic tool loops and can be selected for pipeline execution; three are chat-completion-only and are limited to evaluation, judging, and summarization.

The VS Code extension uses the separately installed Claude CLI for its Claude adapter. It does not bundle Anthropic's Agent SDK. Direct Agent SDK mode is an optional integration for @nightgauge/sdk consumers who install that peer dependency themselves after reviewing Anthropic's terms.

Agentic adapters implement the shared six-stage contract and compatible context files, so they can switch between stages on the same branch. Only Claude Headless is the primary dogfooded path today. Codex is beta; Gemini CLI and Copilot remain experimental until their live provider-matrix runs are recorded. Chat-completion-only adapters are rejected at pipeline dispatch because they cannot edit files, run shell commands, or call gh.

Adapter Selection Guide — Which adapter to choose, setup instructions, env vars, and troubleshooting for each adapter.

Adapter Capability Matrix — Technical audit of adapter capabilities with code-level verification.

The Pipeline

flowchart LR
    A["<b>issue-pickup</b><br/>claim issue<br/>create branch<br/>extract specs"] --> B["<b>feature-planning</b><br/>read docs<br/>design PLAN.md<br/>get approval"]
    B --> C["<b>feature-dev</b><br/>implement the<br/>approved plan"]
    C --> D["<b>feature-validate</b><br/>build and test<br/>validation"]
    D --> E["<b>pr-create</b><br/>pre-flight checks<br/>link the issue"]
    E --> F["<b>pr-merge</b><br/>address reviews<br/>merge"]

Loading

Why This Matters

Pipeline Stages

Stage Invocations by Tool

Use the same six-stage workflow in every supported tool:

Cross-reference:

• Adapter capability matrix: docs/ADAPTER_MATRIX.md
• Codex parity status: docs/decisions/003-codex-adapter-feature-parity.md
• Skills catalog: skills/README.md
• Codex runtime details: configs/codex/README.md

1. Issue Pickup

Claim a GitHub issue and set up your development environment.

/nightgauge:issue-pickup        # Auto-select highest priority issue
/nightgauge:issue-pickup 42     # Pick up specific issue

What it does:

• Selects issue using 7-tier priority algorithm (or manual selection)
• Extracts requirements, acceptance criteria, and technical notes
• Creates properly-named branch (feat/42-add-user-auth)
• Assigns issue and updates status labels
• Sets Start/Target dates in project board (if auto_dates: true)

2. Feature Planning

Design implementation by reading documentation first.

/nightgauge:feature-planning

What it does:

• Reads docs/ folder to understand existing patterns
• Analyzes codebase architecture
• Creates <issue>-<title>.md in the clone's plans directory (nightgauge layout path plans) with:
  • Implementation phases
  • File change summary
  • Test strategy
  • Acceptance criteria checklist
• Requires user approval before implementation

3. Feature Development

Implement features following the approved plan.

/nightgauge:feature-dev

What it does:

• Follows PLAN.md phases exactly
• Runs parallel subagents for independent files
• Executes quality review before completion:
  • Code correctness check
  • Security vulnerability scan
  • Test coverage analysis
  • Documentation sync verification

4. Feature Validation

Verify implementation with build, tests, and manual checklists.

/nightgauge:feature-validate
/nightgauge:feature-validate --auto-pass  # Skip manual checklists (admin only)

What it does:

• Phase 1: Runs automated tests (unit, integration)
• Phase 1.5: Build verification (HARD GATE - cannot be bypassed)
• Phase 2: Generates manual test checklist from acceptance criteria
• Phase 3: User confirms manual testing complete

5. PR Create

Create pull request with proper format and quality checks.

/nightgauge:pr-create
/nightgauge:pr-create --draft    # Create as draft PR

What it does:

• Runs pre-flight validation (tests, no uncommitted changes)
• Generates PR description from commits and plan
• Links issue with "Closes #X"
• Requests appropriate reviewers

6. PR Merge

Address review feedback and complete the pipeline.

/nightgauge:pr-merge
/nightgauge:pr-merge --admin     # Bypass branch protection

What it does:

• Waits for CI checks to complete
• Parses and categorizes review comments
• Auto-fixes minor issues (typos, formatting)
• Asks about major issues before proceeding
• Squash merges and cleans up branches

Quality Gates

The pipeline enforces quality at every step:

Architecture

Product Layers

┌─────────────────────────────────────────────────────────────────┐
│                    USER INTERFACES                               │
├─────────────────────────────────────────────────────────────────┤
│  VSCode Extension          │  CLI Adapters                      │
│  (packages/nightgauge-vscode) │  (claude-plugins + configs/codex) │
│  Primary UX                │  Alternative UX                    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    ORCHESTRATION LAYER                           │
├─────────────────────────────────────────────────────────────────┤
│  Nightgauge SDK (packages/nightgauge-sdk)                             │
│  - Pipeline state management                                    │
│  - Context file I/O                                             │
│  - Claude Agent SDK integration                                 │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    INSTRUCTION LAYER                             │
├─────────────────────────────────────────────────────────────────┤
│  Skills (skills/nightgauge-*)                                      │
│  - Portable SKILL.md files                                      │
│  - Work with any AI tool                                        │
│  - Define "what" not "how"                                      │
└─────────────────────────────────────────────────────────────────┘

Context-Isolated Pipeline

Each pipeline step runs as a fresh subagent with minimal context, passing structured JSON handoff files instead of accumulated conversation history.

flowchart LR
    subgraph "Stage 1"
        A[issue-pickup]
    end
    subgraph "Stage 2"
        B[feature-planning]
    end
    subgraph "Stage 3"
        C[feature-dev]
    end
    subgraph "Stage 4"
        D[feature-validate]
    end
    subgraph "Stage 5"
        E[pr-create]
    end
    subgraph "Stage 6"
        F[pr-merge]
    end

    A -->|"issue-{N}.json"| B
    B -->|"planning-{N}.json"| C
    C -->|"dev-{N}.json"| D
    D -->|"validate-{N}.json"| E
    E -->|"pr-{N}.json"| F
    F -->|"cleanup"| G[🗑️]

Loading

Benefits:

Multi-Repository Workspaces

Nightgauge supports coordinated development across multiple repositories:

# .vscode/nightgauge-workspace.yaml
workspace:
  name: "MyApp"

repositories:
  - name: frontend
    path: ./packages/frontend
    role: primary
  - name: backend
    path: ./packages/backend
    role: primary

routing:
  patterns:
    "area:frontend": frontend
    "area:backend": backend

Features:

• Repository-scoped pipelines (each repo has isolated context)
• Label-based routing (auto-assign issues to correct repo)
• Repository switcher (status bar quick pick)
• Cross-repo epics (track features spanning multiple repos)

See docs/MULTI_REPO_WORKSPACE.md for complete documentation.

Configuration

Nightgauge uses a 6-tier configuration system with layered precedence. The most common configuration file is .nightgauge/config.yaml:

# .nightgauge/config.yaml
project:
  # GitHub Project number (from URL: /orgs/your-org/projects/10)
  number: 10
  # Owner is inferred from repo, but can be overridden
  # owner: your-org

  # Enable automatic date field population
  auto_dates: true

Configuration Tiers

See docs/CONFIGURATION.md for complete configuration reference and docs/MIGRATION.md for migrating from the legacy config file. See also docs/DEPRECATIONS.md.

Repository Structure

nightgauge/
├── packages/                      # Products
│   ├── nightgauge-vscode/           # VSCode extension (primary UX)
│   └── nightgauge-sdk/              # Programmatic SDK
├── skills/                        # Pipeline instruction layer
│   ├── nightgauge-issue-pickup/     # Stage 1: Claim issue
│   ├── nightgauge-feature-planning/ # Stage 2: Design
│   ├── nightgauge-feature-dev/      # Stage 3: Implement
│   ├── nightgauge-feature-validate/ # Stage 4: Validate
│   ├── nightgauge-pr-create/        # Stage 5: Create PR
│   ├── nightgauge-pr-merge/         # Stage 6: Merge
│   ├── smart-setup/              # Utility: Make repos AI-ready
│   └── update-docs/              # Utility: Documentation sync
├── claude-plugins/                # Claude Code integration
│   └── nightgauge/                  # /nightgauge:* commands
├── standards/                     # Coding and security standards
└── docs/                          # Framework documentation

Additional Skills

Beyond the core pipeline, Nightgauge includes utility skills:

Philosophy

Nightgauge is built on these principles:

• Documentation-first — Read docs before writing code
• Plan before implement — Design with user approval
• Quality gates, not suggestions — Enforce standards at each step
• Context isolation — Fresh subagents with JSON handoffs
• Portable skills — Works across all major AI coding tools

Documentation

• Nightgauge Guide — Complete adoption guide
• Adapter Selection Guide — Choose, set up, and troubleshoot adapters
• Architecture — System design and patterns
• Configuration — Full configuration reference
• Multi-Repo Workspaces — Multi-repository setup
• Context Architecture — Pipeline handoff schemas
• Troubleshooting — Common issues and solutions

Contributing

New contributors work from a fork — you do not need push access to the canonical repo. See CONTRIBUTING.md; start with the Your first contribution fork workflow and Prerequisites at the top, then browse good first issue and help wanted.

Community and Support

• Questions & getting started → GitHub Discussions
• Bugs & feature requests → open an issue
• Support policy & triage cadence → SUPPORT.md
• Security vulnerabilities → SECURITY.md (do not open a public issue)
• Community expectations → Code of Conduct

Author: nightgauge License: Apache-2.0