# OpenClacky: a Ruby AI agent that sells token efficiency

> OpenClacky is an MIT-licensed CLI and web agent that claims roughly 0.8x Claude Code's token cost through a 16-tool design, near-100% cache hit rate and idle-time compression. Here is how it installs, what the cost claim rests on, and where it stops being the right tool.

**clacky-ai/openclacky** — The most Token-efficient open-source AI Agent

- Repository: https://github.com/clacky-ai/openclacky
- Website: https://www.openclacky.com/
- Stars: 1,201 · Forks: 111
- Language: Ruby
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/clacky-ai-openclacky

## What OpenClacky is for, and who pays the bill

OpenClacky describes itself as "The most Token-efficient open-source AI Agent." The audience is developers already running a coding agent against a metered API, where the per-task cost is a line item rather than a subscription. The project is Ruby, MIT licensed, and ships as a CLI plus a web UI on port 7070. It is BYOK: you point it at any OpenAI-compatible endpoint, so the model bill stays yours and the agent's job is to spend fewer tokens on the same task. The README positions it against Claude Code as the 1.0x baseline, with OpenClacky at about 0.8x, OpenClaw at about 1.5x and Hermes at about 3x. Those numbers come from internal common agent tasks and the README says full benchmark reports will be published on GitHub, which means the ratio is currently a claim, not a reproducible artifact. That distinction matters more than the number itself, because token cost is the entire pitch.

## The 16-tool bet and the invoke_skill meta-tool

The mechanism behind the cost claim is a deliberately small tool surface. OpenClacky exposes 16 core tools and pushes everything else into Skills reached through a single `invoke_skill` meta-tool. The README contrasts this with 40+ tools in Claude Code, 23 in OpenClaw and 52 in Hermes, and attributes the roughly 3x cost of Hermes to schema bloat of 3 to 4x. The reasoning is that every tool schema is resent with the request, so a large catalogue raises the floor cost of every turn regardless of whether those tools are used. Whether 16 is the right number is not something the README argues beyond the comparison table; it states that "Tool count is not the metric, task completion rate is" and then does not publish a completion-rate figure. That is the weakest joint in the design story. A smaller tool set can also mean more round trips when a task needs capability the core set lacks, and round trips cost tokens too.

## Cache hit rate, Insert-then-Compress and idle compression

Two other mechanisms carry the cost story. First, the system prompt is never mutated, so context compression can still reuse the prompt cache; the README calls this Insert-then-Compress and reports a measured cache hit rate "near 100%." Second, the agent compresses long context in the background during idle periods and pre-warms the cache, which the README says cuts cold-start first-token cost by more than 50%. Both are cache-economics arguments, and both depend on the provider honouring prompt caching on the endpoint you supply. If you route through a relay or an aggregate that does not implement cache markers, the near-100% figure does not transfer, and the cost advantage narrows accordingly. The README does not document how the agent behaves when caching is unavailable, which is the failure mode worth testing before you commit.

## Installing OpenClacky and running a first session

The README offers a desktop installer for macOS and Windows, a one-line shell script, a gem, and Docker. The gem path is the shortest if you already have Ruby. The requirement is Ruby >= 3.1.0, and the gemspec builds from repository source in the Dockerfile, so the published gem and the source tree are intended to match.

```bash
gem install openclacky
```

After the gem installs, the CLI entry point is `openclacky` with no arguments, which the README says starts an interactive agent in the current directory. Run it from the project you want the agent to work on, not from your home directory.

```bash
openclacky
```

For a browser-accessible session instead, the server subcommand starts the web UI on port 7070 by default.

```bash
openclacky server
```

Open http://localhost:7070 to reach it. The Docker route publishes images to GHCR on version tags and mounts a named volume at /root/.clacky. The README notes that `--network=host` is required on Linux so the container can reach Chrome's remote debugging port on the host, and that host networking is not supported on macOS or Windows, where browser automation may be limited.

```bash
docker run -d --name openclacky -p 7070:7070 \
  -e CLACKY_ACCESS_KEY="" \
  -v openclacky-data:/root/.clacky \
  ghcr.io/<owner>/openclacky:latest
```

The image ships a healthcheck that curls http://localhost:7070/health every 30 seconds, so `docker ps` will show a health column you can trust more than the process state alone.

## CLACKY_ACCESS_KEY is the one setting you should not leave empty

The environment variable table lists exactly one variable: `CLACKY_ACCESS_KEY`, described as protecting the web UI with an access key, with an empty value meaning public mode. The README adds that the variable must be present when binding 0.0.0.0. The Dockerfile's default command is `server --host 0.0.0.0`, so a container started from the image without that variable is running in public mode on a non-loopback interface. The README does not state what authentication, if any, applies to the CLI or to the agent's own tool calls, and it does not document a token format or a rotation procedure for the access key. Treat the key as network exposure control, not as a security boundary for the agent's file and shell access.

## Where OpenClacky is the wrong choice

Three cases stand out. First, if your endpoint does not support prompt caching, the two headline mechanisms lose most of their effect and you are paying for a 16-tool agent without the cache dividend. Second, if you need browser automation on macOS or Windows, the Docker path explicitly warns that host networking is unsupported there and browser automation may be limited. Third, if you need an auditable cost claim today, the README's comparison table is sourced to internal tasks and defers full benchmark reports to a future GitHub publication; there is no reproducible harness in what is documented. The repository does contain a benchmark/ directory and a clacky-legacy/ directory, but the README does not explain what either contains, so their presence is not evidence of a published methodology. A team that must justify tooling spend to a finance reviewer will want to run its own A/B before standardising.

## How it differs from Claude Code and from a plain OpenAI-compatible client

Claude Code is closed source and Anthropic-only, and the README uses it as the 1.0x cost baseline while conceding it is a "World-class harness." The difference OpenClacky offers is not capability parity by assertion but the combination of MIT licensing, BYOK against any OpenAI-compatible model, and a Skill system the README says is self-evolving: after each run the agent updates the Skill from execution context and results. Claude Code's comparison row marks Skill self-evolution as absent. A plain OpenAI-compatible client differs in the opposite direction: it gives you the model with no harness, so no cache-marker management, no compression, no tool routing. OpenClacky is the middle position, and its cost advantage is entirely a function of how well that harness is implemented. The README also claims compatibility with Claude Skills and Markdown Packs, which lowers migration cost if you already maintain Skills elsewhere.

## Maintenance, releases and the MIT licence

The last push was on 2026-09-10, the same day as the v1.5.14 release, following v1.5.13 on 2026-09-03 and v1.5.12 on 2026-08-27. That is a weekly release cadence across the three most recent tags. The repository is not archived. The Dockerfile pins ruby:3.4.4-slim in both build stages, and the repository carries Gemfile.lock plus lockfiles for ruby-2.6, ruby-3.3 and ruby-4.0, which suggests more than one supported Ruby line is being tested. The gemspec requires Ruby >= 3.1.0. The licence is MIT, which permits commercial use and modification; the README additionally describes packaging Skills for sale with encrypted distribution and license management, but that is a feature of the agent, not a change to the project's own licence. Nothing here is legal advice, and the LICENSE.txt in the repository root is the document that governs.

## Conclusion

Adopt OpenClacky if you want an MIT-licensed, BYOK agent that runs as a Ruby gem or a Docker container and you are willing to re-run your own token accounting before trusting the 0.8x figure. Skip it if you need browser automation on macOS or Windows over Docker, where the README warns that host networking is unsupported, or if you want published benchmark reports rather than a summary table. Verify three things first: the exact cost ratio on your workload, whether CLACKY_ACCESS_KEY is set before you bind 0.0.0.0, and that port 7070 is the one your firewall allows.

## FAQ

### What is OpenClacky?

OpenClacky is an MIT-licensed AI agent written in Ruby that runs as an interactive CLI or a web UI on port 7070. It describes itself as the most token-efficient open-source AI agent and works with any OpenAI-compatible model via BYOK.

### How do I install OpenClacky?

The README lists a desktop installer for macOS and Windows, a one-line shell or PowerShell script, `gem install openclacky` for Ruby >= 3.1.0, and a Docker image published to GHCR on version tags. The gem path is the shortest if Ruby is already present.

### Does OpenClacky work with models other than Claude?

Yes. The README states it is BYOK and works with any OpenAI-compatible API, including official endpoints, aggregate routing and compatible relays, and suggests auto-routing subtasks to a cheaper model such as DeepSeek.

## Sources

- [clacky-ai/openclacky on GitHub](https://github.com/clacky-ai/openclacky)
- [License: MIT](https://github.com/clacky-ai/openclacky/blob/main/LICENSE)
- [Project website](https://www.openclacky.com/)
- [README](https://github.com/clacky-ai/openclacky/blob/main/README.md)
- [Releases](https://github.com/clacky-ai/openclacky/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/clacky-ai-openclacky