Script a multi-turn Claude Code session that sends prompts, auto-approves safe tool calls, and collects outputs without a human watching the terminal.
Use the npx one-liner to route a single Claude Code session through the harness and answer plan-approval prompts from a script instead of the keyboard.
Build a CI pipeline that runs Claude Code on a pull request, auto-approves read-only actions, and rejects destructive ones based on a policy you define.
Listen to agent events in a Node.js script to log every tool the AI runs and build an audit trail of what happened during an automated coding session.
Works on macOS, Linux, and recent Windows, no persistent system changes, run via npx with no install required for simple use cases.
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.
← wezzard on gitmyhub — every repo by this author, as a profile.
Verify against the repo before relying on details.