Skip to content
Conduit

skill

nightgauge

Open-core, AI-powered issue-to-PR pipeline with enforced quality gates.

nightgauge/nightgaugecommunitylistedunreviewed
Use skill

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/nightgauge/nightgauge itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 21, 2026

Nightgauge

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.

CI CodeQL Release Open VSX Open VSX downloads License: Apache 2.0 Go 1.26

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

What you get

One issue in, one PR out. Six stages take a GitHub issue from pickup through planning, implementation and validation to a merged pull request.

Gates, not vibes. Every stage is checked by deterministic quality gates, not just a model saying it worked.

Budgets and guardrails. Turn, wall-clock and token limits are enforced outside the model, and a stage that breaches one is stopped.

Bring your own agent. Claude Code is the primary path; Codex is beta; Gemini CLI, Copilot CLI and OpenCode are experimental. See Adapters.

Watch it anywhere. VS Code dashboard and board views, the CLI, and live status in Discord, Slack or Mattermost.

Local-first and Apache-2.0. Runs on your machine with your credentials. No account and no hosted service required.

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:

RequirementNeeded for
Claude Code (or another supported adapter)Stage execution — bring your own subscription/keys; nothing is proxied
git + gh CLI (authenticated)Branching, PRs, issue operations
A GitHub repository with issuesThe pipeline's unit of work
GitHub Projects v2 board (+ .nightgauge/config.yaml pointing at it)The autonomous scheduler and board-driven views — without a board you can still run single issues manually
Node.js ≥ 24 (pinned in .nvmrc)VSCode extension and SDK builds

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

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)

Capability GroupStatusNotes
Six core issue-to-PR stages (issue-pickup -> pr-merge)SupportedAvailable in Claude commands and the Codex adapter
Utility accelerators (test-gen, issue-create, doc-gen)BetaUseful but not required for core stage completion
Queue/project-sync orchestration (queue, project-sync, backlog flows)DeferredClaude-first automations; use manual GitHub updates in Codex path

Standalone Skills (Advanced)

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

AI ToolInstallation
GitHub CopilotCopy skills/nightgauge-*/ to .github/skills/
OpenAI CodexCopy to ~/.codex/skills/
Grok Build TUICopy to ~/.grok/skills/
Cursor IDECopy to .cursor/skills/

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.

AdapterPipeline roleRelease confidence
Claude HeadlessAgentic pipeline executionRecommended; primary tested path
Claude SDKAgentic pipeline execution for SDK consumersAdvanced, optional integration
Codex CLIAgentic pipeline executionBeta; strong automated coverage
Gemini CLIAgentic pipeline executionExperimental; live matrix pending
GitHub Copilot CLIAgentic pipeline executionExperimental; live matrix pending
Gemini SDKEvaluation/judging/summarization onlyChat-completion-only
OpenCodeAgentic, hosted or local modelsExperimental
OpenAI-compatibleEvaluation/judging/summarization onlyChat-completion-only

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"]

Why This Matters

Traditional AI CodingNightgauge
AI jumps straight to codeAI reads documentation first
Requirements lost in chatRequirements tracked in PLAN.md
Quality varies by promptQuality enforced at each step
Context lost between sessionsContext preserved in plan files
PRs lack proper linkingPRs auto-link issues with "Closes #X"

Pipeline Stages

Stage Invocations by Tool

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

StageClaude CodeCodex CLI (Beta Adapter)GitHub CopilotCursor IDE
issue-pickup/nightgauge:issue-pickup 42scripts/run-stage.sh codex issue-pickup 42Use skill nightgauge-issue-pickup for issue #42.Use skill nightgauge-issue-pickup for issue #42.
feature-planning/nightgauge:feature-planningscripts/run-stage.sh codex feature-planning 42Use skill nightgauge-feature-planning for issue #42.Use skill nightgauge-feature-planning for issue #42.
feature-dev/nightgauge:feature-devscripts/run-stage.sh codex feature-dev 42Use skill nightgauge-feature-dev for issue #42.Use skill nightgauge-feature-dev for issue #42.
feature-validate/nightgauge:feature-validatescripts/run-stage.sh codex feature-validate 42Use skill nightgauge-feature-validate for issue #42.Use skill nightgauge-feature-validate for issue #42.
pr-create/nightgauge:pr-createscripts/run-stage.sh codex pr-create 42Use skill nightgauge-pr-create for issue #42.Use skill nightgauge-pr-create for issue #42.
pr-merge/nightgauge:pr-mergescripts/run-stage.sh codex pr-merge 42Use skill nightgauge-pr-merge for issue #42.Use skill nightgauge-pr-merge for issue #42.

Cross-reference:

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:

GateEnforced ByWhat It Checks
Requirements capturedissue-pickupExtracts acceptance criteria from issue
Docs read firstfeature-planningReads docs/ before designing
Plan approvedfeature-planningUser must approve PLAN.md
Implementation reviewedfeature-dev4 parallel review subagents
Build passesfeature-validateBuild verification (hard gate)
Tests passfeature-validateUnit and integration tests
Manual verificationfeature-validateChecklist from acceptance criteria
Criteria metpr-createChecklist verification
No plan driftpr-createCompares implementation to plan

Architecture

Product Layers

┌─────────────────────────────────────────────────────────────────┐
│                    USER INTERFACES                               │
├─────────────────────────────────────────────────────────────────┤
│  VSCode Extension          │  CLI Adapters                      │
│  (packages/nightgauge) │  (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[🗑️]

Benefits:

BenefitDescription
SpeedEach step starts fresh—no parsing 100K+ of accumulated history
ReliabilityFailed steps can be retried without re-running earlier phases
QualityFocused context means better responses with less noise
ScalabilityComplex features don't hit token limits
DebuggingJSON files are human-readable for troubleshooting

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
SettingDefaultDescription
project.number—GitHub Project number for board sync
project.ownerrepoProject owner (org or user)
project.auto_datesfalseEnable automatic Start/Target date population

Configuration Tiers

TierFile/SourcePurpose
1Built-in defaultsSensible defaults
2~/.nightgauge/config.yamlUser-wide preferences
3.nightgauge/config.yamlProject/team settings
4.nightgauge/config.local.yamlDeveloper overrides
5NIGHTGAUGE_* environment varsCI/CD overrides
6CLI flagsOne-time overrides

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 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:

SkillPurpose
smart-setupMake any repository AI-ready with AGENTS.md and docs/
update-docsVerify documentation matches current codebase
pr-preflightRun pre-submission validation checks
issue-createCreate well-structured issues with proper labels
test-genGenerate tests for existing code
doc-genGenerate documentation from code

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

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

Author: nightgauge License: Apache-2.0

↑↓ navigate openesc close