NyxAgent

NyxAgent is a small TypeScript CLI that runs a fixed coding-agent pipeline, one GitHub issue at a time, each phase with fresh context.

Pipeline

For every run NyxAgent:

1. Selects executable open GitHub issues to work on (read-only), presenting GitHub sub-issues in parent PRD/plan sections, then asks the user to confirm the proposed checklist with the same section order.
2. Partitions the confirmed selection into one cycle per PRD/plan (plus a misc cycle for ungrouped issues); cycles linked by a cross-PRD dependency merge into one.
3. For each cycle, on its own git branch cut from the current checkout, for each selected issue:
   • implements it (the agent — the only customizable prompt),
   • optionally reviews it in bounded discovery rounds, then revises only verified blockers with locked validation,
   • commits the change (the engine, deterministically).
4. Optionally runs a global review across the whole cycle.
5. Pushes the cycle branch and opens one pull request per cycle (the engine), restoring the original branch between cycles.

The agent only implements, reviews, and revises. Every git/gh side effect — commit, push, pull request — is performed by the engine, so closing the loop never depends on the model. Issues are closed by GitHub when the PR merges (Closes #n in the PR body); parent PRD/plan issues referenced explicitly from child descriptions are grouped for selection, while parent close lines are added only when NyxAgent can prove the PR completes their remaining open executable children. The human merges the PR.

The workflow shape is fixed (not configurable). Only .nyxagent/prompts/execution.md is editable; nyxagent run --instruction can replace that prompt's {{INSTRUCTION}} slot for one run.

Installation

NyxAgent is published as @nyxa/nyx-agent. The executable is nyxagent.

Global install

Use a global install when you want the same nyxagent command available in multiple repositories:

npm install -g @nyxa/nyx-agent
nyxagent --version

Global installs can use NyxAgent's built-in updater:

nyxagent update --check       # check the latest published version
nyxagent update               # update to latest, asking for confirmation
nyxagent update -y            # update to latest without prompting
nyxagent update 0.9.7         # install a specific published version

nyxagent update detects the package manager from the current executable path. Use --package-manager npm|pnpm|yarn|bun to force one.

Project-local install

Use a local install when a repository should pin its own NyxAgent version:

npm install --save-dev @nyxa/nyx-agent
npx nyxagent --version

Run local installs through npx nyxagent ... so the repository's pinned version is used:

npx nyxagent init
npx nyxagent run

Update a local install with the package manager, not nyxagent update:

npm install --save-dev @nyxa/nyx-agent@latest

One-off usage

To try NyxAgent without installing it globally or adding it to a project:

npx @nyxa/nyx-agent@latest --version
npx @nyxa/nyx-agent@latest init

From this source checkout

For development on NyxAgent itself:

npm install
npm run dev -- --version
npm run dev -- run --stream

Usage

Run these commands from the git repository that NyxAgent should operate on.

Initialize a repository

Interactive setup:

nyxagent init

Non-interactive setup:

nyxagent init \
  --repo owner/repo \
  --base-branch main \
  --harness codex \
  --model gpt-5.5 \
  --reasoning-effort medium \
  --review each \
  --review-rounds-each 1 \
  --review-rounds-global 1 \
  --max-iterations 5

nyxagent init writes .nyxagent/config.json, creates .nyxagent/prompts/execution.md, and adds NyxAgent runtime files to .gitignore. Interactive init offers one optional advanced validation/profile step; use --advanced to force it. You can also edit agents.review, agents.global_review, agents.ci_revision, and ci.preflight.commands in the generated config after init. Use --force to overwrite an existing config.

Run the pipeline

nyxagent run                  # select work, ask for confirmation, then run
nyxagent run --harness claude # override the configured harness for one run
nyxagent run --instruction "Use the frontend skill to implement."

A single nyxagent run is a batch. After you confirm the selection, NyxAgent partitions it into one cycle per PRD/plan (plus a misc cycle for ungrouped issues) and reports how many pull requests will be created, e.g. 2 pull requests will be created: PRD: Auth (3 items), misc (1 item). Each cycle cuts its own branch, runs the full implement → review → CI lifecycle, and opens its own pull request. Cycles linked by a cross-PRD dependency are merged into one pull request. Cycles run one after another; if one fails its work is salvaged into a draft PR and the batch continues, and the command exits non-zero when any cycle failed.

Output modes:

nyxagent run --stream         # stream live agent messages and tool calls
nyxagent run --verbose        # stream agent output plus runtime diagnostics

Default runs show only NyxAgent's own narrative. --stream adds the live agent activity stream on stderr. --verbose implies --stream and also prints diagnostic runtime events.

For local installs, prefix the same commands with npx:

npx nyxagent init
npx nyxagent run --stream

Configuration

nyxagent init writes .nyxagent/config.json:

{
  "harness": "codex",
  "model": "gpt-5.5",
  "reasoning_effort": "medium",
  "review": "each",
  "review_rounds": { "each": 1, "global": 1 },
  "tracker": { "type": "github", "repo": "owner/repo" },
  "base_branch": "main",
  "max_iterations": 5
}

• harness: codex or claude (override per run with --harness).
• review: each (per task), all (global only), both, or none.
• review_rounds.each: fresh per-task discovery rounds (default 1).
• review_rounds.global: fresh global discovery rounds (default 1).
• review_max_attempts: deprecated; accepted for old configs with a warning, but ignored by the review loop.
• agents.execution, agents.review, agents.global_review, and agents.global_review.roles.<role> can override harness, model, and reasoning_effort for specialized phases. Global review roles are diff-contract, integration, domain-invariants, and tests-validation.
• max_iterations: the cap on work items per cycle (per pull request), not per run (default 5). The confirmation checklist enforces it for each cycle.
• base_branch: optional; defaults to the current branch at run time.

.nyxagent/prompts/execution.md is a template. Its {{INSTRUCTION}} placeholder renders the default focused implementation instruction, or the text passed with nyxagent run --instruction <text> for that run. Older default prompt files are still recognized; custom files need the placeholder to use --instruction.

If a cycle fails review validation but has already produced commits, NyxAgent commits the work-in-progress, pushes the branch, and opens a draft pull request explaining the failure, so the work is never stranded on an orphaned branch. If even that salvage push fails, the cycle branch is kept locally so the commits stay reachable. The batch then continues with the remaining cycles and the command exits non-zero.

Requirements

• A git repository with a GitHub remote.
• The gh CLI authenticated for the configured repository.
• The selected harness CLI (codex or claude) on PATH.
• An interactive terminal for nyxagent run.