AI Agent Adapters: Claude, Codex, Ollama, and Custom

RepoKernel is agent-agnostic. Every task and sprint runs inside an isolated Git worktree; the agent adapter is the bridge between that worktree and whatever AI coding tool you want to use. RepoKernel invokes the agent, waits for it to finish, parses a structured sentinel result from its output, and then runs the review gate — regardless of which adapter you chose. This page covers the built-in adapters and how to wire a custom one.

Adapter overview

Adapter	Notes
`claude`	Claude Code CLI. Requires `claude login` or `ANTHROPIC_API_KEY`
`codex`	OpenAI Codex CLI. Requires `OPENAI_API_KEY`
`ollama`	Local model via Ollama. No API keys, no cloud
`fake`	Deterministic test agent. Perfect for demos and CI
`manual`	Pauses so you do the work yourself
custom	Any shell command configured in `repokernel.config.yaml`

fake is always safe for testing. It reads the context packet, writes a placeholder rk-fake-output.txt file in the worktree, commits it, and returns a completed sentinel — the full lifecycle without any LLM call or API key. Use it to verify your setup, smoke-test new sprints, and run CI pipelines before connecting a real agent.

Agent adapters

Claude
Codex
Ollama
Custom

Install Claude Code

npm install -g @anthropic-ai/claude-code

Verify the install:

claude --version

Authenticate

For interactive use, log in once with the OAuth flow:

claude login

This writes a credential to ~/.claude/credentials.json. For CI or headless servers, set the environment variable instead:

export ANTHROPIC_API_KEY=your-key-here

The API key takes precedence over the stored credential.

Run a task

rk run -m "Add a /health endpoint that returns 200 OK" --agent claude

How RepoKernel invokes Claude Code

RepoKernel calls the Claude CLI in non-interactive mode, scoped to the sprint worktree:

claude --print --cwd <worktree> -p <packet_path>

Claude Code reads the packet, edits files, runs any checks you configured, and commits its changes inside the worktree. Each commit lands on the sprint branch:

feat(S-001): add /health endpoint returning 200 OK

Common failure modes

Auth not configured

Error: No API key found. Run `claude login` or set ANTHROPIC_API_KEY.

Fix: claude login for interactive use, or export ANTHROPIC_API_KEY=... for headless.Rate limit hitClaude Code exits non-zero; RepoKernel marks the sprint agent_failed:S-001. Retry after the rate limit window:

rk run T-001

Checks failThe sprint stays active. Inspect the diff, then retry or discard:

rk run inspect RUN-001
rk run T-001        # retry
rk discard T-001    # drop

Scope refusalIf Claude Code declines to write a file outside allowed_paths, or the review gate catches out-of-scope changes before rk close will merge:

Review blocked: changed files outside allowed_paths.

Widen allowed_paths in your sprint frontmatter or repokernel.config.yaml if the task legitimately needs broader access.

Install Codex CLI

npm install -g @openai/codex

Verify the install:

codex --version

Authenticate

For interactive use:

codex login

For CI or headless servers, set the API key:

export OPENAI_API_KEY=your-key-here

Add this to your shell profile (~/.zshrc, ~/.bashrc) to persist across sessions.

Run a task

rk run -m "Add a /health endpoint that returns 200 OK" --agent codex

How RepoKernel invokes Codex

The default codex preset confines writes to the worktree and disables network access:

codex exec --cd <worktree> --sandbox workspace-write \
  "Read and follow the RepoKernel sprint packet at <packet_path>. Emit the required RepoKernel sentinel block when complete."

If a task genuinely needs network access or must reach outside the worktree (installing dependencies, fetching remote resources), use --agent codex-danger:

rk run -m "..." --agent codex-danger

codex-danger runs with --sandbox danger-full-access. The name is intentional — opt into it per task, not as a default. RepoKernel’s allowed_paths check still applies at review time regardless of sandbox mode.

Common failure modes

API key not set

Error: OPENAI_API_KEY is not set.

Fix: export OPENAI_API_KEY=your-key-here.Rate limit hitCodex exits non-zero; RepoKernel marks the sprint agent_failed:S-001. Retry:

rk run T-001

Scope violation

Review blocked: changed files outside allowed_paths.

Widen allowed_paths in the sprint frontmatter if the task needs broader access, then retry.

Install Ollama

Download and install Ollama from ollama.ai, then pull a model:

ollama pull llama3.1
ollama serve   # if not already running

Run a task

OLLAMA_MODEL=llama3.1 rk run -m "Add a function add(a,b)" --agent ollama

No API keys or cloud account required — every request stays on your machine.

Environment variables

All variables are optional:

Variable	Default	Purpose
`OLLAMA_MODEL`	`llama3.1`	Model tag from `ollama list`
`OLLAMA_HOST`	`http://localhost:11434`	Ollama HTTP endpoint
`OLLAMA_TIMEOUT_MS`	`1800000` (30 min)	Per-request timeout — local CPUs can be slow on long prompts

How the built-in Ollama adapter works

The adapter implements a deliberately simple single-turn protocol:

Reads the sprint packet plus up to 20 tracked files from the worktree (truncated at 4 KB each to fit modest context windows).
POSTs to /api/chat with format: 'json' to steer the model toward valid JSON.
Parses the response into { summary, files: [{path, content}] }. Each entry replaces the entire file at that path — no diffs.
Writes the files inside the worktree, runs git add + git commit, and returns the result.

Limitations of the built-in adapter: whole-file replacement only (diffs are unreliable on small local models), single turn with no retry or tool use, and output quality scales with model size. For richer multi-turn behaviour against the same Ollama backend, run aider via the custom adapter pattern instead.

Configure a custom adapter

agents:
  my-agent:
    command: ./scripts/run-agent.sh
    args:
      - "{packet_path}"
      - "{worktree}"
    resultFormat: sentinel-json
    timeoutSeconds: 1800

Then invoke it by name:

rk run -m "..." --agent my-agent

Arg placeholders

These placeholders are substituted at runtime:

Placeholder	Value
`{packet_path}`	Absolute path to the context packet JSON file
`{worktree}`	Absolute path to the agent’s working directory
`{sprint_id}`	Sprint ID (e.g., `S-001`)
`{run_id}`	Run ID (e.g., `RUN-001`)
`{epic_id}`	Epic ID (e.g., `E-001`)
`{op_root}`	Root of the main checkout
`{registry_path}`	Absolute path to `registry.json`
`{mode}`	Execution mode: `assisted` or `autonomous`

Sentinel result format

Every agent — custom or built-in — must write the following to stdout before exiting:

REPOKERNEL_RESULT_START
{"status":"completed","summary":"Added JWT signing module","changed_files":["src/auth/jwt.ts"],"needs_human":false}
REPOKERNEL_RESULT_END

Required fields:

Field	Type	Values	Description
`status`	string	`completed`, `failed`, `blocked`	Whether the agent finished successfully
`summary`	string	any	Human-readable description of what was done
`changed_files`	string[]	repo-relative paths	Files the agent modified
`needs_human`	boolean	`true` / `false`	Whether the agent is requesting human intervention

If status is failed or blocked, the run halts with agent_failed:<sprint-id>. The summary is logged for diagnosis.

Minimal shell agent example

#!/usr/bin/env bash
# scripts/run-agent.sh
set -euo pipefail

PACKET_PATH="$1"
WORKTREE="$2"

SPRINT_ID=$(jq -r '.sprint.id' "$PACKET_PATH")
TITLE=$(jq -r '.sprint.title' "$PACKET_PATH")

cd "$WORKTREE"
echo "# $TITLE" > "output-${SPRINT_ID}.md"
git add "output-${SPRINT_ID}.md"
git commit -m "feat: $TITLE"

cat <<'EOF'
REPOKERNEL_RESULT_START
{"status":"completed","summary":"Created output file","changed_files":["output-S-001.md"],"needs_human":false}
REPOKERNEL_RESULT_END
EOF

Timeout

timeoutSeconds (default: 1800) controls how long RepoKernel waits before killing the agent process and marking the sprint failed. Increase it for agents that need more time on large tasks.

Configuring the review gate with `checksCmd`

The checksCmd runs inside the worktree after the agent finishes, before the run enters review state. Set it once in repokernel.config.yaml:

automation:
  checksCmd: pnpm lint && pnpm typecheck && pnpm test

If the command exits non-zero, the sprint stays active and the run does not enter review — rk close will refuse to merge until checks pass. Retry the agent in the same worktree or discard the task:

rk run T-001      # retry the agent
rk discard T-001  # drop the worktree

You can also run the full gate bundle manually for any sprint:

rk gates S-001

rk gates runs checksCmd, diff and path checks, rk validate --fail-on P1, and rk registry --check --explain in one pass, and appends command_evidence to the linked review if one exists.

Choosing an agent

Situation	Recommended agent
Verifying setup or CI pipelines	`fake`
Manual coding with lifecycle tracking	`manual`
Claude CLI integration	`claude`
OpenAI Codex CLI integration	`codex`
Local model, no API keys, no cloud	`ollama`
Custom script or wrapper	External agent via config

Get Started

Guides

Operations

AI Agent Adapters: Claude, Codex, Ollama, and Custom

Adapter overview

Agent adapters

Install Claude Code

Authenticate

Run a task

How RepoKernel invokes Claude Code

Common failure modes

Install Codex CLI

Authenticate

Run a task

How RepoKernel invokes Codex

Common failure modes

Install Ollama

Run a task

Environment variables

How the built-in Ollama adapter works

Configure a custom adapter

Arg placeholders

Sentinel result format

Minimal shell agent example

Timeout

Configuring the review gate with `checksCmd`

Choosing an agent

Build docs developers (and LLMs) love

Get Started

Guides

Operations

Documentation Index

​Adapter overview

​Agent adapters

​Install Claude Code

​Authenticate

​Run a task

​How RepoKernel invokes Claude Code

​Common failure modes

​Install Codex CLI

​Authenticate

​Run a task

​How RepoKernel invokes Codex

​Common failure modes

​Install Ollama

​Run a task

​Environment variables

​How the built-in Ollama adapter works

​Configure a custom adapter

​Arg placeholders

​Sentinel result format

​Minimal shell agent example

​Timeout

​Configuring the review gate with checksCmd

​Choosing an agent

Build docs developers (and LLMs) love

Adapter overview

Agent adapters

Install Claude Code

Authenticate

Run a task

How RepoKernel invokes Claude Code

Common failure modes

Install Codex CLI

Authenticate

Run a task

How RepoKernel invokes Codex

Common failure modes

Install Ollama

Run a task

Environment variables

How the built-in Ollama adapter works

Configure a custom adapter

Arg placeholders

Sentinel result format

Minimal shell agent example

Timeout

Configuring the review gate with `checksCmd`

Choosing an agent