nk is a lightweight personal toolkit for repeatable agentic engineering. It
adds structure around an existing coding harness without replacing it. The same
workflow can support one project or coordinate efforts that span repositories,
trackers, machines, and native resources.
Start with only the layers your work needs:
- Context skills progressively teach the harness about a project as you develop with it. They can be used without task coordination or scheduling.
- Structured tasks add durable specifications, explicit lifecycle state, exact claims, isolated candidates, independent review, and validation.
- Clusters and scheduling add automatic routing across declared Workspaces, Nodes, capabilities, and resources. A local Node is enough to start.
- Bootstrap contracts are optional hooks for converging tools and project checkouts on a Node or Workspace. Missing hooks are no-ops.
There is no central service, resident node daemon, or database. Each Node owns its Agent runs, logs, resources, and runtime state independently of the controller connection. The harness retains its own model selection, authentication, and personal preferences.
nk can use the same agentic workflow it coordinates to improve and repair
itself. With the bundled
operate scheduler skill, an Agent can
observe a live Cluster, contain a failure, stop new dispatch while active work
drains, diagnose and test a narrow code fix, roll the repaired nk revision
out across its Nodes, and resume scheduling under observation.
This self-healing loop preserves active claims and unpublished work, requires evidence before changing product code, and verifies the repaired path on the real Node before uncordoning affected Workspaces.
nk gives each effort the same context, task, execution, review, and validation
contracts. The project supplies the domain knowledge and accepted checks. nk
supplies the repeatable workflow around them.
nk does not replace project repositories or trackers. It gives work from any
of them a common execution model. A Workspace repository can group tasks from
multiple trackers and coordinate changes across its child repositories.
Multiple independent Clusters can coordinate different Workspace repositories
at the same time. Each keeps its own task state and project contracts rather
than folding everything into one central state store.
nk is strongly aligned with the structured, verified end of the spectrum in
Google's Kaggle whitepaper,
The New SDLC With Vibe Coding.
That end of the spectrum turns human intent into explicit specifications and
systematically verifies the resulting work.
nk applies that discipline through:
- Context captured in repository instructions, project documents, and skills for individual tasks.
- Specifications that record goals, acceptance criteria, non-goals, and dependencies before work becomes Ready.
- Bounded execution where one Agent run advances one exact claim.
- Isolated candidates submitted at exact remote commits rather than moving branch tips.
- Independent review in a separate Workspace and harness context.
- Native validation on a Node that satisfies the task's declared needs.
- Durable evidence for claims, findings, approvals, and validation results.
This rigor cannot make an underspecified task correct. Projects still own their instructions and validation definitions, and the operator still owns specification quality before a task becomes Ready.
Ready → Authoring → Draft → Reviewing → Done
↑ │
└──── evidence backed blockers ┘
An author validates and reviews the complete candidate before submission. A separate reviewer reassesses that exact candidate without modifying it, gathers all evidence backed blockers, and either returns the task for repair or records approval and passing candidate validation. Every repaired candidate receives a fresh full review. Completion mechanically integrates that unchanged candidate against current targets, retrying target movement without repeating validation. A merge conflict returns the task to Ready for author repair; external validation evaluates target quality over windows of integrated changes.
Authors, reviewers, and task validation operate directly in their claimed workspaces. Claim preparation places reviewer child repositories at the exact candidate SHAs, so ordinary task work does not use temporary checkouts, worktrees, or another workspace's files.
The Scheduler resumes existing claims before new work. Among new work, it considers Draft reviews before Ready authors so feedback can complete before more work in progress is created; each queue retains its explicit top-to-bottom priority.
Each task keeps current intent in a live README.md and newest-first review,
repair, blocker, and resolution evidence in a live JOURNAL.md. Lifecycle
commands publish their required Journal entries atomically without rewriting
the README. TODO.md remains the lifecycle authority, while structured
evidence binds exact candidates and validation.
Approval and validation remain separate decisions. Nontrivial work checks correctness, simplification, load-bearing complexity, and architecture. Aesthetic or speculative suggestions do not force another review round.
When work remains blocked, the bundled deep blocker diagnosis workflow safely synchronizes the Workspace, inventories every current blocker, and tests each claim against primary evidence. It favors exact reproductions, retained artifacts, falsifiable hypotheses, and probes chosen for their expected evidence gain.
The investigation produces a durable report that separates established facts, open questions, and provisional recommendations. Diagnosis stays separate from repair, task creation, cancellation, and routing until the evidence is exhausted and the operator agrees on the next action.
When one fault or dependency chain is holding unrelated work, the bundled workstream decoupling workflow audits every pending task, contains the demonstrated blast radius, and splits false platform, validation, or task-boundary serialization. It also runs proactively without a known fault to maximize safe queue throughput.
Install with ./install.sh on POSIX or ./install.ps1 on Windows. Configuration
and installed skills live under ~/.nk. Install from a clean commit before
running setup. Setup records that commit on every Node, and the Scheduler
refuses to run a Cluster with mixed revisions.
Provision each Node account, repository access, Git author identity, harness authentication, and harness configuration before setup. Put shared Agent behavior in the Workspace repository's native harness configuration; keep authentication and personal preferences in user-local harness state. Upgrades leave existing user and administrator configuration unchanged.
The Codex entrypoint preserves inherited environment restrictions, including
CODEX_SANDBOX_NETWORK_DISABLED. Launch the Scheduler with the environment
required by the intended workload.
Declare a Cluster, its Nodes, and Workspaces for each role:
nk cluster add work --repository git@example.com:owner/tasks.git
nk node add local --cluster work --target localhost --os linux --architecture x86_64 --gpus 1
nk workspace add author@local --cluster work --path /work/author --role author
nk workspace add reviewer@local --cluster work --path /work/reviewer --role reviewer
nk cluster setup --cluster work
nk cluster verify --cluster work
nk scheduler run --cluster work
For bastions or local SSH wrappers, quote --target as the remote command
prefix. A single word still means ssh <word>:
nk node add horde --cluster work \
--target 'ssh -o StrictHostKeyChecking=no -J horde@bastion.horde-gke.nvidia.com:2222 horde@nkagan-nkagan-horde-next-1.ov-agent-farm.svc.cluster.local' \
--os linux --architecture x86_64 --gpus 1
nk node add horde-next --cluster work \
--target 'hgx ssh nkagan-horde-next-1' \
--os linux --architecture x86_64 --gpus 1
Verification requires effective user-local user.name and user.email Git
configuration on every Node. Setup does not derive or copy those values from
the controller.
Use nk task --help to create, specify, ready, claim, submit, review, complete,
block, or cancel tasks.
Inspect current activity and Node local run state separately from the Scheduler:
nk scheduler status --cluster work
nk scheduler status --cluster work --json
nk scheduler wait --cluster work
nk scheduler events --cluster work -f
nk scheduler recover author@local --cluster work
nk scheduler logs <claim-id> -f
nk scheduler logs --cluster work --workspace author@local
status works without a running Scheduler controller. --json emits the same
observation as one structured snapshot for automation. wait returns when every
Workspace has left reserved and running, and fails when a
complete drain cannot be observed or an interrupted run requires operator
recovery. events tails the Scheduler's append-only JSONL event log at
~/.nk/clusters/<cluster>/state/events.jsonl. None of these commands stops or
alters Agent runs. After inspecting and containing the owning Node, recover
removes only an interrupted run
reservation; it preserves the task claim, checkout, logs, candidate refs, and
artifacts so normal scheduling can resume the exact claim. Until recovery, the
Workspace and its recorded Node resources remain unavailable to dispatch.
Each claim receives Workspace-local scratch through NK_RUN_TEMP, TMPDIR,
TMP, and TEMP. Reconciliation removes the directory after the claim worker
exits, whether the run succeeded, failed, or was interrupted. Evidence that
must outlive the run belongs in the Workspace.
Use nk cluster setup --cluster work --node <name> to converge one declared
Node during repair without touching the rest of the Cluster. Use --verbose
with the Scheduler to include polling details such as run state checks, queue
reads, and idle cycles.
This project is dedicated to the public domain under CC0 1.0. Use any part of it for any purpose. Permission and attribution are not required.