Coder Legion - Recent posts tagged shell

I Tried Needle2 for Local Tool Calling. I Ended Up With llama.cpp + Granite

Fri, 25 Sep 2026 07:28:13 +0000

I’ve been working on a small experiment around a semantic shell.

The basic idea is that the user types something like:

copy report.pdf to backup

and a small local model maps that to a known tool:

filesystem.copy

The shell then takes over. It validates arguments, asks for missing ones, shows confirmation UI when needed, and finally executes the operation.

The model is not supposed to generate shell commands. It only needs to understand intent.

That sounded like a very good fit for Needle2.

Needle2 is tiny, focused on tool calling and structured extraction, and designed to run locally. On paper it looked almost purpose-built for what I needed.

So I tried it.

The first version worked. Then I started adding more realistic cases.

And that’s where things became more interesting.

Five tools is very different from fifty

Most examples of tool-calling models are some variation of:

turn on the kitchen light

with two or three tools available.

That’s fine as an API example, but it doesn’t tell you much about how the model behaves in a real application.

Even my first filesystem package already had things like:

filesystem.copy
filesystem.move
filesystem.delete
filesystem.create_file
filesystem.create_directory
filesystem.list_directory
filesystem.navigate
filesystem.current_directory
filesystem.find

Needle2 uses retrieval when the number of tools gets larger. It selects a small candidate set and then resolves the tool from there.

That makes sense.

But it also means there are really two decisions now:

Which tools should be considered?

and then:

Which of those tools is the right one?

If the correct tool does not make it into the shortlist, the second stage never gets a chance.

For many applications that may be perfectly acceptable. In my case I wasn’t comfortable relying on it without knowing more about how often it happens.

I started thinking about bypassing retrieval entirely by dividing tools into groups of five and running all groups.

Needle is small enough that this is not completely ridiculous.

Something like:

group 1 -> result
group 2 -> result
group 3 -> result
...

then take the strongest candidate.

But immediately another question appears.

Are confidence scores from different candidate groups actually comparable?

Maybe they are. Maybe they are not.

I couldn’t find enough information to feel confident about treating them as globally calibrated scores.

That does not make Needle bad. It just means that once you move away from the demo path, you start needing answers that are not obvious from the examples.

Tool descriptions matter a lot

Another thing I learned quickly was how sensitive a small model is to tool descriptions.

A description like:

Moves files from one place to another.

is not enough if the neighboring tools are:

filesystem.copy
filesystem.navigate
filesystem.rename

You need to be explicit.

For example, “move” should probably say that the original item no longer remains at the source, and that this is not the same thing as changing the shell’s current directory.

The descriptions start looking less like documentation and more like a tiny classification dataset written in English.

That was workable, but it changed how I thought about the model.

It is less “small agent” and more “probabilistic semantic parser with a constrained vocabulary.”

Which is actually fine for this use case.

Then I tried the C++ runtime

For the shell itself I wanted native integration.

No Python process on the side, no extra service, and no awkward lifetime management. The C++ library looked like the right way to do it.

This is where I hit the biggest practical problem.

I was developing on an Intel Mac.

The Cactus Engine code contains ARM NEON includes and intrinsics in many places. Not just one isolated backend file, but spread through engine and kernel code.

That surprised me.

If ARM is the main target, this is understandable. iOS, Android, and Apple Silicon are all important platforms.

But from my side it meant x86 support was not just a matter of enabling another optimized backend.

I ended up spending time patching things simply to answer a much more basic question:

Is Needle good enough for my use case to justify carrying this dependency?

At that point I decided to try a different route before spending more time on the port.

llama.cpp and Granite

So I integrated llama.cpp.

Then I tried Granite 4 350M for the same tool-calling task.

I expected this to be more of a baseline than a solution.

It turned out to work better than I expected.

For the normal cases it selected the tools I wanted.

More importantly, I tried a few deliberately awkward inputs where no good tool really existed, and instead of forcing a call it simply failed to find one.

For my application, that is good behavior.

I would much rather see:

No suitable tool found.

than a confident guess.

The shell can recover from that.

It can ask the user to rephrase, narrow the scope, or choose between two possible interpretations.

A wrong tool call is much harder to recover from once you start dealing with destructive operations.

This changed the architecture less than I expected

The funny part is that switching models did not really affect the shell design.

The important part was already outside the model.

The flow is roughly:

user input
    ↓
intent resolution
    ↓
known semantic capability
    ↓
argument validation
    ↓
ask for missing arguments
    ↓
policy / confirmation
    ↓
execution

If the user says:

copy file

the model only needs to resolve:

filesystem.copy

The shell can notice that source and destination are missing and show proper selectors.

If two tools are plausible, for example copy versus move, the shell can show two buttons.

There is no need to force the model to solve every ambiguity.

That ended up being one of the more useful conclusions from the experiment.

A small local model does not need to be brilliant if the surrounding system is designed to handle uncertainty.

The part I wish documentation focused on more

I still think Needle2 is interesting.

What I missed was more information about the edges.

Not another:

turn on the light

example.

I wanted answers to things like:

how accuracy changes as the tool catalogue grows;
how often retrieval drops the correct tool;
whether confidence remains comparable across different candidate sets;
how similar tools should be described;
what happens on no-match input;
how confidence behaves on incorrect calls;
how much fine-tuning helps with ambiguous tools;
what the realistic native-platform support is.

Those details are not as flashy, but they are what decides whether something works in a real system.

The same applies to structured extraction.

Showing that a model can extract an invoice total is useful.

Showing how it behaves when there are subtotal, tax, total, previous balance, OCR errors, and two dates on the same page is much more useful.

Where I am now

For the moment I’m continuing with:

llama.cpp
Granite 4 350M
typed semantic tools
deterministic argument resolution
small contextual UI
policy-controlled execution

That does not mean Needle2 is a bad model.

It may be an excellent fit for the platforms and use cases Cactus is targeting.

It just stopped being the obvious choice for mine.

And that was probably the main thing I got from the experiment.

A component can look almost perfect from the feature list and still be the wrong foundation once you start testing the boring parts: portability, failure modes, ambiguity, scaling, and integration cost.

For this kind of software, I’m becoming much more interested in how a model fails than in how impressive its best demo looks.

From Game Cheats to C Shell: Matheus’s Journey Into Programming

Fri, 11 Sep 2026 09:52:03 +0000

From Game Cheats to C Shell: Matheus’s Journey Into Programming

A CoderLegion Developer Story featuring Matheus

Interviewed and edited by Mehadi Hasan, Community & Editorial Team at CoderLegion

Matheus has been interested in computers since childhood. What started with playing games, experimenting with cheats, and carefully watching his father repair a computer eventually turned into a deep interest in programming, Unix, Linux, shell scripting, and low-level software.

Today, his interests span languages such as C, Objective-C, Smalltalk, Java, C#, JavaScript, Python, and Shell. More recently, he has been working directly on C shell, forking tcsh and experimenting with new features and changes to the shell's parsing and execution behavior.

His journey isn't really about following one technology.

It is about curiosity.

It Started With a Computer and Game Cheats

Matheus's interest in computers began before he was thinking seriously about programming.

One of his earliest memories involves playing games with cheats on a computer equipped with an Intel MMX processor.

Whenever something went wrong with the computer, he would ask his father to fix it. But he wasn't simply waiting for the computer to work again.

He watched closely.

"I used to pay close attention to the process, so I could reproduce myself."

That habit of watching how things worked would eventually become an important part of his approach to programming.

Instead of simply using technology, he wanted to understand how it worked and reproduce what he had seen.

Discovering Programming Through Game Servers

Matheus's programming journey properly began around 2013 or 2014.

At the time, he was hosting servers for games.

Those games included scripting languages that allowed players to write their own programs and modify the behavior of the game.

That was one of the first opportunities for Matheus to discover that software could be something he could actually change and build himself.

Around the same time, his interest in Linux and Unix began to develop.

The two interests gradually came together.

He started experimenting with shell scripting and quickly became fascinated by what could be accomplished from the command line.

"I played with shell scripting for a long time, until I met the C programming language, around 2021 and 2022."

His exploration of different technologies wasn't driven by a particular career plan.

It was driven mostly by curiosity.

"The reason I've explored many different technologies is mainly due to curiosity. I think my baggage is never enough, so I tend to learn every technology I can."

That curiosity has remained one of the defining characteristics of his programming journey.

Why Unix, Linux, and the Shell?

Matheus describes himself as a Unix and Linux enthusiast, but the part of the ecosystem that attracted him most was the shell.

For him, the shell isn't simply a way to launch programs.

It's a powerful programming environment.

"I think what mostly attracted and kept me interested in Linux and Unix is the shell."

Through shell scripting, he learned many different techniques and ways of solving problems.

The simplicity of the environment also gave him room to experiment.

"I like to think the shell is a great tool."

That interest eventually led him much deeper into understanding how shells work and, eventually, into modifying one himself.

From Shell Scripting to C

Shell scripting became an important part of how Matheus learned and practiced programming.

But learning C introduced a different way of thinking.

One of the interesting differences for him was the presence of pointers in C.

Coming from shell scripting, pointers were initially somewhat counter-intuitive.

Shell scripting doesn't have pointers in the same way C does.

But Matheus eventually came to appreciate how powerful they can be.

In fact, his curiosity went far enough that he began thinking about whether pointers could even be implemented on top of a shell.

That kind of experimentation reflects a broader pattern throughout his journey: rather than simply accepting how a technology works, he likes to ask what else might be possible.

Rethinking the C Shell

Today, Matheus is experimenting directly with C shell.

He is working on a fork of tcsh, exploring fixes and new features while rethinking parts of the shell's behavior.

One of his current projects focuses on one-line control structure parsing.

The goal is to make certain control structures work on a single line in a way similar to Bourne-style shells.

For example, C shell traditionally parses an entire command line before taking further action, which creates limitations around using semicolons and line feeds interchangeably. Matheus's implementation attempts to address that behavior. :contentReference[oaicite:1]{index=1}

He has also worked on other changes to the shell, including function declarations, variable assignment from pipes and redirections, comments in interactive sessions, and other fixes and features. :contentReference[oaicite:2]{index=2}

For Matheus, this isn't simply about using an existing shell.

He wants to understand its internals well enough to change them.

The Challenge of Parsing a Control Structure

One of the most challenging parts of his current work has been implementing one-line control structure parsing.

His first approach was to implement the mechanism through built-ins.

But he quickly realized that this would be dangerous and ineffective.

So he changed his approach.

Instead of handling the feature through built-ins, he moved the implementation into the post-parsing execution stage, where the command line could be reparsed and executed.

The implementation involves recursively analyzing the structure of commands and determining the opening and enclosing blocks of control structures.

Matheus describes the process as a set of recursive functions that analyze the parsed structure.

His recent CoderLegion article describes the implementation in more detail, including the use of new parsing and execution modes and a circular linked list for relevant command nodes. :contentReference[oaicite:3]{index=3}

It's a good example of how his curiosity has evolved.

What started with using software has become an interest in understanding and modifying the machinery underneath it.

Testing: You Can't Always Test Your Own Software

For Matheus, testing is an essential part of software development.

But he has also learned an important limitation:

The person who writes the software may not be the best person to test it.

"A developer by themselves may not be able to play the role of a tester."

A developer knows what they intended to build.

That can make it difficult to see all the unexpected ways another person might use it.

Matheus doesn't consider himself a tester.

He considers himself a developer whose goal is to produce a program.

Of course, he tests everything he develops himself.

But he doesn't assume that his own tests are enough.

Instead, he often asks other people to test his software because they can approach it from a different perspective.

"I'm unaware of the many possibilities of use."

That lesson is especially relevant to the kind of software he is currently building.

When you change something as fundamental as a shell, there can be many behaviors and edge cases that the original developer simply didn't anticipate.

Programming Isn't as Hard as It Looks

After spending years learning different technologies, Matheus has arrived at a surprisingly simple conclusion:

"Programming isn't as hard as thought."

Even subjects that initially appear intimidating can become manageable once you spend enough time with them.

That doesn't mean programming requires no effort.

For Matheus, the difficult part isn't necessarily that programming is impossibly complicated.

It's that understanding something requires time, experimentation, and persistence.

The intimidating subject becomes less intimidating once you start working with it.

The Hardest Part: Deciding How to Solve a Problem

One of Matheus's biggest challenges isn't learning a programming language.

It's deciding how to solve a problem.

"To solve a problem. This has always been challenging for me."

When planning an implementation, he isn't always sure that the solution he's considering is the best one.

There may be another approach that he hasn't thought of yet.

That uncertainty can make it difficult to begin.

Over time, however, he has developed a practical way of dealing with it.

If he has a reasonable solution, he believes it is often better to implement it rather than remain stuck trying to find the perfect approach.

"If you have a solution, put in practice, even if this isn't the best."

And if a better solution becomes apparent later, the software can be reimplemented.

For Matheus, moving forward can be more valuable than remaining paralyzed by uncertainty.

Learning From Other Developers

One of the things Matheus enjoys most about software development is the opportunity to learn from other people.

Building software alongside other developers exposes you to different approaches and different ways of thinking.

"They might have better solutions, and you can aggregate their knowledge."

Even though he doesn't currently work as part of a team, he still enjoys sharing software and ideas with other developers.

For him, open source and developer communities aren't just places to show what you've built.

They're places where knowledge can move in both directions.

You contribute something.

Someone else contributes an idea.

And your understanding becomes a little larger than it was before.

Finding a Community on CoderLegion

Matheus joined CoderLegion in January 2026 and has since shared articles and projects around programming, shell development, testing, Pascal, C, and open source. His recent posts include work on C shell and one-line control structure parsing. :contentReference[oaicite:4]{index=4}

His experience so far has been relatively quiet in terms of comments and engagement.

But that hasn't changed what he wants from the community.

"I'm not only seeking for engagement, but also for contributions."

For Matheus, the value of a developer community isn't simply the number of reactions a post receives.

He wants to expand his network, exchange knowledge, and contribute to other developers.

That's also why feedback matters to him.

A developer can build something alone, but other people can see possibilities, problems, and solutions that the original developer may have missed.

The Advice He Would Give to New Developers

For someone just beginning their programming journey, Matheus's advice is straightforward:

Don't give up.

"My best advice is to never look down and give up."

Programming is a journey, and according to Matheus, it requires dedication and discipline.

There will be moments when a problem seems impossible.

There will be technologies that look intimidating.

There will be times when you aren't sure how to implement something.

His advice is to keep moving.

And when you're stuck, don't be afraid to look for help.

One resource he particularly recommends is books.

"In my experience, I found books to be excellent guides when stuck."

For Matheus, learning isn't about reaching a point where there is nothing left to discover.

His own journey demonstrates almost the opposite.

From game scripting to shell scripting, from Unix and Linux to C, from programming languages to open-source shell development, curiosity keeps pushing him toward the next thing he wants to understand.

Curiosity Is the Common Thread

Looking at Matheus's journey, there isn't one programming language or framework that defines it.

The common thread is curiosity.

It started with watching his father repair a computer.

Then came game servers and scripting.

Then Linux and Unix.

Then shell scripting.

Then C.

And now, instead of simply using a shell, Matheus is working on the shell itself.

His journey shows that learning doesn't always follow a straight path.

Sometimes the best reason to learn a technology is simply because you want to understand it.

And sometimes that curiosity eventually leads you much deeper than you expected.

About Matheus

Matheus is a passionate computer programmer based in Brazil.

His programming interests include C, Objective-C, Smalltalk, Java, C#, JavaScript, Python, and Shell. He has a strong interest in Unix and Linux and is particularly interested in shell scripting and developer tools.

On CoderLegion, Matheus has shared work around C shell, testing, Pascal, C programming, and open source. His current work includes experimenting with and extending tcsh, including one-line control structure parsing and other shell improvements.

You can follow his work on his CoderLegion profile and his GitHub.

About This Developer Story

Developer: Matheus
Series: CoderLegion Developer Stories
Interview format: Q&A
Interviewed and edited by: Mehadi Hasan, Community & Editorial Team at CoderLegion

This story was created from Matheus's own answers and experiences shared during the CoderLegion Developer Stories Q&A.

C shell - Rethought and reimplementation on functions

Sat, 05 Sep 2026 22:12:55 +0000

Hello. Recently, I've added a new feature to the C shell. This feature is for one-line control structure parsing. Now, after this work, I've reimplemented functions. I disliked the work on functions based on pipes. Now, because one-line control structures are a feature, I based functions on aliases.

Should we have goto as one-line? What's your take?

One-line control structure parsing

Fri, 04 Sep 2026 20:27:33 +0000

Hello. I'm writing this post as a matter of contribution. I forked Tcsh, and added some features. My most-recent contribution is on one-line control structure parsing. I'm currently working on an implementation to parse control structures in a single line, as in Bourne shells.

It's well known that, e.g., foreach n ( * ) ; echo $n ; end doesn't work on any C shell. The line is parsed as a whole before further action is taken. The issue here is that ; and a line feed can't be used interchangeably. This work is an attempt to implement this interchangeability.

At first, I thought on implementing this in sh.func.c, the source relating to built-in commands. The work was supposed to create and run temporary functions. However, I realized this would be dangerous and ineffective. Therefore, the implementation is now residing in sh.sem.c, the source relating to post-parsing execution. I parse semicolons into a new node mode (NODE_LINE). I implemented a new mode (F_LINE). I "reparse" the entire tree, setting the F_LINE bit to every command node (NODE_COMMAND). Then, in execute(), I walk through the entire tree, analyzing which of the NODE_COMMAND entries contain the F_LINE mode. The node shall be saved in a circular linked list for each containing the F_LINE mode. Next, the circular linked list is analyzed from search(). search() shall perform a recursive operation, and analyze the opening and enclosing block for each keyword.

Because I first tried to implement this on top of a temporary function, I altered how semicolons are parsed. Notably, the command-line must end with a semicolon. This is only true when a semicolon is inserted. E.g.: echo hello ; echo world ;.

Moreover, I guess this implementation shall make a good companion to aliases. Even though I've worked on the function built-in, I realized aliases may make a great fit for functions. With this ongoing implementation on one-line control structure parsing, aliases may come handy for functions.

alias myfunc 'if \!^ then ; echo hello ; else ; echo bye ; endif ;'

This might be ugly, but is one way to implement functions.

I'm seeking for testers. The implementation is done.

I'd appreciate for contributions and feedback.

Thank you.

Git Will Humble You (And That's Okay)

Wed, 15 Jul 2026 05:28:26 +0000

Hey fam

This is my first ever dev article, and yes - I'm nervous.

So real talk — nobody warned me that learning to code would sometimes feel like arguing with a robot that's always right and never explains why you're wrong.

That robot? Git.

If you're a first-time developer, you've probably already had that moment. You type some command with full confidence, hit enter, and then... chaos. Your files are gone. Or duplicated. Or you're somehow on a branch that doesn't exist. Or the classic — you pushed to main when you absolutely should not have.

We've all been there. This post is for you.

What Even IS Git?

Git is a version control system — basically a time machine for your code. It tracks every change you make, lets you collaborate with other developers, and (in theory) saves you from destroying your own project.

The key word there is in theory.

The Commands That Will Ruin Your Day (If You're Not Careful)

git push --force

Oh, this one. This is the "delete everything and ask questions never" command. If you force push to a shared branch without knowing what you're doing, your teammates will find you. Don't do it until you really understand what it does.

git reset --hard

Hard reset sounds powerful because it is. It throws away all your uncommitted changes — no warning, no undo. Ran it once thinking it would fix my mess. It made a bigger mess.

git merge vs git rebase

These two will have you in a full philosophy debate at 2am. Both combine branches. Both will cause merge conflicts that look like ancient hieroglyphics. Learn the difference early — your future self will thank you.

Committing with no message (or a terrible one)

git commit -m "fix" — said every developer who regretted it 3 weeks later. Be descriptive. Always.

Why Mastering Git Early Actually Matters

When you're just starting out, it's easy to think Git is just a way to upload your code to GitHub or Gitea and look productive. But here's the thing — Git is your safety net. The better you understand it:

The less likely you are to lose work
The easier it is to collaborate without chaos
The more confident you look in team settings (yes, employers notice)
The faster you can recover when things break — and they will break

Git isn't just a tool. It's a habit. Build it early.

Resources to Actually Get Good

Here are some solid places to level up your Git, Go, Shell, and Rust game:

Git:

Pro Git Book — free, thorough, the bible
Oh My Git! — learn Git through a game (yes, really)
Learn Git Branching — visual and interactive

Go (Golang):

Go by Example — clean, no fluff

Shell / Bash:

The Linux Command Line by William Shotts — free online

Rust:

The Rust Book — the official one and it's actually great

Now I Wanna Hear From YOU

Drop it in the comments:

What was your first Git disaster?
What's the command that made you question your life choices?
Are you learning Go, Shell, or Rust right now? How's it going?

Let's laugh about it together — because if you're not breaking things, you're not learning.

If this helped you even a little, hit that ❤️, drop a comment, and let's connect!

Find me on LinkedIn → Mayan Okul — @mayan Okul — come say hi, seriously.

Tags: #git #golang #shell #rust #Zone01 #codenewbie #devjourney #programming #firstpost

"Push code, not limits — unless it's a feature branch. Then push everything."
— stay debugging, stay dangerous ⚡

— Mayan, your fav/baddest developer__

The Bash $PATH Debugger I Run Whenever I Get "Command Not Found"

Fri, 08 May 2026 18:09:24 +0000

Every experienced Linux user has been there: you install something, or move directories around, and suddenly command not found appears for tools you know are installed.

You check which, type, echo $PATH, and still waste 10-20 minutes hunting down the issue. I've done it more times than I care to admit — especially after fresh server setups or when cleaning up dotfiles.

That's why I built (and now constantly use) a Bash $PATH Debugger.

Paste your $PATH and get instant diagnosis

Here's how it works in practice:

Copy your current PATH: echo $PATH
Paste it into the tool
Get a full report + fixed version in seconds

Try it here: Bash $PATH Debugger

What the tool does

The debugger takes your raw $PATH string and analyzes every directory with these checks:

Existence: Does the directory actually exist on the filesystem?
Duplicates: Are you wasting lookup time with repeated entries?
Permissions: Are any directories missing execute permissions for your user?
Order: Shows the exact search priority (first match wins)
Clean output: Generates a cleaned, deduplicated export PATH=... line ready for .bashrc or .profile

It even highlights common problems like missing ~/.local/bin, collapsed entries after moves, or directories that exist but aren't in your current session.

Why this tool saves so much time

"command not found" (exit code 127) is one of the most searched Bash errors online. Yet most resources just tell you to export PATH=... manually without diagnosing why it broke.

This tool does the diagnosis for you. It's especially powerful on fresh VPS setups, after migrating user accounts, or when working with Docker/container environments where PATH behaves differently.

Real-world use cases

After a apt install or brew install that doesn't add itself to PATH properly
Debugging why a script works in one terminal but not another
Cleaning up an overloaded PATH that accumulated junk over years
Preparing a clean minimal PATH for production servers

Pro tip: Test on a clean VPS

One of my favorite workflows is spinning up a fresh $4-5/mo VPS, installing my usual tools, running them through the debugger, and copying the optimized PATH into my base server image.

Common variations & advanced usage

The tool also supports:

Relative path expansion
Handling of ~ and environment variables in PATH entries
Export formats for different shells (bash, zsh, fish compatibility notes)

Full interactive tool with live diagnosis, cleaned PATH generator, and detailed explanations:
https://bashsnippets.xyz/tools/path-debugger.html

Paste your PATH. Fix the problem. Move on.

A Soft Introduction to EasyShell

Tue, 05 May 2026 02:31:45 +0000

"Can it be simpler?" - A recurring thought I've had while working on build automation.

EasyShell (command: easy) is a minimal shell scripting language designed from the ground up for simplicity and cross-platform build/process automation. If you’ve ever felt that PowerShell’s syntax is powerful but easy to forget, or that traditional shell scripts get messy across operating systems, EasyShell aims to strike a cleaner balance.

It's implemented in C# and runs on .NET, giving you natural access to the entire .NET ecosystem while keeping the scripting experience lightweight and approachable.

Design Principles

One command per line (shell-like flow)
Very small set of core concepts
Strongly-typed global variables
Seamless .NET interop via reflection
Expressions in parentheses for inline evaluation
Easy to read, write, and remember

Version 0.1.0 is now available — functional for everyday automation tasks.

Core Language Features

Variables

All variables are declared with an explicit type and live in global scope:

INTVAR Count 42
BOOLVAR Debug TRUE
DOUBLEVAR Ratio 3.14
STRINGVAR Message "Hello from EasyShell"
HANDLEVAR Now System.DateTime.Now   # stores object instances

Variable names are case-insensitive
Reference with $VarName
Re-assign with $VarName = value (or expressions)

Expressions (The Power Feature)

Wrap sub-commands in parentheses to evaluate them inline:

STRINGVAR Formatted (System.String.Format "Count = {0}" $Count)
BOOLVAR IsBig (> $Count 100)
STRINGVAR Today (format "{0:yyyy-MM-dd}" (GetDate))

Calling .NET

Static members (fully qualified):

System.Console.WriteLine "Hello World!"
System.IO.File.WriteAllText "output.txt" $Message

Instance methods via HANDLE:

HANDLEVAR Now System.DateTime.Now
STRINGVAR Stamp (CALL $Now ToString)

Control Flow

IF (== $Count 42)
    print "The answer!"
ELSEIF (> $Count 50)
    print "Too high"
ELSE
    print "Something else"
END

INTVAR I 0
WHILE (< $I 5)
    System.Console.WriteLine $I
    $I = (+ $I 1)   # arithmetic helpers coming soon
END

Functions

Simple named blocks (no parameters — use globals):

FUNC BuildProject
    print "Building..."
    dotnet build
END

CALL BuildProject

External Commands

Any command that isn’t a keyword or .NET call falls back to executing an external process (with stdout capture):

git status
dotnet publish ...

Real-World Example

Check out the full build script used by the project itself:
BuildEasyShell.easy

It demonstrates:

Path handling and folder creation
Running dotnet publish
Conditional logic for OS/architecture
Creating a dated zip package

This script is self-contained and shows how EasyShell can manage non-trivial automation tasks.

Quick Start

# REPL mode
easy

# Run a script
easy path/to/script.easy

# Help
easy --help

A dedicated VS Code syntax highlighting extension is available: Methodox.easyshell

Who Is It For?

EasyShell is ideal for:

Build automation scripts
Simple CI/CD glue
Daily developer tooling
Anyone who wants .NET power without heavy dependency

It's intentionally minimal — no advanced Bash-style features, just the essentials done in a way that’s hard to forget.

Give it a try and let me know what you think!

DevLog 20251214: Yet Another Shell Script – Keeping Build Automation Simple with EasyShell

Tue, 05 May 2026 02:23:48 +0000

As we roll out more tools, both internal and public, there has been a growing need for easy-to-maintain shell scripting and build automation. Build automation is complex enough without all the syntax burden - my favorite is to use PowerShell, but often it feels like wrestling with the tool itself. PowerShell is powerful, sure, but its depth often means hunting down syntax I know I've used a dozen times before. Bash has its quirks across platforms, and honestly I don't know good ways of using it outside MinGW, Git Bash, or WSL - none of which felt quite "right".

I wanted something lighter: a shell scripting tool that's easy to pick up, cross-platform, and hard to forget once you start using it.

So I made EasyShell (or just easy): a minimal shell scripting language implemented in C# that focuses on process automation with a very small set of concepts.

Motivation and Design

EasyShell is for "lazy" developers (like me) who just want to automate common tasks - calling .NET APIs, running external tools, handling simple logic - without a steep syntax curve or platform-specific headaches. It combines a shell-like one-command-per-line flow with strong typing and easy .NET interop. No advanced Bash-style wizardry; just straightforward scripting.

It could also serve as a nice companion alongside other tools in the long-term Divooka ecosystem.

Quick Taste of the Syntax

Files typically use the .easy extension, with syntax highlighting available via the VS Code extension.

Here's a small sample from the repo:

# Comments start with #
HANDLEVAR NOW System.DateTime.Now

# Instance method via CALL
STRINGVAR DATE (CALL $NOW ToString)

# Static .NET call with expression
STRINGVAR VALUE (System.String.Format "Current time: {0}" $DATE)

STRINGVAR PATH "C:/temp/greeting.txt"
System.IO.File.WriteAllText $PATH $VALUE

Variables are declared with their type (INTVAR, STRINGVAR, BOOLVAR, DOUBLEVAR, HANDLEVAR), names are case-insensitive, and everything lives in global scope for simplicity. Expressions are wrapped in parentheses for inline evaluation, like (== $X 10) or sub-commands.

Control flow sticks to the basics:

IF ... ELSEIF ... ELSE ... END
WHILE ... END
Simple FUNC ... END / CALL (globals make "returns" easy via variables)

You can call external executables naturally, and non-built-in commands fall through to process execution (stdout capture included).

Early Days

This is version 0.1.0 territory - functional for everyday build tasks, with room to grow (arithmetic helpers, more examples, etc.). You can run it in REPL mode (easy) or point it at a script. Builds and packages are straightforward with the included scripts.

If you've ever wished for something between a full PowerShell script and a quick batch file that "just works" across machines, maybe give EasyShell a try. The GitHub repo has the full language overview, examples, and build details: MethodoxTech/EasyShell.

How to Detect and Monitor Multiple GPUs on Linux

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

If you run Linux on a system with both an integrated GPU and a dedicated GPU, you may have noticed something strange: some monitoring tools only show one GPU.

This situation is common on:

laptops with hybrid graphics
desktops with iGPU + dedicated GPU
systems using different driver stacks

For example, a monitoring tool like btop might show your AMD integrated GPU but completely ignore your NVIDIA card.

In this article we will walk through how to:

detect all GPUs installed in your system
verify that the correct drivers are loaded
identify which GPU is rendering your desktop
monitor usage for each GPU
automate the entire diagnostic process with a small script

Why This Happens

Linux systems with multiple GPUs may behave differently depending on:

installed drivers (open source vs proprietary)
kernel configuration
which GPU is configured as the primary renderer
monitoring tool capabilities

Example setup used in this article:

AMD Vega (integrated) — Ryzen 5 5600G
NVIDIA GTX 1050 Ti (dedicated)

In this configuration, btop showed only the AMD GPU while the NVIDIA card remained invisible in the default monitoring view.

Step 1 — Check if Both GPUs Are Detected

1.1 List GPUs via PCI

Run:

lspci | grep -i vga

Example output:

01:00.0 VGA compatible controller: NVIDIA Corporation GP107 [GeForce GTX 1050 Ti]
09:00.0 VGA compatible controller: Advanced Micro Devices, Inc. [AMD/ATI] Cezanne [Radeon Vega Series]

If two entries appear, your hardware is being detected correctly.

1.2 Check Loaded Drivers

Run:

lsmod | grep -E 'nvidia|amdgpu|radeon'

Typical modules:

GPU	Kernel Module
NVIDIA	`nvidia`, `nvidia_drm`, `nvidia_modeset`
AMD (modern)	`amdgpu`
AMD (legacy)	`radeon`

If the modules appear, the drivers are loaded by the kernel.

1.3 Check Which GPU Is Rendering Your Desktop

Use:

glxinfo | grep "OpenGL renderer"

Example output:

OpenGL renderer string: NVIDIA GeForce GTX 1050 Ti

If glxinfo is missing, install it.

Ubuntu / Debian:

sudo apt install mesa-utils

Arch Linux:

sudo pacman -S mesa-utils

This command reveals which GPU is rendering the graphical session.

In hybrid setups, the integrated GPU often renders the desktop while the dedicated GPU activates only for demanding workloads.

Step 2 — Monitoring Each GPU

2.1 Integrated GPU (AMD / Intel) — Using btop

Launch:

btop

Inside btop:

press g to toggle GPU views
press 5 / 6 / 7 for specific GPU panels
configure via F2 → Options → CPU box → Show GPU info

2.2 NVIDIA Dedicated GPU — Using nvidia-smi

For NVIDIA GPUs the official tool is the most reliable:

watch -n 1 nvidia-smi

This updates every second and displays:

GPU utilization
memory usage
running processes

Structured output:

nvidia-smi --query-gpu=name,memory.used,memory.total,utilization.gpu --format=csv -l 1

Step 3 — Automating GPU Diagnostics

Create a script called:

check_gpus.sh

Script:

#!/bin/bash

echo "=== GPUs Detected ==="
lspci | grep -E "VGA|3D"

echo -e "\n=== Loaded Drivers ==="
lsmod | grep -E "nvidia|amdgpu|radeon"

echo -e "\n=== NVIDIA GPU ==="
nvidia-smi --query-gpu=name,memory.total --format=csv 2>/dev/null || echo "NVIDIA not detected"

echo -e "\n=== Rendering GPU ==="
glxinfo | grep "OpenGL renderer" 2>/dev/null || echo "glxinfo not available"

echo -e "\n=== DRM Devices ==="
ls /sys/class/drm | grep card

Make executable:

chmod +x check_gpus.sh

Run:

./check_gpus.sh

This quickly shows:

detected GPUs
active drivers
rendering GPU
NVIDIA status
DRM device nodes

Recommended Tools Summary

GPU Type	Recommended Tool	Command
AMD / Intel (integrated)	`btop`	`btop`
NVIDIA (dedicated)	`nvidia-smi`	`watch -n 1 nvidia-smi`
Hardware detection	`lspci`	`lspci \| grep -i vga`
Rendering check	`glxinfo`	`glxinfo \| grep "OpenGL renderer"`

Conclusion

Working with multiple GPUs on Linux doesn't have to be confusing.

Using the commands shown above you can:

verify hardware detection
confirm driver loading
identify which GPU renders your desktop
monitor GPU usage in real time
automate diagnostics with a small script

Different GPU stacks require different tools, but combining a few commands provides full visibility into your graphics subsystem.

Additional Resources

btop documentation
https://github.com/aristocratos/btop

NVIDIA System Management Interface
https://developer.nvidia.com/nvidia-system-management-interface

Arch Linux Wiki — NVIDIA
https://wiki.archlinux.org/title/NVIDIA

From 1.4s to 53ms: Optimizing zsh Startup on macOS

Wed, 11 Feb 2026 13:52:03 +0000

Every time I opened a terminal, I waited. Not long — maybe a second and a half — but long enough to notice. Long enough to be annoying. I finally decided to profile my zsh startup, and what I found took it from 1.4 seconds down to 53 milliseconds.

Here's what I learned.

Profiling with zprof

Zsh has a built-in profiler. Add zmodload zsh/zprof at the top of your .zshrc and zprof at the bottom, then open a new shell:

# top of .zshrc
zmodload zsh/zprof

# ... your config ...

# bottom of .zshrc
zprof

My initial profile told a clear story:

Culprit	Time	% of startup
NVM (`nvm.sh`)	~430ms	31%
Completion subprocesses (kubectl, helm, gh, ...)	~400ms	29%
`compinit` (full rebuild every time)	~240ms	17%
`brew shellenv`	~30ms	2%
`go env GOPATH`	~20ms	1%
Everything else	~280ms	20%

Four of these five are subprocess calls — things like eval "$(brew shellenv)" or source <(kubectl completion zsh) that fork a process just to produce some static text. That's the low-hanging fruit.

Optimization 1: Lazy-load NVM

NVM was the single biggest offender. Sourcing nvm.sh on every shell startup cost ~430ms, and I don't use node in every terminal session. The fix: wrapper functions that defer loading until you actually call nvm, node, npm, etc.

Before:

export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"

After:

export NVM_DIR="$HOME/.nvm"

_nvm_lazy_load() {
  unfunction nvm node npm npx corepack 2>/dev/null
  [ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
  [ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"
}

nvm()      { _nvm_lazy_load; nvm "$@" }
node()     { _nvm_lazy_load; node "$@" }
npm()      { _nvm_lazy_load; npm "$@" }
npx()      { _nvm_lazy_load; npx "$@" }
corepack() { _nvm_lazy_load; corepack "$@" }

The wrapper functions replace themselves on first call via unfunction, then delegate to the real command. Cost at startup: zero. Cost on first node invocation: ~430ms (once).

Optimization 2: Hardcode static values

Several lines in my config were spawning subprocesses to compute values that never change:

# Before — subprocess every startup
eval "$(/opt/homebrew/bin/brew shellenv)"
export PATH="$PATH:$(go env GOPATH)/bin"
. "$HOME/.cargo/env"

These produce the same output every time. Just paste the result directly:

# After — zero subprocesses
export HOMEBREW_PREFIX="/opt/homebrew"
export HOMEBREW_CELLAR="/opt/homebrew/Cellar"
export HOMEBREW_REPOSITORY="/opt/homebrew"
export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:$PATH"
[ -z "${MANPATH-}" ] || export MANPATH=":${MANPATH#:}"
export INFOPATH="/opt/homebrew/share/info:${INFOPATH:-}"

export GOPATH="$HOME/go"
export PATH="$PATH:$GOPATH/bin"

export PATH="$HOME/.cargo/bin:$PATH"

Leave a comment like # regenerate with: brew shellenv so future-you knows where the values came from.

Optimization 3: Cache completions into fpath

This was the big one. My original config eagerly sourced completions from 12 different tools on every shell startup:

# Before — 12 subprocesses, every startup
command -v kubectl  &>/dev/null && source <(kubectl completion zsh)
command -v helm     &>/dev/null && source <(helm completion zsh)
command -v minikube &>/dev/null && source <(minikube completion zsh)
command -v gh       &>/dev/null && source <(gh completion -s zsh)
# ... 8 more tools

Each source <(tool completion zsh) forks a subprocess AND evaluates thousands of lines of shell code. Minikube's completion alone is 5,000 lines.

The fix has two parts:

For completions: write them to files in an fpath directory. Compinit loads these lazily — only when you actually press TAB on that command:

ZSH_COMP_CACHE="$HOME/.zsh-completion-cache"
[[ -d "$ZSH_COMP_CACHE" ]] || mkdir -p "$ZSH_COMP_CACHE"

_cache_fpath() {
  local name="$1"; shift
  local cache_file="$ZSH_COMP_CACHE/_$name"
  local -a stale=($cache_file(N.mh+24))
  if [[ ! -f "$cache_file" ]] || (( $#stale )); then
    "$@" > "$cache_file" 2>/dev/null
  fi
}

command -v kubectl &>/dev/null && _cache_fpath kubectl kubectl completion zsh
command -v helm    &>/dev/null && _cache_fpath helm    helm completion zsh
# ... etc

fpath=($ZSH_COMP_CACHE $fpath)

For plugins that must run at startup (fzf keybindings, direnv hook, oh-my-posh prompt), cache their init output and zcompile for faster sourcing:

_cache_source() {
  local name="$1"; shift
  local cache_file="$ZSH_COMP_CACHE/$name.zsh"
  local -a stale=($cache_file(N.mh+24))
  if [[ ! -f "$cache_file" ]] || (( $#stale )); then
    "$@" > "$cache_file" 2>/dev/null
    zcompile "$cache_file" 2>/dev/null
  fi
  source "$cache_file"
}

_cache_source fzf fzf --zsh
_cache_source direnv direnv hook zsh
_cache_source oh-my-posh oh-my-posh init zsh --config ~/.poshthemes/theme.omp.json --print

Both functions use a 24-hour cache expiry via zsh glob qualifiers. Delete ~/.zsh-completion-cache to force a refresh.

I also cached compinit itself — a full rebuild only runs once per day, and otherwise compinit -C skips straight to the dump file:

autoload -Uz compinit
local -a zcompdump_stale=(~/.zcompdump(N.mh+24))
if (( $#zcompdump_stale )); then
  compinit
else
  compinit -C
fi
{ zcompile ~/.zcompdump } &!

The bug that almost ruined everything

After implementing all of this, I ran time zsh -i -c exit. The result: 1.59 seconds. Slower than before.

I profiled again and saw this:

num  calls                time            self            name
-----------------------------------------------------------------
 1)   15   1180.06  97.34%  1169.02  96.43%  _cache_completion
 2)    1     26.83   2.21%     7.49   0.62%  compinit

The caching function was taking 97% of startup time across 15 calls. The caches existed on disk but were being regenerated every single time. The staleness check was broken.

I restructured the approach — separating completions (fpath-based, lazy) from plugins (source-based, eager) — and tried again. Same problem: _cache_fpath at 72%, compinit doing full rebuilds.

The bug was in this line:

if [[ ! -f "$cache_file" || -n "$cache_file"(#qN.mh+24) ]]; then

This looks reasonable. The glob qualifier (#qN.mh+24) means "match if the file is older than 24 hours, with N (nullglob) to return empty string if no match." The -n test checks if the result is non-empty.

The problem: glob qualifiers don't expand inside [[ ]].

Zsh's [[ ]] conditional construct does not perform filename generation (globbing). The string "$cache_file"(#qN.mh+24) is treated as the literal path with (#qN.mh+24) appended as text. Since that string is always non-empty, the condition is always true. Every cache was being regenerated on every startup. The caching was doing nothing.

The same bug affected the compinit staleness check:

# Also broken — compinit was doing a full rebuild every time
if [[ -n ~/.zcompdump(#qN.mh+24) ]]; then

The fix: expand the glob into an array variable first, then check its length:

local -a stale=($cache_file(N.mh+24))
if [[ ! -f "$cache_file" ]] || (( $#stale )); then

Regular variable assignments DO perform globbing. The (N.mh+24) qualifier (no #q prefix needed outside [[ ]]) expands the glob, and $#stale gives us the match count. If the file is older than 24 hours, stale contains one element; otherwise it's empty.

This is a subtle footgun. The code looks correct, it doesn't produce errors, and the caches are created — they're just never reused. Without profiling, you'd never know.

Result

$ time zsh -i -c exit
zsh -i -c exit  0.03s user 0.02s system 93% cpu 0.053 total

53 milliseconds. A 96% reduction from 1.4 seconds.

Here's what each optimization contributed:

Optimization	Savings
Lazy-load NVM	~430ms
Cache completions into fpath (lazy compinit)	~500ms
Cache plugin init scripts + zcompile	~200ms
Hardcode brew/go/cargo	~50ms
compinit -C (cached dump)	~170ms
Total	~1,350ms

The first shell open after 24 hours takes a couple of seconds to regenerate caches, but every subsequent shell is instant. You can force a full refresh anytime:

rm -rf ~/.zsh-completion-cache ~/.zcompdump*

Takeaways

Profile first. zprof told me exactly where the time was going. Don't guess.
Subprocess calls add up. Each eval $(...) or source <(...) forks a process. Twelve of them cost almost a full second.
fpath > source for completions. Compinit loads completion functions lazily from fpath. Don't eagerly source thousands of lines you might never use.
Test your caching actually works. A cache that regenerates every time is worse than no cache — it has the overhead of both the generation AND the file I/O.
Glob qualifiers don't work inside [[ ]]. This is the kind of bug that looks correct, produces no errors, and silently destroys your performance. Expand globs into variables first.

From 1.4s to 53ms: Optimizing zsh Startup on macOS

Wed, 11 Feb 2026 09:35:03 +0000

Here's what I learned.

Profiling with zprof

Zsh has a built-in profiler. Add zmodload zsh/zprof at the top of your .zshrc and zprof at the bottom, then open a new shell:

# top of .zshrc
zmodload zsh/zprof

# ... your config ...

# bottom of .zshrc
zprof

My initial profile told a clear story:

Culprit	Time	% of startup
NVM (`nvm.sh`)	~430ms	31%
Completion subprocesses (kubectl, helm, gh, ...)	~400ms	29%
`compinit` (full rebuild every time)	~240ms	17%
`brew shellenv`	~30ms	2%
`go env GOPATH`	~20ms	1%
Everything else	~280ms	20%

Optimization 1: Lazy-load NVM

Before:

export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"

After:

export NVM_DIR="$HOME/.nvm"

_nvm_lazy_load() {
  unfunction nvm node npm npx corepack 2>/dev/null
  [ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
  [ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"
}

nvm()      { _nvm_lazy_load; nvm "$@" }
node()     { _nvm_lazy_load; node "$@" }
npm()      { _nvm_lazy_load; npm "$@" }
npx()      { _nvm_lazy_load; npx "$@" }
corepack() { _nvm_lazy_load; corepack "$@" }

The wrapper functions replace themselves on first call via unfunction, then delegate to the real command. Cost at startup: zero. Cost on first node invocation: ~430ms (once).

Optimization 2: Hardcode static values

Several lines in my config were spawning subprocesses to compute values that never change:

# Before — subprocess every startup
eval "$(/opt/homebrew/bin/brew shellenv)"
export PATH="$PATH:$(go env GOPATH)/bin"
. "$HOME/.cargo/env"

These produce the same output every time. Just paste the result directly:

# After — zero subprocesses
export HOMEBREW_PREFIX="/opt/homebrew"
export HOMEBREW_CELLAR="/opt/homebrew/Cellar"
export HOMEBREW_REPOSITORY="/opt/homebrew"
export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:$PATH"
[ -z "${MANPATH-}" ] || export MANPATH=":${MANPATH#:}"
export INFOPATH="/opt/homebrew/share/info:${INFOPATH:-}"

export GOPATH="$HOME/go"
export PATH="$PATH:$GOPATH/bin"

export PATH="$HOME/.cargo/bin:$PATH"

Leave a comment like # regenerate with: brew shellenv so future-you knows where the values came from.

Optimization 3: Cache completions into fpath

This was the big one. My original config eagerly sourced completions from 12 different tools on every shell startup:

# Before — 12 subprocesses, every startup
command -v kubectl  &>/dev/null && source <(kubectl completion zsh)
command -v helm     &>/dev/null && source <(helm completion zsh)
command -v minikube &>/dev/null && source <(minikube completion zsh)
command -v gh       &>/dev/null && source <(gh completion -s zsh)
# ... 8 more tools

Each source <(tool completion zsh) forks a subprocess AND evaluates thousands of lines of shell code. Minikube's completion alone is 5,000 lines.

The fix has two parts:

For completions: write them to files in an fpath directory. Compinit loads these lazily — only when you actually press TAB on that command:

ZSH_COMP_CACHE="$HOME/.zsh-completion-cache"
[[ -d "$ZSH_COMP_CACHE" ]] || mkdir -p "$ZSH_COMP_CACHE"

_cache_fpath() {
  local name="$1"; shift
  local cache_file="$ZSH_COMP_CACHE/_$name"
  local -a stale=($cache_file(N.mh+24))
  if [[ ! -f "$cache_file" ]] || (( $#stale )); then
    "$@" > "$cache_file" 2>/dev/null
  fi
}

command -v kubectl &>/dev/null && _cache_fpath kubectl kubectl completion zsh
command -v helm    &>/dev/null && _cache_fpath helm    helm completion zsh
# ... etc

fpath=($ZSH_COMP_CACHE $fpath)

For plugins that must run at startup (fzf keybindings, direnv hook, oh-my-posh prompt), cache their init output and zcompile for faster sourcing:

_cache_source() {
  local name="$1"; shift
  local cache_file="$ZSH_COMP_CACHE/$name.zsh"
  local -a stale=($cache_file(N.mh+24))
  if [[ ! -f "$cache_file" ]] || (( $#stale )); then
    "$@" > "$cache_file" 2>/dev/null
    zcompile "$cache_file" 2>/dev/null
  fi
  source "$cache_file"
}

_cache_source fzf fzf --zsh
_cache_source direnv direnv hook zsh
_cache_source oh-my-posh oh-my-posh init zsh --config ~/.poshthemes/theme.omp.json --print

Both functions use a 24-hour cache expiry via zsh glob qualifiers. Delete ~/.zsh-completion-cache to force a refresh.

I also cached compinit itself — a full rebuild only runs once per day, and otherwise compinit -C skips straight to the dump file:

autoload -Uz compinit
local -a zcompdump_stale=(~/.zcompdump(N.mh+24))
if (( $#zcompdump_stale )); then
  compinit
else
  compinit -C
fi
{ zcompile ~/.zcompdump } &!

The bug that almost ruined everything

After implementing all of this, I ran time zsh -i -c exit. The result: 1.59 seconds. Slower than before.

I profiled again and saw this:

num  calls                time            self            name
-----------------------------------------------------------------
 1)   15   1180.06  97.34%  1169.02  96.43%  _cache_completion
 2)    1     26.83   2.21%     7.49   0.62%  compinit

The caching function was taking 97% of startup time across 15 calls. The caches existed on disk but were being regenerated every single time. The staleness check was broken.

I restructured the approach — separating completions (fpath-based, lazy) from plugins (source-based, eager) — and tried again. Same problem: _cache_fpath at 72%, compinit doing full rebuilds.

The bug was in this line:

if [[ ! -f "$cache_file" || -n "$cache_file"(#qN.mh+24) ]]; then

The problem: glob qualifiers don't expand inside [[ ]].

The same bug affected the compinit staleness check:

# Also broken — compinit was doing a full rebuild every time
if [[ -n ~/.zcompdump(#qN.mh+24) ]]; then

The fix: expand the glob into an array variable first, then check its length:

local -a stale=($cache_file(N.mh+24))
if [[ ! -f "$cache_file" ]] || (( $#stale )); then

This is a subtle footgun. The code looks correct, it doesn't produce errors, and the caches are created — they're just never reused. Without profiling, you'd never know.

Result

$ time zsh -i -c exit
zsh -i -c exit  0.03s user 0.02s system 93% cpu 0.053 total

53 milliseconds. A 96% reduction from 1.4 seconds.

Here's what each optimization contributed:

Optimization	Savings
Lazy-load NVM	~430ms
Cache completions into fpath (lazy compinit)	~500ms
Cache plugin init scripts + zcompile	~200ms
Hardcode brew/go/cargo	~50ms
compinit -C (cached dump)	~170ms
Total	~1,350ms

The first shell open after 24 hours takes a couple of seconds to regenerate caches, but every subsequent shell is instant. You can force a full refresh anytime:

rm -rf ~/.zsh-completion-cache ~/.zcompdump*

Takeaways

Profile first. zprof told me exactly where the time was going. Don't guess.
Subprocess calls add up. Each eval $(...) or source <(...) forks a process. Twelve of them cost almost a full second.
fpath > source for completions. Compinit loads completion functions lazily from fpath. Don't eagerly source thousands of lines you might never use.
Test your caching actually works. A cache that regenerates every time is worse than no cache — it has the overhead of both the generation AND the file I/O.
Glob qualifiers don't work inside [[ ]]. This is the kind of bug that looks correct, produces no errors, and silently destroys your performance. Expand globs into variables first.

I Replaced nvm, Homebrew Go, and Homebrew Python with a Single Tool

Wed, 11 Feb 2026 08:00:21 +0000

I maintain a symlink-based dotfiles repo for macOS/zsh. Over time, I'd accumulated three different approaches to managing runtime versions: nvm for Node.js, brew install go for Go, and brew install python@3.13 for Python. Each had its own quirks, its own update ritual, and its own startup cost. mise consolidates all of them into one tool with a single config file.

This article walks through the actual migration: what changed, what broke, and the non-obvious tricks that made it worth doing.

The starting point: an nvm lazy-load hack

nvm is slow. Loading it adds 300-500ms to every new shell. My workaround was a lazy-load wrapper in zprofile that deferred the cost until you actually called node, npm, or friends:

# NVM (lazy-loaded for fast startup)
export NVM_DIR="$HOME/.nvm"

_nvm_lazy_load() {
  unfunction nvm node npm npx corepack 2>/dev/null
  [ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
  [ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"
}

nvm()      { _nvm_lazy_load; nvm "$@" }
node()     { _nvm_lazy_load; node "$@" }
npm()      { _nvm_lazy_load; npm "$@" }
npx()      { _nvm_lazy_load; npx "$@" }
corepack() { _nvm_lazy_load; corepack "$@" }

This worked, but it was 15 lines of shell plumbing to avoid a startup penalty from a tool that only manages Node. Go and Python had no version management at all — I just installed whatever Homebrew gave me.

The mise config

mise replaces all of that with a TOML file:

[tools]
node = "22"
go = "1.24"
python = "3.13"

[settings]
idiomatic_version_file = true

That's it. mise install downloads the right versions. The idiomatic_version_file setting means mise reads .nvmrc, .node-version, .python-version, and .go-version files from existing projects — so teams using nvm or pyenv don't need to change anything.

Shell integration: the dual activation trick

This is the part that took some thought. mise offers two modes:

Shims (mise activate zsh --shims): Lightweight stubs in ~/.local/share/mise/shims/ that resolve to the right binary. Fast, works everywhere, but they don't auto-switch versions when you cd into a project with an .nvmrc.
Activate (mise activate zsh): Hooks into your shell's precmd/chpwd to dynamically update PATH. Supports auto-switching, but doesn't run in non-interactive contexts (scripts, IDE terminals running commands, cron jobs).

You need both.

In zprofile (runs for all sessions, including non-interactive):

# Mise — shims for non-interactive sessions (scripts, IDEs, cron)
eval "$(mise activate zsh --shims)"

In plugins.zsh (sourced only in interactive shells via zshrc):

_cache_source mise mise activate zsh

The activate call in interactive shells overrides the shims with real PATH entries, enabling directory-aware version switching. Non-interactive sessions fall back to shims, which resolve to whatever version the config specifies.

The `_cache_source` + zcompile trick

That _cache_source call above is doing more than it looks. Running mise activate zsh generates a shell script on every new shell — and that generation adds 25-300ms depending on the machine. For a shell that opens in 50ms total, that's unacceptable.

The solution: cache the output and compile it to zsh bytecode.

_cache_source() {
  local name="$1"; shift
  local cache_file="$ZSH_COMP_CACHE/$name.zsh"
  local -a stale=($cache_file(N.mh+24))
  if [[ ! -f "$cache_file" ]] || (( $#stale )); then
    "$@" > "$cache_file" 2>/dev/null
    zcompile "$cache_file" 2>/dev/null
  fi
  source "$cache_file"
}

Here's what it does:

Runs mise activate zsh and captures the output to a cache file
Compiles it to zsh bytecode with zcompile (creates a .zwc file)
Sources the cached file on every subsequent shell open
Regenerates after 24 hours (the (N.mh+24) glob qualifier checks mtime)

Why does the compiled version load faster? When you source a plain .zsh file, zsh reads the text, tokenizes the shell syntax, and parses it into an internal representation — every single time. zcompile does that work once and writes the result as a .zwc file — a pre-parsed "wordcode" format that zsh can memory-map and load directly, skipping the tokenize-and-parse steps entirely. For a large generated script like mise activate output, this eliminates the most expensive part of source.

The clever bit is that zsh handles .zwc lookup transparently. When you run source foo.zsh, zsh first checks for foo.zsh.zwc. If the .zwc exists and is newer than the source file, zsh loads the compiled version without being told to. This means _cache_source doesn't need any special logic to prefer the compiled file — source "$cache_file" does the right thing on its own.

And if the .zwc is stale or missing? Zsh silently falls back to parsing the source file the normal way. Nothing breaks — you just lose the speed benefit until the cache regenerates. A stale .zwc can never serve incorrect code because zsh won't use it if the source has changed. This makes the whole approach safe to leave running unattended.

The result: mise activation costs <5ms instead of 25-300ms. This same function works for any "run a command, source the output" pattern — I use it for fzf, direnv, and mise.

This is probably the most reusable thing in the whole migration. If you maintain a zsh config and source any tool's init or activate output, wrap it in something like this.

For the full story on this caching approach — including a subtle glob qualifier bug that silently breaks it — see From 1.4s to 53ms: Optimizing zsh Startup on macOS.

Brew changes

The cleanup was straightforward:

Remove:

nvm — replaced by mise
node — installed by mise
go — installed by mise
python@3.13 — installed by mise
yarn — moved to corepack (see below)

Added:

mise

One gotcha: some Homebrew formulae declare node as a dependency. In my case, markdownlint-cli2 depends on the Homebrew node formula. Removing node from the Brewfile triggers warnings on brew bundle, but it's cosmetic — mise's shims satisfy the actual runtime need. The formula's dependency declaration is about the build, not about your shell having node on PATH. I left it as-is and the warnings are harmless.

Corepack for yarn

With nvm gone, yarn no longer comes from Homebrew either. Node ships with corepack, which manages yarn (and pnpm) natively:

corepack enable

This creates symlinks inside the Node install directory. The catch: when mise installs a new Node version, those symlinks live in the old version's directory. You need to re-run corepack enable after mise install node@<new-version>. It's a one-liner, but easy to forget when you bump Node versions.

The migration procedure

The key insight is that nvm and mise can coexist. This makes the migration safe to do in phases:

Phase 1 — Install mise alongside nvm:

brew install mise
Create mise/config.toml with your current versions
Add the dual activation (shims in zprofile, activate in plugins.zsh)
Open a new shell, verify node --version, go version, python3 --version

Phase 2 — Verify everything works:

Run your builds, tests, dev servers
Check IDE integration (VS Code, JetBrains)
Verify non-interactive contexts: zsh -c 'node --version'
Run corepack enable and confirm yarn --version

Phase 3 — Remove nvm:

Delete the lazy-load block from zprofile
Remove nvm, node, go, python@3.13, yarn from Brewfile
Run brew bundle cleanup --force
Commit

Safety net: nvm's data (~/.nvm/) stays untouched through all of this. If something breaks, you can restore the old zprofile block and you're back to where you started. The whole thing is one git checkout -- shell/zprofile away from reverting.

`.nvmrc` compatibility

If your team uses .nvmrc files (and most Node teams do), the idiomatic_version_file = true setting in mise's config handles it. When you cd into a directory with an .nvmrc, mise reads it and switches to the specified Node version — same as nvm would.

This also works for .node-version, .python-version, and .go-version. So mise supports the conventions from nvm, nodenv, pyenv, and goenv without any extra configuration.

Final result

The zprofile went from 30 lines to 18. The nvm lazy-load hack — 15 lines of shell functions — became a single eval line. Three separate version management approaches (nvm, Homebrew Go, Homebrew Python) became one config file.

Shell startup stayed at ~0.05s thanks to the caching strategy. The dual activation means shims handle non-interactive contexts while the full activate gives you directory-aware switching in your terminal.

The commit tells the story:

Replace nvm with mise for Node.js, Go, and Python version management

8 files changed, 17 insertions(+), 19 deletions(-)

More deletions than insertions. That's usually a good sign.

What else mise can do

This article focused on version management, but mise is a broader dev environment tool. Here's what else it offers once you have it installed.

Task runner

mise has a built-in task runner that replaces Makefiles and npm scripts. Tasks defined in mise.toml (or as standalone scripts in a mise-tasks/ directory) run with the full mise environment — correct tool versions and env vars already set. Dependencies between tasks execute in parallel by default, and mise watch re-runs tasks on file changes. For projects that already have a mise.toml for version management, adding tasks means one fewer tool in the chain.

Environment variables

The [env] section in mise.toml sets project-level environment variables that activate when you cd into the directory — the same behavior as direnv, without a separate tool. It supports dotenv files, required variables with validation, and redactions for secrets that shouldn't appear in logs. Earlier in this article, _cache_source caches direnv's activation output alongside mise's — mise's native env management could replace direnv entirely, removing one more tool from the shell startup chain.

Hooks

mise can run shell commands on directory enter/leave events and after tool installations. The postinstall hook is particularly relevant to this migration — it could automate the corepack enable step that's currently manual after Node upgrades.

Lockfile for reproducible environments

mise.lock pins exact tool versions and checksums per platform, similar to package-lock.json. For teams sharing a mise.toml, the lockfile ensures everyone gets the same binary — not just the same version range. Enable it with mise settings lockfile=true.

This article covered the version management migration, but mise's scope goes well beyond that — it's closer to a unified dev environment than a version manager.

The full dotfiles repo and migration commit are available on GitHub. The _cache_source function lives in shell/zshrc.d/completions.zsh if you want to steal it.