DevEx 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.

Tips for Starting New Projects With Claude Code on iOS

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

I’ve been experimenting with using Claude Code on iOS to build projects from my phone. It’s been a great learning experience, and I wrote about the broader experiment in I Built an App That’s Only Useful Three Weeks a Year. But before that project went smoothly, I hit some friction that’s worth sharing on its own.

Most of these tips are specific to starting greenfield projects from your phone. If you’re making changes to an existing repo that already has the right files in place, the experience is significantly smoother from the start.

Create Your Repo With a Default README

When you start a brand new project from your phone, you need a GitHub repo. The GitHub iOS app doesn’t let you create repos, so you’ll have to authenticate into GitHub in the mobile browser to do it.

Here’s the important part: have GitHub create a default README when you set up the repo. Not for the README content, but just to get a main branch.

Claude Code on iOS works in cloud-prefixed branches (starting with claude/). For reasonable security, it can’t create or edit the main branch or any other non-claude/ branch. If there’s no main branch when Claude pushes its working branch, that branch becomes the default branch of your repo. There’s no easy way to create a main branch from your phone after the fact. Not from the GitHub iOS app, not from the mobile web. It’s a mess to sort out, and Claude can’t help you fix it because of those same branch restrictions.

Set Up a CLAUDE.md Early

A brand new repo won’t have a CLAUDE.md or AGENTS.md file. On desktop, Claude Code has access to your global configuration file with your preferences for things like commit message conventions. On iOS, it doesn’t. So a new project has no context for how you like things done: commit style, language preferences, TDD, commit frequency, any of it.

On my first project from a phone, Claude defaulted to vanilla JavaScript when I would have preferred TypeScript. I just didn’t catch it because everything was moving so quickly in the autonomous mode. That’s the kind of thing a CLAUDE.md would have prevented.

Consider a Template Repo

I’m pretty confident now that the right move is to set up a template repo with sensible defaults for phone-first development:

A CLAUDE.md with your preferences (language, commit conventions, testing approach)
Basic Gitleaks workflows for secret scanning
Whatever project scaffolding makes sense for the kind of things you build

I haven’t built this yet, but it’s next on my list. The goal is to remove as much of the initial setup friction as possible so that starting a new project from my phone is as smooth as working on an existing one.

Override Git's User Email by Folder

Sun, 03 Mar 2024 15:19:19 -0500

Never forget to set your work email after cloning a work Git repository again!

When using a single computer for multiple categories of development (personal, work, etc), there is often a need to set a specific user.email value for each repository cloned depending on the use. For example, it’d make sense to use your work email for repositories cloned for work while you’d use your personal email for you own projects.

Without the following setup, it’s very easy to forget to override your user.email at a repository level and end up committing to one or the other with the wrong email attached. Though not the end of the world, I can imagine your company, coworkers, and security department would prefer to see your work email attached to all commits instead of a random Gmail account.

With the following in place, you’ll never forget to have the correct user.email set again!

Note

The following only works if you split up your repository clones within dedicated folders…which is probably better than mixing professional and personal repository together anyways.

.
├── personal
│   ├── repo1
│   └── repo2
└── work
    ├── repo1
    └── repo2

In your main ~/.gitconfig:

; Set your desired default name and email
[user]
    name = Bob Loblaw
    email = bob@home.com

; Override your user info, and anything else, depending on the folder you're
; currently in
; It's important this comes after anything you're overriding
[includeIf "gitdir:~/Development/work/**"]
    path = ~/.gitconfig_work.inc

Now in ~/.gitconfig_work.inc you can set your work specific information

1
2
3

[user]
    name = Bob Loblaw
    email = bob@work.com

With those configs, now any Git interaction within ~/Development/work/** will be done with user.email set to bob@work.com. No need for any local Git config overrides ever again to set common settings for work vs personal repositories.

A Git Alias for Keeping a Tidy Development Environment

Sun, 25 Feb 2024 22:07:36 -0500

Over time, whether working alone or in a team, your Git environment can become cluttered and messy with branches of the past, both local and remote. Though this isn’t an issue in the short term, if left alone, it can lead to time wasting mistakes, out of date code that doesn’t work once pushed to origin, and clutter in any Git tools or GUIs you may use leading to lower productivity.

How many local and remote branches do you see in one of your projects when you run git branch -a?

The following alias in your ~/.gitconfig will not only become second nature to use when updating your base branch, but it’ll keep your environment tidy at the same time.

[alias]
    update-main = !git checkout main \
        && git pull \
        && git remote prune origin \
        && git branch --merged | grep -v "\\\\*" | xargs -n 1 git branch -d

Now any time you want to begin work on a new branch, first run git update-main to not only update your main branch but also tidy your development environment. Then checkout your new branch and get to work.

It doesn’t really add any time to the process, has a lot of benefits by negating the problems below, and eventually becomes second nature to use any time you move over to a base branch.

Note

If your base branch is different, such as master or develop, add another instance of this alias with the proper replacements. Personally, I have 3 instances covering main, master, and staging which are often used in teams I’ve been on.

Once setup, they rarely change or need to be thought of again. I’ve been using these since around 2013 and I’ve rarely given them a second thought other than to share them with others.

Common Problems with a Messy Environment

Out of Date Base Branch

How often have you completed work on a new feature and pushed your code to Github only to find out your PR is already out of date? How?! It’s a brand new PR!

Well, it turns out locally you forgot to update your base branch (main) before checking out a new branch to start work on your new feature. There’s a high chance of this happening if you’re working within a team and commits are landing in the base branch frequently.

Though this is relatively inconsequential most of the time, the worst case would be that your code doesn’t work with the latest of the base branch at all! Though this would hopefully be very rare, it’s also easily avoided by keeping your environment tidy.

Git Clutter == Cognitive Load & Lower Productivity

Only slightly hyperbolic, a messy Git environment does decrease your overall productivity by making the tools you use to interact with Git slower to use. Whether it’s tab completion or GUIs visualizing branches, keeping a lot of stale or merged branches around adds no value and only presents downsides.

Alias Breakdown

Let’s go through some key points of some of the lines below for clarity and understanding.

[alias]
    update-main = !git checkout main \
        && git pull \
        && git remote prune origin \
        && git branch --merged | grep -v "\\\\*" | xargs -n 1 git branch -d

Running Shell Commands with `!`

By default every alias is expected to be a Git command. If you want to call git itself, you need to prefix the call with ! to indicate it should be calling a shell command instead of a Git command. So !git checkout main at the start of the alias will ensure it and the rest of the commands run as shell commands. No more git: 'git' is not a git command. errors.

Pruning Remote Branches

Over time branches will often be deleted from the remote origin during the natural development process. Your development environment however will not be kept up to date without either the right default configurations or manual calls as I’m using here. git remote prune origin will just ensure that any deleted remote branches are cleared from your development environment as well.

Note

Everything in this process works best if you delete remote branches after they’re merged. Though not fully required, there is no benefit to keeping merged remote branches around.

Pruning Merged Local Branches

`1`	`git branch --merged \| grep -v "\\\\*" \| xargs -n 1 git branch -d`

This is an interesting line in that it’s listing out all local branches that have no changes from the current branch and then deletes them. grep -v "\\\\*" is filtering out the current branch from the output of git branch --merged so that any other lines can be fed to the delete command.

Run this from your base branch

This works best when run from the base branch you’re updating (main) so using it within this alias is recommended. There’s no harm if it removes the local instance of main however, as it will just be re-checked out from remote the next time you need it.

I hope this alias, and some of the backing information, is useful to your every day development. There’s always something new and shiny in the world of software but I always find it interesting to reflect on those little things set up over a decade ago that are still used dozens of times per day and now couldn’t be lived without.

Progress & productivity doesn’t always have to be a search for a new tool or dependency, sometimes it’s just stitching together various commands into an alias that fits your flow, reduces mistakes, and makes your environment more enjoyable to work in.

DevEx on Grant Lucas

For Agents, --help Has to Be Enough

What “AI-Native” Means Here

The Constraint: --help Has to Be Enough

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

The Design Loop

The Trap I Built Myself

What Designing for the Agent Produced

Help Text That Teaches Rather Than Lists

Documented Defaults, Not Implied Ones

No Quoting Ceremony

A Non-Interactive Path for Everything

Composable, Greppable Output

Loud Failure on Ambiguity

Humans Get It for Free

Why This Is Worth Practising Now

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

The Spark

Note

Getting to Production

Sidenote

The Iteration Loop, a Few Days Later

What Went Well

Where There Was Friction

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

The Phone is Just a Litmus Test

Tips for Starting New Projects With Claude Code on iOS

Create Your Repo With a Default README

Set Up a CLAUDE.md Early

Consider a Template Repo

Override Git's User Email by Folder

Note

A Git Alias for Keeping a Tidy Development Environment

Note

Common Problems with a Messy Environment

Out of Date Base Branch

Git Clutter == Cognitive Load & Lower Productivity

Alias Breakdown

Running Shell Commands with !

Pruning Remote Branches

Note

Pruning Merged Local Branches

Run this from your base branch

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

Running Shell Commands with `!`