Giving Agent Framework workflows a local-machine executor (open-source file-based bridge)

[abhinaykrupa]

Sharing something I built that fills a gap I kept hitting with Agent Framework: an agent can reason about my machine, but it can't touch it. When the process runs in a container, a cloud sandbox, or anywhere that isn't my laptop, "run the test suite and tell me what broke" is out of reach — the filesystem, the toolchain, the local Docker daemon, and the git credentials all live somewhere else.

cowork-to-code-bridge (MIT) is a small async bridge that closes that gap. A sandboxed agent queues a task; a daemon on my own Mac/Linux box executes it and returns the result.

How it works

Deliberately boring: no network calls from the agent side, no inbound ports, no daemon listening on the internet. Everything moves through a shared directory holding queue/, results/, and to_cowork/. Both sides only ever read and write files, which is what makes it survive reboots and sandbox timeouts.

from cowork_to_code_bridge import call_remote, queue_task, poll_task_result

# blocking — you want the answer now
call_remote("scripts/git_status.sh", args=["~/src/myrepo"])

# non-blocking — long work, short sandbox timeout
job = queue_task("scripts/run_claude.sh",
                 args=["run the test suite and fix what breaks"],
                 timeout=1800,
                 idempotency_key="ci-fix-2026-07-25")
poll_task_result(job["task_id"])

Where it fits an Agent Framework workflow

The natural shape is a local-execution executor in a workflow graph. Upstream executors plan and reason in the cloud; one downstream executor hands the side-effecting step to the real machine and yields the result back into the graph. Because poll_task_result is idempotent and non-blocking, it maps cleanly onto a long-running workflow that checkpoints — you don't hold a thread open for a 20-minute build.

The headline script is run_claude.sh, which hands the task to a full Claude Code agent on the machine rather than just running a fixed command, so the local side can plan and iterate too. There are ~22 other bundled scripts (health, disk, ports, Docker, git, package state) for the smaller cases.

The parts I'd actually flag

Handing an agent a shell on your own machine deserves guardrails, so per-task there's:

• max_budget_usd — a spend ceiling, so a runaway loop can't drain credits
• permission_scope — plan / readonly / edit / full
• plan="…" — requires a human to approve before anything runs
• idempotency_key — retries don't double-fire state-changing work

It also streams progress back (call_remote_streaming) so a long build isn't a silent wait, and supports a bidirectional mode where the machine-side agent can ask the calling agent a question mid-task.

Status

Working and tested (330+ tests), MIT, macOS/Linux/WSL2. I'm the author — genuinely after feedback rather than stars. The thing I'm least sure about is the right integration seam for Agent Framework specifically: a plain executor is the obvious answer, but if there's a more idiomatic extension point for "this step must run on host hardware," I'd rather build to that than bolt on my own.

Repo: https://github.com/abhinaykrupa/cowork-to-code-bridge