gnhf AGENTS.md

AGENTS.md

This file provides guidance to agents when working with code in this repository.

Project

gnhf ("good night, have fun") is a CLI that runs a coding agent in a loop inside a git repo. The supported-agent roster is owned by the README's Agents table. Each successful iteration is a separate commit, normally on a dedicated gnhf/<slug> branch; --current-branch uses the existing branch instead, and --push publishes each successful iteration. Failure and rollback semantics are owned by the README's How It Works section. The acceptance policy for what gnhf should and should not become is owned by VISION.md; test feature or scope decisions against its aligns/resist criteria. Target: Node 20+, published to npm as a bundled ESM CLI with optional agent-facing skills under skills/.

Commands

package.json scripts are the source of truth for build/test/lint commands; the "Developing" section in CONTRIBUTING.md documents them plus single-test invocation, the e2e prior-build requirement, and the CI matrix - keep all CI jobs green. pnpm test builds and then runs all tests. Releases are automated via release-please; never hand-edit CHANGELOG.md or .release-please-manifest.json.

Architecture

Entry point is src/cli.ts. It parses flags with commander, resolves config, handles stdin/worktree/resume setup, then hands off to the orchestrator. Everything else is plain modules under src/.

Run lifecycle (the critical flow)

1. cli.ts decides one of four modes: new branch, resume an existing gnhf/<slug> branch, --current-branch, or --worktree (creates a sibling <repo>-gnhf-worktrees/<slug>/ checkout). New branch and worktree runs probe numeric suffixes such as gnhf/<slug>-1 and <repo>-gnhf-worktrees/<slug>-1/ on collisions; current-branch runs first resume an exact same-prompt .gnhf/runs/<runId>/ on a clean working tree, otherwise they probe .gnhf/runs/<runId>-1/ metadata collisions without creating a branch; worktree mode also resumes preserved suffixed worktrees before creating a new one. When resuming with a different prompt, it asks whether to update prompt.md and continue the existing run history, start a new branch, or quit; if stdin is piped, that confirmation comes from the controlling terminal before any sleep-prevention re-exec. setupRun/resumeRun in src/core/run.ts create .gnhf/runs/<runId>/ with prompt.md, notes.md, output-schema.json, base-commit, optional stop-when, commit-message, and gnhf.log, and add .gnhf/runs/ to .git/info/exclude so run metadata stays local.
2. Orchestrator (src/core/orchestrator.ts) is an EventEmitter loop. Each iteration: build prompt via src/templates/iteration-prompt.ts (injects current notes.md), add commit-repair instructions when a prior git commit failed, call agent.run(...), then on success commitAll + append to notes.md and optionally pushCurrentBranch; on failure resetHard unless a pending commit failure is preserving uncommitted work for repair. The user-visible failure/rollback contract lives in the README's "How It Works"; in code, commitAll throws CommitFailedError, logs git:commit:failed, and records the commit output in notes.md so the next iteration can repair the workspace, retryable thrown agent errors increment the backoff streak, RateLimitAgentError rolls back and waits until the provider-reported reset time (bounded escalating fallback when absent) before retrying the same iteration number without counting a failure, an iteration the provider billed to extra usage instead of rejecting (Claude's isUsingOverage, reported out-of-band via onOverage so a terminal path that throws still carries it) keeps its committed work and waits after the post-iteration checks but before any error backoff, failing closed when the reported reset time is unusable - providerResumeWait is the single owner of what a reported reset time is worth, and both waits share waitForUsageWindowReset and the --max-rate-limit-wait budget - and PermanentAgentError aborts after rollback with lastAgentError set for the renderer. The RunLimits object enforces --max-iterations (between iterations), --max-tokens (mid-iteration via AbortController), --max-rate-limit-wait (total usage-limit wait before aborting), --stop-when (post-iteration via the agent's should_fully_stop output, deferred while a commit failure awaits repair), and --push post-success publishing.
3. Renderer (src/renderer.ts + src/renderer-diff.ts) is a cell-based TUI using the alt screen buffer. cli.ts enters/exits alt screen around it. The renderer subscribes to orchestrator events, diffs frames to minimize writes, and updates the terminal title live. MockOrchestrator (src/mock-orchestrator.ts) drives the renderer offline via --mock for demos/testing.
4. Shutdown path: SIGINT routes through orchestrator.handleInterrupt(). The first press requests a graceful stop, letting the current iteration finish or ending backoff early; the second press force-stops via orchestrator.stop(). SIGTERM force-stops immediately. cli.ts only keeps the done screen open for aborted runs; graceful stops exit once shutdown cleanup finishes. The README's How It Works section owns worktree preservation and cleanup behavior. That rule must hold on every exit path, not just the normal cleanup block: the process.on("exit") cleanup fallback re-checks orchestrator state before removing a worktree, and the force-exit timeout prints the preserved path before calling process.exit(). After cleanup, cli.ts collects final branch/diff stats via src/core/git.ts and writes the permanent stdout summary rendered by src/core/exit-summary.ts, including an uncommitted-work warning when a commit failure is still pending.