OkComputer Agent Harness

English | 中文

OkComputer is a small, model-agnostic agent harness in Python. A model uses it to work over files, tools, context, and sub-tasks across long-running tasks.

It has two things most coding-agent harnesses don't: a small core with a clean, deletable extension boundary, and a self-improvement loop that lets the harness adjust its own configuration under human review.

Status: alpha. The core loop is stable. The self-improvement loop works and is covered by deterministic tests, but is kept under human review by design.

---

What's different

• Small core, deletable extensions. The core is three pieces: AgentLoop, Workspace, and ToolRuntime. Hooks, the task manager, context management, memory, and the whole self-improvement loop are extensions. Remove any of them and the core behaves the same.
• A self-improvement loop. The harness can read its own recorded trajectories, find recurring weaknesses, propose configuration changes, validate them against regression gates, and apply them under review. It only changes a whitelist of config values and an optional prompt overlay. It never edits the core.
• Bounded and reversible. Nothing is applied automatically. An edit stays a proposal until you accept it, applies per workspace, and can be reverted or retired. Each accepted edit records the model it was validated against.
• Deterministic tests, your own model. About 530 tests run with scripted transports and no API calls. Providers are OpenAI- or Anthropic-compatible.

---

The self-improvement loop

Each stage is a CLI command and a deletable extension. Stages read and write files under .agent-harness/ in the workspace and never modify the core.

 okc mine ──▶ weakness playbook ──▶ okc propose ──▶ gate ──▶ okc edits ──▶ (apply) ──▶ revalidate on model change

Stage	Command	What it does
Mine	okc mine <session> / --all	A constrained, propose-only agent reads a finished session's trajectory digest and records weakness findings (a WeaknessSignature: terminal outcome, causal role, mechanism, editable surface).
Playbook	okc mine --rebuild-playbook	Clusters findings across sessions into an (id, description) playbook with dedup and occurrence counts. Deterministic, no LLM.
Propose	okc propose / --llm	Turns a weakness into a bounded harness edit. A rule engine covers config knobs; the optional LLM tier can also propose a prompt overlay.
Gate	okc gate (+ held-out)	Validates an edit differentially: a free deterministic held-in gate for config edits, and a real-provider held-out gate for prompt edits. Accept only if nothing regresses.
Apply	okc edits --accept <id> then --enable-apply	An accepted edit affects future runs only after you enable it for the workspace. --revert and --retire roll it back.
Revalidate	okc edits --revalidate	After a base-model change, edits validated under the old model are excluded, then re-checked under the new one: pass reactivates, fail retires.

The gates check for regressions, not for improvement. Whether an edit is worth keeping is a human decision.

---

Quickstart

# 1. Install (Python >=3.11; uv recommended)
git clone https://github.com/Niraya666/OkComputer && cd OkComputer
uv sync --extra test           # add --extra tui / --extra gateway / --extra mcp as needed

# 2. Configure a provider
cp .env.example .env           # then set DEEPSEEK_API_KEY=... (or your own endpoint)

# 3. Run a task
uv run okc --prompt "Fix the failing test in math_utils.py"

# ...or an interactive session
uv run okc chat                # terminal chat   (uv run okc tui for the full TUI)

# 4. Mine one of your own sessions
uv run okc mine default
uv run okc edits --list-applied

Without extras, okc and okc chat work out of the box. okc tui needs --extra tui.

---

Architecture

Frozen core (does not change):

• AgentLoop — the model/tool turn loop.
• Workspace — sandboxed file access and recovery.
• ToolRuntime — tool dispatch.

Deletable extensions (remove any, the core still runs):

• Context engineering — offloads large tool outputs to content-addressed refs, projects a read-only working set, and compacts deterministically first with LLM summarization optional. Recoverable and inspectable.
• Hooks, tasks, memory — lifecycle hooks, a sub-agent task manager, and proposal-first memory.
• Self-improvement — mining, weakness_playbook, harness_proposer / llm_proposer, regression_gate / holdout_gate, harness_edits_apply / harness_edits_revalidate.

Runtime state lives under .agent-harness/ in the workspace (git-ignored). Design details are in docs/agent-harness-design.md and docs/weakness-mining-design.md.

---

CLI reference

Command	Purpose
okc --prompt "..." / --interactive	Run a one-shot or interactive coding task.
okc chat / okc tui	Terminal chat / full TUI.
okc mine <session> --all --rebuild-playbook	Mine weaknesses and cluster them into the playbook.
okc propose --llm	Propose bounded harness edits (rule-based or LLM).
okc gate	Run the deterministic held-in regression gate.
okc edits --list-applied --accept --revert --retire --enable-apply --disable-apply --revalidate --audit	Manage the accepted-edit lifecycle.
okc trace	Inspect and explain a recorded trajectory.

---

Providers

Providers are configured through environment variables (see .env.example). A provider speaks one of two transport families, set by its kind: openai (Chat Completions) or anthropic (Messages). Two providers are built in — deepseek (openai) and kimi (anthropic) — and you can add your own.

Add your own provider. List the names in OKCOMPUTER_PROVIDERS, then give each a <NAME>_* block:

OKCOMPUTER_PROVIDERS=openai
OPENAI_KIND=openai                       # openai | anthropic (default: openai)
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o
OKCOMPUTER_DEFAULT_PROVIDER=openai       # use it by default

Then okc run --provider openai --prompt "...". A name declared here overrides a built-in of the same name.

Variable	Default	Purpose
OKCOMPUTER_PROVIDERS	(empty)	Comma-separated names of providers you define via <NAME>_* blocks.
<NAME>_KIND	openai	Transport family: openai or anthropic.
<NAME>_API_KEY / _BASE_URL / _MODEL	(empty)	Key, endpoint, and model id for that provider.
DEEPSEEK_API_KEY / _BASE_URL / _MODEL	https://api.deepseek.com, deepseek-chat	Built-in deepseek provider (OpenAI-compatible).
KIMI_CODING_API_KEY / _BASE_URL / _MODEL	https://api.kimi.com/coding/, kimi-for-coding	Built-in kimi provider (Anthropic-compatible).
OKCOMPUTER_DEFAULT_PROVIDER	deepseek	Provider used when none is passed.
OKCOMPUTER_PROVIDER_CHAIN	deepseek,kimi	Fallback order when a provider fails.

---

Development

uv run pytest -q --ignore=tests/integration --ignore=tests/e2e   # deterministic, no API (~530 tests)

The deterministic suite uses scripted transports and needs no keys. tests/e2e/ holds opt-in real-provider evals; they cost API budget and are gated behind OKCOMPUTER_RUN_LIVE_TESTS=1. Contribution conventions are in AGENTS.md.

---

License

Apache License 2.0. Copyright 2026 Niraya666.