DEV Community: zhayujie

Designing an agent-friendly CLI

zhayujie — Fri, 17 Jul 2026 07:12:32 +0000

As agents mature, more and more products will need to serve two kinds of users at once: humans and agents. A CLI is one of the easier forms for an agent to call, and in the future many products may want to ship their own CLI to expose their core capabilities to agents. This post walks through the design of a CLI we recently open-sourced for a platform product, covering six areas: language choice, login and authorization, command and flag design, skills, distribution, and security.

Why a CLI

An agent can reach an external capability in roughly three ways: calling an API directly, going through MCP, or running a command in a terminal. All three are ultimately wrappers over the same remote interfaces, but a CLI has two advantages for agents. First, almost every general-purpose agent already ships with a Bash tool (Codex, Claude Code, CowAgent, OpenClaw, and so on), so there is no MCP server for the provider to stand up. Second, the CLI packs auth, parameter assembly, pagination, and error handling into the command itself: the agent does not have to construct HTTP requests, and it does not need the full API reference in context — a short command description is enough to decide what to run, which saves tokens and reduces mistakes.

What changes is the shape of the user. A CLI used to be driven by a developer sitting at a terminal; now there is also an agent running a "read output, decide, run the next command" loop. The two have quite different needs, and serving both well becomes a design problem in itself. The rest of this post uses a real CLI as an example and walks through the key decisions along the way. The overall picture:

1. Language

A few hard requirements shaped the language choice:

Single file, no runtime dependency: an agent's environment is unpredictable — a local machine, a Docker container, a remote Linux box — and you cannot assume the right Node or Python version is installed. Ideally you download one binary and it just runs.
Easy cross-compilation: it needs to cover macOS / Linux / Windows × amd64 / arm64 from a single codebase.
Fast startup: an agent calls commands frequently, so a compiled language is preferable to an interpreter that pays cold-start cost each time.

A quick comparison of the candidates:

Node / TypeScript: great ecosystem and fast to write, but it depends on a Node runtime on the target machine, and bundling to a single file produces large artifacts.
Python: same runtime and version headaches, and distribution is a real pain.
Rust: single binary, good performance, meets every requirement, but development and compile speed are slower.
Go: a single static binary, zero dependencies with CGO_ENABLED=0, solid cross-compilation, millisecond startup, and reasonable development speed.

We ended up choosing Go, with Cobra as the CLI framework for command parsing and routing. Because the artifact is a plain binary, a single GoReleaser config can produce the npm package, Homebrew cask, and GitHub release together. There is no universal answer here — it depends on your team's stack — but if agents are the primary users, a language that compiles to a zero-dependency single binary should come first. How smoothly you can distribute it directly decides whether an agent can install it on its own.

2. Login and Authorization

The simplest way to authorize a CLI is to have the user paste an API key. The problems are obvious: an API key is usually long-lived, carries full permissions, and sits in plaintext on disk. If it leaks, everything is exposed, and there is no way to scope it per operation. For a CLI that agents call automatically and that manages real resources, that "one key opens every door" model is too risky.

So we use the OAuth 2.0 Device Authorization Grant (device flow). The user logs in and grants scopes in a browser, and the CLI receives a short-lived, refreshable, scope-limited access token that the server can revoke at any time. The flow has three steps:

There is another common OAuth variant where the CLI starts a temporary local HTTP server to catch the browser redirect (tools like gh and gcloud do this). That does not work well for agents, which often run on a server with no browser, no display, and no open ports. The device flow lets the authorization happen in a browser on any machine, while the CLI side only kicks it off and polls. Two parts of this are worth calling out.

2.1 Two-phase polling

When a human logs in, the CLI can open the browser and block on polling until the user is done. But an agent runs a "run a command, read the result, decide the next step" loop. If a single tool call both prints the login link and then blocks on polling, the link never makes it back to the user through the model, and the whole session stalls.

So the agent login is split into two phases. The first phase returns immediately. The JSON it returns includes the verification URL, the device code, and a next_action field that tells the agent exactly what to run next:

linkai auth login --no-wait --json

The second phase polls, blocking for at most a bounded number of seconds before returning. If the user has not finished, the agent simply runs the same command again on its next tool call:

linkai auth login --device-code <code> --wait 60 --json

The --wait flag distinguishes the two users: leaving it off (blocking until the device code expires) gives the interactive human flow; passing --wait switches to the bounded polling path an agent needs.

2.2 The authorization page

The authorization page is where the user actually interacts and makes a decision, so it needs to make three things clear:

which account / device / CLI is requesting authorization
which permissions are being requested, listing the scopes per module so the user can see exactly what the CLI is being granted
a note that they can return to the terminal once done, since the terminal is still polling

3. Commands and Flags

For the same command, a developer wants a clean table and streaming output, while an agent wants a single parseable, structured response. A few details follow from that.

3.1 JSON output

--json is a global flag that makes any command emit structured JSON. With it, the agent's skill only has to say "always pass --json," and every command returns output the agent can parse reliably.

3.2 Streaming vs. non-streaming

For commands that talk to a model, humans like the streaming (SSE) typewriter effect. But when an agent calls the command through Bash, the output gets piped, and streaming breaks the reply into fragments that are hard to parse — the agent wants the full reply in one piece.

Rather than forcing the user to remember --stream / --no-stream, the default follows the environment: streaming in a terminal, non-streaming when the output is piped or redirected (the typical agent case), and always non-streaming with --json. An explicit flag overrides all of this.

3.3 Dry run for writes

Destructive or mutating commands support --dry-run, which prints the request that would be sent instead of actually sending it. The agent can check the parameters before it commits to the operation, which also adds a layer of safety.

3.4 Output separation and exit codes

Results go to stdout; everything procedural goes to stderr. Progress notes, update notices, and confirmation prompts are all things that, if mixed into stdout, would break the agent's JSON parsing. With them on stderr, the agent only has to read stdout.

Exit codes are also structured so the agent can decide whether to retry or stop: 0 success, 1 generic error, 2 bad arguments, 3 auth/permission, 4 network. On a permission error (exit 3), the message includes the command to fix it (for example linkai auth login --scope "..."), so the agent re-triggers authorization instead of retrying blindly.

4. Skill Design

The CLI wraps a set of interfaces in commands; the next problem is helping the agent understand how to call them correctly. Probing with --help over and over is too costly, so the CLI ships a companion skill — a manual written for the agent.

The skill structure is kept as flat as possible: a single SKILL.md as the entry point, with per-module command details under a references/ directory.

skills/linkai-cli/
├── SKILL.md          # entry point: global notes + module overview + decision flow
└── references/       # details per module: auth / install / admin ...

Installed into an agent, this is a single directory. The idea is to have the agent read the main skill first and only dig into references/ when it needs module-level detail. Some CLIs install every sub-module as its own separate skill, which is not ideal: the agent loses a global view of the CLI, and a large number of sub-skills inflates its context.

The skill is embedded into the binary with go:embed and locked to the CLI version, so the docs never drift from what the binary actually supports. A skill install command handles installation in one step.

One more detail: the main SKILL.md includes a short install section. When an agent gets the skill first — for example by downloading it directly — it can still follow those instructions to install the CLI binary.

5. Distribution and Updates

Distribution matters a lot for usability, and there are two things to distribute: the CLI binary and the agent skill. The goal is that one sentence to an agent is enough for it to get set up. It helps to support several channels so developers and agents on any platform can find one that works:

Method	Command
npm	`npm i -g linkai-cli`
install script	`curl -fsSL .../install.sh`
Homebrew	`brew install .../linkai`
Go	`go install .../linkai-cli@latest`
GitHub Release	download the binary

On a machine with Node, npm is the most convenient path: it hides the OS and CPU differences, picks the right binary, and puts it on PATH. The install script is a better fit for dependency-free environments; besides downloading the CLI, it also drops the skill into the skill directories of common agents (Codex, Claude Code, Cursor, OpenClaw, CowAgent, and others).

To let an agent set everything up from one sentence, a clear install guide (install.md) matters too. It writes out the full from-scratch steps, so the user can just hand the agent a line like:

Read https://cdn.link-ai.tech/cli/install.md and follow it to install the CLI and skill, then start using it.

Updates are an extension of distribution, done in two layers:

Passive notice: on startup the CLI fetches and caches the latest version in the background, and prints a one-line notice to stderr on exit (mainly for the human at the terminal, so it never pollutes the stdout an agent parses).
Active update: update detects how the CLI was originally installed, calls the matching package manager to upgrade, and syncs the skill afterward.

6. Security

Least privilege. Scopes use a resource:action format (for example app:read, db:write). By default only read and content-generation scopes are granted; mutating and destructive operations must be requested explicitly. Each command declares the scope it needs and it is checked centrally, so even if an agent slips, it cannot go beyond what the user granted.
Token storage. On macOS the credential goes into the system keychain; on other platforms it is stored in a file (mode 0600). The token is an opaque, server-revocable token rather than a self-decoding JWT, and logout revokes it on the server.
Device binding. Every request carries a device ID, and the server binds the token to that device, which limits abuse if a token leaks.
Dangerous-character filtering. Content an agent handles may come from untrusted sources (web pages, external input) and can carry invisible attack characters — Bidi overrides, zero-width characters, ANSI escapes — that alter command meaning or spoof the terminal. The CLI rejects these on input and strips them on output.

Wrapping Up

The way you design a CLI is quite different from designing a GUI product, and even among CLIs, one for agents differs from one for developers. To summarize the main ideas:

Language: prefer a compiled language that produces a single binary.
Login: use the device flow so authorization happens in a browser, and support phased login for agents.
Commands and flags: give humans a clean view and agents structured data, tolerate extra flags, allow dry runs, and return next-step hints on error.
Skill: as a manual for the agent, keep it a single directory with a flat structure to lower both the learning and context cost.
Distribution: support multiple channels and add an install guide an agent can follow on its own.
Security: beyond login, cover least privilege, credential protection, device binding, and filtering of untrusted content.

None of this is specific to CLIs. Structured output, tolerant error handling, a companion skill, smooth distribution, and least privilege apply just as well to APIs, SDKs, and other products that serve both humans and agents.

Open-source project referenced in this post: github.com/MinimalFuture/linkai-cli

A Five-Layer Self-Evolution Mechanism for AI Agents

zhayujie — Wed, 17 Jun 2026 11:50:24 +0000

Self-evolution is a core module of the Agent Harness. With it, an Agent can keep improving across long-running tasks: refining its own skills, recording user feedback and preferences, and reviewing its own work to keep getting better. This post walks through the architecture and engineering behind a five-layer self-evolution mechanism, drawn from a real open-source agent implementation.

Overall Design

Self-evolution is not just about making an Agent remember things. It is about letting the Agent improve and repair itself through continuous feedback. The mechanism divides into five layers by depth: recording information, retaining information, taking action, consolidating, and self-rewriting. Each depth differs in what it improves, when it triggers, and how far its effects reach.

Two questions drive the implementation: when evolution is triggered and what gets improved. The full mechanism is built from five layers, each mapping to a different depth of evolution: basic memory and knowledge maintenance, smart context summarization, post-session review, dream-based memory consolidation, and source-code self-update. The overall architecture:

Layer	What it improves	When it triggers	Depth
Basic memory & knowledge maintenance	Memory / knowledge / prompts	During each conversation	Record
Smart context summarization	Memory	When context overflows	Retain
Post-session review	Skills / memory / prompts / tasks	After a session goes idle	Act
Dream-based memory consolidation	Long-term memory	Daily, on schedule	Consolidate
Source-code self-update	Code	Passive / active trigger	Self-rewrite

1. Basic Memory and Knowledge Maintenance

The most basic layer of self-evolution happens inside every conversation. Guided by the model's tool-use decisions and the system prompt, the Agent judges whether a conversation contains anything worth keeping, then uses built-in tools to write preferences, decisions, facts, and lessons into long-term memory, reusable knowledge into the knowledge base, and anything about its own persona or operating rules into prompt files.

These three kinds of information differ in target and timing:

Memory: persisted as files in the workspace, split into core memory and daily memory. Core memory (MEMORY.md) holds long-lived facts such as user preferences and key decisions, and is injected into the system prompt of every conversation, so it must stay concise. Daily memory (memory/YYYY-MM-DD.md) records key events and conversation summaries by day, and is loaded only when the Agent uses its memory-retrieval tool.
Knowledge base: stored as Markdown source files in the workspace with vectorized data in the database, organized by topic and cross-linked into a knowledge graph. When a conversation involves research or learning, the Agent proactively files the organized knowledge here.
Prompts: persona (AGENT.md), rules (RULE.md), and user info (USER.md) can also be edited mid-conversation. All of them load into the system prompt, letting the Agent adjust its own settings based on feedback and fit the user's habits.

Example above: in a single message the user states a preference and asks the Agent to research a new concept. While answering, the Agent writes the preference into memory and files the organized material into the knowledge base.

2. Smart Context Summarization

The previous layer is about how to remember key information. This one is about how the Agent avoids losing information as it evolves. Context is short-term memory, with configurable limits on both turn count and token length. When those limits are exceeded, the system does not simply drop old messages. It distills and summarizes the important parts and writes them into daily memory. The compression runs in four steps:

Truncate oversized tool results: the first and cheapest step. When a single tool result in a past turn (say, a search that returned tens of thousands of lines) exceeds a threshold, only the head and tail are kept along with a short elision note; the current in-progress turn is left untouched. This step is pure string handling with no model call, and it often absorbs most of the growth.
Trim by complete turns: when the turn limit is exceeded, the system trims the oldest half using a full conversation turn as the smallest unit, rather than deleting messages one by one. This keeps each tool call's input and result paired, so the model is never left with a tool call that has no matching result. The trimmed content is not discarded: an LLM organizes, distills, and summarizes it, then writes it into the day's daily memory for persistence and injects the summary back at the start of the retained messages, so the model can still pick up the thread after the raw detail is gone.
Compress by token budget: if the token limit is still exceeded after trimming turns, a finer pass runs. When there are only a few turns, each turn is compressed to text (keeping the user's first question and the Agent's final reply, stripping the tool-call chain in between); when there are many turns, the earlier half is trimmed and summarized.
Overflow fallback: if the model API itself throws a context-overflow error, the system first summarizes the current conversation into memory, then applies a more aggressive truncation. This is the last line of defense.

3. Post-Session Review

Post-session review is the most active and most central part of self-evolution. When a session wraps up and goes idle, the Agent revisits the whole conversation: fixing problems that surfaced, turning reusable workflows into skills, finishing tasks that were left undone.

3.1 What It Improves

Here is what a review mainly does:

Improve and create skills: when a Skill exposed a problem in use (wrong configuration, a missing step, stale content), the Agent edits the skill file directly so it does not recur; when a reusable workflow emerged in the conversation, the Agent turns it into a new skill so the next similar task runs more reliably. This step turns the Agent from a user of skills into a maintainer of skills.
Finish unfinished tasks: tasks promised to the user but left undone, or interrupted by a transient failure (a network hiccup, an environment issue), get reviewed and attempted again.
Fill gaps in memory / knowledge / prompts: only as a backstop. The main conversation already writes memory and knowledge on its own, so this is a fallback.

Example above: during a post-session review the Agent spots a reusable workflow, turns it into a new skill, and notifies the user.

Two design trade-offs run through this layer:

Skills and unfinished tasks are the primary value; memory, knowledge, and prompts are only gap-filling, since they are already covered by the other layers and need no duplicate attention.
Fix the source, do not just log the symptom. If the root cause lives in a skill, the right move is to edit that skill, not to leave a note in memory saying "skill X has a bug." Many Agent projects stop at the symptom. Recording a symptom does not prevent recurrence; only fixing the source does.

3.2 When It Triggers

Review fires after a session ends and stays idle for a while, and only once enough conversation has accumulated to be worth reviewing. In short: the user has stopped chatting, and the session held enough substance. Both conditions must hold before a single review runs.

In the project, self-evolution can be toggled on or off from the Web console, and the idle threshold (10 minutes by default) and turn threshold (6 turns by default) can be tuned further in the config file.

3.3 Safety and Control

Once you let an Agent edit itself, the question that matters most is whether it might break something or interrupt the user. A system that can modify itself tends to fail in a few specific ways: writing wrong information into memory or skills; overstepping its scope and touching built-in modules while running commands; or making changes that cannot be traced or rolled back.

So this layer is designed around three goals: traceable, reversible, isolated execution.

Isolated execution: each review is a separate, asynchronous, temporary task. It uses the same main model but with a sharply narrowed tool set (it can only read context and edit memory and skills), so it neither pollutes nor slows the main conversation. The project's own built-in skills are write-protected at the code level.
Reversible changes: relevant files are backed up automatically before the Agent edits them. If a user disagrees with a change, sending a message like "undo the last change" restores the workspace.
Traceable changes: every change is persisted in the workspace, and the details can be tracked under "Web console → Memory → Self-Evolution."
No change, no interruption: after a review, the Agent checks whether anything was actually changed. If so, it pushes the result to the user; if not, it stays silent and the user notices nothing.

4. Dream-Based Memory Consolidation

Dream-based memory consolidation (Deep Dream) runs as a nightly scheduled task (23:55 by default). It first writes each session's context (short-term memory) for the day into daily memory, then runs a distillation pass: it reads the current core memory and the day's daily memory and asks the model to deduplicate, merge near-duplicate entries, prune, extract new information, and replace stale entries, producing a refined core memory. It also writes a narrative dream journal recording what this pass found, merged, and cleaned up.

This is a daily, global-scope form of self-evolution, a single sweep over all of the day's sessions. It addresses the two problems long-term memory runs into over time: unbounded growth and internal contradiction. The pass follows a few core rules:

Multiple near-identical entries are merged into one higher-density statement.
New information worth keeping (preferences, decisions, rules, lessons) is extracted from the daily journals; when new and old memory conflict, the new entry replaces the old one.
Temporary records, empty entries, and redundancy already covered elsewhere are cleaned out, keeping core memory (MEMORY.md) within a bounded size (around 50 entries).

A few safeguards keep consolidation safe and controlled:

If there are no new journals for the day, the pass is skipped, so it never overwrites existing core memory with nothing.
Journal content and each message are hashed for deduplication, so the same content is never written into daily memory twice (even across days).
The prompt strongly constrains the pass to the actual records, so it does not invent memories that never existed.

Besides the nightly run, consolidation can be triggered manually for the last N days. All consolidation output is persisted in the workspace as journals.

5. Source-Code Self-Update

Source-code self-update means the Agent modifies its own code at runtime and restarts, to solve problems that external skills and tools cannot. Because this carries some risk, the discussion here is more open-ended.

For safety, the project does not ship source-code self-update as a built-in, enabled feature. Users can still achieve it by asking for it directly. The project installs from source by default, so the Agent already has access to its own code; you only need to tell it where the project code lives and give a clear change request, and it can modify its own code and restart. To make it more proactive about editing code, you can wrap this into a Skill or prompt as a built-in capability.

Editing code changes the Agent's capabilities themselves, not just data like memory or skills, so the blast radius is larger. Two hard problems stand out:

How to keep the Agent from breaking the code and failing to start.
How to shut down the current process and start a new one from within the running process.

To handle both, the project provides a cow self-restart CLI command dedicated to the Agent restarting itself. It first runs a self-check on the code; any import or interpreter error aborts the restart. Once the check passes, it launches a relay process detached from the current process tree, which shuts down the old process and starts a new one, achieving a graceful self-restart.

In an open-source setting there is one more issue: version conflicts. Once the code is modified locally, it diverges from the upstream branch, and a later official update may conflict on pull. Resolving that still relies on a person, or on the Agent's help.

Example above: the Agent locates a problem in its own code and fixes it, then runs the command to self-check and restart.

Closing

Across these five layers, the Agent learns to adjust its own prompts, memory, knowledge, skills, and even its source code. Looking back at the design, the hard part was never giving it the ability to change itself; it was making those changes restrained and controllable. The goal is plain: an Agent that understands you better and makes fewer mistakes the more you use it, instead of one that meets you fresh every day.

The implementation here comes from the open-source project CowAgent. If the ideas are useful, the source and docs are there to look at.