DEV Community: Eric Mono

Building an Agent I Could Actually Trust: What I Learned from Agent CLI

Eric Mono — Thu, 20 Aug 2026 17:09:23 +0000

What building Agent CLI taught me about evidence, permissions, verification, and the systems around LLMs.

Over the past month, I've been building an open-source project called Agent CLI.

Today it's a local-first, terminal-native agent harness that can work across code, shell commands, Git, browser automation, research, DOCX/PDFs, and remote delivery.

But it didn't start because I wanted to build another coding agent.
It started with a much simpler question:

What would an AI agent be like if I cared less about how many capabilities it had, and more about whether I could trust what it actually did?

That question ended up shaping the whole project.

Starting again after building too much

Before Agent CLI, I already built a much larger local AI system called Agent OS.

It explored multi-agent orchestration, memory, Git workflows, deployment, browser automation, recovery, research, skills, and a graphical interface.

It was a useful learning project, but it also exposed a problem: adding capabilities faster than architectural guarantees makes an agent look more mature than it really is.

A polished UI could hide unclear boundaries; Confirmation prompts could be mistaken for actual sandboxing; Large feature increments became harder to review; And a convincing model-generated summary was still just a summary.

So instead of keep expanding the same system, I started Agent CLI around a narrower thesis:

Build a trustworthy execution kernel first. Expand the workflows later.

The basic loop became:
Understand → Plan → Act → Observe → Verify → Record → Resume

What began as a design principle gradually became a test for almost every feature I added.

An agent is more than an LLM with tools

The interesting engineering problem isn't about the model.

Once an agent can modify files, execute processes, access the network, or publish code, the important part becomes the execution harness around the model.

The model can propose an action;
The runtime decides whether it's allowed.

The model can say tests passed;
The runtime should know which process ran and the exit code.

The model can say a file was fixed;
The runtime should know what bytes changed and whether verification happened afterwards.

This led to one rule that has survived almost every iteration of Agent CLI:

The model may reason about reality, but it shouldn't define reality.

Whenever possible, reality comes from files, hashes, process results, diffs, Git state, browser observations, and other external evidence.

Evidence over narration

Agent runs naturally produce persuasive narratives:

Implemented the feature, fixed the bug, and all tests pass.

But many subtle failures can hide behind that sentence.

Maybe the test ran before the final edit; Maybe it ran in the wrong package; Maybe the command timed out; And maybe the model interpreted partial output as success.

Agent CLI therefore records important actions into an append-only event log: approvals, commands, file mutations, hashes, verification results, and other consequences.

Reports are derived from that evidence rather than reconstructed from the model's memory.

Verification is also temporal.

A file is only considered checked when a real verification process succeeds after its last relevant mutation; A successful build in one project cannot certify a change in another; A killed command without an exit code cannot quietly become a pass.

This sounds like implementation detail, but it changed the architecture significantly.

The conversation is context.
The model's explanation is interpretation.
The execution record is evidence.

Those are three different things.

Permission, approval, and sandboxing are different problems

Another lesson came from trying to define what “safe execution” actually means.

Agent tools often expose broad modes such as safe, automatic, or full access. They are convenient, but they can hide what has actually been authorized.

Agent CLI instead evaluates individual actions through a centralized policy gate.

Tools declare facts about their effects—running a command, mutating files, reading remotely, sending data externally—and the runtime decides whether that action is allowed, requires approval, or should be denied.

This also forced me to separate three concepts I previously treated too loosely:

Trust: permission to operate inside a workspace.
Approval: authorization for a particular consequential action.
Sandboxing: technical enforcement by the operating system.

A confirmation prompt isn't a sandbox.
A workspace path check isn't a sandbox.
And trusting a project doesn't mean approving every future action.

Agent CLI currently has real OS-level sandboxing for eligible auto-run commands on Windows, using Low Integrity and a Job Object. But that boundary is deliberately described narrowly: it doesn't prevent reads or control network access, and explicitly approved commands run unsandboxed.

On platforms where the same enforcement is unavailable, command auto-run fails closed instead of pretending the guarantees are equivalent.

That produced another principle I now care about:

Security degradation should be visible degradation.

An honest weak boundary is more useful than a strong-sounding label.

Reversibility is an underrated form of autonomy

As agents gain more authority, the obvious solution is to ask users for confirmation more often.

But an agent that asks before every small edit quickly stops feeling like an agent, but more like a baby you have to look after all the time.

A better solution for many local operations is to make them cheaply reversible.

Agent CLI snapshots workspace changes before applying them. /undo can restore them later and refuses to overwrite files that have drifted. Larger recovery points can use hidden Git references without moving the user's branch or HEAD.

Mutating delegated agents work in disposable Git worktrees, and their changes reach the main workspace only through explicit integration.

This changed the question from:

Should the agent be allowed to modify this file?

to:

Can this operation be made reversible enough that review afterwards is cheaper than interruption beforehand?

Not every action fits that model. Publishing, destructive operations, and sensitive external effects still deserve stronger approval boundaries.

But for ordinary local work, reversibility can often buy useful autonomy without simply removing control.

General-purpose shouldn't mean improvising everything

Agent CLI started as a coding agent, but I wanted to know whether its architecture was actually general or merely coding-specific.

DOCX and PDFs became an early test.

Instead of creating a separate “document agent,” the same runtime writes a structured specification, deterministic software renders the artifact, the result is parsed back for validation, pages can be rasterized, and a vision-capable model can inspect the real output.

This led to a broader idea:

Many high-quality agent workflows need an intermediate representation between language and effects.

Code already has source files.
Docs can have a document specification.
Slides can have a layout model.
Video can have an edit decision list.
Deployment can have typed desired state.

The model handles ambiguity and high-level decisions. Deterministic software handles repeatable transformations and validation.

That seems much more promising to me than letting the model rediscover an ad-hoc workflow every time.

More agents doesn't mean a better agent system

Agent CLI eventually gained planning, delegated research, reviewing, and isolated mutating workers.

But building those features actually made me less interested in the “agent team” metaphor.

Once the implementation becomes concrete, multi-agent execution looks much more like a familiar systems problem:
How do we delegate bounded work, isolate concurrent mutation, preserve provenance, and safely integrate results?

A child agent should inherit the same or narrower authority.
A mutating worker shouldn't casually share the parent's workspace.
An approved plan should refer to specific content, not merely an old conversational “yes”.

Those boundaries matter more than how many agents appear in the terminal.

The main lesson: remove ambiguity before adding intelligence

Agent CLI is now a substantial project: more than 50k lines of TypeScript source, over 2400 hermetic tests, five model providers, multiple workflow areas, and a runtime that has been exercised end-to-end on real software work.

But the most valuable improvements rarely came from adding more features.

They came from replacing vague concepts with precise ones.

“Safe command” became an action contract plus policy plus an enforcement boundary.
“Verified” became a successful process after the relevant mutation.
“Plan approved” became approval of specific semantic content.
“Memory” became context that carries no authority.
“Multi-agent” became bounded delegation and isolated workspaces.
“Done” became something that should be justified by evidence.

That has changed the question I ask when an agent behaves unreliably.

Instead of immediately asking:

How should I improve the prompt?

I now ask:

What ambiguity is the model currently resolving that the system could resolve instead?

Sometimes the model really should reason about it.

But surprisingly often, the better answer is a type, a state machine, a hash, an exit code, a sandbox boundary, or a deterministic renderer.

Agent engineering is increasingly systems engineering

Models will keep getting stronger.

But stronger models also mean we will delegate more consequential work to them, which makes the surrounding harness more important rather than less.

For me, the interesting questions are increasingly:
What may happen?
What actually happened?
How do we know it worked?
What happens if it fails halfway through?
Can someone else inspect the evidence and reach the same conclusion?

These are not entirely new questions.

Operating systems, databases, build systems, version control, security engineering, and distributed systems have been dealing with variations of them for decades.

The model is new.
Many of the engineering problems around it are not.

Agent CLI is still an experiment rather than a claim that I have found the “correct” architecture.

The project is completely open source under MIT, and I'm sharing it mainly as part of the learning process instead of a commercial launch.

If you are also working on coding agents, local AI systems, sandboxing, verification, agent runtimes, or related infrastructure, I would genuinely be interested in criticism or alternative approaches.

GitHub: github.com/earthwalker17/agent-cli

Issues, PRs, and technical discussion are all welcome.

How I Made a Product Demo with Claude Code, Playwright, and FFmpeg

Eric Mono — Mon, 13 Jul 2026 14:47:14 +0000

I recently needed a short product demo for my open-source project called Agent OS.

The goal was modest: create a clear 45–60 second walkthrough of the real product.

I didn't need a polished advertisement. I also didn't want to:

manually record a dozen clips
learn Premiere or After Effects
move every cut and caption on a timeline
recreate the product interface with generated animation

So I tried a simple automated workflow:
Claude Code + Playwright + FFmpeg

The result was a 56-second silent MP4 created in roughly 30 minutes, using around 50K tokens with Opus 4.8.

What Claude Code handled

Claude Code first inspected the application and identified the existing product states that could form a complete story:

The Agent OS landing page
Main Agent planning and Coding Agent handoff
A real task graph and execution trace
Build, browser, and visual verification
A failed browser run with runtime evidence
A linked bounded-recovery run
A preview-only Git contract
The finished Pulseboard application

It then started the locally served frontend and backend and used Playwright to navigate through those states.

Nothing was recreated or fabricated for the video. The walkthrough used existing persisted run records from the real Pulseboard build.

Why it recorded several short clips

The first instinct was to record one continuous browser session.

That became unreliable when dense modals and long smooth scrolling caused the Playwright video encoder to fall behind.

The practical fix was simple:

record one short clip for each narrative beat
give each clip its own BrowserContext
store the content start and end times
close the context after every clip so the recording is finalized

The result was much more stable than one long recording.

What FFmpeg handled

After Playwright produced the raw WebM files, a small Python script used FFmpeg to:

trim each clip to its useful content window
add short labels
create a simple opening card
create a GitHub end card
concatenate everything
export a 1280×720, 30 fps H.264 MP4

There were no complex transitions. The product interface remained the main visual.

Why this workflow was useful

This won't replace professional video editing.

But it seems well suited to:

open-source project demos
internal product walkthroughs
release previews
reproducible UI recordings
projects where authenticity matters more than elaborate motion graphics

The useful shift was treating the demo as another automated software artifact.

The browser flow is code.
The selected product state is deterministic.
The labels and timings are configuration.
The video can be regenerated when the interface changes.

The project shown in the demo

Agent OS is a local-first AI Project Operating System — the harness around coding models that adds persistent memory, controlled execution, real verification, bounded recovery, and approval-gated delivery.

The project is open source here:
https://github.com/earthwalker17/agent-os

The demo doesn't prove that the system is perfect. It simply gives people a much faster way to see what it actually does.

Agent OS: A Local-First Harness Around Coding Models

Eric Mono — Fri, 10 Jul 2026 16:48:13 +0000

AI coding model can generate code.
That doesn't mean it can reliably finish real software work.

Between a plausible diff and a completed task, a real software agent still needs memory, execution boundaries, verification, recovery, permissions, and delivery infrastructure.

That's the problem I've been exploring through Agent OS, which I now release as an open-source project.

GitHub: https://github.com/earthwalker17/agent-os

The model is only one part of the agent

Agent OS is a local-first AI Project Operating System: a harness around coding models.

The core architecture separates two responsibilities.

Main Agent: the brain

The Main Agent handles:

Conversation
Planning
Project memory
Context assembly
Orchestration
Delegation decisions

It cannot change code or execute shell commands directly.

Coding Agent: the hands

The Coding Agent operates inside one sandboxed project workspace.

It can inspect files, edit code, run bounded commands, but it cannot modify project memory or access another project’s workspace.

The two sides communicate through summaries and structured artifacts rather than unrestricted shared control.

“Done” must come from verification

Agent OS doesn't accept the model’s own claim that a task is complete.

A coding run must pass a real build or test command.

It can then:

Launch the application
Walk declared browser flows
Capture screenshots and runtime evidence
Run visual review
Classify failures
Propose or execute a bounded repair pass

Recovery is deliberately limited. The goal isn't unlimited autonomy, but controlled progress with evidence and an audit trail.

External actions remain human-controlled

Git pushes, pull requests, deployments, database migrations, and Stripe test-mode operations use explicit preview-and-confirm contracts.

The agent can prepare the operation, but it cannot silently mutate an external system because it inferred that the user probably wanted it.

Testing the system on a real product

To pressure-test the architecture, I used Agent OS itself to build and deploy Pulseboard, a full-stack SaaS, from an empty repository.

The process included real build, runtime, browser, visual, deployment, and database failures. Those failures became the test for whether the system could collect evidence, expose the problem, and recover instead of simply producing a confident success message.

What's included in the first public release

Local filesystem and SQLite-based project state
Structured Markdown memory
Claude, GPT, Gemini, DeepSeek, Kimi, and GLM support
Sandboxed coding execution
Parallel agent teams in isolated Git worktrees
Command, browser, and visual verification
Typed bounded recovery
GitHub, Vercel, Supabase, and Stripe test-mode connectors
Apache-2.0 licensing
GitHub CI and 832 backend tests
One-command Windows installation

Current limitations

This is an early public release.

The Windows setup is currently the most thoroughly tested. macOS and Linux users need to follow the manual setup instructions. At least one supported model provider API key is required.

Local-first means that project memory, workspaces, credentials, and execution records live on the user’s disk. It doesn't currently mean that every supported model runs locally.

What I'm looking for

I'm especially interested in feedback on:

The separation between the Main Agent and Coding Agent
The first-run installation experience
The boundaries of automated recovery
Which internal components should become independent libraries

The repository, architecture documentation, installation guide, and production showcase are all available here:
https://github.com/earthwalker17/agent-os