coding-worker

A shared local MCP worker for coding tasks. Use it from Codex, Claude Code, or another MCP client to implement changes, investigate code, diagnose bugs, run checks, and review diffs. Your agent keeps control of scope and acceptance.

Operation	Purpose
worker_implement / worker_continue	Implement a change and address feedback
worker_explore	Answer code questions with source citations
worker_diagnose	Investigate a bug and propose a minimal fix
worker_verify	Run an explicit check without a model
worker_review	Review worktree changes against HEAD

Runs return an ID promptly. Wait for completion with worker_wait, retrieve evidence with worker_result, and record external acceptance with worker_record_review. Investigation results are compact, cite sources, and detect repository changes.

Install

Requires Go 1.26+, a C compiler, Git, and the selected backend on PATH for model-backed operations: Pi 0.78.1 (default) or OpenCode. Implementation supports Linux/macOS; exploration, diagnosis, verification and review require Linux with Bubblewrap and working user namespaces. Windows users need WSL.

git clone https://github.com/vojtabiberle/coding-worker.git
cd coding-worker
make install
export PATH="$HOME/.local/bin:$PATH"

npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.78.1
pi --list-models
mkdir -p ~/.config/coding-worker
cp examples/config.toml ~/.config/coding-worker/config.toml

Edit the copied configuration to select a model available from your provider; configure Pi authentication as described in Pi setup. Profiles without engine use Pi. For OpenCode, set engine = "opencode" and an agent, then run opencode auth login. Run workerctl doctor inside a Git repository with an initial commit to check setup.

make install installs both binaries and the Codex skill. For another agent:

make install-skill SKILLS_DIR="$HOME/.claude/skills"
# Or any directory your agent scans:
make install-skill SKILLS_DIR="$HOME/.agents/skills"

The skill is optional; it guides operation selection and result handling. See installation options and profiles for custom paths, CODEX_HOME, binary-only installation and configuration precedence.

Connect your agent

Use an absolute binary path. For Codex, add to ~/.codex/config.toml:

[mcp_servers.coding-worker]
command = "/home/YOU/.local/bin/coding-worker"
tool_timeout_sec = 1800
env = { CODING_WORKER_WAIT_SECONDS = "300" }

For Claude Code:

claude mcp add --transport stdio --scope user coding-worker -- /home/YOU/.local/bin/coding-worker

All clients must share the same data directory (default ~/.local/share/coding-worker). Repositories can live anywhere; they do not need a common parent. Reconnect MCP clients after updating the server. See MCP setup for additional configuration.

Use it

Ask your connected agent, for example: “Explore the input handling path, identify possible latency sources, and change nothing.” The skill helps select the appropriate operation.

Direct MCP calls follow this sequence:

worker_explore {"cwd":"/absolute/repo","question":"Where is input polling scheduled?"}
→ run_id
worker_wait {"run_id":"RUN_ID","timeout_seconds":300}
→ done, iteration, state and phase
worker_result {"run_id":"RUN_ID","max_output_bytes":4096}
→ report once the run finishes

timeout_seconds accepts up to 600; use the longest value below your client's tool timeout, since every repeated wait costs your agent a model turn. If timed_out:true, repeat worker_wait with its returned iteration; retrieve the report when done:true. Use worker_status for an immediate progress snapshot.

Explore, diagnose and review accept follow-up questions with the same run_id. Their results default to 800 UTF-8 JSON bytes; request details or a larger budget when needed. Implementation results are a compact summary by default (detail:true for the full iteration), and diff:true pages the worktree diff against HEAD, untracked files included, so a reviewing agent loads only what it reads.

For CLI implementation:

workerctl run "Fix the timeout handling and run relevant tests"

One run holds the worktree lock at a time. Implementation writes code and requires independent review; it does not commit or push. Investigation tools use a read-only filesystem sandbox, while check/reproduction commands have private temporary storage and no network. Accepted jobs continue after request cancellation, but stopping their MCP server cancels them.

Documentation

• Setup and configuration — installation, profiles, client connections.
• MCP tool reference — inputs, evidence, pagination, diagnosis and review rules.
• Operations and troubleshooting — CLI, run lifecycle, locking, storage and errors.
• Profile experiments — compare model profiles using recorded outcomes.
• Development and contributing — architecture, tests and PR requirements.
• Roadmap — planned work.

Licensed under Apache License 2.0.