HAHWUL

Traveling with Hermes in Japan

Sun, 19 Apr 2026 00:00:00 +0000

I spent the past week traveling in Japan. It's a country I visit every year, so it's familiar territory, but this year I prepared a little experiment. I set up the Hermes Agent on the Mac Studio at home, and kept directing it through Discord to work on projects while I was away. The results turned out better than I expected, and I wanted to share that experience.

In most of my AI workflows, I sometimes hand the orchestrator role to an AI, but for important projects I prefer to stay hands-on. This time, driving Hermes remotely let me make good use of travel and downtime. Of course, I brought my MacBook too, so I still did some work directly late at night or early in the morning.

Hermes Agent

Hermes is an open-source AI Agent from Nous Research, and it's been getting attention as an alternative to OpenClaw. Its core feature is self-improvement. After the Agent finishes a task, it reviews the result itself, remembers patterns, or turns them into new skills it can reuse. The more you use it, the smarter it gets.

I've personally been a fan of the self-learning concept, so I'd been testing it locally since March. This time I finally put it to work on an actual open-source project.

Setup

Hermes supports a variety of providers, so you can configure it however you like. Since I use Claude, Codex, and Gemini subscriptions heavily, I hooked up GitHub Copilot, which had more room to spare, for lighter tasks. (I'd been struggling to burn through Copilot's monthly quota anyway, so it was a perfect fit.)

Since provider handling is a lightweight task, I mostly used the Sonnet 4.6 model. If you want to save even more on cost, Grok Code Fast would also be a solid choice.

For the messaging gateway, I went with Discord. You create a Discord bot and register its token with Hermes.

Personally, I think the messaging channel is critical from a security perspective. Discord lets you control bot permissions in fine detail, and Hermes' settings let you restrict access to specific user IDs via ALLOWED_USERS. With this setup, the bot only carries the permissions it actually needs, and random users can't just invoke it at will.

If you look at ~/.hermes/.env, it's defined like this:

DISCORD_BOT_TOKEN=********
DISCORD_ALLOWED_USERS=********
DISCORD_HOME_CHANNEL=********

Workflow

Coding requires precision, so Hermes (Copilot) alone isn't quite enough in terms of quality. So most of the real work got delegated to Claude Code, Codex, and Gemini. Early on I had to give multiple directions, but once the conversation built up some context, Hermes started routing to the appropriate model (Claude, Codex, Gemini) on its own depending on the situation. Copilot was mostly used for the chat channel and light tasks. (The way Hermes automatically branches between Claude, Codex, and Gemini based on purpose, once the conversation has some history, was especially appealing.)

flowchart LR A[Me] -->|Send Message| B(Hermes Agent with Github Copilot) B --> C{Thinking} C -->|Write Code| D[Claude Code] C -->|Code Refactoring| E[Codex] C -->|Design Task| F[Gemini]

Block macOS sleep

Leaving the Mac Studio idle for long periods puts it to sleep automatically, so I needed to prevent that. I handled it with a small app I've been developing myself called NoDecaf, which was nice because it doubled as a real-world test.

In Japan

Before leaving, I finished plenty of testing and dropped the main work instructions into Discord, then went off to enjoy the trip. Feedback requests and permission approval notifications came in occasionally, but nothing overwhelming. I could check and handle them pretty casually.

Once the conversation had built up some history, I could keep my instructions brief and Hermes would still handle things well, which was satisfying. One moment that honestly moved me a little was watching it notice a usage limit and queue up a pending task on its own :D

Generated Skill

I could see the skills Hermes had automatically generated from its workflow. The hwaro-examples-batch skill visible in the image above is a good example. It studied the patterns of tasks I frequently assign around hahwul/hwaro-examples and turned them into a skill on its own.

Skills are stored under ~/.hermes/skills, with built-in skills and user-generated ones managed together. hwaro-examples-batch lived at ~/.hermes/skills/github/hwaro-examples-batch, and looking at its SKILL.md, it documented the trigger phrases I usually use, the local clone path (interestingly, even though I told it a specific path was fine to use, it set up a separate one — probably to avoid conflicts with the user's own workspace), and the scripts needed to carry out the task.

Since skills are built from actual performed work, it's starting to feel like generating them automatically from the AGENT's workflow might be a better choice than writing SKILLs by hand. I'll have to keep running Hermes and squeeze out more skills.

Jules

Separately from Hermes, Jules was actually running continuously on autopilot during the trip too. I keep Jules on lighter tasks, and because it's purely cloud-based, I can run it comfortably from home or on the road. A few scheduled jobs are set up on the hwaro-example side, periodically identifying pages with problems, fixing them, and sending PRs. The PRs it opens then get handled by Hermes using Codex.

If you set up the working environment within Jules' Environment, there will be little difference from running it on an actual local PC.

Areas for Improvement

Convenience comes with security risks. One thing I felt going through this flow is that permission separation matters. In particular, for high-privilege accounts like GitHub, I think it's worth creating a separate dedicated account just for the Agent.

Conclusion

Since I usually do most of my work sitting right at my Mac, my biggest question was whether I could actually use AI effectively from just my phone while traveling. It turned out to be more comfortable than I expected, and the setup seems to save a lot of time during transit, so once vacation is over I might try applying this flow to my commute as well. Serious work is still better when I'm hands-on (easier for me, easier for the AI, better results), but anything that can be verified through skills (e.g., development with tight test coverage, tasks that don't need broad permissions) seems better handled through Hermes in the gaps.

Being able to fully enjoy my own time while small tasks keep ticking along is genuinely appealing. Raising an Agent with self-improvement like Hermes also feels like a pretty meaningful experience. If it sounds interesting, I'd recommend giving it a try.

Building AI-Friendly CLIs

Sun, 22 Mar 2026 00:00:00 +0000

These days, AI agents are writing code, calling tools, and even handling deployments. With that shift, the CLI is getting attention again. GUIs and web dashboards are great for humans, but from an AI agent's perspective, CLIs are a much easier interface to work with.

The thing is, most existing CLIs were designed for humans. Pretty table outputs, color codes, shorthand flags. All nice for human eyes, but painful for agents to parse. Output formats subtly change between versions, and figuring out the exact usage often means reading separate documentation.

This week, I did a major overhaul of our team's internal CLI at work, rebuilding it around JSON I/O and schema commands. The agent's task success rate jumped noticeably. Based on that experience, I want to share some thoughts on how to build AI-friendly CLIs.

Why JSON-First Input / Output Matters for AI Agents

Human vs AI CLI Usage Patterns

When humans use a CLI, they check --help, read man pages, eyeball error messages, and iterate through trial and error. Even if the output changes a bit, they adapt by reading the context. AI agents, on the other hand, take the output as a raw string and process it literally. They have to parse table-formatted output with regex, and the moment column order shifts or line breaks change, things break immediately.

# This is convenient for humans, but...
$ kubectl get pods
NAME                     READY   STATUS    RESTARTS   AGE
my-app-7d4b8c6f5-x2k9z  1/1     Running   0          3d

# This is what agents need
$ kubectl get pods -o json
{
  "items": [{
    "metadata": {"name": "my-app-7d4b8c6f5-x2k9z"},
    "status": {"phase": "Running", "containerStatuses": [{"ready": true}]}
  }]
}

The Pain of Unstructured Text Output

Unstructured text output causes more problems for agents than expected. Here are some patterns I actually ran into:

Inconsistent parsing: sometimes the output has headers, sometimes it doesn't
Locale dependency: date/number formats change based on system locale
Color code pollution: ANSI escape codes sneak in and break string comparisons
Progress bar collisions: stderr and stdout get mixed up, garbling the output
Silent truncation: long values get clipped to ... with no way to detect it

When you start handling these edge cases one by one, your agent code ends up buried in CLI parsing logic instead of actual work.

Advantages of JSON

JSON I/O solves most of these.

Type safety: numbers are numbers, strings are strings. You can distinguish "3" from 3
Schema-based validation: define and validate input/output shapes upfront with JSON Schema
Easy chaining: instantly parseable by jq, pipelines, and any programming language
Consistency: identical output regardless of locale or terminal settings
Structured errors: return errors as JSON so agents can identify error types and respond appropriately

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Pod 'my-app' not found in namespace 'default'",
    "suggestions": ["Check namespace with --namespace flag"]
  }
}

Real-World Test Results from Our Project

Here's a quick summary of what changed after adding a --json flag to the CLI and having agents perform the same tasks:

Metric	Text Output	JSON Output
Task success rate	Around 60%	Around 90%
Average retries	2.3 times	0.4 times
Parsing-related errors	41% of all errors	Nearly 0%

These numbers are from specific tasks I tested, so your mileage may vary. Still, just switching to JSON making this much difference was surprising.

The Schema Command – Letting AI Learn and Adapt at Runtime

JSON I/O alone is a huge improvement, but there's a way to take it one step further: the schema command.

Inspiration from Google Workspace CLI (gws)

This idea was inspired by Google Workspace CLI (gws). gws has a structure that lets you query schema information per resource at runtime. Looking at that, I thought: "Why not let the agent ask the CLI directly instead of reading documentation?"

How the Schema Subcommand Works

The concept is simple. Add a schema subcommand to your CLI — specify a resource and action, and it returns the JSON Schema for that command's input and output.

$ mytool schema user.create
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "Create a new user",
  "input": {
    "type": "object",
    "required": ["email", "role"],
    "properties": {
      "email": {"type": "string", "format": "email"},
      "role": {"type": "string", "enum": ["admin", "member", "viewer"]},
      "name": {"type": "string", "maxLength": 100}
    }
  },
  "output": {
    "type": "object",
    "properties": {
      "id": {"type": "string", "format": "uuid"},
      "email": {"type": "string"},
      "role": {"type": "string"},
      "created_at": {"type": "string", "format": "date-time"}
    }
  }
}

Even better if you can also query the list of available resources:

$ mytool schema --list
["user.create", "user.delete", "user.get", "user.list", "project.create", ...]

Benefits for Agents

No external docs needed: agents can query the CLI directly and construct accurate inputs
Auto-adapts to API changes: when the CLI updates, the schema updates with it, so agents always work against the latest spec
Pairs with dry-run: build input from the schema, validate with --dry-run, then execute
Self-describing: the CLI can describe itself without needing a separate AGENTS.md or tool description

Our Implementation Overview

In our project, we implemented it with the following structure:

Define input/output schemas on each command handler (based on Pydantic models)
The schema subcommand serializes these into JSON Schema and returns them
A --list option allows browsing the full resource/action tree
Include an examples field in schema responses so agents have something to reference

The implementation itself wasn't particularly difficult. Since we were already defining input/output models with Pydantic, most of it was solved just by calling .model_json_schema().

Example Agent Workflow Using Schema

Here's what the actual flow looks like when an agent uses the schema:

1. Agent: mytool schema --list
   → Check available commands

2. Agent: mytool schema user.create
   → Check input schema (required fields: email, role)

3. Agent: mytool user create --json '{"email":"new@example.com","role":"member"}' --dry-run
   → Validate before execution

4. Agent: mytool user create --json '{"email":"new@example.com","role":"member"}'
   → Execute, receive JSON response

5. Agent: Use the id field from the response for the next task

Throughout this entire flow, the agent never references documentation once. The CLI itself serves as the documentation.

Practical Design Patterns

Some patterns worth considering when applying JSON I/O and Schema.

Input Design Choices

Roughly three input approaches, pick based on the situation:

Approach	Example	Best For
stdin JSON	`echo '{"key":"val"}' \| mytool create`	Large payloads, pipeline chaining
argument JSON	`mytool create --json '{"key":"val"}'`	Single command execution, keeping it in shell history
Mixed	`mytool create --name foo --json '{"extra":"opts"}'`	Frequently used options as flags, the rest as JSON

Personally, I'd recommend argument JSON as the default with stdin support as well. From an agent's perspective, a self-contained single command is the easiest to work with.

Output Design Best Practices

A few important principles for output design:

--json flag: keep the default human-readable, but return structured output when --json is passed
NDJSON support: for streaming scenarios (logs, events, etc.), support line-delimited JSON
Errors in JSON too: in --json mode, errors should also be returned as JSON, alongside exit codes
Include metadata: pagination info, request IDs, timestamps should be part of the response

# Normal mode
$ mytool user list
EMAIL              ROLE     CREATED
alice@example.com  admin    2026-01-15
bob@example.com    member   2026-02-20

# JSON mode
$ mytool user list --json
{
  "data": [
    {"email": "alice@example.com", "role": "admin", "created_at": "2026-01-15T00:00:00Z"},
    {"email": "bob@example.com", "role": "member", "created_at": "2026-02-20T00:00:00Z"}
  ],
  "meta": {"total": 2, "page": 1, "per_page": 50}
}

In the end, I actually went with JSON output as the default and added a --no-json flag instead. If the tool isn't meant for human use, unifying all I/O as JSON gave us the best hit rate.

Versioning & Backward Compatibility

Versioning JSON output needs some care. A few strategies:

Adding fields is safe, removing/changing is not: adding new fields doesn't break backward compatibility, but removing fields or changing types can break agents
Include a version field: putting something like "api_version": "v1" in the response lets agents branch based on version
Deprecation warnings: fields slated for removal should be flagged in a separate warnings array

Using Pydantic / Zod / JSON Schema for Validation

Some tools for schema definition:

Python: Pydantic is the most convenient. Model definition → automatic JSON Schema generation → input validation, all in one
TypeScript/Node: Define schemas with Zod and convert using zod-to-json-schema
Go/Rust etc.: Write JSON Schema files directly or use code-generation libraries

The key point is that the type definitions used in your code and the schema returned by the schema command must come from the same source. If these are managed separately, they will inevitably drift out of sync.

Truth be told, we didn't pay much attention to this in our project. And it led to quite a few failures.

AI-Friendly Helper Flags

Beyond schema and JSON, a few more agent-friendly flags worth adding:

--dry-run: preview results without actually executing. Lets agents safely test things out
--explain: describe what the command will do in natural language. Helps with agent planning
--output-format: choose between json, yaml, csv, etc.
--quiet: strip unnecessary banners and warnings, return only essential output
--no-color: remove ANSI escape codes (honestly, every CLI should have this)

Results, Lessons, and Caveats After Adoption

Quantitative & Qualitative Outcomes

I shared the JSON transition results earlier. Here's what changed after adding the schema command:

Metric	JSON Only	JSON + Schema
Task success rate	Around 90%	~97% (almost all succeeded)
Agent first-try accuracy	~70%	~90% (honestly, this was the biggest improvement)
Doc references needed	Avg 1.2 per task	Nearly 0

The sample size wasn't huge, so take the numbers with a grain of salt. But more importantly, the agent code got much simpler. Parsing logic disappeared and we could focus on business logic.

Common Failure Patterns We Observed

It's not perfect though. Common failure patterns and their fixes:

Oversized JSON responses: when a list API returns thousands of items, it blows the agent's context window. Pagination and filtering are essential
Deeply nested structures: JSON nested 5+ levels deep is hard for agents to navigate accurately. Keep it flat when possible
Enum value errors: even with enums defined in the schema, agents sometimes insert similar but incorrect values. Input validation + clear error messages help
optional vs required confusion: agents sometimes skip required fields. Mark required fields clearly in the schema and tell them which fields are missing in error messages

Remaining Challenges

Some unsolved problems remain:

Complex pagination: getting agents to handle cursor-based pagination smoothly remains tricky
Binary data: file uploads/downloads and other binary data are hard to express cleanly in JSON
Long-running operations: tracking status and handling timeouts for tasks that take several minutes

I still haven't found great answers for these. The long-running operations problem is particularly interesting. Most agents end up polling with their own sleep loops, which is pretty inefficient. Ideally, agents should be able to receive callbacks, but that's not easy to pull off.

Conclusion

Two essentials for building AI-friendly CLIs:

JSON-First I/O: structure your inputs and outputs so agents can parse and use them reliably
Schema Command: let the CLI describe its own interface, eliminating the dependency on external docs

Just these two things made a noticeable difference in agent performance. If you want to start right away, the easiest entry point is adding a single --json flag to your existing CLI. That alone makes agent integration much smoother.

CLIs are back.

10 Years of Reflection and a New Beginning

Sun, 22 Feb 2026 00:00:00 +0000

Hello everyone! This is my first post of 2026. I wanted to publish this back in January, but various things kept piling up and the work took longer than expected, so I'm finally getting it out now.

As we hit 2026, there's something pretty cool: amazingly, it's been exactly 10 years since I started using this domain and going by the name hahwul. It feels like such a long time when I think about it, but it passed by in the blink of an eye. Today, along with looking back on these 10 years, I also have some fairly big changes to share regarding the blog's operation, content, and overall direction.

Domain Name: hahwul.com
Registry Domain ID: 1992489747_DOMAIN_COM-VRSN
...
Updated Date: 2026-01-05T20:29:07Z
Creation Date: 2016-01-07T23:55:03Z

10 Years Ago

Truth be told, even before using the name hahwul, I ran another domain for about two years, and before that, I had a different blog during my kiddie days. So all in all, I've been writing online for well over 15 years now. Of course, those early blogs were just basic development notes where I organized stuff. The thing that really brought me to where I am today is the name hahwul and this blog.

I made up the name hahwul based on my own name, and over these past 10 years, I've written a huge number of posts with it. After a couple of major cleanups here and there, I've still managed around 1,400 articles. Most of them were about security and development topics, along with my personal struggles, thoughts, and reflections. The habit of putting things into writing has been a great way to truly absorb knowledge, and I feel like those years were incredibly meaningful for learning and growing.

I couldn't have kept writing all this time through sheer consistency alone — it's been possible thanks to all of you who kept coming back to read my posts. Thank you from the bottom of my heart!

Announcement

I have one announcement regarding the direction of my content going forward. While the blog has been more of a general resource covering all sorts of information until now, I want to shift toward sharing more of my own stories and personal thoughts from here on out.

Of course, that doesn't mean the existing style of posts will vanish. They'll just be reorganized. Posts that are too outdated or too light will be removed, and I'll focus on creating more solid, substantial content.

Under Posts, I'll occasionally share my thoughts and opinions on technology. Under Notes, I'll keep more standardized and well-polished articles. And if I have enough time and energy, I'd also like to add content in series format (e.g., a ZAP Guide series, etc.).

Conclusion

Anyway, to sum it up, I want to say thank you once again. I'll keep writing steadily into the future, so please stick around and enjoy the ride!