How to Use Yardlet: The Beginner's Guide (Your Own CLI and Sign-In, Agent-to-Agent Handoffs, and the Change-Nothing Rule)

CodexFuse Team · 2026-11-03T08:59:24.469Z · 12 min read min read

Learn how to use Yardlet: install the free Mac workbench, connect your own CLI and sign-in, run agent-to-agent handoffs, and leave your agents' configs untouched.

If you code with AI every day, your work is probably scattered: a Codex session in one terminal tab, Claude Code in another, OpenCode somewhere else — each with its own context and its own window to lose. Learning how to use Yardlet solves that sprawl without asking you to abandon anything: it is a free, MIT-licensed Mac app that starts the coding-agent CLIs you already use, with the sign-in you already have, and gathers every session into one sidebar. This beginner guide walks you from install to your first agent-to-agent handoff on Yardlet v0.11.8, the current release from maker Jeongki Park.

This Yardlet tutorial assumes one thing: you already run at least one coding-agent CLI and you are comfortable in the terminal. If the whole idea of AI coding agents is still new, read an OpenClaw beginner guide first for the vocabulary — then come back, because Yardlet sits one layer above the agents themselves. Nothing here replaces your agents, and that is the point.

What Is Yardlet, Exactly?

Yardlet is a free, open-source macOS workbench that unifies the coding-agent CLIs you already use. Instead of replacing your agents, it starts the CLIs you already have — Codex, Claude Code, OpenCode and seven more — using your existing sign-ins, and shows every session in one sidebar. Sessions stay in each agent's own store, so a task started in Yardlet also opens in the agent's own app and vice versa. And Yardlet writes nothing into your agents' configurations, so stopping it or deleting it leaves every agent, sign-in and session exactly as it was.

Jeongki Park built Yardlet in Swift and launched it on Product Hunt on 2026-10-27 as a workbench for developers who juggle several agents at once. The framing he gives is deliberate: you pay only for the agents' own plans, because Yardlet itself costs nothing and asks for no account. There are no analytics, no server receiving your work — your data lives in ~/.yardlet and the macOS Keychain, and the daily update check just reads an appcast.xml while updates download from GitHub Releases through Sparkle, signed with Yardlet's release key and Apple-notarized.

What Do You Need Before You Install Yardlet?

Two things, and both are non-negotiable: an Apple Silicon Mac running macOS 15 or later, and at least one supported agent CLI already installed and signed in on that Mac. Yardlet never asks you for your agent credentials — it uses your own sign-in, which is why the CLI has to exist and work before Yardlet does.

The supported list at v0.11.8 names Codex, Claude Code, OpenCode, Cursor Agent, Antigravity CLI, Kimi Code, Grok Build, Hermes Agent, Muse Code and Pi, plus five more — and Yardlet needs only the CLI, never the agent's desktop app. One honest note before you continue: this is a young app with rough edges, which the maker says outright. Install it as a power tool you are trying out, not as finished infrastructure.

How Do You Install Yardlet?

Installation is one Homebrew command, or a plain download from the official site. The full beginner arc looks like this:

1. Open Terminal on your Mac and confirm your agent CLI works (for example, that Codex or Claude Code is signed in).
2. Install Yardlet with this command:

   brew install --cask zzunkie/tap/yardlet

3. Launch Yardlet from Applications or Spotlight — it scans for the agent CLIs you already have installed and signed in to.
4. Pick an existing session from the sidebar, or start a new one under the agent of your choice.
5. Type in the composer the way you would in the agent's own terminal — you are now running your agent through the workbench.
6. When an agent asks for permission, answer the approval card that appears; your approval carries your own words (more on this below).
7. If you prefer downloads over Homebrew, grab the app from yardlet.app and drag it to Applications — same result.

After install, updates arrive through Sparkle from GitHub Releases, so keeping current is automatic.

How Do You Run Your First Session in Yardlet?

Open the sidebar, pick a session or start a new one, and type. That is the whole mental model: the composer talks to your agent's real CLI, and the session list shows everything you have running across all your agents in one view.

Two details matter here. First, because sessions live in each agent's own store, you can bounce between Yardlet and the agent's own terminal freely — nothing is copied or moved, so a session started in Yardlet resumes in the agent's own app and the reverse works too. Second, the maker's key design choice is worktree isolation per agent: each agent works in its own isolated checkout, so parallel agents do not step on each other's changes. Try this as a first run: give one agent a small refactor task, watch its session appear in the sidebar next to your other agents, then open that same session in the agent's own terminal to prove to yourself that both are the same underlying session.

How Do Approval Cards Work in Yardlet?

When an agent wants to do something that needs your sign-off, an approval card appears in the workbench — and approvals passed along between agents carry your own words, verified verbatim against your messages.

That last part is the one worth paying attention to. In a setup where agents can hand work to each other, permissions could quietly mutate as they travel. Yardlet's rule is that an approval always traces back to exactly what you said, in your own wording, so a subagent never arrives with a permission you never granted. Answer the card once and the agent continues; decline it and nothing happens. It is a small piece of UI, but it is what makes the multi-agent setup above it trustworthy.

How Do Agent-to-Agent Handoffs Work in Yardlet?

One task can read another task, message it mid-run, or hand work to a different agent — even across agent brands. This is Yardlet's sharpest feature, and the one no single-agent workflow can copy.

The session tools behind it are named plainly: read_task, send_message_to_task, create_task, run_agent, wait_tasks and create_scheduled_task. Codex, Claude Code and ACP-based agents get these tools. A realistic arc: you are in a Claude Code session doing a feature, you spin up a one-off Codex subagent with run_agent to do a focused audit of the new code, you wait on its results, and you keep the main thread clean. The agents can also start tasks under themselves on any agent or account, and schedule tasks for later. Because each runs in its own isolated worktree, the handoff is a real handoff — not two agents fighting over the same files.

Five further agents are supported on top of these ten — the count grows as the app matures, so check the current list on the official site before assuming anything.

How Does Yardlet Handle Usage Limits?

Yardlet shows every account's session and weekly limits in one view, and starts new work on the account with the most room left.

If you hold multiple agent accounts, this is the feature that pays for itself. Yardlet displays each account's session and weekly limits — for example the five-hour Codex limits, the five-hour-plus-weekly Codex limits, and the seven-day Claude limits — with support for multiple accounts per provider. If you are new to how one of these agents meters you, a Claude Code beginner guide covers the plan side; Yardlet covers the routing side.

Here is the arithmetic that makes the feature click. Suppose you hold two Codex accounts and one Claude Code account. Codex account A is at 96 percent of its five-hour limit, account B at 40 percent, and the Claude account at 30 percent of its weekly window. Without Yardlet you would open a terminal, guess, and pile new work onto the nearly-spent account A. With Yardlet all three limit meters are in view, and the next task starts on the account with the most room left. Over a month of heavy use, that routing is the difference between hitting a wall mid-afternoon and never thinking about limits at all.

What Are Connectors in Yardlet?

You set up a connector once, and every agent can use it. That single setup is the whole idea.

Yardlet runs a built-in MCP server on your Mac that covers Gmail, Google Calendar and Google Drive, and one sign-in also connects GitHub, Slack and dozens of remote MCP services. Because connectors are set up once and offered to all agents, you never repeat the same OAuth dance inside each agent. The built-in browser completes the picture: agents drive a Chromium panel that can fill your saved sign-ins from a vault without ever seeing your passwords, with two-step codes and passkeys supported — and anything sensitive like a CAPTCHA or a payment step hands the tab back to you instead of the agent.

How Do You Review Diffs and Ship a PR in Yardlet?

Diffs of the last turn sit beside the conversation, and the PR tab follows checks and reviews through your own gh before merging.

The review surface is everything you would want next to a chat: the diff of the agent's latest turn, file restore and fork options, a terminal, and a files pane — all beside the conversation rather than in another app. When the work is ready, the PR card tracks checks and reviews through your own GitHub CLI and merges, and failed checks surface their logs with a "Fix CI" action so you can send the agent straight back to repair what broke. It is a short loop: prompt, diff, approve, merge.

Yardlet vs Paradev: What Is the Difference?

Paradev spawns parallel agents in isolated worktrees for a review-and-merge flow; Yardlet does not spawn or re-route agents at all — it unifies the ones you run yourself. That one sentence is the whole distinction, and it decides which tool fits you. If the parallel-spawning model sounds more like your workflow, read a Paradev parallel-agents guide next.

One disambiguation, because the name space is crowded: wrkbench.tech ("Workbench") is an agent process and bench-mode tool, and "y coding agent" is a self-modifying app — both are different products from Yardlet, not competitors.

How Does Yardlet Compare to OpenClaw?

OpenClaw is a personal agent you run; Yardlet is a workbench for the coding agents you run. They sit at different layers, so they do not compete.

If you have never run an agent CLI at all, start with OpenClaw — it teaches you the agent-shaped habits. Once you are running two or three CLIs and drowning in terminal tabs, Yardlet is the layer that puts them back in one place. Many developers will end up using both ideas: an agent they trust, and a workbench that keeps every agent honest.

What Are the Limits of Yardlet Right Now?

It is young, Mac-only and early — and the maker's own rough-edges warning means you should treat it as a power tool, not finished infrastructure.

Windows and Linux are officially "not yet," so this guide has nothing to offer those platforms today. An Android companion app is coming — QR pairing, end-to-end encrypted, letting you answer approvals and start tasks from your phone. Until then, keep a copy of anything important outside the app, expect the occasional rough edge, and watch the release notes: the supported-agent list and the feature set are moving fast.

Sources

Yardlet official site (yardlet.app) — product page with requirements, agent list, features and FAQ, current version 0.11.8; Yardlet on Product Hunt (producthunt.com/products/yardlet-2) — the maker's launch post by Jeongki Park, published 2026-10-27, updated 2026-11-02; Steemit/Steemhunt repost of the Product Hunt pitch (~2026-10-29); GptOnline.ai explainer "Yardlet: One Mac App For The Coding Agents You Already Use" (updated about five days before this writing); AIToolly AI news launch snippet (2026-10-29). All sources fetched on 2026-11-03.

Frequently Asked Questions

Is Yardlet free?

Yes. Yardlet is free and MIT-licensed with no account and no subscription. You pay only for your agents' own plans — your Claude, Codex or other subscriptions and API usage stay exactly what they are today.

Does Yardlet change my Claude Code or Codex setup?

No. The change-nothing rule is the product's core promise: Yardlet writes nothing into your agents' configurations. As the maker puts it, stop using it — or delete it — and each agent, its sign-in and its sessions are as they were.

Which agents does Yardlet support?

At v0.11.8 the named list is Codex, Claude Code, OpenCode, Cursor Agent, Antigravity CLI, Kimi Code, Grok Build, Hermes Agent, Muse Code and Pi, with five more supported on top. Codex, Claude Code and ACP-based agents get the agent-to-agent session tools.

Can agents really hand work to each other in Yardlet?

Yes. One task can read another, message it mid-run, start tasks under itself on any agent or account, or run a one-off subagent — for example a Codex subagent inside a Claude Code run — and wait on the results. Approval handoffs carry your own words, verified verbatim against your messages.

Does Yardlet work on Windows or Linux?

Not yet. Yardlet is a Mac app today — Apple Silicon, macOS 15 or later — and the maker's own page lists Windows and Linux as "not yet." Check the official site for the current status if you are on another platform.