DOCSEARCHbyAlgolia
Submit Docs

gnhf (good night, have fun)

repository·main·Indexed 25 days ago

https://github.com/kunchenguid/gnhf

An autonomous orchestrator for coding agents that executes long-running tasks in iterative, committed steps. It allows developers to set an objective and let agents work autonomously, providing documented and committed code. Key features include an autonomous loop with resilient iterations, support for isolated Git worktrees for concurrent agents, and compatibility with various coding agent CLIs and ACP targets.

Tokens
9.1K
Snippets
17
Records
67
Agent score
86%

What's inside gnhf

  1. Overview of gnhf

    main

    gnhf (good night, have fun) is an autonomous orchestrator designed to run coding agents overnight or during long breaks. It follows a 'ralph' or 'autoresearch' style, where each iteration results in a small, committed, and documented change towards a specified objective.

    Key features:

    • Autonomous Loop: Runs until stopped or a runtime cap (iterations/tokens) is reached.
    • Resilient Iterations: Each successful iteration is committed; failures are rolled back with sensible retries.
    • Live Status: Updates terminal titles with live status, token totals, and commit counts.
    • Exit Summaries: Provides a permanent summary of elapsed time, branch diffs, token usage, and review commands.
    • Agent-Agnostic: Compatible with popular coding agent CLIs and any ACP target.

  2. Understand the gnhf execution workflow

    main

    gnhf operates in an iterative loop to achieve a goal defined in a prompt. The workflow follows these steps:

    1. Initialization: Validates a clean git state, creates or selects a branch, and writes the prompt.md file.
    2. Iteration Loop:
      • Builds an iteration prompt by injecting context from notes.md (shared memory).
      • Invokes the agent in non-interactive mode.
      • On Success: Performs an incremental git commit and appends progress to notes.md.
      • On Failure: Performs a git reset --hard to roll back, unless the failure was a commit error (in which case uncommitted work is preserved for repair).
    3. Termination: The loop continues until a runtime cap is hit, a stop condition is met, or a threshold of consecutive failures is reached (defaulting to 3 failures before aborting).

    Key Concepts:

    • Incremental Commits: Each successful iteration is a separate unsigned commit, allowing for easy cherry-picking or reverting.
    • Shared Memory: The agent uses notes.md to maintain context and communicate progress across iterations.
    • Local Metadata: Run metadata (prompts, notes, stop conditions) is stored in .gnhf/runs/ and is ignored by git so it doesn't clutter your branch.

  3. Commit and push on the current branch

    main

    By default, gnhf may use worktrees. To force it to work directly on your current branch and automatically push to the remote after every successful iteration, use the --current-branch and --push flags.

    $ gnhf --current-branch --push "keep improving this app"

  4. Quick Start with gnhf

    main

    To start an autonomous loop, run gnhf followed by your objective string from within a Git repository with a clean working tree. If you are in a plain directory, run git init first.

    Basic usage:

    gnhf "your objective here"

    To prevent infinite loops, you can set limits on iterations and tokens:

    gnhf "your objective here" --max-iterations 10 --max-tokens 5000000
    gnhf "reduce complexity of the codebase without changing functionality"

  5. Run multiple agents using worktrees

    main

    You can run multiple gnhf instances on the same repository simultaneously by using the --worktree flag. This allows different agents to work on different tasks in isolated Git worktrees without interfering with each other.

    $ gnhf --worktree "implement feature X" &
$ gnhf --worktree "add tests for module Y" &
$ gnhf --worktree "refactor the API layer" &

  6. Perform a Companion Review of GNHF results

    main

    In Companion mode, do not assume "Stop condition met" equals user acceptance. Follow these steps to review results:

    1. Inspect State: Check the branch, status, commits, changed files, and diff.
    2. Verify Claims: Treat GNHF logs/notes as claims, not evidence. Run independent verification (tests, lint, build, typecheck, or manual QA).
    3. Compare: Match the result against the original stop condition and the user's latest feedback.
    4. Decide: Categorize the result as Mergeable, Needs follow-up GNHF run, or Do not merge.

  7. Steer an active GNHF run in Companion mode

    main

    When in Companion mode, you can steer the worker by providing a steering prompt if you observe issues. Use the following template to refocus the agent:

    Continue from the current repo state. The previous run partially succeeded: <evidence>.

Do not redo completed work. Focus only on <bounded correction>.

The issue to fix now is <specific observed issue>. Verify with <commands/checks>.

Stop only when <observable condition>.

    Common Steering Actions:

    • Real blocker found: Stop or relaunch with blocker-specific instructions.
    • Skipped research: Relaunch with research as an explicit first deliverable.
    • Unrelated file changes: Stop and review before continuing.
    • False success: Relaunch with an evidence-based stop condition.

  8. Run gnhf in Worktree Mode for concurrent agents

    main

    Use the --worktree flag to run agents in isolated git worktrees. This allows you to run multiple agents on the same repository simultaneously without interference.

    • Each agent gets its own working directory and branch inside a <repo>-gnhf-worktrees/ folder.
    • Preservation: Worktrees containing commits are preserved after the run so you can review or merge the work. gnhf will provide the path and cleanup command.
    • Cleanup: Worktrees with no commits are automatically removed upon exit.
    • Requirement: --worktree must be run from a non-gnhf branch (e.g., main).

  9. Launch a GNHF run

    main

    GNHF (an agent orchestrator) can be launched via the CLI to run an agent repeatedly until a natural-language stop condition is met. Before launching, it is recommended to check your current git state (git status --short, git branch --show-current, and git log --oneline --max-count=5).

    Use the following command structure:

    gnhf \
  --agent <agent> \
  --max-iterations <n> \
  --stop-when "<observable completion condition>" \
  --prevent-sleep on \
  "<worker prompt>"

    Note: If the CLI version you are using does not have a --model flag, include model requirements directly within the <worker prompt> or your backend configuration.

  10. Choose a GNHF mode: Hands-Off vs Companion

    main

    Select one of two modes depending on the task requirements:

    Hands-Off Mode

    Use for bounded tasks with clear verification where the user wants a single configured run to proceed without supervision.

    • Workflow: Prepare a precise prompt with constraints and a stop condition, launch GNHF, and wait for completion.
    • Intervention: Only intervene for hard failures, runaway scope, or destructive behavior.

    Companion Mode

    Use for uncertain, exploratory, design-heavy, or research-heavy tasks that require course correction.

    • Workflow: Poll the active process, monitor diffs, and intervene when the worker optimizes the wrong thing, repeats failures, or drifts scope.
    • Key Principle: Treat review findings as the next set of acceptance criteria. Prefer launching a new bounded GNHF prompt over manually taking over the implementation.