🇳🇴 Norsk

nokto-agent-orchestrator

Orchestrates Claude Code and OpenAI Codex in a controlled delivery workflow for code changes submitted through pull requests.

Each task is planned, validated, implemented in an isolated Git worktree, reviewed independently, and verified against the task's own test commands. Changes are never merged automatically.

The system is built and used in production by Nokto. Missing providers are reported as unavailable, failing tests stop the run, and model output that cannot be parsed is treated as an error.

Workflow

1. Planning Claude creates an implementation plan with read-only access and without modifying files.

2. Validation The plan is checked using static controls for allowed paths, hard-blocked areas, and secrets. It can also be evaluated by a language model against custom quality profiles through AGENT_PROFILE_FILES.

3. Isolation A separate Git worktree is created from a new branch using the naming format agent/<id>-<attempt>. Agents never work directly in the main working copy.

4. Implementation Codex is the primary implementer, with Claude as the fallback. Permitted implementation agents are controlled by allowedImplementers in the task contract.

5. Code review Claude reviews the diff independently and receives access only to the change itself, not the implementer's own summary.

6. Secondary review Codex performs an additional review in a read-only sandbox when Claude implemented the change, or when the primary review identified material findings.

7. Verification The commands in testRequirements.commands are executed in the worktree through an explicit command allowlist.

8. Correction Verification failures and review findings are returned to the implementer as specific correction items.

9. Re-review and verification Steps 4–7 are repeated after corrections. The number of additional attempts is limited by maxRetries.

10. Pull request The diff is scanned for secrets, pushed, and opened as a pull request with a complete report containing the implementation plan, review findings, and verification results. The change must be merged by a human.

State is stored atomically after each step. An interrupted run can therefore resume from the exact last completed step.

All events are stored in an append-only JSONL audit log. Secrets are redacted before they are written to the log.

Related MCP server: github-workflow-mcp

Security

The following Git operations are always blocked:

git reset
git clean
git filter-branch
git filter-repo
git checkout -- <path>

Allowed binaries include:

git
pnpm
npm
node
tsc
vitest
eslint
prettier
python3
pytest

Requirements

• Node.js 20 or later

• pnpm 9

• claude CLI, installed and authenticated for planning and code review

• codex CLI, installed for implementation and secondary review

• GITHUB_TOKEN if the orchestrator should create pull requests automatically

Codex is optional. Claude can be used as the only implementer by specifying:

allowedImplementers:
  - claude

Check which providers and binaries are actually available in the environment:

nokto-agent doctor

doctor checks the real binaries and reports missing dependencies without assuming availability.

Installation

Local development

pnpm install
cp .env.example .env
pnpm run build

.env.example contains safe default values.

Installation from GitHub with npm

npm install github:noktohq/nokto-agent-orchestrator

The prepare script builds the package automatically when installed directly from Git.

Installation from GitHub with pnpm

pnpm add github:noktohq/nokto-agent-orchestrator

pnpm blocks build scripts for Git dependencies by default. This is a pnpm security measure and must be approved explicitly.

Add the package to pnpm-workspace.yaml:

onlyBuiltDependencies:
  - nokto-agent-orchestrator

Then approve the build script:

pnpm approve-builds

The repository is public on GitHub. The "private": true setting in package.json only prevents accidental publication to npm and does not affect the repository's visibility.

CLI

nokto-agent doctor
nokto-agent plan --task tasks/example.yaml
nokto-agent dry-run --task tasks/example.yaml
nokto-agent run --task tasks/example.yaml
nokto-agent status
nokto-agent status --task-id <id>
nokto-agent resume --task-id <id>
nokto-agent cancel --task-id <id>
nokto-agent review --task <file> --worktree <dir>
nokto-agent verify --task <file> --worktree <dir>

The commands are used as follows:

Run the CLI directly from the source code during development:

pnpm run cli -- <command>

MCP server

The following seven operations are exposed as MCP tools over stdio:

agent_doctor
agent_plan_task
agent_run_task
agent_review_task
agent_get_status
agent_resume_task
agent_cancel_task

Start the built MCP server with:

node dist/mcp/server.js

Start the MCP server directly from the source code during development:

pnpm run mcp

Task contract

Tasks are defined as YAML or JSON files and validated against a strict Zod schema in src/types.ts.

See tasks/example.yaml for a complete example.

Plans and file changes outside the permitted scope are rejected.

Testing

Run the checks separately:

pnpm run lint
pnpm run format:check
pnpm run typecheck
pnpm run test
pnpm run build

Run the complete validation chain:

pnpm run lint && pnpm run format:check && pnpm run typecheck && pnpm run test && pnpm run build

The project has 80 tests.

The worktree-isolation and verification tests use real Git repositories in temporary directories, not mocks.

Provider adapters are tested with mocked process execution. The standard test suite therefore performs no paid API calls.

A real integration test against claude -p is available through explicit opt-in:

RUN_LIVE_PROVIDER_TESTS=1

Cost control

Every call to claude -p and codex exec is a real invocation that may incur costs.

The following settings limit resource usage:

• AGENT_CLAUDE_MAX_BUDGET_USD limits the cost per Claude invocation

• constraints.maxRetries limits the number of implementation attempts

• constraints.timeoutMinutes limits the runtime of each task

The total_cost_usd value reported by Claude CLI is recorded for each invocation.

Operations

See RUNBOOK.md for:

• health checks

• common failures

• troubleshooting

• cancellation

• cleanup

• incident handling

License

MIT © 2026 Nokto — nokto.no