WeZZard

WeZZard / toll-free-harness

Public

Interactive PTY harness for local coding agents.

16
2
69% credibility
Found May 22, 2026 at 16 stars -- GitGems finds repos before they trend. Get early access to the next one.
Sign Up Free
AI Analysis
TypeScript
AI Summary

Toll-free-harness is an open-source testing framework that lets developers run Claude Code (an AI coding assistant) in automated, reproducible sessions. It creates a simulated terminal environment where the AI can work on your projects while you define how to respond to its questions, approve or reject its plans, and observe everything it does. The framework supports recording sessions for later replay, works across Mac, Linux, and Windows, and requires users to run their own Claude Code accounts with their own credentials.

How It Works

1
💡 You want to automate testing with an AI coding assistant

You've been using Claude Code to help with your projects, and now you want to run automated tests on your code without sitting at the computer.

2
🔧 You find a tool that lets AI assistants work hands-free

Toll-free-harness is a framework that runs coding assistants in a simulated environment, automatically answering questions and watching what the AI does.

3
🎯 You set up how the AI should respond to questions

You tell the harness which option to pick when the AI asks you to choose something, and whether to approve or reject the AI's plans.

4
▶️ You launch the AI into your project

The harness starts the AI in a virtual terminal, pointing it at your codebase with your instructions.

5
You can watch everything the AI does, or let it run on its own
📊
Watch in real-time

You see every command the AI runs and every file it touches, useful for understanding the AI's behavior.

🎬
Record and replay

Save the entire session to replay later, great for creating reproducible test scenarios.

6
✅ The AI completes its task automatically

The AI goes through your project, fixes bugs, writes tests, or explains errors—all without you touching the keyboard.

🎉 You get automated, repeatable AI-powered results

Your tests run the same way every time, you can replay sessions to debug issues, and you understand exactly what the AI did.

Sign up to see the full architecture

5 more

Sign Up Free

Star Growth

See how this repo grew from 16 to 16 stars Sign Up Free
Repurpose This Repo

Repurpose is a Pro feature

Generate ready-to-use prompts for X threads, LinkedIn posts, blog posts, YouTube scripts, and more -- with full repo context baked in.

Unlock Repurpose
AI-Generated Review

What is toll-free-harness?

toll-free-harness is a TypeScript library that lets you script interactions with Claude Code by running it inside a pseudo-terminal and simulating real user input. Instead of using `claude -p` for headless prompts, you get a full session object where you can answer questions, approve plans, and watch what the agent does. It works by injecting a plugin into Claude Code that bridges events back to your code via a Unix socket, letting you respond with typed decisions rather than raw keystrokes. The library exposes both a CLI drop-in for `claude -p` workflows and a programmatic API for building test harnesses or automation around the agent.

Why is it gaining traction?

The killer feature is that it translates your intent into the correct keystrokes automatically. When Claude asks a multiple-choice question, you return `{ selectedIndex: 0 }` instead of figuring out arrow keys and enter. When it shows a plan, you return `{ decision: "approve" }` instead of typing "y". This makes testing agent scripts deterministic and scriptable in ways that brittle screen-scraping approaches cannot match. The guardrail system lets you wait for specific tool calls with timeouts, which is essential for writing tests that don't flake. The project also includes session recording and playback, so you can capture a real interaction and replay it later with different responses.

Who should use this?

Developers building test suites for Claude Code integrations will find the most value here. If you've been manually piping prompts to `claude -p` and hoping the output format stays stable, this gives you a proper abstraction. Teams running CI pipelines against agent scripts can use the guardrail to assert that specific tools get called in specific order. Researchers exploring agent behavior might appreciate the recording feature for capturing and replaying sessions. This is not for casual users wanting a better CLI; it's for people building infrastructure around coding agents.

Verdict

toll-free-harness solves a real problem for a narrow audience, but with only 16 stars and a credibility score of 0.7%, the project is early and unproven. The API surface is clean and the documentation is decent for a hobby project, but test coverage and stability are unknowns. If you're building agent tooling in production, wait for a more mature release or budget time to contribute fixes. If you're experimenting with agent testing and want a cleaner abstraction than raw PTY manipulation, this is worth a weekend experiment.

Sign up to read the full AI review Sign Up Free

Similar repos coming soon.