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:

Requirement	Needed 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 issues	The 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

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)

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

Standalone Skills (Advanced)

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

AI Tool	Installation
GitHub Copilot	Copy skills/nightgauge-*/ to .github/skills/
OpenAI Codex	Copy to ~/.codex/skills/
Grok Build TUI	Copy to ~/.grok/skills/
Cursor IDE	Copy 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.

Adapter	Pipeline role	Release confidence
Claude Headless	Agentic pipeline execution	Recommended; primary tested path
Claude SDK	Agentic pipeline execution for SDK consumers	Advanced, optional integration
Codex CLI	Agentic pipeline execution	Beta; strong automated coverage
Gemini CLI	Agentic pipeline execution	Experimental; live matrix pending
GitHub Copilot CLI	Agentic pipeline execution	Experimental; live matrix pending
Gemini SDK	Evaluation/judging/summarization only	Chat-completion-only
OpenCode	Agentic, hosted or local models	Experimental
OpenAI-compatible	Evaluation/judging/summarization only	Chat-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 Coding	Nightgauge
AI jumps straight to code	AI reads documentation first
Requirements lost in chat	Requirements tracked in PLAN.md
Quality varies by prompt	Quality enforced at each step
Context lost between sessions	Context preserved in plan files
PRs lack proper linking	PRs auto-link issues with "Closes #X"

---

Pipeline Stages

Stage Invocations by Tool

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

Stage	Claude Code	Codex CLI (Beta Adapter)	GitHub Copilot	Cursor IDE
issue-pickup	/nightgauge:issue-pickup 42	scripts/run-stage.sh codex issue-pickup 42	Use skill nightgauge-issue-pickup for issue #42.	Use skill nightgauge-issue-pickup for issue #42.
feature-planning	/nightgauge:feature-planning	scripts/run-stage.sh codex feature-planning 42	Use skill nightgauge-feature-planning for issue #42.	Use skill nightgauge-feature-planning for issue #42.
feature-dev	/nightgauge:feature-dev	scripts/run-stage.sh codex feature-dev 42	Use skill nightgauge-feature-dev for issue #42.	Use skill nightgauge-feature-dev for issue #42.
feature-validate	/nightgauge:feature-validate	scripts/run-stage.sh codex feature-validate 42	Use skill nightgauge-feature-validate for issue #42.	Use skill nightgauge-feature-validate for issue #42.
pr-create	/nightgauge:pr-create	scripts/run-stage.sh codex pr-create 42	Use skill nightgauge-pr-create for issue #42.	Use skill nightgauge-pr-create for issue #42.
pr-merge	/nightgauge:pr-merge	scripts/run-stage.sh codex pr-merge 42	Use skill nightgauge-pr-merge for issue #42.	Use skill nightgauge-pr-merge for issue #42.

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:

Gate	Enforced By	What It Checks
Requirements captured	issue-pickup	Extracts acceptance criteria from issue
Docs read first	feature-planning	Reads docs/ before designing
Plan approved	feature-planning	User must approve PLAN.md
Implementation reviewed	feature-dev	4 parallel review subagents
Build passes	feature-validate	Build verification (hard gate)
Tests pass	feature-validate	Unit and integration tests
Manual verification	feature-validate	Checklist from acceptance criteria
Criteria met	pr-create	Checklist verification
No plan drift	pr-create	Compares 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:

Benefit	Description
Speed	Each step starts fresh—no parsing 100K+ of accumulated history
Reliability	Failed steps can be retried without re-running earlier phases
Quality	Focused context means better responses with less noise
Scalability	Complex features don't hit token limits
Debugging	JSON 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

Setting	Default	Description
project.number	—	GitHub Project number for board sync
project.owner	repo	Project owner (org or user)
project.auto_dates	false	Enable automatic Start/Target date population

Configuration Tiers

Tier	File/Source	Purpose
1	Built-in defaults	Sensible defaults
2	~/.nightgauge/config.yaml	User-wide preferences
3	.nightgauge/config.yaml	Project/team settings
4	.nightgauge/config.local.yaml	Developer overrides
5	NIGHTGAUGE_* environment vars	CI/CD overrides
6	CLI flags	One-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:

Skill	Purpose
smart-setup	Make any repository AI-ready with AGENTS.md and docs/
update-docs	Verify documentation matches current codebase
pr-preflight	Run pre-submission validation checks
issue-create	Create well-structured issues with proper labels
test-gen	Generate tests for existing code
doc-gen	Generate 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

• 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