Agentic Engineering on Grant Lucas

For Agents, --help Has to Be Enough

Wed, 29 Jul 2026 19:00:00 -0400

Designing an AI-native CLI: usable by humans, and especially usable by coding agents

Logger-TXT started life as a shell script over a decade ago. It does one small thing: append a timestamped line to a text file so I can remember what I did on that Tuesday two weeks ago. I rewrote it in Go recently, and the surface reason was capabilities. Date ranges, type and project filters, reverse scanning so a decade-deep log file stays fast.

That’s not really why I did it, though. The rewrite was an excuse to practise designing an AI-native command-line tool: one a coding agent can pick up and drive correctly, with no help from me, on the first try.

Every loop in the process that follows (the constraint, the testing, the rewrites of my own help text) was for the agent. Humans get a better tool out of it, and I’ll get to why that happens, but that’s the dividend rather than the motivation.

What “AI-Native” Means Here

Worth defining, since the phrase gets used for something else entirely.

An AI-native CLI isn’t a CLI with AI inside it. There’s no model in Logger-TXT, no natural-language parsing, no logger-txt ask "what did I do Tuesday". It’s a tool that treats a coding agent as a first-class consumer of its interface, alongside the human at the terminal.

A human explores. They run the command, squint at the output, try a flag, read the error, and converge. They carry context between attempts, and they can go ask someone or read the source when they’re stuck.

An agent commits. It reads the interface once, picks the command that best matches its intent, and runs it. An error it will read and route around, so a command that fails outright is no problem. A plausible-looking result it simply accepts, because it has no independent sense that the number should have been 40 instead of 10.

So an agent is functionally a user with no prior context, no accumulated intuition about your tool, and no way to ask a clarifying question, who nonetheless has to get it right immediately.

The Constraint: `--help` Has to Be Enough

Here’s the rule I gave myself: an agent handed nothing but this binary should reach the right command on the first try.

No instruction file to load. No skill to install. No MCP server wrapping the CLI. No prose in a repo telling the agent which flag to prefer. Everything it needs to use the tool correctly ships inside the tool.

Why Not a CLAUDE.md, a Skill, or an MCP Server

Those are the normal answers to “make this tool legible to an agent,” and each one puts the knowledge in the wrong place:

A CLAUDE.md section lives in your repo, not mine. It drifts out of date the moment I ship a flag, and it only helps agents that happen to read that file, in that repo.
An MCP server is a second artifact to build, version, release, and keep in sync with the binary. Now there are two things that can disagree about how the tool behaves. It does buy something help text can’t, in fairness: a typed schema constrains arguments structurally, where help text only asks nicely. I went the other way regardless, for the reason below.
A skill has to be installed before it can help, so the tool doesn’t work until someone has already done setup on the agent’s side.

Help text ships with the binary, versions with the binary, and is already the first place both consumers look. It’s the only documentation surface that can’t drift from the thing it documents. That matters most in the case the tool actually gets used in: someone runs brew install grantlucas/tap/logger-txt and there is no repo, no README, and no source to fall back on. There’s a binary and its help output, and nothing else.

Though the better reason I picked it is that it’s a forcing function. If --help is the only channel I’m allowed to use, every ambiguity in the tool has to get sorted out in the help text or in the design itself. I can’t paper over a confusing interface with a paragraph somewhere else.

The Design Loop

The constraint makes the workflow concrete, and it ends up looking like usability testing with an agent as the test subject:

Hand an agent the binary and nothing but --help
Watch for the spot where it picks a plausible-but-wrong command
Fix the help text, or the design, until a cold read leads somewhere better

Step 2 is the whole game, because plausible-but-wrong is the failure mode agents produce and humans mostly don’t. An agent that picks a command which errors out is fine, since it reads the error, adjusts, and gets there. An agent that picks a command which succeeds and returns believable-but-wrong results has no signal that anything went wrong, and neither do I until I notice the numbers look off weeks later.

The Trap I Built Myself

The best example came from a change that looked purely additive.

I added -t (type) and -p (project) filters to both show and search. Nice and consistent: same flags, both commands. Except that quietly created a trap.

1
2

logger-txt search WORK   # matches "WORK" anywhere in the line
logger-txt show -t WORK  # matches only entries tagged WORK

These now look interchangeable, but search matches the term anywhere in the full log line, including the message body, so an entry like 31/01/26 13:30 -0600 - PERSONAL - Followed up on WORK email shows up in the first command and not the second.

Asked to find my work entries, the agent reasonably picked search and got plausible results back. Nothing in the help text would have told it otherwise. A human who wrote the tool would never make this mistake, which is exactly why I couldn’t see it.

The fix went into the help string, not into a document telling the agent what to do:

Note: "search TYPENAME" is not equivalent to "show -t TYPENAME". The search
term matches anywhere in the full log line — including message text — so
entries that mention the type name in their message body will appear as false
positives. Use "show -t" to filter strictly by the type tag.

It’s deliberately blunt, and it names the wrong choice explicitly, because a disambiguation that only describes the correct option is useless to a reader who already believes they’ve found it.

What Designing for the Agent Produced

A handful of patterns fell out of running that loop. Each one is here because of a specific way an agent breaks without it.

Help Text That Teaches Rather Than Lists

Without this, an agent works out the data format by running commands and inferring from whatever comes back, which burns turns and produces a wrong inference when the sample isn’t representative.

So the root --help embeds the log entry format and the full file-resolution order. One read establishes where the data lives and what it looks like:

Log entry format:
  DD/MM/YY HH:MM -0700 - Message
  DD/MM/YY HH:MM -0700 - TYPE - Message
  DD/MM/YY HH:MM -0700 - (PROJECT) - Message
  DD/MM/YY HH:MM -0700 - TYPE (PROJECT) - Message

File resolution order:
  1. --file flag value
  2. ./log.txt if it exists in the current directory
  3. LOGGERTXT_PATH environment variable
  4. ./log.txt (default)

Subcommand examples show their expected output inline:

1
2
3

  # With both type and project
  logger-txt add -t dev -p acme Fixed login bug
  # => 04/03/26 14:30 -0500 - DEV (ACME) - Fixed login bug

That # => line costs nothing and removes a round trip. It also makes the uppercasing visible, since -t dev comes back as DEV and -p acme as (ACME), instead of leaving it as a surprise to be discovered later.

Documented Defaults, Not Implied Ones

An undocumented default gets guessed at, and a guess that happens to return rows is indistinguishable from a correct answer. So the ones that could bite are spelled out:

A date-only --start begins at 00:00
A date-only --end ends at 23:59
An active date range overrides the default count of 10

That last one especially. show --start 01/03/26 --end 14/03/26 returning everything in the range rather than the last 10 is the behaviour I want, and it flatly contradicts the count default documented a few lines above it in the same help output. That contradiction is exactly why it has to be stated: left implicit, an agent summarising two weeks of entries would confidently report on ten of them.

No Quoting Ceremony

Quoting is one of the most reliable ways to make a generated command fail: nested quotes, shell escaping, an apostrophe in the message. So there’s nothing to quote.

`1`	`logger-txt add Had coffee with the team`

Arguments are joined into the message, which removes the whole class of failure and is pretty nice to type besides.

A Non-Interactive Path for Everything

A blocking prompt is a hung agent. It sits there waiting on stdin that will never come, and the turn dies on a timeout with no useful error. So delete asks for confirmation and delete -y skips it. This is the oldest advice on the list and the easiest to forget when you write the interactive path first.

Composable, Greppable Output

One entry per line on stdout, plain text on disk:

1
2

logger-txt show | grep MEETING
logger-txt show -c 50 | wc -l

The property I care about here is the escape hatch. When my CLI is the wrong tool for the job, the agent can ignore it entirely and read the log file directly. That was always the point of the plain-text format, though it pays off differently with a consumer that’s perfectly happy to grep a file when that’s the shorter path.

Loud Failure on Ambiguity

Passing --start without --end is an error with a clear message, not a guessed range. The temptation is to be helpful: assume “until now,” assume “for one day.” But a guessed range produces results that look correct, which puts us straight back into plausible-but-wrong.

Erroring out converts a silent wrong answer into an immediate, self-correcting retry. For an agent, a good error message beats a permissive default, since the error is information and the default is a coin flip.

Humans Get It for Free

Here’s the part I didn’t expect: I never once had to trade one consumer against the other. Every change on that list made the tool better for me at the terminal too.

I think the reason is structural, and it’s the most useful thing I’ve taken from the exercise. An agent is the worst-case human. No context, no accumulated intuition about the tool, no memory of the last time it hit this flag, no way to ask. Every affordance a human silently supplies from experience, the agent needs supplied by the interface.

Which means designing for the agent isn’t a parallel track to designing for humans. It’s designing for the strictest possible human, the one on their first day, at 2am, with no colleague to ask. Satisfy that reader and the experienced one is covered by construction.

So there’s no “agent version” of the interface to maintain, and I’d push back on the idea that this is extra work. It’s one interface, held to a standard that was always the right one, now with something that reliably tells me when I’ve fallen short of it. I knew search WORK and show -t WORK differed, since I wrote both. My tool’s ambiguities were invisible to me precisely because I held all the context that resolved them. The agent holds none of it, and it doesn’t have the good grace to quietly work around my gaps. It takes exactly the wrong turn my help text permits, immediately and repeatably, where I can watch it happen.

Why This Is Worth Practising Now

Logger-TXT is a personal tool. The stakes are that I mis-tally my hours one week, which makes it a pretty good place to practise something that gets expensive elsewhere.

The ratio is shifting, though. More and more of the tools I build, at work and otherwise, are going to spend most of their invocations being driven by something that can’t ask a clarifying question in Slack, can’t absorb the tribal knowledge in someone’s head, and can’t infer intent from a hallway conversation. The interface is all it gets, and if the interface is ambiguous then the tool is wrong in a way that looks right, at whatever scale the agent is operating at.

That’s a design discipline, and it’s worth practising deliberately before it matters. Which flags are confusable. Which defaults are guessable. Which prompts hang. Which errors teach. None of it is hard, it’s just invisible until you put something in front of the tool that can’t paper over your omissions with intuition.

If you want to poke at the result, it’s on GitHub, or brew install grantlucas/tap/logger-txt and run --help. If you try it with an agent and it takes a wrong turn I haven’t caught yet, let me know. Those are the gaps I can’t find on my own, since I already know what my own tool means.

I Built an App That's Only Useful Three Weeks a Year

Wed, 18 Feb 2026 20:00:00 -0500

How building from my phone exposed every point of friction in my workflow, and how I can make it better for all devices

Let me be upfront: the app I’m about to describe is useful for maybe three weeks out of the year. It helps you figure out when to tap a maple tree for sap. That’s it. The rest of the year it just sits there, waiting for February to roll around again. I can’t think of much else targeting such a specific, and time-limited, niche…

A year ago, I wouldn’t have built this. Not because it’s hard, but because the return on investment is laughable. A few weeks of utility for evenings of development time, if I finish it at all, is not worth it. I’d just check the weather forecast myself, squint at the overnight lows, and make a guess like I did last year. The motivation simply wouldn’t survive contact with the reality of actually sitting down to build it.

At the end of the day or on the weekend, at this point in my life, I just don’t have the time or remaining brain cycles, to work through software side projects when life’s already busy or I spent all day in meetings. But the cost of producing code has changed. And that changes which ideas I can tackle in the limited time I have available.

With many experiments, learnings, and changes to my flows over the past 6-8 months, I’ve produced more code than in the past 6 years since getting into management. Finally a lot of the ideas I’ve had can see the light of day as I can instead focus on the product/feature, secure deployments, smooth DevEx, and architecture of the thing I’d like to see. And each time through this process, whether at my computer, or now at my phone, I find points of friction I can smooth out so that next time it’s just a bit easier.

The Spark

I’d been having ongoing conversations with a family member about the impact of AI on software engineering: what’s possible now, what’s overhyped, where it’s actually headed. The kind of back-and-forth where you’re theorizing about the future but don’t have a great concrete example to point at. I’d been thinking about what simple, real app I could build to just show what’s possible instead of talking about it abstractly.

Then, sitting at dinner, talking about tapping maple trees (because it’s that time of year), the idea clicked. Last year I’d manually checked the forecast every day, trying to figure out when the freeze-thaw cycle was right for sap to flow. Lots of guessing, lots of doubt. Why not build something that does that automatically?

I pulled out my phone, opened the Claude iOS app, and started describing what I wanted using Wispr Flow for voice dictation. I gave it the problem I was trying to solve, a high-level overview of my understanding of how maple sap tapping works, and told it to do research so it could cite its sources. Then I let it work.

By the time I got home, maybe 20 minutes later, I ran npm run dev and had a working application. It detected my location, pulled a 7-day temperature forecast, and graded each day as poor, fair, good, or excellent based on the freeze-thaw cycle. It had information explaining how the cycle works, how the ratings are calculated, and a full section of sources and further reading based on the research it had done. Not a skeleton. A real app with real content.

That was pretty eye opening. Was it perfect? Definitely not. Did I trust it yet? Nope. Did it “work” and could I build from this? Oh yeah… Let’s iterate.

Note

This wasn’t my first attempt at building from my phone. I’d hit some friction on a prior project that taught me a fair amount about the workflow, like making sure your repo has a main branch before Claude tries to open PRs. I wrote up those learnings separately in Tips for Starting New Projects With Claude Code on iOS.

Getting to Production

Once I was home with the app running locally, the next step was getting it deployed. I connected a Cloudflare Worker to my GitHub repo so that every merge to main triggers a production deploy, with preview URLs enabled for pull requests. There were a couple of build issues to work through, and I had Claude move the project from vanilla JavaScript to TypeScript, which is what I would have preferred from the start. I just hadn’t caught it during that initial phone session because everything was happening so quickly.

Sidenote

That’s one of the trade-offs of the autonomous mode that Claude Code on iOS runs in. It’s not asking for permission as frequently as it does on desktop because it’s working in a sandboxed environment. The upside is speed: it moves fast and gets a lot done. The downside is that it might make a bunch of decisions and execute on them before you have a chance to review and steer it in a different direction. Though once you do steer it, it shifts pretty easily, so I’m not sure it’s actually a drawback so much as something to be aware of. 🤔

I was watching the output, bouncing between the Claude app and GitHub on my phone to see what commits were getting pushed. That back-and-forth between apps is the closest thing to a “review loop” you get on the phone.

One thing I made sure to do was have Claude create unit tests for the rating logic. The app was functionally showing me different ratings for different days, but I wasn’t confident it was correct until I could read through test cases. Once I could see “given this overnight low and that daytime high, the rating should be X,” I had a lot more confidence that it would work in reality.

Like a tale as old as time, good, clear unit tests, help enable an Agent to prove its work and help us humans build confidence in the underlying code.

The Iteration Loop, a Few Days Later

A few days passed. I had more ideas. Season timing estimates based on latitude, so if you haven’t had a good tapping window, you’d know when to just tap anyway before you miss the season. A map showing your location. Better error handling if location services weren’t working. Analytics and a feedback widget through PostHog so I could get basic analytics and collect feedback.

By this point, the development flow was established. Here’s what the loop looked like:

Open Claude on my phone
Describe the change I want
Claude writes the code, pushes a PR to GitHub
Cloudflare builds a preview URL within seconds
I review the changes in the preview on my phone
If something’s off, I go back to Claude, request changes, and it pushes to the same PR, and Cloudflare picks up the update automatically
Merge the PR, Cloudflare deploys to production

Rinse and repeat. The whole thing, from idea to production, could happen in minutes. And because each change was isolated in its own PR with a preview deployment, I could spin up multiple Claude sessions for independent changes and review them in parallel: one adding Gitleaks scanning, another adding help docs for location service issues, a third integrating PostHog.

In this round of iteration, the only thing I needed my laptop for was setting a new secret variable in Cloudflare for the PostHog API key. Everything else was done entirely through the feedback loop between Claude on iOS, GitHub, and Cloudflare.

What Went Well

Voice-to-code is surprisingly effective for greenfield work. Describing a new application out loud, conversationally, maps well to how you’d explain a feature to a colleague. I didn’t think about file structure or naming conventions. I described the problem and the desired outcome and let Claude sort out the implementation.

The research was genuinely good. I told Claude to research maple sap tapping and cite its sources. The result was an app backed by real references: academic papers, extension programs, established guides. For something I’m still learning about myself, having that research done and integrated into the app was valuable.

The phone-to-production cycle time was genuinely fast. Once Cloudflare was wired up, making a change and seeing it live took minutes. That’s competitive with, or better than, a lot of traditional workflows where you’d context switch to a terminal, run a build, push, wait for CI, and deploy. This was somewhat aided by Claude’s sandboxed, more autonomous mode.

PR-based workflow with preview URLs gave me confidence. Every change went through a PR. Every PR got a preview deployment behind Cloudflare Access. I could see exactly what the change looked like in a real environment before merging, and share preview URLs for feedback without exposing half-finished work.

Unit tests removed the doubt. Asking Claude to write tests for the rating logic helped the project go from “this looks right” to “I’m pretty sure this is right.” Being able to read through concrete test cases grounded the whole thing.

Where There Was Friction

Greenfield setup from a phone has gotchas. Repo creation, default branches, missing config files. I covered these in detail in the companion tips post.

The autonomous mode is a double-edged sword. Claude on iOS moves fast and doesn’t ask for permission as often. That’s great for momentum but means it can make a batch of decisions before you’ve reviewed the first one. Bouncing between the Claude app and GitHub to watch commits is the workaround, but it’s not the same as the more interactive desktop experience. This is definitely a pro and a con at the same time.

Secrets management breaks the flow. Every time I needed to add a new API key or environment variable in Cloudflare, I had to go to my laptop. This happened for Pirate Weather (a Dark Sky compatible weather API) and again for PostHog. It’s a small interruption, but it breaks the autonomy of the phone-based loop.

Infrastructure setup is still a laptop task. Configuring the Cloudflare Worker, setting up the custom domain, wiring up DNS, configuring Cloudflare Access for preview environments. All of that was done on the laptop the first night. It’s not a Claude Code limitation; it’s a “managing cloud infrastructure from a phone browser” limitation.

An App That Doesn’t Really Need to Exist (But Can)

The result is Sapcast. It takes your location, pulls real forecast data, and tells you when conditions are right to tap your maple trees. It rates each day, highlights the best tapping window, estimates season timing based on your latitude, and includes educational content with cited sources. All in a beginner-friendly way.

Last year I was guessing. This year I have an app backed by research that I can check in seconds. I’m also sharing it with other people who are into tapping to get feedback. I’m not 100% confident in my own understanding of all this, so getting real-world feedback matters.

Does this app need to exist? Honestly, no. People have been tapping maple trees forever without issue. But a year ago, the effort-to-payoff ratio would have killed this idea before I finished dinner. Now, the idea survived because the cost of going from “that would be neat” to “it’s live at a URL” has dropped to the point where three weeks of utility is enough. I didn’t have to carve out a weekend. I didn’t have to weigh it against other projects competing for my limited free time. I described it out loud at dinner and had something real by the time I got home.

That shift, from “not worth building” to “why not,” is the thing I keep coming back to. It’s not about this app specifically. It’s about all the small, niche, only-useful-to-a-few-people ideas that now clear the bar.

The Phone is Just a Litmus Test

I don’t want to do all my development from my phone. That’s not the point.

Building from a phone is an extreme scenario, and extreme scenarios are useful because they amplify every point of friction. On a desktop, you can work around a snag quickly enough that you don’t even register it as friction. On a phone, there’s nowhere to hide. Every rough edge stops you cold. Each of the friction points I listed above is a small inconvenience on a desktop but a real blocker on a phone.

That’s what makes it a useful experiment. If I can smooth out friction in an environment where any friction is hostile to the development flow, removing that same friction in a more amenable environment becomes trivial.

Template repos with sensible defaults
Automated preview deployments
PR-based workflows with visual review

All of that makes the desktop experience better too. The learnings transfer directly.

For me, this is a learning process I can apply back to my career. I’ve been thinking a lot about developer experience and reducing the distance between having an idea and seeing it running. The phone is just a litmus test. If the workflow holds up there, it’ll hold up anywhere.

The side benefit is that I can finally build some of the side projects I’ve been sitting on. The cost of going from idea to working software has dropped enough that even something useful for three weeks a year is worth doing. And the next time someone asks me what’s actually possible with AI and software engineering, I won’t have to theorize. I’ll just show them.