toll-free-harness

toll-free-harness is a TypeScript library that lets you write automated scripts to control a local AI coding assistant as though a human were sitting at the keyboard. It is primarily aimed at Claude Code, a terminal-based AI tool that normally requires a person to type prompts, answer questions, and approve or reject plans during a session. This library intercepts those interactive moments and lets code handle them instead.

The way it works is by running the coding agent inside a PTY, which is the type of virtual terminal that normally connects a program to a real keyboard and screen. The library watches what the agent outputs and, when it pauses waiting for user input, such as when it asks a question or presents a plan for review, injects the correct keystrokes on behalf of your script. Events from the agent, like which tool it is about to run or when it finishes, are exposed as typed callbacks you can listen to in your code.

There are three things you can tell the library to do on behalf of a user: send a text prompt (with optional image attachments), select an answer when the agent asks a multiple-choice question, and approve or reject a plan with optional feedback. Everything else is read-only observation. The library translates your decisions into the keystrokes the UI expects, so you never write raw terminal escape sequences yourself.

You can use it from the command line without installing anything, by replacing the usual invocation of the coding agent with an npx command that routes the session through the harness. Or you can install it as a Node.js library and build more sophisticated automation with event handlers, timeouts for specific events, and multi-turn conversations.

Under the hood, each session creates a temporary plugin directory, starts a small HTTP server over a Unix socket for inter-process communication, spawns the agent with that plugin loaded, and cleans everything up when the session ends. No persistent changes are made to the user's system configuration. The library works on macOS, Linux, and recent versions of Windows. The license is Apache-2.0.