code-worker

Narrow-region LLM code worker. Given a TOML task spec, extract a region from a file, ship it to a hosted model (via OpenRouter), splice the model's reply back into the file. Or — in create mode — skip the extract step and write the model's reply to a new file.

No unified diffs are ever produced by the LLM. Apply/splice is pure code, so failures are deterministic.

Why

Hosted frontier models can reliably rewrite small regions of source code when given a clear instruction and the region itself. They cannot reliably produce unified diffs against files larger than ~100 LOC — line arithmetic hallucinates, and git apply rejects. This tool sidesteps the diff problem by asking the model for plain fenced code and splicing it back by exact substring match.

See docs/hosted-coding-agent-design.md for the full design.

Install

uv tool install git+https://github.com/usedarwin/code-worker
# or
pip install git+https://github.com/usedarwin/code-worker

Use

export OPENROUTER_API_KEY=sk-or-v1-...

# Dry-run (default)
code-worker path/to/task.toml

# Write
code-worker path/to/task.toml --apply

# Pick a different model
code-worker path/to/task.toml --model qwen/qwen3.5-35b-a3b

The tool operates on the current working directory. All file paths in the spec are resolved relative to it; any attempt to escape (absolute paths, ..) is rejected before any write.

Task spec

# Edit an existing file (narrow-region mode)
[[edits]]
file = "path/to/file.tsx"
anchor = 'describe.skip("My suite"'   # literal substring; must be unique
before = 10                            # context lines above anchor
after = 15                             # context lines below anchor
language = "tsx"                       # fenced-block language hint
instructions = """
    Replace describe.skip with describe.
    In beforeEach, before jest.useFakeTimers(), install ...
"""

# Create a new file
[[edits]]
file = "apps/web/app/admin/layout.tsx"
create = true                          # opt in to create mode
overwrite = false                      # optional; default false
language = "tsx"
instructions = """
    Create a Next.js App Router layout that ...
"""

# Optional: verification commands printed after the run
[verify]
commands = [
  "npm run type-check",
  "npm test apps/web",
]

See examples/ for working task specs.

Secrets

The tool reads OPENROUTER_API_KEY from the environment. How you populate it is your call:

# 1Password
export OPENROUTER_API_KEY="$(op read 'op://dev/openrouter/api-key')"

# AWS Secrets Manager
export OPENROUTER_API_KEY="$(aws secretsmanager get-secret-value \
    --secret-id your/prefix/openrouter-api-key \
    --query SecretString --output text)"

# Plain .env
source .env && code-worker task.toml

Design principles

• Snippet-splice, not diff. Model produces plain code in a fenced block. Apply is pure Python string replacement with drift detection.
• Deterministic failure modes. Anchor not found, region drifted, malformed API response — each raises EditError with a specific message.
• Path safety. File paths in specs cannot escape the working directory.
• Strict spec parsing. Boolean fields must be real TOML booleans, not quoted strings. Better to fail loud on a typo than silently misinterpret.

Related

This tool is used by darwin-platform (via its own task specs) and will be the worker layer for darwin-tech-ai/finch-style orchestration in the future.