An AI coding agent
with harness engineering.
harnext is an interactive terminal agent that reads, writes, and edits files, runs shell, and drives MCP servers — and generates GitHub Actions workflows so AI can pick up issues and ship them, end to end.
Requires Node.js ≥ 20 · MIT licensed · Works with Anthropic, OpenAI, Google, Ollama, and 20+ providers via pi-ai
- 🔍harnext-bot picked up the issue
- 📋generated plan · 3 steps
- ✏️implementing on harnext/dark-mode
- 🚀pushed branch · opened PR #43
- 📸posted browser-verify proof to PR
Everything you'd build into a coding agent — in one CLI.
harnext ships the agent, the harness, and the runner. No glue scripts, no agent server.
Interactive terminal agent
A REPL that reads, writes, edits, runs bash, and drives MCP servers. One-shot mode with -p for scripts and CI.
20+ providers, one CLI
Anthropic, OpenAI, Google, Ollama, NVIDIA, and more via pi-ai. Switch with --provider and --model on the fly.
Harness for your repo
Generates GitHub Actions workflows that pick up issues by label, run the right stage, and post results back.
Self-hosted runner
Register a daemon on your own machine (systemd / launchd) and run stages on your hardware. Idempotent install.
Skills & MCP
Bundle reusable skills (review, init, browser-verify) and connect any MCP server with proxy or direct mode.
Replays & status
harnext status shows active runs; replays let you re-run any session step-by-step. Sessions live in ~/.harnext.
Minimal agent.
Local models.
harnext is a small, focused CLI agent. Six tools, a few skills, and an MCP bridge — that's the whole executor. Point it at a local model and your codebase never leaves the machine.
- Tiny tool surface
read · write · edit · bash · skill · MCP. That's the whole agent. No wrappers, no glue scripts, no hidden orchestration.
- Local-first models
Point harnext at Ollama or NVIDIA out of the box, or any OpenAI-compatible endpoint. Your code never has to leave your machine.
- Switch providers per stage
Run interactive REPL on Anthropic, then dispatch a CI stage to a local llama. One flag: --provider, --model.
- Open & inspectable
MIT-licensed monorepo, plain-JSON sessions in ~/.harnext. Replay any run, audit any tool call.
● local · ○ cloud — all routed through pi-ai
$ harnext --provider ollama --model llama3.2 ✔ ollama @ http://localhost:11434 ✔ tools: read · write · edit · bash · skill · mcp ✔ sessions: ~/.harnext/sessions > add input validation to the signup endpoint ⏺ Read(packages/api/signup.ts) ⏺ Edit(packages/api/signup.ts) ↳ added zod schema · 4 invariants ⏺ Bash(npm test --workspace=api -- signup) ↳ 9 passing · 0 failing ✓ (no tokens left the host · 0 bytes uploaded)
harnext drives itself — or any agent you trust.
Each pipeline stage can dispatch a different executor. Use the harnext REPL for interactive work, and pick claude-code or codex per-stage when running unattended in CI.
harnext
Built-in. The interactive REPL.
Read, write, edit, bash, and MCP — driven by your provider of choice (Anthropic, OpenAI, Google, Ollama, +20 more via pi-ai).
Claude Code
Anthropic's CLI, dispatched.
harnext can hand a stage to claude-code with --max-turns and sandbox flags applied automatically.
Codex
OpenAI's CLI, dispatched.
Same interface for the codex CLI — approval and sandbox bypass flags wired in for unattended runs.
Agent names and marks are property of their respective owners; shown here only to indicate compatibility.
From a GitHub issue to a merged PR — on rails.
harnext setup writes a staged pipeline of GitHub Actions workflows. Each stage is a label; promoting a label triggers the next stage. Run on GitHub-hosted runners, your self-hosted daemon, or both.
- 1
issue:taggedTagger workflow applies the first stage label
- 2
stage:planAgent reads the issue, writes a plan as a comment
- 3
stage:implementAgent opens a branch, edits files, opens a PR
- 4
stage:reviewReviewer agent comments; fix workflow re-runs
- 5
stage:mergedPost-merge cleanup runs after the PR lands
name: stage-implement
on:
issues:
types: [labeled]
jobs:
run:
if: github.event.label.name == 'stage:implement'
runs-on: [self-hosted, harnext-<hash>]
steps:
- uses: actions/checkout@v4
- run: npm i -g harnext
- run: harnext --provider anthropic \
-p "Implement issue #${{ github.event.issue.number }}"
- run: gh issue edit ${{ github.event.issue.number }} \
--remove-label stage:implement \
--add-label stage:reviewThree commands to a running agent.
Install
$ npm install -g harnext
Requires Node.js ≥ 20. Stored at ~/.harnext.
Set up the pipeline
$ cd my-repo $ harnext setup ✔ generated 5 workflows
Adds labels, writes the staged GitHub Actions workflows, and (optionally) registers a self-hosted runner.
Use it as your coding agent
$ harnext > refactor packages/api/auth ⏺ Read · Edit · Bash · ✓
The same CLI is your interactive agent — read, write, run, drive MCP. Pass -p for one-shot use.
Run the agent on your own hardware.
harnext setup can register a GitHub Actions self-hosted runner pinned to your repo with a project-specific label, install it as a systemd or launchd service, and keep it alive across reboots. harnext runner status and harnext runner logs tail the daemon.
- Idempotent install — re-running skips work that's already done
- Project-pinned label prevents shared-host runners from picking the wrong job
- Public-repo guardrail: confirms fork-PR approval gates are on
- Best-effort cleanup on uninstall: deregister, stop service, drop artifacts
$ harnext runner status service active (running) since 2h ago registered ✓ harnext-9f4ac1b online ✓ visible to GitHub labels self-hosted, harnext-9f4ac1b jobs (24h) 18 picked up · 17 ok · 1 failed log ~/.harnext/runner/diag.log
Build the harness. Ship the work.
harnext is open source and MIT licensed. Star it on GitHub or install from npm and try the agent in your terminal in under a minute.