amanhimself.dev

Taking the terminal seriously in the age of AI coding agents

Fri, 28 Aug 2026 00:00:01 GMT

These days I am spending more time in the terminal app than any other environment on my development machine. Most of it comes down to using agentic harnesses such as Claude Code, Codex CLI, and more.

Previously, for the last two months, I have been using Otty terminal app and left my Ghostty setup in between. However, after constantly running across one or two frustrations with the app itself, I have decided to go back to use Ghostty as my main terminal app. By the way I still keep iTerm2 around as a backup.

In Ghostty, I have been using some preconfigured settings and updating configuration to my taste. I started with Solarized Dark Higher Contrast theme and here is how my terminal window looks like at the moment:

The configuration I have applied to Ghostty so far is minimal and to my own taste. I am not going to go into details about each configuration option in this post since I have already written a post a few months back about it.

Here’s my current Ghostty configuration:

# .config/ghostty/config

theme = Solarized Dark Higher Contrast

background-opacity = 0.9
background-blur-radius = 20

font-family = JetBrainsMono Nerd Font
font-size = 18
font-thicken = true

macos-titlebar-style = tabs

macos-option-as-alt = left
keybind = alt+left=unbind
keybind = alt+right=unbind

cursor-style = block
cursor-style-blink = false

shell-integration-features = ssh-terminfo,ssh-env
shell-integration = zsh
tab-inherit-working-directory = true
split-inherit-working-directory = true

window-decoration = true
window-padding-x = 8
window-padding-y = 6

confirm-close-surface = always

In the previous screenshot, the background blur and opacity are not noticeable but my desktop’s background wallpaper is slightly visible when I am using Ghostty. Solarized Dark with a higher contrast makes the text feel less dull in the theme itself and is something I want to give try for next few coming days before deciding to move to another theme.

There are multiple themes that Ghostty comes with and to view the list quickly, you can use the ghostty +list-themes command in a terminal window:

This list of themes is larger than the iTerm2 and I think the most I have ever seen included by default in a terminal app. Nice to see that people who spend time in terminals these days are taken care of by the Ghostty team.

Most of my daily workflow revolves around my work which is documentation and using agent harnesses. I switch between apps like terminal, GitHub desktop app, VS Code, and Obsidian a lot while I am working. I got curious recently about how much of my work I can shift to one single terminal app instead of switching between different apps. Claude Code and other harnesses moved me into the terminal land, to be honest.

We will see how it goes for me. Just wanted to share some quick thoughts before I dive deeper into the nerdy rabbit hole. If you have tips and/or suggestions what other part of my work I operate without leaving the terminal window, reach out to me.

Adding Content-Signal to a docs site

Mon, 24 Aug 2026 00:00:01 GMT

A few weeks ago I ran isagentready.com on docs.expo.dev, a site that I manage and work on, for my day job. One of the failed references during the check was the lack of Content-Signal policy in robots.txt file of the site.

Just for context, isagentsready.com is a tool that checks if a site is ready for AI agents to crawl and index, and is developed by Cloudflare.

What is `Content-Signal`?

Cloudflare announced the Content Signals Policy in September 2025 as an extension to robots.txt. It is one policy with three flags, each set to yes or no. In a nutshell, if you add it, this is what it looks like in your robots.txt file:

User-Agent: *
Content-Signal: search=yes, ai-train=no, ai-input=yes
Allow: /

The flags to pay attention in the above snippet are the following signals:

search which covers building a search index and returning results with links and short excerpts
ai-train which covers including training or fine-tuning LLMs
ai-input which covers feeding your content into a model at answer time. This is for retrieval augmented generation and AI search answers.

One thing to note here is that Cloudflare do mention that omitting a signal neither grants nor restricts permission. So, it is more of a nice to have, cover the grounds so your documentation site isn’t left behind.

Note: The reference site, contentsignals.org, describes the vocabulary as coming from a proposed IETF standard drafted by the AI Preferences (aipref) working group.

Why is this an auto-yes for a docs site

The content policy’s obvious audience is on of those publisher who wants to refuse. Documentation run on different economics and for many of us, docs is the product.

Adding this policy to your robots.txt file doesn’t replace the work you need to do to get answers picked from your docs site for AI Answer search engine optimization. You still need to apply other methods or audit your docs site using afdocs.dev to ensure your docs site is ready for AI agents. There are also other methods like exposing JSON-LD structured data and adding llms.txt, which I have written before in docs discoverability layers, and about adding llms.txt to this blog.

My impressions after using Claude Code for six months

Mon, 17 Aug 2026 00:00:01 GMT

Last time when I started to write this post, I got carried away. My brain was on verge of explosion because Claude and I had worked together on so many projects and stuff over the last six months.

My first interaction with the harness was in February 2026 when I started adopting it in my daily work and personal projects slightly more than Codex CLI. I went from having a large CLAUDE.md file in my global configuration to a smaller one that works 99% of the time.

I work on documentation and everything related to it in my day job. I have used Claude Code to help me with my daily tasks, adding/removing small pieces of content in docs, building tools to support my work and help me work faster, building tools to narrow the change of drifts, building personal apps with Expo and React Native, and so on.

The list is endless, but this time I am not going to get carried away while writing this post.

My first encounter with Claude Code

Before I started using Claude Code, I was using Codex CLI. I was quite satisfied with the amount of work Codex models were doing. However, my experience of interacting with an LLM via command-line app started to change slightly when I first used Claude Code for work and then slowly and gradually adopted it for personal use over the course first quarter of 2026.

I remember asking it vague questions, and it was quite chatty about it. Chattier and descriptive than Codex. Initially, it felt like having a smart rubber duck of my own that can do stuff for me and listen to me.

My first big project with Claude Code was to publish my first app Last time I on Google Play Store and Apple App Store. This was the nail in the coffin that I was looking. Just by telling it what I want to do, it went with me step by step to prepare and submit my app for app review processes on both app stores without making a single mistake. Yes, sometimes a particular settings or a page’s information it had was outdated, sharing screenshots on what was in front of me, back and forth, cleared that huddle.

If you have never published your app or went through the process of publishing an app, it can be daunting and overwhelming for the first time. Using Claude to guide you through the process as well as also learn from it about the niche points of publishing an app, the experience becomes less daunting and more learning. And if you want to go extra mile, you can give Claude access to your Android emulator or screenshots to produce decent looking app store assets without having an external skill or putting to much effort. It will generate those assets in the appropriate size (which is what I did with my second app: RHT - Reading Habit Tracker).

Quick impressions of using Claude Code

Here are some of my thoughts that I would say are some of the significant Claude Code impressions I have observed:

I am currently subscribed to Claude Code via their Open Source program which gives access to Max plan.
I appreciate the verbosity but sometimes it is too much.
Fable is quite different. Even after using Opus 5, Fable is a bit clever and approaches a problem differently.
Opus is smart enough most of the time for most complex tasks.
I need to try Sonnet more.
Fable consumes a lot of tokens that is true but gets the work done.
You can build a decent mobile app by orchestrating Claude Code.
Love the artifacts to visualize options for a task I am working on and how that feature is also integrated in Claude Code. It has been time saver on some of the recent projects I have worked on and I’d like to continue using it more.

From plan mode to auto mode in Claude Code

Sun, 09 Aug 2026 00:00:01 GMT

I am using Claude Code since February 2026 and recently I have completely stopped using “plan mode” in Claude Code most of the time and using “auto mode” most of the time during my workday.

Is plan mode necessary?

The feature plan mode was introduced in Claude Code on June 5, 2025 in v1.0.14. It was initially shipped quietly.

I think plan mode is necessary when I am exploring something from scratch or I want Claude to plan a series of tasks that I can come back to, in another session or on different system. I also think plan mode plays role when I, the user, have to make a decision and I don’t want to delegate that part to Claude. It acts as a guardrail that prohibits editing files in a codebase.

I want to control interactions

Although, another workaround I have found when exploring something, is to ask Claude Code explicitly “to not touch or edit any file…”. This works 100 percent of the time with new top frontier models like Opus 5 and Fable 5 and doesn’t require me selecting plan mode in Claude Code.

This is also known as being a human-in-the-loop. Some of the ways I indulge in interactions is by adding one of the following in a prompt:

“list all options I have to do this task”
“do not edit any files and list/discuss options”

The emphasis here is to have Claude list all the options before I proceed on a given task. After it lists all the options to do X task, I can interact with by asking questions and offer personal opinions and select the direction I want it to go to perform the action. This way, you can also say, the person initiating the Claude Code session becomes the orchestrator.

Multiple back and forth exchanges are required for the complex tasks or larger tasks in my opinion. Without having any sort of interactions I won’t know what is Claude working on and I still don’t completely trust LLMs to make decisions on their own, all the time.

If not plan mode, then what mode am I using?

In most sessions with Claude Code, I am using auto mode. I have multiple sessions open at one time in my terminal app and I try to go through them as quickly as I can be depending on the nature of each session. I only want to be a bottleneck where my attention is required.

For example, a documentation pull request (PR) review can be done with my custom skill. It doesn’t require my attention when I have given the context. A session can itself trigger the skill and have the review ready in the pending state. My attention in this process is only required when the comments on the PR are posted in the pending the state on GitHub. Then, I can go through what Claude posted and if there’s anything I have to add further for the benefit of the PR author.

Another example of using auto mode is when I have already investigate the problem and have a good idea on how to solve it. Consider a linear issue with an appropriate title and a description that contains enough context for an LLM to go through and implement the solution. I have also instructed Claude to check out a Git branch based on the Linear issue and then proceed with the rest of the issue. This way, I am not the bottleneck and the approach works for low and/or none complex tasks.

2026 - half year in books

Wed, 05 Aug 2026 00:00:01 GMT

In 2026, I set a goal to read 26 books. I had the lowest expectations of myself, and I stayed true to those expectations, because in January I did not read anything.

I started reading in February, which is why I decided to write a six-month review of my 2026 books at the end of July.

So far, the first six months of reading have been sustainable. I completed my 26-book to read in a year goal, in July. If you are curious, I use Goodreads to track my reading challenge and the books I read.

I won’t list every book I read this year, but like every other year, I do have some recommendations:

Warbreaker by Brandon Sanderson: An absolute delight to read. Hook after hook after hook. I expected a slow start from a 600+ page fantasy, but there isn’t one. Sanderson gives you a man arguing with his sword, two sisters swapped into the wrong lives, and a magic system built on the selling and purchasing of air. I don’t know how he does it, but I am eager for more Sanderson works.
A Wanted Man by Lee Child: Lee Child’s writing style is terse, and his hooks kept me going. Jack Reacher is also a well-developed character who has some mystery about him. And that is the mystery I wanted to solve. I don’t know why I started with book number 17 in the series, but once I picked it up and got going, it never felt like I was reading the 17th book in a series. This was also the first paperback I bought and finished this year.
Odyssey by Stephen Fry: If someone manages a shelf where they list all the books that retell a story thousands of years old with elegance and easy-to-digest prose, then this book should be on that shelf, in the first row.
Docs as Tests & AI by Manny Silva: If you write or manage docs and want to explore how the docs world is changing in 2026, how it is influenced by LLMs, and how to test your docs deterministically and probabilistically, then this book is for you.

Other stats

The following stats are provided by Goodreads on my account:

Total books read: 26
Pages read: 5263
Longest book: Warbreaker by Brandon Sanderson

Wrap up

I am glad I have completed my reading challenge. At the same time, I am eager to read more.

Finally, I have acquired a taste for reading Brandon Sanderson’s books, and I do think highly of him after finishing Warbreaker. I can say it now: I get why he’s famous. I think I’ll be diving more into fantasy as a genre. Maybe I’ll go back to Wheel of Time series after 7 years, which I left half-way. Only time will tell.

Reach out to me. I’d love to hear about some of the books you have read this year or would like to recommend. My ever-growing and never-ending TBR list is waiting :)

Notes that can never be atomic

Wed, 22 Jul 2026 00:00:01 GMT

Every guide to atomic notes eventually meets the same objection: most of what I write cannot be atomic. A meeting note is a list of actions and a transcript of a specific day. It’s an event. A project plan is a spec file that contains decisions and at times, serialized tasks, glued together. I do think if a system demands everything become atomic, that system quickly becomes useless.

In Sönke Ahrens’ description of the Zettelkasten workflow, permanent atomic notes are the output of a pipeline, not the only format allowed to exist. The original system never demanded that.

Fleeting notes capture and source-bound notes feed the pipeline and remain themselves. They are only as useful till I reach the output. This is why the kind of note file should live inside different folders. They have different life cycles.

How to set a custom folder order in Obsidian

Wed, 15 Jul 2026 00:00:01 GMT

Obsidian’s file explorer sorts folders alphabetically. The sort menu offers file name, modified time, and created time, and nothing else. There is no built-in way to arrange folders by hand.

For my Obsidian vault, I like to see the organization in a specific way. For example, I like to keep the inbox folder at the top since it contains files I capture quickly for any reason during the day.

I also have a _meta/ folder where I keep a short note on how my vault’s folder structure is organized and why it is that way, along with my templates. This folder isn’t part of the main structure, but seeing it at the top irks me a little every time I open the Obsidian app.

Another folder I have is archive, which I want to be the last folder in my structure. Its only use is to keep retired notes that I don’t want to delete yet.

Overall, here’s the structure I have in mind:

inbox
notes
sources
blog
projects
journal
writing
archive
... any other folder

I have written why I organize my vault this way in A minimal Obsidian vault structure that sticks.

And the current structure of my vault looks like this:

The fix is to use the Custom File Explorer sorting plugin, which has around 184k downloads, so it seems like a popular plugin. However, I came across it for the first time only recently, probably because I accepted a long time ago that there was no way to custom sort folders in Obsidian. In previous versions of my vault, I relied on emojis.

To install it, open Settings, select Community plugins, and choose Browse. Search for “Custom File Explorer sorting”, install it, and enable it. The plugin adds an up-and-down arrows icon to the ribbon.

The icon is a toggle and it being grayed out means the plugin is suspended and the sidebar falls back to Obsidian’s default sorting, highlighted means the custom order is active.

There is no drag-and-drop settings screen. Instead, the plugin reads the order from a regular note, which suits a vault that lives in git: the sidebar order becomes a versioned file like everything else. I created the note at _meta/sortspec.md and declared the order inside a sorting-spec frontmatter property:

---
sorting-spec: |-
  target-folder: /
  inbox
  notes
  sources
  blog
  projects
  journal
  writing
  archive
---

The target-folder: / line scopes the rules to the vault root. The lines after it are folder names, top to bottom, in the exact order I want them in the sidebar. Any folder I leave out keeps the default alphabetical sorting and lines up below the listed ones. That covers the “any other folder” part of my list without any extra configuration.

The Custom File Explorer sorting plugin has made a huge difference in organizing my notes inside my Obsidian vault.

A minimal Obsidian vault structure that sticks

Wed, 08 Jul 2026 00:00:01 GMT

My Obsidian vault has 291 notes captured over the last three years. Some are long-form notes, prompts for tools like Claude Code, or quick captures from reading on the internet.

When I created this vault, I started with 8 folders, but over time the number has grown to 16. I like to keep this vault minimal so it stays useful, but a lack of timely archiving has turned it into a disorganized mess.

My quick capture system was a single file called _inbox.md, which grew to 139 KB across 23 sections titled by week over six months. Each section held whatever I threw at it. As a system for thinking, it was a graveyard with good intentions.

Last weekend, I spent a few hours organizing the vault before things got further out of hand. The first problem I tackled was getting the folder structure back to minimal and useful.

Existing systems aren’t enough

Over the last 5 years, I have tried keeping up with the PKM and Obsidian communities and have spent countless hours trying to understand systems like PARA, Zettelkasten, Johnny Decimal, or a hybrid of all three.

After reading the comparisons and trying to apply them to whatever my notes looked like at the time, I ended up dissatisfied.

Folders encode lifecycle, links encode topics

One common pattern I took away from the existing systems:

A folder should answer what kind of note is this, and where should it live?
A folder should not answer what topic is this about?

Topics belong to links. A note about a technical documentation approach belongs to “docs testing” and “CI” at the same time, yet it can only sit in one folder.

Forcing topics into folders creates friction: every capture begins with a filing decision, which gets in the way of capturing the information at all.

The solution is to let links carry topics and meaning, and let folders group notes by their kind. Obsidian Rocks argues folders should manage workflow, not subject. Andy Matuschak goes further and argues hierarchies fuzz conceptual edges because they force singular placement.

The honest counter-position is Steph Ango, Obsidian’s CEO, who avoids folders almost entirely and organizes with properties and links alone. I respect all of the above creators’ methods, but avoiding folders altogether horrifies me.

Not because I can’t, but because I use my Obsidian vault not only to capture information but also to do my long-form writing. The post you are reading started as a Markdown file in the vault named “Untitled 2” (I couldn’t come up with a title at the time).

From now on, I am going to call them lifecycle folders and treat them as the lifecycle of my system. I consider them training wheels that might never come off.

How many folders is too many?

This is my current entire structure, annotated with the rule that keeps each folder honest:

Folder	Holds	The rule
`inbox/`	Every capture	Emptied every Saturday
`notes/`	Atomic notes	Flat, no subfolders, titles are claims
`sources/`	Literature notes	One note per book, article, or talk
`journal/`	Daily and meeting notes	Sources to mine, never things to convert
`projects/`	Active work, drafts in progress	The only survivor from the old structure
`blog/`	Finished drafts	Final drafts for my blog, ready to publish
`writing/`	Personal writing	Long-form stays long-form
`archive/`	Everything retired	Keep, don’t delete

I also created a _meta/ folder that contains my templates, plus a README.md that holds the table above.

Why? As a reminder to myself of why the vault is structured this way and as context for tools like Claude Code when they access my notes from a terminal session.

How I track my token maxxing

Sat, 30 May 2026 00:00:01 GMT

Back in February 2026, I wrote two posts about how I am tracking Codex CLI and Claude Code token usage. During that time, I used both CLI agent tools for work and personal projects.

Both posts used a tool called ccusage and its variant (at that time), @ccusage/codex. ccusage is created by ryoppippi and is a popular command-line tool to analyze coding agent token usage and costs from local data that lives in your Claude or Codex sessions. It also support other CLI agents and its latest version provides daily, weekly, monthly, or session usage stats.

It’s latest version also allows seeing the combined usage stats from Claude and Codex. All I need to do is run the following command:

bunx ccusage

And the output would be:

Date	Agent	Models	Input	Output	Cache Create	Cache Read	Total Tokens	Cost (USD)
2026-05-30	All		407.2K	334.5K	933.6K	17.3M	18.9M	$33.55
	Claude	opus-4-8	71.5K	305.4K	933.6K	11.0M	12.3M	$19.32
	Codex	gpt-5.5	335.7K	29.1K	0	6.3M	6.6M	$14.23

Recently, I found about tokscale, which is created by junhoyeo. It pulled me in from the first use because it provides more insights with a heatmap and daily session usage in a single dashboard and I don’t have to remember different command-line options.

The default bunx tokscale opens an interactive TUI where you can navigate between Tokens per day/hour view, Models, Stats, and per agent.

The above is my favorite screen from the TUI because it clearly allows me to see the total tokens and cost estimation summaries for each model I have used on my machine since December 2025.

tokscale also comes with a --light version, which allows viewing the above information quickly.

Since those two posts back in February, checking this has quietly become a habit. ccusage is still my quick check when I just want a number in the terminal, and tokscale is the one I open when I want to look around, mostly for that model summary screen and the heatmap.

I do feel like I am in early days of using these agent tools and there is no way I am bothered about the pricing and usage. I hardly ever hit my 5 hour session limit with my current subscriptions. Maybe I am not really token maxxing. However, I do like that both tools are useful tool in what they do and provide me an insight on how much tokens consumed for a given day or session. I am sure as I use these tools more, I will find more insights and patterns in my usage. If you are using these agent tools, I highly recommend checking out both ccusage and tokscale to get a better understanding of your token usage.

Moving away from Oh My Zsh (OMZ)

Thu, 14 May 2026 00:00:01 GMT

I’ve been running Oh My Zsh (OMZ) on every workstation I’ve ever owned. It was one of the first things I’d install when setting up a new machine or cleanly updating an existing one. For years, I’ve blindly copied my workstation configuration from one Macbook to the next, without questioning whether I still needed something in the current day and age, or whether it had quietly been replaced by something better.

The first time I wrote about my setup was in 2023 and since then I’ve written about it every year: 2024 and 2025 and recently in 2026. The last post is a result of me taking my time and making conscious decisions. Somewhere in that process, I realized that my setup and especially my terminal setup, was bloated.

That realization has been growing strong over a period of last few months. I didn’t have the time to act on. But a few weeks back, I reconfigured my Starship prompt and wrote about it. During the process, I opened up .zshrc to do some cleanup and that is when I noticed I had quietly stopped using Oh My Zsh a while ago, and don’t need it anymore.

Started in 2009 by Robby Russell as a personal config, OMZ solves a real problem when Robby was asked by his coworkers on setting up zsh on their machines. Rather than walking them through the same commands every time, he packaged his dotfiles into a single install.

That is the exact problem OMZ has solved for me. Especially, the plugins were my favorite feature even though I’ve narrowed it down to only four plugins:

plugins=(
    git
    node
    vscode
    direnv
)

ZSH_THEME="robbyrussell" was commented out. Had been for over a year, since Starship started running my prompt. Auto-updates were disabled. zsh-syntax-highlighting was being sourced manually, with its full path written by hand, sitting outside the plugin system entirely

However, now when I am writing it, I am realizing it I never took its advantage to full. Primarily, because adding more plugins would slow down the shell startup. I use iTerm2 and recently started using Ghostty as well, and the shell startup was noticeably slow in both. I haven’t done the profiling with zprof but a friend of mine, Scott Spence has written about it here Speeding Up My ZSH Shell. Go read it if you are interested about the details and you might end up listening to the tips Scott has to share.

After replacing Oh My Zsh framework, here’s how my .zshrc file looks like. It has more alias that I use daily and less configuration:

export PATH=/opt/homebrew/bin:$PATH

# Required for Expo and React Native local app development
export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home

# Android specific paths after installing Android Studio
export ANDROID_HOME="$HOME/Library/Android/sdk"
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools

# To stop brew from auto updating
export HOMEBREW_NO_AUTO_UPDATE=1

## Compilation flags
export ARCHFLAGS="-arch x86_64"

## Enable AUTO_CD to automatically change to a directory when you `cd` into it
setopt AUTO_CD

## Opening various directory
alias g="cd $HOME/github/"
alias n="cd $HOME/github/notes/"

## Show touch on iOS simulator
alias showtouch="defaults write com.apple.iphonesimulator ShowSingleTouches 1"

## Hide touch on iOS simulator
alias hidetouch="defaults write com.apple.iphonesimulator ShowSingleTouches 0"

## Show/Hide hidden files in Finder
alias show="defaults write com.apple.finder AppleShowAllFiles -bool true && killall Finder"
alias hide="defaults write com.apple.finder AppleShowAllFiles -bool false && killall Finder"
alias killds="find . -type f -name '*.DS_Store' -ls -delete"
alias kdock="killall Dock"

## git shorthands
alias gall="git add ."
alias ga="git add"
alias gc="git commit -m"
alias gs="git status"
alias gpush="git push -u origin"
alias glog="git log --oneline --graph --decorate --color"
alias gap="git add -p"
alias gck="git checkout"
alias gb="git branch"
alias gslog="git shortlog -s"

eval "$(/opt/homebrew/bin/brew shellenv)"

# Starship
eval "$(starship init zsh)"

# mise
eval "$(mise activate zsh)"

# Enable syntax highlighting
source $(brew --prefix)/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

OMZ solved a real problem for me for a long time. It collected the good parts and gave me a single install command. For its time, it was a genuinely useful piece of software, and it deserves credit for the role it played in making zsh approachable when I had no idea what I was doing.

New blog theme again

Sat, 09 May 2026 00:00:01 GMT

In January 2025, I shared an update on updating the blog theme and code block themes. The Astro setup that builds this blog uses Shiki, which makes it easier to switch between any supported code theme.

What about the blog’s primary and accent colors?

In the age of LLMs, it has to be quick update right? Yes, I used Claude Design screenshots to the previous version of this blog and with some instructions like using a specific saturated blue color. It iterated over four themes.

I have to say Claude Design is impressive. It read my old-blog screenshots like a reference, and let me steer through chat, inline comments, and adjustment sliders it generated on the fly for whatever I was tweaking. When I was done and got the idea for which direction to pick, I came back to the Claude Code in the terminal window, who was waiting for me. I took those designs, told Claude Code to tone down a bit and ended up with the current theme of the blog.

When using Claude Design, make sure to keep an eye on its usage limit. It burns out fast since it likes to overdo the initial instructions or fails to follow the exact prompt.

Here’s one example where I let it run wild and it ended-up turning my blog into a complete magazine:

And then, into a newspaper:

Updating your blog’s theme might sound trivial with tools like Claude Design to come up with something to your liking and Claude Code to implement it your codebase. What important now is where you draw the line.

Week notes 17

Sun, 03 May 2026 00:00:01 GMT

A heavy week on the docs side. Two things shipped that I had been chewing on for a while, and a couple of small skills came together. Some reading and writing on the side too.

🧪 Built a docs-ja-translator skill and landed the Japanese tutorial pilot at work. The skill takes an existing MDX document from Expo tutorial, mirrors it under pages/ja/<same-path>, preserves frontmatter, JSX tags, code blocks, and link URLs, and translates the prose, headings, link text, and string-valued props into Japanese.
💼 Shipped per-page Markdown serving on docs.expo.dev (/page.md sibling paths), implemented as a Cloudflare Worker rewrite so it works in previews too. I documented the worker behavior in the docs README for AI agents.
💻 Switched the light-mode code theme on this blog to GitHub Light so it matches the rest of the page.
📚 Read Kepano’s stephango.com/vault post and compared his ideas to my vault’s structure. Most of what I keep in the vault are personal notes, blog post drafts, projects and blog post ideas that are work in progress, some attachments, and work meeting notes. Recently, I have been using the vault as context management system for Claude, especially when I am exploring some idea or skill generation.
🔗 Podcasts
- Listened to Agent-Harness.ipynb* with Vincent Warmerdam and found the discussion around keeping a physical notebook for jotting down thoughts and creating plans on how to steer an agentic task interesting.
- Listened How valuable are agent skills? Conversation with Larah Vasquez and Fabrizio Ferri-Benedetti is an interesting discussion on the value of agent skills. I was also curious to hear on how other technical writers/docs engineers are creating/using skills with agentic tools.

Playwright to Chrome

Sun, 19 Apr 2026 00:00:01 GMT

Back in January, I had just started using Codex CLI and Claude Code. I was spending more time with Codex CLI and ended up creating a small Expo and React Native app as well. As I was learning how to use these tools, I wrote about using Codex CLI with Playwright for browser automation tasks in First Few Days with Codex CLI post.

The approach I discussed initially, worked for me for some tasks by setting up Playwright MCP and managing its browser extension. However, the approach isn’t flawless. Any time, Playwright MCP gets an update or its browser extension does, each requires to make a new connection to exchange token between them. The token mechanism is what Playwright MCP and its Chrome extension use to connect Codex CLI or Claude Code.

At the time of writing this post, Claude Code has already announced a beta feature called /chrome and have released their Chrome extension. This changed a few of my workflows. Instead of orchestrating a headless browser extension and MCP through Playwright, Claude Code now uses its own tools which I had to authorize only once when I enabled /chrome.

Another cool thing about Claude Code’s approach I have found so far is that I don’t have to maintain or manually update Claude Code or Claude’s browser extension and go through the process of setting them up again.

My Mac setup

Sat, 18 Apr 2026 00:00:01 GMT

In past I have documented my entire setup when I switched to MacBook Pro with Apple Silicon in December, 2020. Since then I have also documented my setups on different MacBooks with adjustments and changes. This guide is mostly about my latest setup, which includes using tools from AI and some new tools on my Mac.

Initial setup

First few things I like to set up or configure are the system settings and install essential tools that are required for my daily workflow.

Updating macOS

As usual after logging in, I have to ensure the macOS is on the latest version. This time I decided to upgrade it to macOS Tahoe.

Xcode and Command Line Tools

The following tools must be installed before proceeding with the rest of the guide:

Xcode: Open App Store, install Xcode. It’s a large download and will take awhile.
Terminal: iTerm2 as the primary terminal app.

After the Xcode installation finishes, install Command Line Tools. Open the terminal app and run:

xcode-select --install && sudo xcodebuild -license

Let’s verify that Command Line Tools have been installed properly and install iOS simulators (only required if you are into mobile app development):

Verify Command Line Tools installation: Open Xcode from the menu bar, go to Xcode > Preferences > Location, and make sure that Command Line Tools point towards the current Xcode app.
When opening Xcode for the first time, you’ll be prompted to select platforms for development. Select iOS 26.2 and click Download and install to download iOS simulators.

The initial setup is complete! You’ve now reached a point where you can proceed further.

Fix the default macOS settings

In my previous setup guides, I went through each setting manually in the System Settings app. This time, I’m using defaults write commands in the terminal to apply them all at once.

Dock

# Automatically hide and show the Dock
defaults write com.apple.dock autohide -bool true # false for other devices

# Disable suggested and recent apps in Dock
defaults write com.apple.dock show-recents -bool false

# Set Dock size to 30%
defaults write com.apple.dock tilesize -int 36

# Enable magnification and set to ~50%
defaults write com.apple.dock magnification -bool true
defaults write com.apple.dock largesize -int 54

# Disable automatically rearrange Spaces
defaults write com.apple.dock mru-spaces -bool false

# Disable click wallpaper to reveal Desktop
defaults write com.apple.WindowManager EnableStandardClickToShowDesktop -bool false

# Disable Widgets
defaults write com.apple.WindowManager StandardHideWidgets -bool true

# Disable all hot corners
defaults write com.apple.dock wvous-tl-corner -int 0
defaults write com.apple.dock wvous-tr-corner -int 0
defaults write com.apple.dock wvous-bl-corner -int 0
defaults write com.apple.dock wvous-br-corner -int 0

# Restart Dock to apply changes
killall Dock

Finder

# Show hidden files
defaults write com.apple.finder AppleShowAllFiles -bool true

# Show Path Bar and Status Bar
defaults write com.apple.finder ShowPathbar -bool true
defaults write com.apple.finder ShowStatusBar -bool true

# Show filename extensions
defaults write NSGlobalDomain AppleShowAllExtensions -bool true

# Set new Finder windows to open in Downloads
defaults write com.apple.finder NewWindowTarget -string "PfLo"
defaults write com.apple.finder NewWindowTargetPath -string "file://${HOME}/Downloads/"

# Disable .DS_Store files on network and USB volumes
defaults write com.apple.desktopservices DSDontWriteNetworkStores -bool true
defaults write com.apple.desktopservices DSDontWriteUSBStores -bool true

# Show hard disks on desktop
defaults write com.apple.finder ShowHardDrivesOnDesktop -bool true

# Hide CDs, DVDs, and iPods on desktop
defaults write com.apple.finder ShowRemovableMediaOnDesktop -bool false

# Show Library folder
chflags nohidden ~/Library

# Restart Finder to apply changes
killall Finder

Keyboard and input

# Key repeat rate: Fast
defaults write NSGlobalDomain KeyRepeat -int 2

# Delay until repeat: Short
defaults write NSGlobalDomain InitialKeyRepeat -int 15

# Disable autocorrect
defaults write NSGlobalDomain NSAutomaticSpellingCorrectionEnabled -bool false

Trackpad

# Enable tap to click
defaults write com.apple.AppleMultitouchTrackpad Clicking -bool true

# Set tracking speed (0.0 to 3.0, default is 1.0)
defaults write NSGlobalDomain com.apple.trackpad.scaling -float 2.5

# Disable natural scrolling
defaults write NSGlobalDomain com.apple.swipescrolldirection -bool false

# Disable force click and haptic feedback
defaults write com.apple.AppleMultitouchTrackpad ForceSuppressed -bool true

# Enable secondary click with bottom right corner
defaults write com.apple.AppleMultitouchTrackpad TrackpadCornerSecondaryClick -int 2
defaults write com.apple.AppleMultitouchTrackpad TrackpadRightClick -bool true

# Disable Look up & data detectors
defaults write com.apple.AppleMultitouchTrackpad TrackpadThreeFingerTapGesture -int 0

# Disable swipe between pages
defaults write NSGlobalDomain AppleEnableSwipeNavigateWithScrolls -bool false

Lock Screen and Battery

# Set screen saver to start after 1 hour (in seconds)
defaults -currentHost write com.apple.screensaver idleTime -int 3600

# Set display off on battery after 3 hours (in minutes)
sudo pmset -b displaysleep 180

# Set display off on power adapter after 3 hours (in minutes)
sudo pmset -c displaysleep 180

# Disable slightly dim the display on battery
sudo pmset -b lessbright 0

Other

# Disable Siri
defaults write com.apple.assistant.support "Assistant Enabled" -bool false

A few settings still need to be changed manually in System Settings:

Privacy & Security > FileVault: Turn on
Spotlight: Disable all search categories except Apps, Files, Folders, Menu Items, Calculator, Conversion, Dictionary, and System Settings
Trackpad > Point & Click: Set click to Medium
Finder > Tags: Switch off all

Install Homebrew: macOS package manager

An important step in installing development-related tools is using Homebrew, a package manager I’ve trusted for nearly eight years.

To install Homebrew, open iTerm and run the command:


/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After installing, add the Homebrew to the PATH:


echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/username/.zshrc

eval "$(/opt/homebrew/bin/brew shellenv)"

Note: If you don’t have a .zshrc, create one at /Users/username/.

Then, add the following to .zshrc:


export PATH=/opt/homebrew/bin:$PATH

Install apps from Homebrew bundle

I keep a list of must install apps in a Homebrew bundle inside my dotfiles repo. Download the file from the repo and run the following command to install the apps:

brew bundle --file=brewfile.sh

Tip: Git is already installed as part of Xcode Command Line Tools. However, I prefer to install the latest version from brew and avoid using the outdated version installed by Apple. After installing git, run git --version in a new terminal window. If you run this command in the same terminal window, it will show the Apple Git version.

Git global configurations

After installing Git, apply the following global configurations:

Set up the default branch for any new project to main (This was introduced in Git version 2.28):

git config --global init.defaultBranch main

Enable colors in command output:

git config --global color.uni auto

Set up real name and email:

git config --global user.name "Real name"
git config --global user.email email@domain.com

To check or verify the global git config, run:

git config -l --global

Configure .zshrc

In previous setup guides, I used Oh My Zsh as a shell framework. This time, I’m skipping it entirely. I already use Starship for my prompt, so Oh My Zsh was just adding shell startup lag for features I wasn’t using. The only plugin I need is syntax highlighting, which can be installed directly via brew.

Install zsh-syntax-highlighting:

brew install zsh-syntax-highlighting

The key additions to .zshrc:

# Auto cd into directories without typing cd
setopt AUTO_CD

# Mise (version manager for Node.js, bun, pnpm)
eval "$(mise activate zsh)"

# Starship prompt
eval "$(starship init zsh)"

# Syntax highlighting (must be last)
source $(brew --prefix)/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

Copy the full .zshrc from dotfiles to ~/.zshrc.

Configure Starship prompt

I have been using Starship as my command line prompt for a while now. It’s fast, configurable, and works across shells.

Since Starship is already installed from the brew bundle step, copy starship.toml from the dotfiles repo to ~/.config/starship.toml.

Configure iTerm

Open iTerm > Preferences > Profiles and Import iterm-default.json from dotfiles repo.
Profiles > Terminal > Show mark indicators > Disable.
Text > Font, select JetBrainsMono Font.
Text > Non-ASCII Font, select JetBrainsMono Nerd Font.
Appearance > General > Theme > set to Minimal.
General > Selection > Clicking on command selects it to restrict Find and Filter > Disable.

Setup a primary web browser

By now, you will need a primary web browser to set up and do some things further.

Chrome for work
- Log in to work email
  - Extensions: 1 Password, Cuik SEO, and Harper
Chrome Canary for personal
- Log in to personal email
  - Extensions: 1 Password, Cuik SEO, and Harper

Shared configuration or steps required in both browsers

Create a Google meet, and share and record the screen. This will get all required permissions to be working, and you don’t have to restart the browser in an actual meeting.
Log in to GitHub, Gmail, and Calendar.

GitHub setup and configuration

To configure an account on GitHub.com and use an SSH key, follow the steps from GitHub documentation:

Install Node.js, bun, and pnpm

In previous setup guides, I used NVM (Node Version Manager) to install and manage Node.js versions. This time, I’m using mise, a polyglot version manager written in Rust. It replaces nvm, pyenv, and similar tools with one consistent interface. It’s faster (no shell startup lag), auto-switches versions when you cd into a project, and reads existing .nvmrc files.

Since mise is already installed from the brew bundle step, activate it in the shell:

echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
source ~/.zshrc

Install Node.js, bun, and pnpm:

mise use --global node@lts
mise use --global bun@latest
mise use --global pnpm@latest

Verify the installations:

node --version
bun --version
pnpm --version

After installing Node.js

Node.js comes with the default package manager npm. Set defaults for it:

npm config set init-author-name "your name"
npm config set init-author-url "example.com"
npm config set init-license MIT

Install global npm packages:

npm i -g eas-cli

Useful mise commands

# Update Node.js to latest patch
mise upgrade node@22

# Install a different version for a specific project
mise use node@20

# List installed tools
mise ls

# List available remote versions
mise ls-remote node

VS Code

My current setup supports JavaScript, TypeScript, Node.js, React, React Native, Expo, and documentation work.

Setup VS Code as the default editor

After installing VS Code from the brew bundle step, open it and set up the code command in PATH. Open the command palette (Cmd + Shift + P) and search for Shell Command: Install ‘code’ command in PATH.

Settings

Copy the vscode_settings.jsonc from the dotfiles repo to ~/Library/Application Support/Code/User/settings.json.

Here is what the settings file includes:

{
  "editor.tabSize": 2,
  "workbench.editor.tabSizing": "shrink",
  "editor.cursorBlinking": "phase",
  "editor.fontLigatures": false,
  "editor.wordWrap": "on",
  "editor.cursorSmoothCaretAnimation": "on",
  "editor.tabCompletion": "on",
  "editor.formatOnPaste": true,
  "editor.formatOnSave": true,
  "git.openRepositoryInParentFolders": "always",
  "editor.semanticHighlighting.enabled": true,
  "editor.guides.bracketPairs": true,
  "editor.bracketPairColorization.enabled": true,
  "files.trimTrailingWhitespace": true,
  "readTime.enabled": true,
  "readTime.fileTypes": ["markdown", "plaintext", "yaml", "mdx"],
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "cSpell.language": "en,en-US",
  "cSpell.enabledFileTypes": {
    "markdown": true,
    "mdx": true
  },
  "editor.inlineSuggest.enabled": true,
  "editor.minimap.enabled": true,
  "editor.fontSize": 13.5,
  "terminal.integrated.fontFamily": "JetBrainsMono Nerd Font",
  "editor.fontFamily": "JetBrains Mono",
  "editor.fontWeight": "normal",
  "[markdown]": {
    "editor.quickSuggestions": {
      "comments": "on",
      "strings": "on",
      "other": "on"
    }
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[jsonc]": {
    "editor.defaultFormatter": "vscode.json-language-features"
  },
  "[html]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "markdown"
  ],
  "files.associations": {
    ".env*": "dotenv"
  },
  "mdx.validate.validateFileLinks": "ignore",
  "workbench.editor.enablePreview": false,
  "explorer.confirmDelete": false,
  "editor.renderLineHighlight": "line",
  "githubPullRequests.pullBranch": "never",
  "editor.linkedEditing": true,
  "workbench.startupEditor": "none",
  "update.mode": "manual",
  "telemetry.telemetryLevel": "crash",
  "redhat.telemetry.enabled": false,
  "errorLens.enabledDiagnosticLevels": ["error", "warning"],
  "extensions.ignoreRecommendations": true,
  "window.commandCenter": true,
  "explorer.confirmDragAndDrop": false,
  "claudeCode.preferredLocation": "panel",
  "github.copilot.nextEditSuggestions.enabled": true,
  "github.copilot.enable": {
    "*": true,
    "plaintext": false,
    "markdown": true,
    "scminput": false
  },
  "workbench.colorTheme": "Light 2026"
}

Extensions

Install all extensions with the following commands:

code --install-extension anthropic.claude-code
code --install-extension astro-build.astro-vscode
code --install-extension atishay-jain.all-autocomplete
code --install-extension bradlc.vscode-tailwindcss
code --install-extension christian-kohler.npm-intellisense
code --install-extension dbaeumer.vscode-eslint
code --install-extension eamodio.gitlens
code --install-extension esbenp.prettier-vscode
code --install-extension expo.vscode-expo-tools
code --install-extension formulahendry.auto-close-tag
code --install-extension formulahendry.auto-complete-tag
code --install-extension formulahendry.auto-rename-tag
code --install-extension github.copilot-chat
code --install-extension github.vscode-pull-request-github
code --install-extension johnpapa.read-time
code --install-extension mathiasfrohlich.kotlin
code --install-extension naumovs.color-highlight
code --install-extension oderwat.indent-rainbow
code --install-extension openai.chatgpt
code --install-extension orta.vscode-ios-common-files
code --install-extension oxc.oxc-vscode
code --install-extension redhat.vscode-yaml
code --install-extension riussi.code-stats-vscode
code --install-extension streetsidesoftware.code-spell-checker
code --install-extension tamasfe.even-better-toml
code --install-extension unifiedjs.vscode-mdx
code --install-extension usernamehw.errorlens
code --install-extension vincaslt.highlight-matching-tag
code --install-extension wakatime.vscode-wakatime

This list of extensions can be generated by running code --list-extensions in the terminal.

AI tools and services

Currently, I am using the following tools from different providers:

Claude Code
Codex CLI
Codex desktop app
LM Studio

I keep syncing my personal skills for Claude Code and Codex CLI from dotskills repository. To set that up, open the terminal window, navigate to the dotskills directory, and run:

bash setup.sh

Wrap up

These configurations and tools are what I am currently using on my Mac. It is a work in progress as I expect to make adjustments and changes to it over time.

Week notes 16

Sun, 12 Apr 2026 00:00:01 GMT

Mixed week. A small side-project release, a couple of satisfying wins on the work side, and a lot of late-night ideas I want to act on coming week.

🚀 Shipped SkillsBar v1.7.0. The big addition is Codex plugin support and adding custom collections view where one can organize their skills based on a theme or topic or work repository. Codex plugins now show up under User Skills in the Codex tab, alongside the Claude Code skills SkillsBar already tracked. Also fixed a quiet bug where the Usage Stats screen was silently dropping historical data beyond four weeks. This is a major update, and I used GPT 5.4 to add more tweaks apart from doing this major update.
💼 One Vale win on the Expo docs side. First, lint-prose had quietly drifted from around 6 seconds back up to 13. Turned out the out/ directory was not actually being excluded the way I thought, because .vale.ini exclusions run after Vale walks the tree. Patched the script to use CLI glob negation and the time dropped back down. Second, got the Vale install script checksum verification. Now Vale can be installed locally by any member of the team and have 5 seconds reduction when running lint-prose command.
📝 Published a post on Replacing rm command with trash in Claude Code.
🧪 Started looking into AI evals and automation for documentation. There’s so much ground to cover.

Replacing rm command with trash in Claude Code

Sat, 11 Apr 2026 00:00:01 GMT

The fear of losing a file is a big deal using Claude Code since it has access to bash tools and can run bash commands on its own. This is possible whenever --dangerously-skip-permissions is enabled or I have accepted edits inside a particular session.

A workaround for this can be to skip running rm command inside Claude Code settings. I have added "Bash(rm:*)" to a “deny” list inside Claude Code’s global settings file (~/.claude-code/global-settings.json):

{
  "permissions": {
    "deny": ["Bash(rm:*)"]
  }
}

The deny list in settings.json lives outside of the conversation/session, which means Claude cannot run rm even if it wants to during a session. It will trigger the command during a session but the tool call will get blocked and the command will fail to run.

This is a good workaround to prevent accidental file deletions. However, it also means that if I want Claude Code to delete a file, I will have to manually keep track of each file from the session and delete it myself. That is tiresome and ideal for me.

What if I could allow Claude Code to safely delete those files instead of permanently delete them?

There is a tool exactly for deleting files safely without permanently deleting them. It is called trash, a CLI that moves a file or a directory to the Finder trash on macOS. To install it, you can use Homebrew:

brew install trash

Running a command like trash file.txt, will move the file.txt inside the Finder trash. This is normal macOS trash behavior. I added trash in my Claude’s global CLAUDE.md file with the following instruction:

## No `rm` Rule

Never use `rm` or `rm -f` to delete files. Always use `trash` instead (e.g., `trash .eslintcache`). This ensures files can be recovered.

Now, instead of rm, Claude reaches for trash on its own. The deny list keeps on handling the edge case where the initial intent is to use rm fails and the Claude picks up trash.

Here is an example of how it works in practice from a real session, where I was working on migrating from ESLint to OxLint:

trash ~/.claude/skills/docs-freshness/SKILL.md
trash ~/.claude/scripts/docs-freshness.sh ~/Library/LaunchAgents/com.claude.docs-freshness.plist
trash .oxlintrc-test.json
trash .oxlintrc.json.bak
trash .eslintcache
trash scripts/oxlint-migration-status.ts

Each of the above files would have been permanently deleted with rm. With trash, they all went to the Finder trash where I can recover them if I need to. I have stopped thinking about losing an important file permanently. I just approve the cleanup step and move on.

Week notes 15

Sun, 05 Apr 2026 00:00:01 GMT

This week leaned heavy into to upgrading lint tools at work and a bit of writing. I also managed to create a skill to perform a tedious activity with Claude Code and /chrome tool it has, which I am going to write about in a future post.

📝 Wrote three short blog drafts that will go live on this blog soon.
🧪 Built a broken link checker skill for the Expo docs using Claude Code Agent Teams. Instead of one agent crawling more than 1000 files and reporting gaps in its findings, I split the work across six agents, each running in its own tmux pane with a different color label. It was joy to watch multiple agents running in parallel for a few minutes.
🧪 Built a Claude Code skill that automates Algolia crawler’s recrawls using the /chrome browser integration. The Algolia runs autonomously every day at a specific time. It occasionally fails and the only way to resolve the network errors is to go to the monitoring dashboard manually and recrawl each failed link. Now Claude Code can do this automatically for me while I can sip my morning coffee.
💼 Lot of chores and work around admin stuff.

Week notes 14

Sun, 29 Mar 2026 00:00:01 GMT

Busy week with mix of publishing, drafting, and big changes. The kind where you look back and wonder how it all fit into five days.

📝 Wrote a blog post based on the recent works on Expo docs. It talks about different layers of discoverability that have become essential for human readers and AI agents.
📝 Redesigned the blog footer with social icon buttons.
🧪 Explored switching the Astro blog from npm to bun. Netlify supports it, but the practical gain for this repo’s dependency size is small. Still thinking about it.
💼 The big one this week was migrating the Expo docs linting setup from ESLint and Prettier to Oxlint and Oxfmt. The speed is real.
- Both are Rust-based tools from the Oxc project that replace ESLint and Prettier with significantly faster alternatives.
- Big because the migration includes 188 rules from ESLint to Oxlint. I have successfully removed Prettier entirely. One thing I think Oxlint could do better is to allow us to create our own custom plugins so I can port over MDX rules even though Oxlint does not supports MDX. In the end, Tailwind CSS and MDX are both using ESLint.
📚 Started reading “Chop Wood, Carry Water”. I need to finish more books.

Docs discoverability layers

Sat, 28 Mar 2026 00:00:01 GMT

When someone says a doc site is “discoverable”, they often mean that a human can find it through a search engine or use the in-site text-based search. Most documentation sites are built for human readers. If a page loads correctly and reads well, it is considered discoverable. This assumption covers only one dimension.

Search engines need signals to crawl and index pages. They need to know which URL is authoritative, what a page is about, and how to display it in results. Schema parsers (systems like Google’s Rich Results engine that read structured data) need typed metadata to understand what a page represents, not just what it says. AI agents need clean text they can consume without wasting tokens on parsing HTML, JavaScript, and navigation.

Search crawlers, schema parsers, and AI agents each need different things from the same documentation page. The infrastructure serving one of them does almost nothing for the other two.

At my day job, I work primarily on a documentation site which has more than 1,000 pages. I have observed that treating “discoverability” as a single concern can lead to blind spots that only became visible when I started looking at what each machine reader actually needs.

This post highlights some key points I found after attempting to satisfy all three. It is based on what we’ve shipped so far, including what we already had in place and was working for us (mostly for search engines).

The assumption worth questioning

Most documentation sites invest, or I should say, used to invest in one surface: HTML rendered for human readers. If they do any machine-facing work at all, it’s usually meta tags in the <head> element for search engines. All of us who work on documentation used to stop there because the implicit assumption is that search engine visibility equals discoverability. If a search engine like Google can find the page, the job is done.

This still holds true in 2026. Yes, I am making this claim because AI agents can do web search and humans are still reading documentation and still use search engines. We just don’t know for how long.

So, if search visibility isn’t the whole picture, what else is there? There are three types of machine reader, each piece needing its own layer:

Search crawlers: They need control signals. They need to know which URL is canonical when versioned docs produce near-identical pages. They need robots directives to know what to skip and a few more meta tags. This is the most established layer since most documentation sites have them.

Schema parsers: This includes Schema.org and Google’s Rich Results engine. AI agents can also benefit from this data when available. I think of this as an identity layer which is usually constructed from breadcrumb chains, FAQ structures, video detection, and so on. This is achieved by using JSON-LD structured data and while JSON-LD is used on over half of all websites, most of that is on large platforms. In my experience working across documentation sites, I haven’t seen many using docs-specific types like TechArticle or BreadcrumbList.

AI agents: This can include coding assistants, chat interfaces, and other LLM based tools that fetch documentation when a user asks a question. This is the newest layer and needs a clean, compact mechanism to consume the content. This is usually done in the form of Markdown files, and an llms.txt file is a small but efficient starting point.

These three layers overlap in some ways.

Testing these layers

At my day job, all three layers are implemented and I have also implemented two out of three layers on my personal blog (this blog!).

The blog uses metadata and has an LLM access layer using .md URLs. I think using structured data might be overkill for it. The documentation site I work on is more of a complete case study. The following table describes each layer and its implementation status from the documentation site:

Layer	Consumer	What is implemented
Head metadata	Search crawlers, social platforms	Title, description, canonical URL, robots directives, Open Graph (OG) tags, Twitter Cards, dynamic OG images
JSON-LD	Schema parsers, Google rich results	Schema types such as: Organization, WebSite, BreadcrumbList, TechArticle, FAQPage, VideoObject
llms.txt + markdown	AI agents (coding assistants, chat interfaces)	llms.txt endpoints, per-page `/index.md`, Cloudflare worker that serves markdown when requested via HTTP headers

The layers are independent. You do not have to implement them all at once. You can add them incrementally and test the value each one provides.

My framing was wrong

Before all of this together, I had a narrow framing that I used to call “crawlability”. This was wrong because I used to think that the <head> metadata is only about whether a crawler can reach a page or not. It is not just about that. It is also about control, selection, and presentation. A canonical tag tells search engines which URL represents the content, robots controls the indexing behavior, meta description provides a candidate summary for search results, OG and Twitter/X tags control social preview cards, and so on.

How you frame each layer matters. Getting specific about what each one does helped me see where the gaps were.

Three layers together and where to start

All three layers overlap in some ways and are dependent on each other.

The <head> metadata comes first. If a page is not indexed, then it doesn’t matter what JSON-LD or llms.txt coverage it has. The page will not appear in search results and will often be skipped by AI agents that rely on search indexes to find content. If there is one place you are looking to get started, start with <head> metadata.

JSON-LD adds semantic understanding to each indexed page. It doesn’t help a page get indexed. It helps machine readers understand what the page represents after they find it. For documentation, BreadcrumbList is the most immediately valuable because it can visibly change how the page appears in Google search results, showing a navigation path instead of a raw URL.

llms.txt provides the site-level overview that neither page-level layer can offer. It gives AI agents a curated map of the entire documentation. To actually consume individual pages, per-page .md URLs are efficient. Some sites also support serving Markdown when an AI agent requests it via the Accept: text/markdown HTTP header, so the same URL can return HTML for browsers and Markdown for agents.

                     One docs page
                          |
        ---------------------------------------------
        |                     |                     |
        v                     v                     v
   HTML <head>         JSON-LD scripts      Markdown access
   control layer       identity layer       LLM layer
        |                     |                     |
  canonical URL         WebSite             llms.txt index
  robots rules          Organization        llms-full.txt
  meta description      TechArticle         per-page index.md
  OG/Twitter            BreadcrumbList      Accept: text/markdown

Wrap up

If you maintain a documentation site, or if you are thinking about how machines consume your content, I would be curious to hear how you think about these layers. I’m not presenting this three-layer model as the definitive way to think about docs discoverability. This is how I ended up thinking about these layers.

My Starship prompt setup

Sun, 22 Mar 2026 00:00:01 GMT

The prompt is the line you stare at before every command in a terminal app. It can be as minimal as a symbol like $ or >. By default, the Terminal app on macOS uses zsh with a plain prompt that shows your macOS username. While it shows some information, it tells you nothing about the current directory you are working in.

There are various configurations you can use with zsh or the shell of your choice. Right now, I am using zsh and I prefer a clean setup. I have been using Starship for a while now and recently went through a major rewrite of my configuration.

Getting started with Starship

Starship is a cross-shell prompt written in Rust. It works with zsh, bash, fish, and more. You typically configure it with a single TOML file and it handles showing you things like the current directory, git branch, and other toolchain versions. All of these status related configurations depend completely on you and how you configure it.

Installing Starship is easy via Homebrew:

brew install starship

Once you have it installed, add the following eval at the end of your .zshrc file:

eval "$(starship init zsh)"

Starship looks for its configuration at ~/.config/starship.toml. Create the file if it doesn’t exist.

Why did I rewrite my Starship configuration

My old Starship config had Nord theme colors hardcoded as hex values. Values like #88C0D0 for cyan and #D8DEE9 for white. These looked perfect in a dark terminal with a Nord color scheme. When I switched to a light theme, the prompt became unreadable. Yellow text became invisible on a white background. The light blue Nord colors had zero contrast against a light background.

The fix was to use ANSI color names like blue, cyan, green and so on. These names map to whatever the terminal theme defines. So cyan in a dark theme looks like dark-theme cyan, and cyan in a light theme looks like light-theme cyan. The terminal handles the contrast, not the Starship config.

If you switch between light and dark themes, or might switch terminals someday, use ANSI color names instead of hex values.

Using a two-line prompt

Previously, I used a single-line prompt with the directory name on the left and git branch and toolchain versions on the right.

I wanted to split this into two lines. Line 1 shows the directory, git info, and toolchain versions. Line 2 is just the prompt character waiting for input.

Starship provides a right_format option, but it renders on the same line as the prompt character. So if your format splits into two lines, the right-aligned content ends up next to ❯ on line 2, not next to the directory on line 1.

The trick is to use the $fill module instead of right_format. It fills the space between left and right content on the same line. Instead of splitting across format and right_format, you put everything in format with $fill as the separator:

format = """$directory$fill$git_branch$git_status$cmd_duration$package$nodejs$python$docker_context
$character"""

The above configuration piece splits directory name on the left, a gap in the middle, and then all other information pushed towards the right. This way, the line 2 holds > character and waits for your input.

Using Nerd font icons

Next configuration I did is to show icons for the git branches, Node.js, Python, and other toolchain versions. These icons come from Nerd Fonts, which are patched versions of regular programming fonts that include thousands of extra glyphs.

Since I use JetBrainsMono font in my terminal previously, and to match that, I switched to use jetbrains-mono-nerd-font. It can be installed via Homebrew:

brew install --cask font-jetbrains-mono-nerd-font

You also need to configure your terminal app to use the Nerd font variant. For example, in Ghostty, it’s one line of configuration in the global configuration:

font-family = JetBrainsMono Nerd Font

In iTerm2, you can set this up by going to Settings > Profiles > Your default profile > Text > Non-ASCII Font and then select JetBrainsMono Nerd Font in the drop down next to it.

Note: If your icons aren’t showing, your editor may have silently stripped the glyph characters from the TOML file during copy-paste or save. You can use TOML Unicode escapes (\uXXXX) instead of literal glyphs as a workaround:
[git_branch]
symbol = "\ue0a0 "

[nodejs]
symbol = "\ue718 "

Complete Starship configuration

Here’s my complete starship configuration. I have a few toolchain stuff disabled since I either find them annoying or don’t consider them important enough to be displayed all the time.

"$schema" = 'https://starship.rs/config-schema.json'

add_newline = true
format = """$directory$fill$git_branch$git_status$cmd_duration$package$nodejs$python$docker_context
$character"""
command_timeout = 10000

[fill]
symbol = ' '

[character]
success_symbol = '[❯](bold green)'
error_symbol = '[❯](bold red)'
vimcmd_symbol = '[❮](bold purple)'

[cmd_duration]
min_time = 2_000
format = "[\uf252 $duration]($style)"
style = 'bold purple'

[directory]
style = 'bold blue'
format = "[\uf115 $path]($style)[$read_only]($read_only_style)"
read_only_style = 'bold red'
read_only = "\uf023 "

[git_branch]
format = '[$symbol$branch(:$remote_branch)]($style) '
style = 'bold cyan'
symbol = "\ue0a0 "

[git_status]
format = '[$all_status$ahead_behind]($style)'
style = 'bold cyan'
conflicted = "\uf0e7 "
ahead = '⇡${count} '
behind = '⇣${count} '
diverged = '⇕⇡${ahead_count}⇣${behind_count} '
untracked = "\uf128 "
stashed = "\uf01c "
modified = "\uf044 "
staged = "\uf067 "
renamed = '󰑕 '
deleted = "\uf014 "

[gcloud]
disabled = true

[nodejs]
format = '[ $symbol($version)]($style)'
symbol = "\ue718 "
style = 'green'

[python]
format = '[ $symbol$version]($style)'
symbol = "\ue73c "
style = 'purple'

[rust]
disabled = true

[golang]
disabled = true

[docker_context]
format = '[ $symbol$context]($style)'
symbol = "\uf308 "
style = 'blue'

[package]
format = '[ $symbol$version]($style)'
symbol = '󰏗 '
style = 'blue'

Between iTerm2 and Ghostty, my terminal is a configuration file powered by Starship and I can easily switch or explore new terminal apps.

Color-coding my Claude Code sessions

Sat, 14 Mar 2026 00:00:01 GMT

I usually have two or more sessions running at a time either in the same or different project directories. One of the longest and most used sessions I have is in my notes directory, where I am constantly creating specs or taking notes on the stuff I am working on.

One problem when running multiple Claude Code sessions in different terminal windows or tabs is visually distinguishing them.

Claude’s team recently released /color and /rename slash commands in Claude Code in v2.1.75. Together, they can turn anonymous Claude Code sessions into visually distinct workspaces. And this kind of solves the problem of visually separate multiple sessions on my end.

The /color allows changing the color of the prompt bar. For example, if I type /color orange in a currently active session, I immediately see it. Below is an example of two sessions running in the same directory. The first session has the default prompt color which matches my iTerm2 theme and the second session’s prompt bar:

Before /color, these sessions looked identical. I’d glance at a terminal tab, guess which session it was, and then had to look a bit deeper to recall what the session was about.

For a full list of available colors, see the official docs.

Also, notice that both sessions say “Claude Code (node)” in the header of each terminal tab in iTerm. This can be modified using /rename, which lets me name a session and also affects the prompt bar.

By default, /rename command without an argument will auto-generate a name based on a session. I can override this by /rename your-session-name:

/rename command also affects the name of the terminal session window/tab. After setting it up or using the auto-generated session name, in iTerm2, the header reflects the same value.

This solves a huge problem for me because iTerm2 has profile-based coloring and I use the default profile for all sessions.

Now, I can also trigger a new session that has the color set by default for that session:

claude "/color yellow"

The above command will automatically trigger the session with the prompt bar’s color already set to the color yellow.

However, this does not allow chaining slash commands yet. This means, I cannot run claude "/color yellow" "/rename notes". If you want to automate this, one little thing I’ve done is set a specific color at the start of a session for a specific project by creating an alias in my .zshrc like:

alias cnotes="claude '/color yellow'"

This way, I can run the alias command when starting a new session in the specific directory every time.

TIL Remotely accessing one MacBook from another MacBook

Wed, 11 Mar 2026 00:00:01 GMT

macOS has a built-in way to remotely access another Mac using Screen Sharing and Remote Login (SSH). No third-party tools needed.

How to set it up

On the remote Mac (the one you want to access), go to System Settings > General > Sharing. Enable Screen Sharing for full GUI access, or enable Remote Login for SSH/terminal access. Note the local IP address or hostname shown in the Sharing settings.

Connecting

For Screen Sharing, open Finder on your local Mac, press Cmd + K, and enter vnc://<remote-ip>.

For SSH, open Terminal and run:

ssh username@<remote-ip>

Both Macs need to be on the same network (or use a VPN for remote access over the internet).

Using Ghostty for the first time

Wed, 04 Mar 2026 00:00:01 GMT

It’s 2026, a time for AI agents and AI tools like Claude Code and Codex CLI to be alive. I am using them every day and I find myself spending more time inside a terminal app rather than a code editor.

In the past, I’ve written about setting up and installing Oh My Zsh and using iTerm2 as my de facto terminal app. I’ve used iTerm2 as long as I can remember, probably around a decade. I have switched between different color schemes and configurations, even saved them in my dotfiles.

Recently, I’ve been hearing a lot about Ghostty, which is a new terminal app in town and is created by Mitchell Hashimoto (co-founder of HashiCorp). Everyone keeps saying it is minimal and fast. You had me at minimal.

Why I switched

iTerm2 is a great terminal but is a complete app that offers more settings than I need right now.

Ghostty seems the opposite. It requires one plain text file. Doesn’t provide a GUI settings panel. The default settings in Ghostty aren’t too bad. It all made sense when I first installed and ran the app on my Mac.

Another reason is that Ghostty is GPU-accelerated and noticeably snappier. Window launches feel instant. Scrolling through my conversations with Claude Code sessions feels smoother. These details add up when you are looking at and interacting with a terminal window for at least 1/3rd of your full day’s work. Maybe more on some days.

Getting Ghostty

Ghostty is available at ghostty.org. On macOS, download the .dmg from the website or install via Homebrew:

brew install --cask ghostty

Ghostty configuration

I was mind-blown when I found out that Ghostty uses a single plain text file for configuration. Press Cmd + , and the config file opens right inside the terminal. No settings GUI, no preferences panel with dozens of tabs. Just a text file.

An example of this is the terminal app theme. Ghostty ships with hundreds of built-in themes and does not require importing or downloading anything. All you need to do is mention the name.

theme = light:Gruvbox Light,dark:dracula

If you are like me and want to stick to one theme, you can define a single theme:

theme = Gruvbox Light

My complete Ghostty configuration

Here’s my complete Ghostty configuration. There is nothing fancy about it:

# Theme
theme = Gruvbox Light

# Contrast
minimum-contrast = 1.3

# Font
font-family = JetBrainsMono Nerd Font
font-size = 16
font-thicken = true

# Window
macos-titlebar-style = tabs
window-padding-x = 8
window-padding-y = 4
background-opacity = 0.96
background-blur = 10
unfocused-split-opacity = 0.6
window-padding-balance = true

# macOS
macos-option-as-alt = left

# Cursor
cursor-style = bar

# Mouse
mouse-hide-while-typing = true

That’s it! A few lines of configuration is all I need. Everything is documented in the official documentation, but here’s what the above configuration does:

theme: Sets the color scheme. Ghostty ships with hundreds of built-in themes, and you can also add custom ones. You can use light: and dark: prefixes to auto-switch based on macOS system appearance.
minimum-contrast: Ensures every foreground/background color pair in the terminal meets a minimum contrast ratio. Setting it to 1.3 is a subtle floor that prevents any theme colors from becoming unreadable.
font-family: The font used for all terminal text. I use JetBrainsMono Nerd Font, which includes icons for git, Node.js, Python, and other developer tools in the prompt.
font-size: Font size in points. 16 works well on a large external monitor.
font-thicken: Makes the font slightly bolder. Adds a bit of weight to the text, which improves readability on high-resolution displays.
macos-titlebar-style = tabs: Integrates tabs directly into the macOS titlebar. Saves vertical space and looks native.
window-padding-x / window-padding-y: Adds breathing room between the text and the window edges. Without it, characters feel crammed against the border.
window-padding-balance: Automatically centers the text when you resize the window, instead of pinning it to the top-left corner.
background-opacity: Controls window transparency. 0.96 gives a subtle translucency where you can barely see the desktop behind the terminal without sacrificing readability.
background-blur: Blurs the background visible through the transparent window. Paired with opacity, this gives a frosted glass effect.
unfocused-split-opacity: When you split panes, the unfocused pane dims to this value. 0.6 makes it obvious which pane is active.
macos-option-as-alt = left: On macOS, the Option key produces special Unicode characters (like ø or å) instead of acting as Alt. This setting makes the left Option key behave as Alt.
cursor-style = bar: A thin bar cursor instead of the default block.
mouse-hide-while-typing: Hides the mouse cursor while you type so it doesn’t sit in the middle of your terminal output.

Shortcuts to remember

Whenever you make a change to your configuration, always remember to press Cmd + Shift + , to reload your changes.

Splitting panes works by default. You can press Cmd + D for vertical splits and Cmd + Shift + D for horizontal ones.

Why minimal

I have seen many cool terminal configurations that are quite long and contain custom themes, and complex keybindings. I want to keep things minimal on my end because I have a minimal setup and using default keybindings are part of my muscle memory now. There are definitely things I can improve in near future, if I have to spend more time inside a terminal window. When a configuration gives me everything I need, there’s hardly any reason to make it complex.

This how my current Ghostty window looks like:

Slash pages you need for your blog

Sat, 28 Feb 2026 00:00:05 GMT

The pages outside /blog can matter just as much as your posts. Slash pages like /now, /about, and /uses show readers who you are beyond your writing.

I currently have 12 slash pages. That’s too many. Here’s the thing: each one serves a purpose and I have found myself visiting other people’s slash pages more than I expected. Weirdly compelling. Let me walk through what I have and why:

/about: I’ve rewritten this page the most over the years. It’s never quite right. But you need it. People need to know who you are and what you do. It’s often the second page people visit after stumbling onto one of your blog posts.

/now: This is inspired by Derek Sivers’ now page movement and it’s genuinely one of my favorite pages to maintain. Unlike /about, which is basically static, this changes all the time. What am I working on right now? What am I reading? It’s a snapshot of the present moment. I update it maybe every three months.

/links: All the places I exist on the internet. GitHub, X, LinkedIn, and so on. Sounds redundant but it’s useful as a single source of truth. “Where can I find you?” Here’s the list.

/blog or /archive: An archive of everything. Not just the last 10 posts, but everything. This matters more than you’d think once you have a few hundred posts. People want to browse.

/stats: I share my Fathom analytics publicly. Why? Honestly I think it’s interesting. Transparency is cool. And it’s kind of fun to see what resonates.

/posts-count: How many posts I’ve published each year.

/search: Once you have more than 50 posts, you might need this if your site is as static as mine.

/rss: RSS is not dead. Some of us still use feed readers, and a discoverable feed link helps.

/support: How to sponsor the site. I don’t push this hard at all, but it exists for people who want to.

/ai: My stance on AI and how it relates to the content on this site. I think being explicit about your approach matters.

/been: A list of countries I’ve visited. Is this necessary? No. Is it fun? Yes.

/llms.txt: This one is new and meta. It’s an llms.txt file that points to my content in a machine-friendly format.

You definitely don’t need 12 slash pages. That’s overkill for most people. But express yourself beyond your posts. It’s your blog. Share a little bit of your personality.

If you need more inspiration, check out Robb Knight’s Slash Pages project for more ideas. And then go add some to your own site. It’s weirdly satisfying.

Using images in Claude Code

Wed, 18 Feb 2026 00:00:05 GMT

Recently I wrote a post on Running headless Codex CLI inside Claude Code, which describes a way to use Codex models in a headless way when you have Claude Code installed on your local machine. I ended up creating a skill for it where Claude Code will ask you to go through a series of questions to select which Codex model and its reasoning level. It also goes through the task you want to achieve with Codex without leaving your session inside Claude Code.

During the development of that skill, I found because an LLM can have stale training data, it might not choose the right set of models. This is exactly what happened on the first iteration of the skill development. Opus 4.6 initially had GPT 4 models added to the skill and I only found out about it after running the skill manually (and no, I didn’t read the skill file when it was created for the first time).

To have the current set of models presented when running this skill, I asked Claude Code to adjust the skill itself. I ran /model picker inside Codex CLI, took a bunch of screenshots of the currently available models and their reasoning levels and gave them to Claude Code without further explanation. I found that it is easier for an LLM to pick information from an image.

Claude Code was able to rectify its own mistake. Most modern LLMs available are multimodal, including Claude and GPT models. They can process images natively without the need of converting them to text first.

In Claude Code specifically, you can paste screenshots with Cmd+V (on macOS), drag-drop files, or reference image paths from your machine’s filesystem. Think of it like giving someone directions to your house. You can either describe the route over a phone call or text including nearest landmarks or you can just drop a pin in an instant messaging app which will allow them to view the dropped pin (capture of the location using a maps app). The pin can’t be misinterpreted easily.

With the help of screenshots, you can also eliminate a lot of back and forth for what you want to describe. Images are first-class content blocks in Claude. They are interpreted as tokens using a formula as per official Claude’s documentation. A 1000 by 1000 px image is roughly 1334 tokens. Not exactly too much considering the context length and the level the latest LLMs operate these days.

Next time you are stuck at explaining something in the input field in Claude Code or are looking for a way to move things faster, take a screenshot and paste it in your terminal window.

Running headless Codex CLI inside Claude Code

Fri, 13 Feb 2026 00:00:05 GMT

I have both Claude Code CLI and Codex CLI installed on my local machine. I often use Codex to code review or tighten the code on something I am working on. Claude has a better terminal UI, which is not only pleasing to use, but it respects my terminal app’s theme. Switching between both CLIs and then finding a way to write prompts wasn’t fruitful. So I created a Skill in Claude Code to allow me to use Codex CLI in a headless way.

Codex has a non-interactive mode that can be enabled using codex exec. It dumps output in stdout. This is what makes it possible to use inside Claude Code CLI.

All of this is possible by creating a Skill inside Claude Code. A Skill is basically a markdown file (SKILL.md) with some frontmatter at the top and instructions in the rest of the file. You can think of it as a task that has a bunch of instructions on what to do, how to do it, and what not to do. I also think of them as recipes where I want Claude Code to perform a task by following a bunch of steps.

In Claude, you can have global-level skills and project-level skills. I created this new skill as a global one so I could trigger it in any project I want. All global level skills in Claude live in ~/.claude/skills/your-skill-name/, where your-skill-name is that global or project level skill’s directory.

The skill is called /run-codex. A skill in Claude Code can be triggered using a /. When I invoke /run-codex, it starts in a read-only mode. It asks me which model to pick and what should be its reasoning level.

Here are some screenshots of when I invoke this skill:

Then, it provides three ways I can use it:

Code Review
Refactoring Suggestions
Code Editing

In the above screenshots you are seeing that invoking the skill, Claude Code is asking me a bunch of questions. This is essential since codex exec runs silently in the background. Without passing any user input, it won’t know how to proceed.

All of this interactivity comes from Claude’s side. I do have these questions in a specific order so Claude Code always follows it. Asking such questions inside Claude Code is possible because of AskUserQuestion, which is a built-in tool that Claude Code can access. This tool lets Claude Code present the user with a question and a set of options. You can invoke this tool inside your SKILL.md file and then define the options.

Here’s the reasoning level step defined in my skill’s file. It asks Claude Code to invoke AskUserQuestion to allow me to select a reasoning level for the model I selected in the previous step:

### Step 2 - Reasoning Level

Use AskUserQuestion to ask which reasoning level to use. This maps to the `model_reasoning_effort` config. Options:

- **Low** - Fast responses with lighter reasoning

- **Medium** - Balances speed and reasoning depth for everyday tasks (default)

- **High** - Greater reasoning depth for complex problems

- **xhigh** - Extra high reasoning depth for complex problems

The selected level is passed via `-c model_reasoning_effort="<level>"`.

Going through this prompt process, you might wonder what is the exact Codex command invoked here. Just for demonstration purposes, I invoked the /run-codex skill inside the open-source repository that I work on at work and this is the exact command:

codex exec -c model="gpt-5.3-codex" -c model_reasoning_effort="xhigh" --sandbox read-only --ephemeral "Review the code in the ui/components/ directory for bugs, quality…

An important thing to note here is the --sandbox read-only --ephemeral. The --sandbox read-only tells Codex to run in a sandbox where it can read files but cannot write, create, or delete. This is enforced at the OS level. Think of this as a guard that Codex can’t do anything without your permission other than reading one or many files in your codebase.

The --ephemeral tells Codex not to save the session to disk. Normally, when I run Claude Code or Codex, all sessions are stored in files so you can resume them later using, for example codex --resume command from a terminal window. With --ephemeral passed as an option to codex exec, the session exists only while it runs.

Another thing to note here, since codex exec is now running inside Claude Code, Claude will take care of saving the session and I don’t need two different AI CLIs to store the same session.

After 14 something minutes, I had the result with me. The code review part was done on a specific directory where the repository has most of its UI components. A comparison table is provided at the end when code review analysis is done by Codex. In my skill file, for this specific task, I also have instructions for Claude Code to do its own analysis and then compare its results with Codex’s output.

I think the code review is a fair report. Before running this, I was aware that there is some dead code. I am glad Claude Code picked it up while Codex couldn’t. Another thing I want to highlight is that the Claude Code’s way of presenting the final report in markdown (especially the tables) is much cleaner than in Codex CLI (at least at the time of writing this post, where codex is versioned at 0.99).

When creating the /run-codex skill, I use Claude Code’s planning mode to figure out how the skill can be structured. I gave it a prompt, fairly based on an idea I had in my mind. Initially, the version of this skill Claude built was wrong. It had wrong Codex model names, and there was no way to select the reasoning level, which is mostly fine. With LLMs stateless nature, I don’t expect them to one-shot the exact result of a given task to be perfect. This also helped me to dive deeper into how skills work and how to make them interactive.

You can build your skills that you expect to use again and that may contain executing a series of tasks. If you use both Claude Code and Codex and prefer Claude Code’s interface, try to build one for your own use case or ask Claude Code to build a skill for one of the most repeatable tasks you do. Claude is usually really helpful in building initial skills. You can always tweak them as you use them. I am going to tweak the /run-codex next time I am using it.

The above screenshot is from SkillsBar, a macOS menu bar app I built to browse and manage Claude Code skills.

TIL about tracking your Claude Code tokens usage

Wed, 11 Feb 2026 00:00:01 GMT

I wrote about tracking Codex tokens usage recently, and the same tool works for Claude Code. Different command though:

npx ccusage

The tool is part of the ccusage project. Works with Claude Code’s local logs, no API keys needed. It reads your local Claude Code logs and gives you a daily breakdown of exactly what you’re spending.

Here’s an example usage:

Date	Models	Input	Output	Cache Create	Cache Read	Total Tokens	Cost (USD)
2026-02-05	haiku-4-5, opus-4-5	54.3K	9.7K	3.2M	87.1M	90.4M	$59.20
2026-02-06	haiku-4-5, opus-4-5, opus-4-6	11.0K	5.4K	1.2M	25.7M	26.9M	$18.59
2026-02-07	haiku-4-5, opus-4-6, sonnet-4-5	27.3K	4.9K	718.7K	10.6M	11.3M	$7.39
2026-02-08	haiku-4-5, opus-4-6, sonnet-4-5	15.4K	4.9K	287.9K	7.7M	8.0M	$5.17
…	(other sessions)	…	…	…	…	…	…

Compared to the Codex output, the Claude Code breakdown adds a Cache Create column. This tells you when it’s building up context vs reusing it through Cache Read.

The ratio between the two shows cache efficiency. For example, 454.4M cache reads vs 28.8M cache creates means the context is being reused about 16x. Cache behavior explains why some sessions feel faster.

If you’re on Claude Code and haven’t checked your usage, run npx ccusage. You might be pleasantly surprised after checking your usage.

TIL about tracking your Codex tokens usage

Sun, 08 Feb 2026 00:00:01 GMT

I use Codex for both code-related and non-code tasks in Cursor and in the terminal. I wanted a better way to track Codex token usage day by day.

Recently, I learned about @ccusage/codex, which reads your local Codex logs and spits out a table of exactly how many tokens you used each day. This breakdown isn’t provided by the Codex usage page.

npx @ccusage/codex@latest

If you’re using Codex CLI and haven’t run this yet, do it. You might be very surprised. I certainly was when I looked at my usage.

Here is a snapshot from Feb 06 to Feb 08, 2026. The Total row is my cumulative usage since September 2025, not only these three days:

Date	Model	Input	Output	Reasoning	Cache Read	Total Tokens	Cost (USD)
Feb 06, 2026	gpt-5.2-codex	396.8K	26.4K	20.8K	1.0M	1.4M	$0.89
Feb 07, 2026	gpt-5.2-codex	1.1M	208.5K	91.1K	18.2M	19.5M	$5.79
Feb 08, 2026	gpt-5.3-codex	83.0K	16.3K	10.5K	498.6K	597.9K	$0.33
…	(other sessions)	…	…	…	…	…	…

It reads your local logs and gives you a breakdown of your Codex token usage, including input, output, reasoning, cache reads, total tokens, and even the cost in USD based on current pricing. The tool pulls live pricing from LiteLLM, so the cost calculations should stay accurate even when OpenAI changes rates again.

Migrating from Cursor to VS Code

Sat, 07 Feb 2026 00:00:01 GMT

I recently migrated from Cursor to VS Code. Cursor’s agentic code integration was a huge part of my daily workflow.

If you’re switching from Cursor to VS Code, the migration is straightforward. There are a few steps to get it right.

Why move back to VS Code

Claude Code runs in the terminal. It doesn’t care which editor is open. That made Cursor redundant.

Cursor is a VS Code fork with all the same capabilities. I used it for almost a year. Over the last month, I stopped using Cursor’s agent integration and switched to Claude Code in the terminal, and before that, Codex CLI. Claude and Codex extensions are also available in VS Code.

What to migrate from Cursor to VS Code

Three things to migrate: settings, keybindings, and extensions. The key directories for both editors on macOS are:

What	Cursor location	VS Code location
Settings	`~/Library/Application Support/Cursor/User/settings.json`	`~/Library/Application Support/Code/User/settings.json`
Keybindings	`~/Library/Application Support/Cursor/User/keybindings.json`	`~/Library/Application Support/Code/User/keybindings.json`
Extensions	`~/.cursor/extensions/`	`~/.vscode/extensions/`

Migration steps

Close VS Code before you start. If it’s running, extension installs can conflict with VS Code’s internal updater and you’ll get errors.

If you’ve used VS Code before, clean out the old data first.

rm -rf ~/.vscode/extensions/

# Remove old settings
rm -f ~/.vscode/settings.json
rm -f ~/Library/Application\ Support/Code/User/settings.json

# Clear caches (optional, frees up space)
cd ~/Library/Application\ Support/Code/
rm -rf Backups blob_storage CachedData CachedExtensionVSIXs CachedProfilesData \
  "Code Cache" Cookies Cookies-journal Crashpad DawnGraphiteCache DawnWebGPUCache \
  GPUCache languagepacks.json "Local Storage" logs "Network Persistent State" \
  Preferences "Service Worker" "Session Storage" "Shared Dictionary" shared_proto_db \
  SharedStorage TransportSecurity "Trust Tokens" "Trust Tokens-journal" \
  VideoDecodeStats WebStorage

Next, you need to copy the settings and keybindings:

cp ~/Library/Application\ Support/Cursor/User/settings.json \
   ~/Library/Application\ Support/Code/User/settings.json

cp ~/Library/Application\ Support/Cursor/User/keybindings.json \
   ~/Library/Application\ Support/Code/User/keybindings.json

If you have any custom snippets in Cursor, don’t forget to copy those as well:

cp ~/Library/Application\ Support/Cursor/User/snippets/ \
    ~/Library/Application\ Support/Code/User/snippets/

Your settings.json will have Cursor-specific keys that VS Code doesn’t understand. Anything prefixed with cursor.. Remove them before copying.

{
  "cursor.cpp.disabledLanguages": ["plaintext", "scminput"],
  "cursor.cpp.enablePartialAccepts": true
}

Next are extensions. Install them fresh in VS Code. This ensures VS Code gets the correct platform-specific versions:

ls ~/.cursor/extensions/ \
  | grep -v extensions.json \
  | sed -E 's/-[0-9]+\.[0-9]+\.[0-9]+.*$//' \
  | sort -u \
  | xargs -L 1 code --install-extension --force

Some extensions might be Cursor-only and won’t exist on the VS Code marketplace. These include anything from anysphere.*. They’ll fail to install with an error and that’s expected.

Use a Claude Code plugin for migration

After running through these steps manually, I turned them into a reusable Claude Code plugin. It includes helper scripts that handle JSONC parsing (for settings files with comments), Cursor-specific key stripping, and extension ID extraction with skip lists for Cursor-only extensions.

You can install it in Claude Code:

/plugin marketplace add amandeepmittal/cursor-to-vscode-migration
/plugin install cursor-to-vscode-migration

After restarting Claude Code, tell it to migrate my setup from cursor to vscode. The skill walks through each step and asks for confirmation before doing anything destructive.

The plugin is open source: github.com/amandeepmittal/cursor-to-vscode-migration.

TIL about git shortlog

Sun, 01 Feb 2026 03:42:51 GMT

I have been using Git for all my career in the tech. I am habitual of the basic commands such as git add, commit, status, log and a few more that I use consistently. Yes, until last week, I had never once used or heard about git shortlog.

Sometimes you want to know who actually did the stuff inside a repository. Or like me, at the end of each year at work, I have to compile a list of external contributors along with their contributions count.

To make this happen, you don’t need a fine-grained commit-by-commit archaeology, but look at the big picture. You can pipe log through grepand create a slightly complex pipeline. Or you could just use the tool that already exists on your system for exactly the purpose described previously:

git shortlog

The above command groups commits by author and lists of their commit messages. Readable? yes. Was I done? No.

The command also have some useful flags that you can use. One of them is -s, which gives you a summary mode. It counts the amount of commits without any commit message.

Then there’s -n, which sorts the number of commits in a descending order. When both of these flags are used along with git shortlog, the output displayed to you looks like below:

123 ABC
23  EFG
3   IJK

Instantly you can see the view that your stakeholder might have demanded. This goes beyond compiling a list and giving a shoutout to the contributors. When used in a new codebase, you can leverage this to understand it by talking to the top contributors who might know more about the project repository. Probably the person with over a thousand commits.

You can scope it to a time range or between tags:

git shortlog -sn --since="2025-01-01"

The above command is particularly nice for generating contributor lists for release notes or end-of-year lists. No more manual scrolling through a git log that is long and will take plenty of your time.

I think the reason I never discovered this command before is that I always reach out for git log first and then on a suggestion from a a colleague, started using grep when I needed to fulfill the release notes. However, Git has many commands like these under its umbrella, which might come handy in some situations.

Anyway. git shortlog -sn. Burn it into your brain.

amanhimself.dev

Taking the terminal seriously in the age of AI coding agents

Adding Content-Signal to a docs site

What is Content-Signal?

Why is this an auto-yes for a docs site

My impressions after using Claude Code for six months

My first encounter with Claude Code

Quick impressions of using Claude Code

From plan mode to auto mode in Claude Code

Is plan mode necessary?

I want to control interactions

If not plan mode, then what mode am I using?

2026 - half year in books

Books I recommend

Other stats

Wrap up

Notes that can never be atomic

How to set a custom folder order in Obsidian

A minimal Obsidian vault structure that sticks

Existing systems aren’t enough

Folders encode lifecycle, links encode topics

How many folders is too many?

How I track my token maxxing

Moving away from Oh My Zsh (OMZ)

New blog theme again

Week notes 17

Playwright to Chrome

My Mac setup

Initial setup

Updating macOS

Xcode and Command Line Tools

Fix the default macOS settings

Dock

Finder

Keyboard and input

Trackpad

Lock Screen and Battery

Other

Install Homebrew: macOS package manager

Install apps from Homebrew bundle

Git global configurations

Configure .zshrc

Configure Starship prompt

Configure iTerm

Setup a primary web browser

Shared configuration or steps required in both browsers

GitHub setup and configuration

Install Node.js, bun, and pnpm

After installing Node.js

Useful mise commands

VS Code

Setup VS Code as the default editor

Settings

Extensions

AI tools and services

Wrap up

Week notes 16

Replacing rm command with trash in Claude Code

Week notes 15

Week notes 14

Docs discoverability layers

The assumption worth questioning

Testing these layers

My framing was wrong

Three layers together and where to start

Wrap up

My Starship prompt setup

Getting started with Starship

Why did I rewrite my Starship configuration

Using a two-line prompt

Using Nerd font icons

Complete Starship configuration

Color-coding my Claude Code sessions

TIL Remotely accessing one MacBook from another MacBook

How to set it up

Connecting

Using Ghostty for the first time

Why I switched

Getting Ghostty

Ghostty configuration

What is `Content-Signal`?