harness: Instructions file for Codex

AGENTS.md

This file provides guidance to agents when working with code in this repository.

What This Is

Harness is a minimal agent loop in bash. The core script (~100 SLOC) is a bootstrap, hook pipeline runner (call), state follower, and CLI dispatch. Even source discovery is hookable — the sources stage lets plugins control which directories participate. Everything else — session management, provider discovery, tool discovery, message assembly, API calls, response parsing, tool execution, prompt loading — lives in hooks and plugins that can be written in any language.

Dependencies: bash 4+, jq, curl. No package manager, no language runtime.

Commands

# Run the agent
bin/harness "do something"           # one-shot (args = message)
echo "do X" | bin/harness            # one-shot (stdin)
bin/harness                          # interactive REPL
bin/harness <session-id>             # resume session

# Inspect
bin/harness tools                    # list discovered tools
bin/harness hooks [stage]            # list discovered hooks
bin/harness session list             # list sessions
bin/harness session show <id>        # inspect session

# Tests
spec/run                             # run all tests
SPEC_DIR=spec bash spec/tests/NAME/test.sh  # single test

The bin/hs symlink is an alias for bin/harness.

Architecture

The State Machine

The core loop is a pure state follower. It dispatches hooks for the current state, reads next_state from the hook output, and transitions. The core has no built-in transitions — state flow is entirely declared by hooks. An empty or absent next_state stops the loop. After the loop ends, output is read from the terminal state's result and printed.

start → assemble → send → receive → done
                    ↑                  │
                    │   tool_exec → tool_done
                    │                  │
                    └──────────────────┘

This diagram is emergent from hooks, not hardcoded. Hooks drive iteration: tool_exec pops one call, tool_done routes back to tool_exec or assemble.