Open-source blueprint

Build an agent harness your team owns

Use this copyable structure to keep context, tools, permissions, verification, and coordination in your repository instead of rebuilding them around every new model.

See the harness we use to build Nimbalyst Read the agent harness guide

The architecture

The model sits inside the system

An agent harness is the project-owned system around a coding model. The model generates and reasons; the harness supplies durable context, permission boundaries, tools, workflow, and evidence. Claude Code, Codex, and OpenCode can all sit beneath the same project layer.

Your project harness

Versioned rules, context, tools, workflows, verification, provenance, interface, and coordination

Coding-agent harness

The vendor or open-source runtime that loads prompts, calls tools, and manages execution

Model

The underlying model selected for the task

Copyable repository shape

Start small, leave room to compound

Names differ between agents. Claude Code reads CLAUDE.md and a .claude/ directory, other runtimes use AGENTS.md or their own paths, but the ownership boundaries are stable. Keep the source of truth in versioned files and link agent-specific entry points back to it.

your-project/
├── AGENTS.md                 # Cross-agent project map and hard rules
├── CLAUDE.md                 # Claude Code entry point
├── docs/
│   ├── architecture.md       # Durable system context
│   ├── decisions/            # Why important choices were made
│   └── runbooks/             # Repeatable operational procedures
├── .agents/
│   ├── rules/                # Path-scoped instructions
│   ├── skills/               # Reusable workflows and examples
│   └── evaluations/          # Real tasks and scoring rubrics
├── tools/agent/              # Project-specific tools and MCP servers
├── tests/agent-harness/      # Verification and regression loops
└── .github/workflows/        # Automated checks for harness changes

Starter files

Give every session a map, boundaries, and proof

Treat these as prompts to customize, not universal boilerplate. Delete rules you cannot explain and add examples drawn from real mistakes in your own repository.

AGENTS.md

A short, cross-agent entry point that explains the project and routes agents to deeper context.

# Project operating guide

## Start here
- Read `docs/architecture.md` before changing system boundaries.
- Read the nearest scoped rule before editing a package.
- Preserve user changes that are unrelated to the task.

## Verification
- Reproduce bugs before fixing them.
- Run the smallest relevant test, then the package check.
- Report the command and result; do not claim success without evidence.

## Approval boundaries
- Ask before changing shared external state.
- Never expose secrets or weaken a safety check to make a test pass.

Scoped rule

Instructions that load only for a sensitive package or path, keeping the root guide short.

# Rules for persistence code

Applies to: `src/persistence/**`

- All schema changes require a forward migration and rollback note.
- Add a fail-first test for every persistence bug.
- Verify both a fresh database and an upgraded database.
- Never write directly to production data from an agent session.

Evaluation case

A real, repeatable task that detects whether a harness change improved outcomes or merely added instructions.

id: persistence-restart-001
task: Fix the record body disappearing after restart.
fixed_inputs:
  - repository commit
  - model and version
  - task prompt
  - tool permissions
  - token budget
required_evidence:
  - failing test before the change
  - passing test after the change
  - migration safety check
  - changed-file rationale

Eight-layer checklist

A production harness is more than an instruction file

Context

Can the agent find the relevant code, conventions, decisions, and examples without a prompt dump?

Root guide, scoped rules, architecture docs, decisions, examples, memory

Provenance

Can a person or agent trace a change back to the task, decision, session, and evidence that produced it?

Typed links, tracker history, session-to-diff links, decision records

Capability

Can the agent observe live state and act through safe, project-specific tools?

Logs, database readers, browser control, screenshots, MCP tools

Workflow

Do recurring jobs follow reusable investigation, planning, implementation, and review paths?

Commands, skills, runbooks, hand-off templates

Restraint

Do permissions and approvals become stricter as capability becomes more powerful?

Allowlists, scopes, approval gates, audit logs, cost boundaries

Verification

Can the agent prove the change works at the layer where users experience it?

Fail-first tests, type checks, end-to-end loops, screenshots, simulators

Visual interface

Can people review plans, diffs, diagrams, mockups, and results without reconstructing them from chat?

Rendered artifacts, red and green diffs, review surfaces, discussions

Coordination

Can the team see ownership, state, dependencies, and hand-offs when several agents run in parallel?

Session board, workstreams, isolated branches, parent-child runs, hand-offs

Adoption order

Build reliability before orchestration

A small harness that proves one agent's work is more valuable than elaborate multi-agent coordination around an unreliable loop. Add layers in the order your incident history demands.

01

Capture the map and hard rules

Write a concise root guide, architecture map, and the approval boundaries that cannot be inferred from code.
02

Close one verification loop

Give the agent a real task, a way to observe the result, and an automated or inspectable success condition.
03

Turn repeated explanations into scoped assets

Promote recurring guidance into path rules, examples, skills, runbooks, or tools only after it repeats.
04

Record provenance and evaluations

Keep the task, trace, diff, test output, and decision connected. Rerun real cases when the harness changes.
05

Add coordination when parallel work needs it

Introduce workstreams, isolated branches, ownership, and hand-offs once several reliable agent loops run together.

No black box

Inspect the harness Nimbalyst uses

Nimbalyst's desktop and iOS code is MIT licensed. Its living harness catalog names the actual instruction files, skills, tools, verification loops, provenance features, and coordination mechanisms used to build the product. Use the product, copy individual patterns, or compare the implementation with your own stack.

Read docs/THE_HARNESS.md on GitHub Browse the Nimbalyst source Test the blueprint with the benchmark protocol

FAQ

Open-source agent harness questions

Is this agent harness blueprint open source? +

The blueprint is published for anyone to use, and the linked Nimbalyst implementation is MIT licensed. Your own instruction files, tools, workflows, and evaluations stay in your repository under the terms you choose.

Does the same harness work with Claude Code and Codex? +

The project-owned layer can. Keep shared context, rules, tools, and evaluations in neutral repository files, then use small agent-specific entry points where Claude Code, Codex, or another runtime requires a different filename or configuration shape.

Do I need all eight layers before using a coding agent? +

No. Start with context, restraint, and one verification loop. Add tools and reusable workflows as repeated needs appear. Provenance, visual review, and coordination become more valuable as the work and number of concurrent agents grow.

What should stay in house? +

Keep your project rules, sensitive context, permissions, examples, incident-derived evaluations, and acceptance criteria under your control. Generic workspace and orchestration capabilities can come from an open-source base if they remain inspectable and portable.

How should I measure whether the harness helps? +

Run the same real tasks with fixed model, repository commit, prompt, tools, and budget. Compare correctness, verification, policy adherence, context efficiency, recovery, and provenance. The companion benchmark page provides a protocol and 100-point rubric.

Nimbalyst: the open-source visual workspace for building with Codex, Claude Code, and more

Download

Works with your existing Claude Code and Codex subscription or API key

Other downloads: Apple Silicon Mac Intel Mac Windows Linux