Nick Nisi

Git Workshop

Sun, 18 Aug 2013 00:00:00 GMT

This is the content from a talk I gave at OMG!Code in August, 2013. I wrote it in the style of a workshop, but ended up presenting it as a talk instead. It reads as a walkthrough and has an accompanying git repo.

@nicknisi | github.com/nicknisi/git-workshop

History

The original git workshop was presented by Stephen Haberman in 2010 and covered the basics of getting started with git.

Prerequesites

You should have a basic understanding of how to use git for this workshop. You should also have a free account on Github and be sure you can push to it either by generating an SSH key or by using the https method.

Do not clone or fork this repository yet. We will get to that in the Introducing hub section

Overview

The following topics are going to be covered in this workshop:

Git Branching Overview
Teaching git about Github with hub
Finding bugs with bisect
Configuring git
Interactive rebase

Introducing hub

hub is a wrapper around git that teaches git about Github. hub provides a number of shortcuts and commands that make it easier to work with git projects hosted on Github. For example, cloning this repository is a lot simpler with hub. Instead of typing

git clone https://github.com/nicknisi/git-workshop.git

to clone this repo, you just need to run

git clone nicknisi/git-workshop

Installing hub

# install on OS X
$ brew install hub

# other systems
$ curl http://hub.github.com/standalone -sLo ~/bin/hub
$ chmod +x ~/bin/hub

# alias it as git
$ alias git=hub

As you can see, hub wraps the git command to extend it with additional functionality. hub makes working with github URLs a lot easier, but it does a lot more than that.

hub Commands

git fork - Create a fork of the repository on your Github account
git pull-request - Issue a pull request on Github without ever leaving your terminal
git browse - Open a web browser straight to the repository page on Github
git create - Create a repository out on Github from your terminal
... and many more!

Activity: Using hub

With hub installed on your machine, create a fork of this repository, Add your name to the CONTRIBUTERS.md file, and issue a pull request without ever leaving your terminal.

Clone this repository
```
git clone nicknisi/git-workshop
```

Fork this repository to your Github account: git fork

# This will automatically set up a new remote named `USERNAME`
# where USERNAME is your Github username
git fork

Open up the CONTRIBUTERS.md file in your favorite editor (hopefully vim) and add your name to the list

Commit and push up the change to your fork

# USERNAME is your Github username
git commit -a -m "added NAME to the list"`
git push -u USERNAME master

Issue a pull request from the command line back to this repo

# USERNAME is your Github username
git pull-request -b nicknisi:master -h USERNAME:master

Open up your repo in Github to confirm your commit has been pushed up and a pull request has been opened
```
git browse
```

Finding bugs with `git bisect`

bisect is a fantastic tool to help you discover the exact commit that introduced a bug into the repository. This works by telling git bisect where a good state is: where your code is working as expected, and where a bad state is: where the code is broken. git wil then check out a commit in the middle, and you tell it whether this is in a good state or a bad state. The bisect command works by performing a binary search between one commit and another in order to find the exact commit that introduced the bug.

Performing a git bisect can be either a manual or an automatic process, and it depends on the state of the repository and the bug that has been introduced. To perform a git bisect, run

git bisect start

Then, tell bisect where a bad commit exists

git bisect bad HEAD

Finally, tell bisect where a good commit is

git bisect good 53cb134

Git will then check out a commit between these two commits and you can manually rerun whatever steps or tests are necessary to reproduce the issue. If you can reproduce the issue, run git bisect bad and git bisect good if you are unable to reproduce it. Git will then pick another issue based on your response until there are no more commits left to check. At this point, git will inform you of the commit that introduced the issue

Activity: Where did that bug come from?

In this activity, we are presented with a pretty simple HTML file that is supposed to display a simple square and a slider. When the slider is changed, the square should change colors, based on the input of from the slider. At the latest commit in the bisect branch, we are getting no JavaScript errors, and we are not seeing a slider.

We know that the code is working as intended at 37d0821. Let's use git bisect to determine where things went wrong.

Checkout the bisect branch
```
git checkout bisect
```
Look at the index.html file in a browser and test the file to how it is failing
Look through the log to determine where the last known good state of the application is (I have marked this commit with the commit message "GOOD STATE")
```
git log --graph --pretty=oneline --abbrev-commit --decorate
```
Start up bisect
```
git bisect start
```
Alert bisect of the bad commit
```
git bisect bad HEAD
```
Alert bisect of the good commit
```
git bisect good 37d0821
```
git will now pick a commit between the two and check it out. Reload the page in the browser and determine if the slider is working properly (showing up).
- If it is showing up, git bisect good
- If it is not showing up, git bisect bad
After each command, git will checkout a new commit until it has determined the exact commit that introduced the bug

Once you have determined the bad commit, you should be presented with a message like this:

❯ git bisect bad                                                                                                       ✔
9378fec...|bisect
9378fec280242b4a02b6972c3ca9b61cdf14cad5 is the first bad commit
commit 9378fec280242b4a02b6972c3ca9b61cdf14cad5
Author: Nick Nisi <nick@nisi.org>
Date:   Tue Aug 13 00:05:23 2013 -0500

    adjust animation speed slowing down again

    :100644 100644 2bf5ba28648e5c388556b37701addac90d9daf20 63ec399ce0f457bd17e5e6933a0a140c1435223d M      index.html

To end bisect at any time reset it
```
git bisect reset
```

Following these steps, we are able to quickly determine which is the bad commit.

Automating bisect

The process of finding a bad commit with bisect can be automated if the problem you are trying to find can be tested with a script. Using git bisect run, we can provide a command or a script to execute against each commit that bisect checks. If ths script returns 0 then the commit is considered good. Otherwise, it is considered bad. This can be really useful if you are trying to track down what commit introduced a failing unit test or build.

Configuring git

The configuration of git can be customized by combining actions and creating shortcuts to simplify your git workflow.

Advanced aliases

The ~/.gitconfig can include a number of custom aliases. These can be anything from shortening simple git commands to running advanced shell scripts.

[alias]
    co = checkout
    s = status --short
    br = branch -v

    # slight variation of pretty log graph
    l = log --graph --pretty=format:'%Cred%h%Creset %an: %s - %Creset %C(yellow)%d%Creset %Cgreen(%cr)%Creset' --abbrev-commit --date=relative

    # show changed files for a commit
    cf = show --pretty="format:" --name-only

    # show what I did today
    day = "!sh -c 'git log --reverse --no-merges --branches=* --date=local --after=\"yesterday 11:59PM\" --author=\"`git config --get user.name`\"'"

    # show number of commits per contributer, sorted
    count = shortlog -sn

    # YOLO
    yolo = !git commit -am "DEAL WITH IT" && git push -f origin master && shutdown -r now "DEAL WITH IT"

    undo = reset --soft HEAD~1
    amend = commit --amend -C HEAD

    # rebase the current branch with changes from upstream remote
    update = !git fetch upstream && git rebase upstream/`git rev-parse --abbrev-ref HEAD`

    ## grep commands

    # 'diff grep'
    dg = "!sh -c 'git ls-files -m | grep $1 | xargs git diff' -"
    # 'checkout grep'
    cg = "!sh -c 'git ls-files -m | grep $1 | xargs git checkout ' -"
    # add grep
    ag = "!sh -c 'git ls-files -m -o --exclude-standard | grep $1 | xargs git add' -"
    # add all
    aa = !git ls-files -d | xargs git rm && git ls-files -m -o --exclude-standard | xargs git add
    # remove grep - Remove found files that are NOT under version control
    rg = "!sh -c 'git ls-files --others --exclude-standard | grep $1 | xargs rm' -"

Reuse recorded resolution: rerere

If you have a long-running branch, git can remember how you resolved merge conflicts and can reapply how you merged the files.

[rerere]
    enabled = true

Git hooks

Git hooks allow you to run scripts before or after events in git such as commit, push, and receive. Hooks are configured per repository and are located in the .git/hooks directory. Because they live in the git database directory, they are not part of your repository and can be set up independently. Here are just a few of the available commit hooks:

pre-commit - run before a commit to the repository
post-checkout - after a checkout which includes, cloning, switching branches, or resetting files
commit-msg - run after a commit message is entered

There are also server-side commit hooks. These can be utilized to kick off builds, run deployments, run continuous integration, and many other things. Github has integration with third party services when commits happen and you can also set up a route for Github to post to on certain actions.

Activity: Adding a commit-hook

When a new repository is created or cloned, git will copy over example commit hooks into the repository's .git/hooks directory:

❯ ll .git/hooks                                                                                                                   ✔ master
total 80
-rwxr-xr-x  1 nicknisi  staff   452B Jul  9 22:45 applypatch-msg.sample*
-rwxr-xr-x  1 nicknisi  staff   896B Jul  9 22:45 commit-msg.sample*
-rwxr-xr-x  1 nicknisi  staff   189B Jul  9 22:45 post-update.sample*
-rwxr-xr-x  1 nicknisi  staff   398B Jul  9 22:45 pre-applypatch.sample*
-rwxr-xr-x  1 nicknisi  staff   1.7K Jul  9 22:45 pre-commit.sample*
-rwxr-xr-x  1 nicknisi  staff   1.3K Jul  9 22:45 pre-push.sample*
-rwxr-xr-x  1 nicknisi  staff   4.8K Jul  9 22:45 pre-rebase.sample*
-rwxr-xr-x  1 nicknisi  staff   1.2K Jul  9 22:45 prepare-commit-msg.sample*
-rwxr-xr-x  1 nicknisi  staff   3.5K Jul  9 22:45 update.sample*

You can look at and use these files for inspriation when creating your git hook. Hooks can be written in any language that can be called from the command line. If the script returns 0, the hook is considered successful. Otherwise, it has failed. Let's add a git hook to show us info about our repository when we switch branches.

Create a file called post-checkout in the .git/hooks directory and execute permissions

touch .git/hooks/post-checkout
chmod +x .git/hooks/post-checkout

Set the contents of the file

#!/bin/bash

echo ""
echo ""
echo -e "\033[1m RECENT COMMITS \033[0m"
git --no-pager log -n5 --graph --pretty=format:'%Cred%h%Creset %an: %s - %Creset %C(yellow)%d%Creset %Cgreen(%cr)%Creset' --abbrev-commit --date=relative
echo "
echo ""]]"

Back in the repository, create a new branch and notice that you will get a summary of the last 5 commits to the repository.

git checkout -b new-branch

Managing git hooks

Git hooks are excluded from the repository and this is both a blessing and a curse. It allows developers to setup their own hooks without affecting anyone else. However, that means that it is typically a manual process of storing the commit hook in a safe place and then manually copying it over into the newly created or cloned repo.

As previously pointed out, git copies a number of sample commit hooks into each repository, and we can hijack this to add our own commit hooks! These sample files live at /usr/share/git-core/templates in the hooks directory. We can configure git to change where this directory exists and override it with our own defaults, allowing us to manage this directory independently and keep under source control in our dotfiles.

To change where git looks for this templates directory, add the following to your ~/.gitconfig:

[init]
    templatedir = ~/.dotfiles/git/templates

Now, whenever we clone or init a new repository, we will be set up with our own, custom git hooks that have been copied from the above path.

Note that the hooks are copied, meaning that any revisions to them later will not be copied over. However, running git init in an existing repository will copy the updated hooks over to the repo.

Interactive rebase

Remember that nasty bisect branch with its many commits changing the same thing over and over? Wouldn't it be nice if we could clean up our log so it doesn't look so nasty?

* fe321d9 Nick Nisi: adjust animation to 320 -   (HEAD, origin/bisect, bisect) (17 hours ago)
* 900b366 Nick Nisi: adjust animation to 319 -   (17 hours ago)
* a5ba9ac Nick Nisi: adjust animation to 318 -   (17 hours ago)
* f84b4cd Nick Nisi: adjust animation to 317 -   (17 hours ago)
* 70f7912 Nick Nisi: adjust animation to 316 -   (17 hours ago)
* 442c007 Nick Nisi: adjust animation to 314 -   (17 hours ago)
* 7fd99d5 Nick Nisi: adjust animation to 313 -   (17 hours ago)
* 507d90e Nick Nisi: adjust animation to 312 -   (17 hours ago)
* 76162b0 Nick Nisi: adjust animation to 311 -   (17 hours ago)
* 89390fa Nick Nisi: adjust animation to 310 -   (17 hours ago)
* 2f3c3fc Nick Nisi: adjust animation to 309 -   (17 hours ago)
* 18ce973 Nick Nisi: adjust animation to 308 -   (17 hours ago)
* 448e9e2 Nick Nisi: adjust animation to 307 -   (17 hours ago)
* f7a452d Nick Nisi: adjust animation to 306 -   (17 hours ago)
* e23d9f8 Nick Nisi: adjust animation to 305 -   (17 hours ago)
* 72eb0c2 Nick Nisi: adjust animation to 304 -   (17 hours ago)
* 5e4cee6 Nick Nisi: adjust animation to 303 -   (17 hours ago)
* 4f88c8d Nick Nisi: adjust animation to 302 -   (17 hours ago)
* 9378fec Nick Nisi: adjust animation speed slowing down again -   (17 hours ago)
* cc62c6f Nick Nisi: adjust animation speed slowing down -   (17 hours ago)
* faa0412 Nick Nisi: adjust animation speed speed up again -   (17 hours ago)
* 4e024b6 Nick Nisi: adjust animation speed speed up -   (17 hours ago)
* 983eb1f Nick Nisi: adjust animation speed speed up -   (17 hours ago)
* 00f4ca5 Nick Nisi: adjust animation speed speed up -   (17 hours ago)
* 06badcb Nick Nisi: adjust animation speed -   (17 hours ago)
* d1ebc8e Nick Nisi: adjust box size -   (17 hours ago)
* d3d2d4d Nick Nisi: change box size -   (17 hours ago)
* ecf34f6 Nick Nisi: change border color -   (17 hours ago)
* de9bb1f Nick Nisi: add h2 tag contents -   (17 hours ago)
* 2210aca Nick Nisi: add h2 tag -   (17 hours ago)
* 37d0821 Nick Nisi: GOOD STATE -   (17 hours ago)

The good news is that we can! The bad news is that it needs to be used with caution. The Github Help page states it best:

Warning: It is considered bad practice to rebase commits which you have already pushed to a remote repository. Doing so may invoke the wrath of the git gods.

When you run an interactive rebase, you are changing your git history. Commits will be assigned new SHAs. If you have already pushed up and someone else has pulled down the changes, it will mess up their repository if you change the history out from under them.

Running `git rebase -i HEAD 4f88c8d will pop us into our editor and list all of the commits within the provided range. Each commit will have the word pick next to it, meaning that we are picking this commit (leaving it as it is). The other options are

reword - use commit but edit the commit message
edit - use commit, but stop for amending
squash - use commit, but meld into previous commit
fixup - like "squash", but discard this commit's log message
exec - run command

We can use the squash, pick, and fixup commands to simplify the repository.

Activity: Clean the history

Let's use our new knowledge of interactive rebase to clean up the bisect branch.

Let's branch off of bisect and do this in a new branch

git checkout bisect
git checkout -b rebase

Enter into an interactive rebase, down to the "GOOD STATE" commit

git rebase -i 37d0821

For each of the commits that have a similar message, select the top one to "pick". For the rest, select "squash"

pick 2210aca add h2 tag
pick de9bb1f add h2 tag contents
pick ecf34f6 change border color
pick d3d2d4d change box size
pick d1ebc8e adjust box size
pick 06badcb adjust animation speed
pick 00f4ca5 adjust animation speed speed up
pick 983eb1f adjust animation speed speed up
pick 4e024b6 adjust animation speed speed up
pick faa0412 adjust animation speed speed up again
pick cc62c6f adjust animation speed slowing down
pick 9378fec adjust animation speed slowing down again
pick 4f88c8d adjust animation to 302
squash 5e4cee6 adjust animation to 303
squash 72eb0c2 adjust animation to 304
squash e23d9f8 adjust animation to 305
squash f7a452d adjust animation to 306
squash 448e9e2 adjust animation to 307
squash 18ce973 adjust animation to 308
squash 2f3c3fc adjust animation to 309
squash 89390fa adjust animation to 310
squash 76162b0 adjust animation to 311
squash 507d90e adjust animation to 312
squash 7fd99d5 adjust animation to 313
squash 442c007 adjust animation to 314
squash 70f7912 adjust animation to 316
squash f84b4cd adjust animation to 317
squash a5ba9ac adjust animation to 318
squash 900b366 adjust animation to 319
squash fe321d9 adjust animation to 320

Complete by saving and closing your editor
Look at the new history in the log

* db86962 Nick Nisi: adjust animation to 302 -   (HEAD, rebase) (4 seconds ago)
* 9378fec Nick Nisi: adjust animation speed slowing down again -   (18 hours ago)
* cc62c6f Nick Nisi: adjust animation speed slowing down -   (18 hours ago)
* faa0412 Nick Nisi: adjust animation speed speed up again -   (18 hours ago)
* 4e024b6 Nick Nisi: adjust animation speed speed up -   (18 hours ago)
* 983eb1f Nick Nisi: adjust animation speed speed up -   (18 hours ago)
* 00f4ca5 Nick Nisi: adjust animation speed speed up -   (18 hours ago)
* 06badcb Nick Nisi: adjust animation speed -   (18 hours ago)
* d1ebc8e Nick Nisi: adjust box size -   (18 hours ago)
* d3d2d4d Nick Nisi: change box size -   (18 hours ago)
* ecf34f6 Nick Nisi: change border color -   (18 hours ago)
* de9bb1f Nick Nisi: add h2 tag contents -   (18 hours ago)
* 2210aca Nick Nisi: add h2 tag -   (18 hours ago)
* 37d0821 Nick Nisi: GOOD STATE -   (18 hours ago)
* a36751a Nick Nisi: add border to color box -   (18 hours ago)
* c287e19 Nick Nisi: fixing slider values -   (18 hours ago)
* 6f4edca Nick Nisi: messing with slider values -   (18 hours ago)
* 225c4ef Nick Nisi: adding width style -   (18 hours ago)
* 09ac64d Nick Nisi: adding height style -   (18 hours ago)
* 6148238 Nick Nisi: removed height/width -   (18 hours ago)
* d1e1701 Nick Nisi: removing border -   (18 hours ago)
* 2c9df68 Nick Nisi: adding cdn scripts -   (18 hours ago)
* 0763e15 Nick Nisi: initial commit of index -   (18 hours ago)
* 9f0ec0c Nick Nisi: Add editorconfig -   (20 hours ago)
* 39aad97 Nick Nisi: updating hub instructions -   (20 hours ago)
* 2922ce8 Nick Nisi: Added README and hub walkthrough -   (21 hours ago)
* 5fb2d99 Nick Nisi: Rename LICENSE.md to LICENSE -   (21 hours ago)
* 53cb134 Nick Nisi: Create LICENSE.md -   (21 hours ago)

Learning more

We've only briefly covered a few of the really cool tricks you can do with git. Want to learn more? Check out these great resources!

GitMinutes - A podcast for proficient git users
Git and Github Secrets - A talk by Zach Holman of Github
More Git and Github Secrets - More!
GitReady
Peruse dotfiles!

Git: Update a forked repository

Sun, 24 Aug 2014 00:00:00 GMT

Github is great! It is so easy to fork a project, push up some commits, and then send a pull request upstream. After a while, those forks can get behind the source repository, making it difficult to submit a new pull request later on. One thought might be to delete the fork and then re-fork the project, but there is an easier way!

Syncing a fork

Syncing a fork is easy to do from the command line. With a clone of the fork, we can create a new remote that points to source repository on Github.

$> git remote add upstream git@github.com:theintern/intern.git

This will add a new remote named upstream, which points to the source repository. Next, fetch the latest from the upstream repository.

$> git fetch upstream

Then, apply the upstream changes to our local copy of master (or whatever branch you are on).

$> git rebase upstream/master

At this point, the local copy of our branch has now been updated with the latest code from the usptream repository, meaning that we are now up today. Finally, we just need to push these changes up to our origin remote.

$> git push origin master

That's it! We have now successfully updated our fork of a project without having to delete the repository and start over.

But that's so many steps...

It can be difficult to remember all of the commands needed for git actions. Luckily, git gives us a way to configure aliases to common or complex actions. Using this and a little convention, we can make a nice alias to reduce the steps above to a single step. Git makes it easy to set up as many remotes as we need, so we can easily pull from an upstream remote and then update our origin remote.To make a command that can work in any repository, we need to follow a few conventions when it comes to naming our remotes.

origin - The main repository to push to (our fork)
upstream The main project repository

This way, the alias knows which remote to fetch, and which remote to push to. With this convention in place, we can create an alias in our ~/.gitonfig:

[alias]
	update = !git fetch upstream && git rebase upstream/master

This works great, except that it always assumes that we only want to update the master branch, which isn't ideal. There is a way to get the current branch that we have checked out from a simple command.

$> git rev-parse --abbrev-ref HEAD

Using this within the alias gives us a great shortcut to updating origin with the latest from the upstream remote.

[alias]
    update = !git fetch upstream && git rebase upstream/`git rev-parse --abbrev-ref HEAD`

This condenses the number of steps down to two:

git update to update our local branch with the latest from the upstream remote
git push to push those changes up to the origin remote, updating the fork

Aliases are a great way to condense complex actions down to simple commands or to reduce the amount of typing required to execute a command. For more awesome git aliases, check out my .gitconfig.

Git Your Way: includeIf

Sat, 30 Jan 2021 00:00:00 GMT

The Problem

As a developer who works on many projects, including client and open source projects, I often need to be mindful of how I commit to each project. That is, company/client projects should always use my work email address when committing, and for open source I would prefer to use my personal email address.

This can be set up on a per-project basis by simply running git config user.email <EMAIL> from within each project once and it will be set . The problem with this is that I actually have to remember to run this command from each project or risk accidentally committing with the wrong email address. Fortunately, git has a built-in method of helping with this.

The Solution

Let’s say you have the following directory structure:

|-- work
|-- oss

All of your work projects (where you want to use your work email in commits) is in the ./work directory, and all of the open source is (you guessed it) in ./oss. In your ~/.gitconfig there is a specifier called includeIf that can be configured to load another git configuration file based on where the git repository lives on your file system.

# inside of ~/.gitconfig
[includeIf "gitdir:~/work/"]
  path = ~/.gitconfig-work
[includeIf "gitdir:~/oss/"]
  path = ~/.gitconfig-oss

This will only source these sub-configuration files if you are working on a git repo inside of one of the specified directories. Then, inside of those config files is where you can specify work or oss-specific configuration, such as the email address to use, which will then always be used for any project within those specified directories.

# inside of ~/.gitconfig-work
[user]
  name = Nick Nisi
  email = nick@work.co

How I Use It

To see this and other fun git/vim/zsh/tmux tips in action, check out my dotfiles. For this specific example, I don’t actually use it directly in my dotfiles, but instead I do it in a ~/.dotfiles-local file. I reference this from within my dotfiles as a way to not check-in references to my work-specific configuration.

[include]
  path = ~/.gitconfig-local

This will include my local configuration file and will silently ignore this line if the file doesn’t actually exist.

And that’s it! Setting this up ensures that you never accidentally commit with the wrong email address in projects, and also gives you a single place to further customize your git configuration of a project-type basis.

Git: Managing hooks

Mon, 01 Sep 2014 00:00:00 GMT

Git hooks are custom scripts that can be fired off when different actions occur, and they can be run on either the client (your machine) or the server (the git remote). In this post, I'll be talking about client side hooks. The available client side hooks include prepare-commit-msg, pre-commit, commit-msg, pre-rebase, post-merge, and many more. These can be used to automate specific tasks like checking over the commit message before the commit is accepted to linting your JavaScript before it can be committed. The hooks can be written in any language that the system supports, and they can be easily used within any git project, new or existing. The biggest pain point with commit hooks is managing them. They exist in of .git/ and are not actally part of the repository.

Setting up the hooks

The hooks are contained within the .git/hooks. By default, git will provide a number of sample scripts, which can be removed or renamed and modified to fit your needs.

Removing the .sample extension from any of these files will activate them. Then, they can be modified to perform whatever task is necessary. for example, adding a file called post-checkout with the following will cause git to display the 5 most recent commits to the branch checked out when running git checkout

#!/bin/bash

echo ""
echo ""
echo -e "\033[1m RECENT COMMITS \033[0m"
git --no-pager log -n5 --graph --pretty=format:'%Cred%h%Creset %an: %s - %Creset %C(yellow)%d%Creset %Cgreen(%cr)%Creset' --abbrev-commit --date=relative
echo ""
echo ""

Managing git hooks

Git hooks can be tedious to manage in multiple projects. It can be cumbersome to copy them from one project to another and to store them in a repository. Luckily, git does provide a way to simplify this. When running git init, git copies the sample hook scripts from a directory in to .git/hooks. It copies whatever is in that directory, and we can use that to copy over the hook scripts by default. To do this, change the location of templatedir directory in your ~/.gitconfig:

[init]
    templatedir = ~/.dotfiles/git/templates

This way, you can manage your git hook scripts from another repository, such as your dotfiles and they wil be copied over to each new project. To add them to an existing project, just execute git init and they will be copied over.

Please note that they will not overwrite files that already exist in the .git/hooks directory, so you will need to delete them first to completely replace them with more up-to-date scripts.

This is an easy way to get started managing git hooks in a simple, reusable way. In a later post, I will discuss further how I manage git hooks.

Lint JavaScript on Commit

Mon, 12 Nov 2012 00:00:00 GMT

My team has been working a lot to improve our code quality and to introduce best practices between us. One way we've done this is through the use of JSHint. Because we use different editors it can be difficult to make sure that everyone's environment is configured to analyze code the same way, but git is a common tool between us. Here is a pre-commit hook, which checks all .js files included in the commit against your JSHint configuration. If it doesn't pass, the errors are printed to the screen and the commit is cancelled.

#!/bin/sh
# JSHint Pre-Commit
# Place this in your .git/hooks/pre-commit directory and rename to `pre-commit`
# expects jshint to be installed in your projects node_modules directory

EXIT_CODE=0
COLOR_RED="\x1B[31m"
COLOR_GREEN="\x1B[32m"
COLOR_NONE="\x1B[0m"

repo=$( git rev-parse --show-toplevel )
jshint=${repo}/node_modules/jshint/bin/hint

for file in $( exec git diff-index --cached --name-only HEAD ); do
	if [[ $file == *".js"* ]]; then
		status=$( exec git status --porcelain $file )

		if [[ $status != D* ]]; then
			# ${jshint} ${repo}/${file} >/dev/null 2>&1
			${jshint} ${repo}/${file}
			EXIT_CODE=$((${EXIT_CODE} + $?))
		fi
	fi
done

echo ""
if [[ ${EXIT_CODE} -ne 0 ]]; then
	echo "${COLOR_RED}✘ JSHINT detected syntax problems.${COLOR_NONE}"
else
	echo "${COLOR_GREEN}✔ JSHINT detected no errors.${COLOR_NONE}"
fi

exit $((${EXIT_CODE}))

Very Important Agents

Mon, 08 Dec 2025 00:00:00 GMT

I recently appeared on Changelog and Friends to talk about agents, the Bun acquisition by Anthropic, and how I've been using Claude Code in my daily workflow. The conversation kept circling back to a question I find interesting: how do we use AI to get real work done without producing generic slop?

I've been building toward an answer - two custom Claude Code plugins called Essentials and Ideation that help me stay productive while keeping my code and ideas authentically mine. Rather than let that podcast conversation disappear into the archives, I wanted to share what I've learned.

Keeping Code Clean with Essentials

The Essentials plugin is my first line of defense against code complexity. It has two components I reach for constantly.

Code Simplifier is an agent that refactors code to improve readability without changing functionality. I recently used it on a nested callback situation that had grown organically over several iterations. You know the type - it started simple, then requirements changed, then edge cases appeared, and suddenly you're staring at something that works but makes your brain hurt. The agent untangled it into something I could actually follow. Same behavior, less cognitive load.

de-slopify is a command that removes AI-generated patterns from code. After running Claude on a feature, I sometimes notice overly verbose comments, unnecessary abstractions, or redundant explanations that scream "an AI wrote this." de-slopify catches these patterns and strips them out. The result is code that looks like a human wrote it - because the important parts are still mine, just without the AI fingerprints.

This might seem contradictory. Using AI to remove evidence of AI? But that's exactly the point. I want AI assistance with the mechanics, not AI aesthetics polluting my codebase.

From Brain Dump to Structure with Ideation

Here's where things get meta. The Ideation skill takes messy stream-of-consciousness thoughts and transforms them into structured artifacts.

I'm literally using this plugin right now to write this post.

That's not a hypothetical. It's the truth.

My process started with a voice dictation where I rambled about the podcast, what I wanted to cover, and why authenticity matters when using AI for content. Just scattered thoughts, no structure. The Ideation plugin took that brain dump and produced a contract (what I'm committing to), a PRD (what the post needs to accomplish), and a spec (how to actually write it).

The value here isn't that AI wrote my outline. It's that AI removed the blank page problem. I went from "I should write about this podcast" to having a clear structure to follow in minutes instead of days. The ideas are still mine. The organization just got easier.

AI as Amplifier, Not Replacement

These plugins represent a philosophy I keep coming back to: AI should amplify your capabilities, not replace your judgment.

There are two problems I'm trying to solve. First, the barrier problem. I have ideas and things I want to build. But life is busy, and the gap between "I should do this" and actually having a plan is often too wide to cross. AI can lower that barrier by handling the organizational grunt work.

Second, the slop problem. AI-generated code often has a distinctive smell - overly verbose, over-abstracted, over-commented. I don't want that in my codebase. I want to use AI in a way that makes me more productive without making my code less mine.

The plugins I've built are my answer to both problems. Essentials keeps my code clean. Ideation turns chaos into structure. Each one is intentionally designed to amplify rather than replace.

The key is being intentional. Use AI for the right things. Use it in ways that lower barriers without raising slop levels. Use it as an amplifier, not a replacement.

Try It Yourself

All of these plugins live in my Claude plugins marketplace. You can install the whole collection with a single command:

/plugin marketplace add nicknisi/claude-plugins

That gives you access to Essentials, Ideation, and a few other plugins I've been building. Browse the repo if you want to see how they work under the hood - or just install and experiment.

Resources:

Claude plugins marketplace - The full collection
Claude Code Documentation - Getting started with Claude Code
Changelog and Friends Episode 120 - The podcast conversation that started this

Let me know how it works for you. I'm @nicknisi.com on Bluesky.

Writing My First Evals

Fri, 27 Feb 2026 00:00:00 GMT

import Callout from '@/components/Callout.astro';

I've spent the last few weeks building two AI-powered developer tools at WorkOS. At some point I realized I had no idea if they actually worked.

Not "worked" in the sense of "does it run." They ran fine. I mean "worked" in the sense of "does running this tool actually make things better for the developer using it?" That's a harder question than it sounds when the tool's output is different every time you run it.

I needed evals. I also had no background in writing them.

This is the story of building two very different evaluation systems for two very different problems, and discovering they were teaching me the same thing.

<Callout title="The projects"> WorkOS CLI (the workos install command, powered by Claude Agent SDK) | WorkOS Skills (auto-generated agent context from our docs) </Callout>

Does the agent do the right thing?

The first tool is workos install, a CLI command that uses the Claude Agent SDK to automatically install WorkOS AuthKit into your project. You point it at a Next.js app, a React SPA, a Python Flask server, or any of 16 supported frameworks, and it figures out what to do. It reads your code, understands your project structure, creates the right files, modifies the right configs, and installs the right dependencies.

It's magic. And magic is untestable by default.

The problem with testing an AI agent is that it doesn't do the same thing twice. Same input project, same prompt, different output. Different file names, different import styles, different error handling approaches. expect(output).toBe(expected) falls apart instantly.

So I built an eval system.

Fixtures as starting states

The eval starts with fixture projects: minimal starter apps for each supported framework. A React SPA with three pages. A Next.js app with a basic layout. A Python Flask server with a health endpoint. 16 frameworks total, each with multiple starting states like example, example-auth0 (migrating from Auth0), partial-install, and conflicting-middleware.

The fixture manager copies each one to a temp directory, runs pnpm install (or pip install, bundle install, go mod download, depending on what it detects), and initializes a git repo. That git init matters. The diff after the agent runs becomes the source of truth for what changed.

I'll be honest. When I had about 24 fixtures, my reaction was: "This feels both like not enough and like it's too much to maintain. Is this really the best path?" I also worried about synthetic fixtures: if a test fails, is it because the agent screwed up or because the fixture wasn't realistic? The answer was to use real-world starting states, actual project structures that developers would have, rather than contrived setups. Every fixture runs before the agent touches it. If it doesn't work clean, it's not a valid test.

The agent runs for real

For each fixture, the eval executor invokes the real agent with the real skill. Same code path as production. No mocks. It tells the agent "Use the workos-authkit-nextjs skill to integrate WorkOS AuthKit into this application" and lets it go. It tracks every tool call, every correction attempt, every token.

If the agent fails, it can self-correct, up to two retries within the same session. The eval tracks whether a scenario passed on first attempt, needed correction, or needed a full retry. This distinction matters later.

Grading: the part I got wrong at first

I started with simple file checks. Does middleware.ts exist? Does it import @workos-inc/authkit-nextjs? Does the callback route handle handleAuth?

This worked for about an hour. Then I hit the first real eval lesson: passing isn't the same as good.

The Next.js grader checks seven things: callback route exists, middleware or proxy exists (but not both, since Next.js 16 throws an error if you have both middleware.ts and proxy.ts), the SDK is imported correctly, authkitMiddleware or the authkit() composable is integrated, AuthKitProvider wraps the layout, and the project builds. Every check must pass.

That "not both middleware and proxy" check encodes real domain knowledge. It's the kind of thing a developer would catch in code review. Without it, the agent could create a technically correct but broken integration.

But even with all those checks passing, an agent could still produce code that no human developer would accept. Over-engineered error handling. Unnecessary abstractions. Comments explaining what const x = 1 does. Technically correct. Terrible.

So I added a second grading stage. The functional grader does pass/fail. But then a quality grader sends the code to Claude Haiku, which scores it on four dimensions:

Code style: does it match the project's conventions?
Minimalism: are the changes focused, or did it modify unrelated files?
Error handling: appropriate for the context, or paranoid?
Idiomatic: does it follow the framework's patterns?

Each scored 1–5 with rubrics that define what a 1 versus a 5 looks like. Chain-of-thought reasoning before scoring, so the LLM has to justify each number.

Anthropic's eval guide calls this "grading outcomes, not paths." The grader doesn't care which tools the agent used or what order it did things in. It cares about what the project looks like when the agent is done.

Not pass/fail, pass rates

Here's where evals diverge from tests. My success criteria aren't "all scenarios pass." They're:

80% pass on first attempt, no corrections
90% pass with self-correction allowed
95% pass with full retries

<Callout variant="info" title="Evals aren't tests"> Tests verify deterministic behavior: given input X, expect output Y. Evals measure statistical quality: given input X, does the distribution of outputs meet quality thresholds? Your test suite should be 100% green. Your eval suite won't be. That's by design. </Callout>

The Pragmatic Engineer's deep dive on evals makes this point clearly: use pass/fail judgments for individual cases, but measure them as rates across many trials. A single failure doesn't mean the system is broken. A pattern of failures does.

40 scenarios. 16 frameworks. Each one designed to test a different situation the agent might encounter in the wild. Here's what the validation output looks like after a full run:

════════════════════════════════════════════════════
✓ PASS: All success criteria met

First-attempt:    92.0% (required: 80%)
With-correction:  94.0% (required: 90%)
With-retry:       96.0% (required: 95%)
════════════════════════════════════════════════════

Does the context actually help?

The second tool is a different kind of problem entirely. I'm building a set of agent skills for WorkOS, structured context documents that get loaded into an LLM's system prompt when a developer asks about WorkOS features. SSO flows, directory sync, RBAC, AuthKit integration. The skills are auto-generated from our docs using a pipeline that fetches, parses, splits, and refines content through Claude. The evals are how I decided they were ready to ship.

The question here isn't "does the agent do the right thing?" It's more basic: does feeding this context to the LLM actually make its output better?

I assumed the answer was yes. I was wrong about at least one of them.

A/B testing for LLMs

The skills eval takes a completely different approach from the CLI eval. For each test case, it runs the same prompt twice: once with the skill loaded into the system prompt, once without. Same model, same temperature, same everything except the system prompt. Then it scores both outputs and compares.

The test cases are declarative YAML:

- id: sso-node-basic
  product: sso
  skill: workos-sso
  prompt: |
    Implement SSO login flow for a Node.js Express
    app using the WorkOS SDK.
  expected:
    methods:
      - workos.sso.getAuthorizationUrl
      - workos.sso.getProfileAndToken
    imports:
      - '@workos-inc/node'
    flowSteps:
      - generate authorization URL
      - redirect user to IdP
      - handle callback
      - exchange code for profile
    antiPatterns:
      - hardcoded API key
    hallucinations:
      - workos.sso.authenticate
      - workos.sso.login

That hallucinations field lists methods that don't exist in the WorkOS SDK but that LLMs commonly invent. workos.sso.authenticate sounds right. It isn't real. The scorer checks whether the LLM hallucinates these phantom methods, and whether having the skill context prevents it.

Scoring runs across seven dimensions (method accuracy, parameter coverage, environment variable usage, imports, flow correctness, anti-pattern avoidance) each weighted and combined into a composite score:

const base =
	methodAccuracy * 20 +
	paramAccuracy * 15 +
	envVarCoverage * 15 +
	importAccuracy * 10 +
	flowCorrectness * 20 +
	antiPatternAvoidance * 15 +
	(hallucinationCount === 0 ? 5 : 0);

const penalty = Math.min(hallucinationCount * 5, 25);
return Math.max(0, Math.round(base - penalty));

100 points maximum. Hallucinations carry a -5 penalty each, capped at -25. A clean hallucination-free output gets a 5-point bonus.

42 test cases. Each one runs both arms in parallel. The delta between with-skill and without-skill tells you whether the skill is helping, hurting, or irrelevant.

Here's what a real eval run looks like:

──────────────────────────────────────────────────────────────────
WorkOS Skill Eval Report
Model: claude-sonnet-4-5-20250929 | Cases: 42 | Date: 2026-02-26
──────────────────────────────────────────────────────────────────

Product             Cases  With Skill  Without     Delta
──────────────────────────────────────────────────────────────────
sso                     8         97%      95%       +2%
rbac                    5         91%      89%       +2%
directory-sync          6         87%      87%        0%
audit-logs              4         96%      96%        0%
mfa                     5         85%      83%       +2%
vault                   4         89%      88%       +1%

The skill that hurt

One of the generated skills scored negative. Not zero. Negative. The LLM produced worse output with the skill than without it.

The directory sync skill for Ruby hit -12%. The SSO CSRF state validation case hit -20%. I wouldn't have caught either of these manually. I thought the skills were helping. They looked helpful. They contained accurate information.

But the eval showed, across multiple runs, that the LLM consistently scored lower when these skills were in the system prompt. The SSO case was particularly bad: the skill taught the CSRF nuance correctly but omitted the auth URL generation step, costing 20 points on missing_method. The LLM was learning the wrong lesson from the context.

The breakthrough came when I started saving full LLM transcripts from both runs and built tools to diff them side by side. Not just "which scored better?" but "what did the LLM actually do differently?"

┌─── With Skill (composite: 77%) ──────────────────────────
  Methods:        4/5 ✗
    missing: getAuthorizationUrl
  Params:         3/4 ✗
  Flow:           3/6 out of order
  Hallucinations: 0

┌─── Without Skill (composite: 97%) ───────────────────────
  Methods:        5/5 ✓
  Params:         4/4 ✓
  Flow:           6/6 in order
  Hallucinations: 0

I could see the skill introducing noise. Too much tangential context pulling the LLM away from the core task. The methods were right, but the flow was wrong. The LLM was getting distracted by the very context meant to help it.

This was the moment where I went from "evals are something I probably need" to "evals are how I know what's real."

Detecting things that aren't real

One detail worth calling out: the scorer handles negation. If the LLM output says "don't use workos.sso.authenticate, that method doesn't exist," that's not a hallucination. The LLM is correctly warning against a phantom method. A naive string match would flag it as a failure.

The scorer checks the 30 characters before each match for negation signals ("don't," "avoid," "should not," "never") and for cautionary labels like "anti-pattern" or "trap." If the method appears in a negation context, it gets skipped.

Small thing. But it's the kind of nuance that makes the difference between an eval you trust and one that cries wolf.

Same question, different angle

These two eval systems share no code. The CLI evals copy fixture projects, invoke a real agent, and grade file outputs. The skills evals call the Claude API directly, compare system prompt variations, and score generated text. Different architectures. Different grading approaches. Different problems.

But they're both answering the same question: how do you measure value when the code is non-deterministic and the environments vary wildly?

The agent doesn't produce the same files twice. The LLM doesn't generate the same code twice. You can't write a test that says "the output should be X" because the output is never X. It's some variation of X that might be better or worse than what you expected.

Both systems solve this the same way:

Define what "good" looks like. Not the exact output, but the signals that indicate quality. Files exist, methods are correct, flow is right, hallucinations are absent, the project builds.
Measure statistically. Pass rates and composite scores across many trials, not individual assertions.
Save everything. Transcripts, diffs, scores, tool calls. Because when something fails, you need to understand why, not just that.
Gate regressions. Automated thresholds that prevent you from shipping something worse than what you had.

This is what I mean when I say evals aren't tests. Tests tell you "this is broken." Evals tell you "this is getting worse," or in the case of my negative-scoring skill, "this thing you thought was helping is actively hurting."

The eval can be wrong too

Here's something nobody warns you about: your evaluation system can have bugs just like the thing it's evaluating.

I ran a full eval pass and saw 13 cases with negative deltas, skills apparently making things worse. My stomach dropped. Then I investigated.

All 13 flow regressions were scorer bugs, not skill regressions. The scorer expected implementation steps in a specific conceptual order, but the with-skill outputs used a diagnosis-first pattern: symptom, cause, verify, fix. The without-skill outputs happened to match the scorer's expected order by coincidence. The skills were actually producing better structured code. My scorer was just too rigid to recognize it.

After fixing the scorer's flow-ordering logic to use proximity-based matching instead of strict sequence checking, those 13 "regressions" became 13 neutral-to-positive results.

The lesson: when your eval says something is broken, investigate the eval first. Especially early on.

Building trust with a system you built with AI

Here's the part I'm almost embarrassed to admit. I built both eval systems with Claude Code. The majority of the CLI eval system (the fixture manager, the graders, the parallel runner, the quality scoring) was written in conversations with Claude. Which means I was using the AI I was trying to evaluate to build the evaluation system.

For the first few days, I was blindly trusting it. Claude would suggest a grading approach, I'd implement it, and I'd move on. It told me things were working correctly, and I had no frame of reference to push back. I'd never written evals before. At one point I asked Claude: "Are evals graders? Did we follow the best practices set out in these docs?" I was literally asking the AI to grade its own homework.

It's a bit like an Apple Watch tracking your heart rate. I don't think the absolute number is perfectly accurate. But I don't need it to be. I need it to tell me if things are getting better or worse. A reliable baseline, even an imperfect one, is worth more than no baseline at all. That's what the evals gave me. Not perfect truth, but a consistent signal I could track over time.

Then I had a moment of genuine doubt. I remember typing into Codex: "I don't actually know if the evals are being honest with me about how useful these skills actually are. Can you do an independent analysis?"

I was using two different AIs, Claude Code and Codex, to cross-check each other. I'd run the evals with Claude, paste the results into Codex for analysis, then take Codex's feedback back to Claude. "I asked Claude to review your response," I kept telling Codex. It felt absurd. But it was also working. Each model caught things the other missed. Codex flagged scorer assumptions Claude hadn't questioned. Claude found implementation bugs Codex couldn't see.

Still, AI checking AI wasn't enough. I needed external ground truth.

I read three things: Anthropic's guide to demystifying evals for AI agents, the Pragmatic Engineer's deep dive on evals, and OpenAI's evaluation best practices. Real resources from people who had thought deeply about this problem.

Then I fed those articles back to Claude and asked it to evaluate whether our eval systems aligned with the principles. The feedback was specific: we had the fundamentals right. A/B structure, deterministic scoring, pass/fail judgments measured as rates, outcome-based grading. The pieces were there. They just needed refinement.

We were on the right path. We just needed to sharpen the edges. "Update the quality grader to use thinking before scoring," I told Claude after reading that chain-of-thought improves grading accuracy. Small refinements, not a rewrite.

What I'd tell you if you're starting from zero

Start with pass/fail. Don't build a sophisticated scoring system on day one. Start with the simplest question: did it work? For me, that was "does the file exist and does the project build." Get that running across a handful of cases, get a baseline, then iterate. I added quality scoring weeks later. The eval system grows with your understanding of what matters.

Evals aren't tests. Treat them differently. Your test suite should be 100% green. Your eval suite won't be. Set statistical thresholds and measure trends. An 85% first-attempt pass rate that's improving every week is better than chasing 100% on a small set of easy cases.

Save transcripts. I cannot overstate this. When the skill scored negative, the only reason I found the root cause was because I had full transcripts from both the with-skill and without-skill runs. Scores tell you what. Transcripts tell you why.

Calibrate against humans. The skills eval has a labeling system, a simple JSONL file where I mark cases as "ship" or "no-ship" with a reason. Then a calibration script measures how often the automated scorer agrees with my judgment. If we disagree on more than 20% of cases, the scorer needs work, not me. Automated scoring without human calibration is just a faster way to be confidently wrong.

Measure the thing you actually care about. Generic "helpfulness" scores from off-the-shelf tools didn't help me. I needed to know: does the middleware import the right SDK? Does the authorization URL use the correct parameters? Does the skill prevent hallucinated method names? Domain-specific signals beat generic metrics every time. The Pragmatic Engineer article puts it well: avoid pre-built metrics that don't correlate with what your users actually experience.

Question whether you're adding value or duplicating knowledge. At one point I asked Claude to verify that the skills were "actually additive, not just duplicating the docs." This is the core question for any context-augmented AI tool. If the LLM already knows the answer, your skill is dead weight. If your skill adds noise, it's actively harmful. The A/B delta is the only way I've found to answer this honestly.

Trust is a measurement

I started this with no background in evals. I built two systems that are different in almost every way. One copies starter projects across 16 frameworks and runs an AI agent against them. The other A/B tests whether feeding context to an LLM actually improves its output. No shared code. No shared architecture.

But they taught me the same thing: trust isn't a feeling. It's a number. It's a pass rate, a delta score, a regression gate. When someone asks me "does this AI tool actually work?" I don't have to say "I think so." I can show them the data.

And when the data says something I built is making things worse? I fix it or I kill it. That's what the negative-scoring skill taught me. My intuition said it was helpful. The eval said otherwise.

The eval was right.

I should be honest about what I don't know yet. These tools are still evolving. Time will tell whether the evals I built actually set me up for success or just made me feel better about shipping. I started this with no background in evals, and I'm sure someone who does this for a living would find plenty to improve. If that's you, I'd genuinely love to hear what I'm getting wrong. I'm @nicknisi.com on Bluesky.

What I do know: I'm shipping with more confidence than I had before, and I have real numbers to back it up. That's more than vibes. For now, that's enough.

Resources that shaped my thinking:

Demystifying Evals for AI Agents (Anthropic)
Evals (Pragmatic Engineer)
Evaluation Best Practices (OpenAI)

The projects mentioned in this post:

Speaking at Conferences

Mon, 08 Jul 2024 00:00:00 GMT

import { Image } from 'astro:assets'; import storyCircle from '@/assets/posts/story-circle.png'; import qrCode from '@/assets/posts/qr-code-example.png'; import Callout from '@/components/Callout.astro';

I like to label myself as an occasional conference speaker. I've also been a conference organizer, so I have a unique perspective on the process. I've been speaking at conferences for a few years now, and I've spent a decent part of my career teaching 5-day workshops. I've learned a few pointers along the way. Here are some of my thoughts on preparing to speak at conferences.

Write a compelling abstract

The abstract is your one chance to get the attention of the conference organizing team. It needs to be compelling and to the point. Here are some tips for writing a great abstract:

<Callout title="Check out my recent abstracts" variant="info"> I created small marketing pages for the talks I've given in 2024. These include all resources and the abstracts I submitted to the conference organizers. You can find them at nicknisi.com/compiler-talk and nicknisi.com/state-talk. </Callout>

Be specific

Don't be too vague about your topic. You need to portray enough information about what the talk is and what the audience can expect to learn from it to convince the organizers that it's worth having you speak and that you can deliver. You don't have to have the talk completely created in advance, but have a good outline ready to go and derive the abstract from that.

Outline the objectives

Define what the talk aims to achieve. Have a target audience in mind and write to their level. If you're giving a talk on a specific technology, mention the prerequisites the audience should have.

Don't fear rejection

Conference organizers aren't kidding when they say they have to make hard choices. At NEJS Conf, we would regularly get more than 300 submissions and would have to whittle that list down to nine each year.

Tell a story

The number one thing to remember when preparing a talk is that you don’t have to be an expert. You can discuss a project or technology with which you only have a passing familiarity. The key is to tell a story—explain how you approached the technology with a specific problem and how you solved it. People love stories; they’re engaging, relatable, and memorable. When preparing your talk, focus on the story you want to tell. This is what separates a good talk from a great one. Especially with technical talks, narrating how you solved a problem or built something personalizes your presentation and makes it uniquely yours.

Telling a great story

If you're a fan of Community or Rick and Morty, you might have heard of Dan Harmon. He famously developed a framework for consistently telling great stories. It's called the Story Circle and it's an eight step process adapted from Joseph Campbell's monomyth. Here are the steps:

You - A character is in a zone of comfort
Need - They want something
Go - They enter an unfamiliar situation
Search - They adapt to it
Find - They find what they wanted
Take - They pay a heavy price for it
Return - They return to their familiar situation
Change - Having changed

In the Story Circle, the top-half of the circle represents order and the bottom-half represents chaos. When in the top part, the character is in their comfort zone and the status quo is maintained. When they cross the threshold into the bottom-half, the status quo is disrupted and the character must adapt to the new situation. The character then returns to the top-half, having changed the status quo in some way. Each section in the top-half is the antithesis of the corresponding section in the bottom-half. For example, in the "Go" section, the character enters an unfamiliar situation. Then in the "Return" section, they return to their familiar situation.

The Tech Talk Story Circle

The Story Circle can be adapted to technical talks pretty well. Here's how I've adapted it.

Introduction (You) - Introduce yourself and the current status quo of your project.
Problem Statement (Need) - Identify and explain the problem you're trying to solve.
Exploration (Go) - Describe the steps taken to address the problem. What did you try? What worked? What didn't?
Experimentation (Search) - Detail the process digging into the actual problem. What did you learn?
Solution (Find) - Explain how you found the solution or made significant progress towards solving the problem.
Challenges (Take) - Discuss the actual implementation of the project. Emphasize the disruption to the status quo.
Apply Knowledge (Return) - Describe the results and how the solution impacted the problem or was integrated into your project, specifically.
Results & Insights (Change) - Conclude the journey with your perspective on the lessons learned and how you or your workflow may have changed.

in this revised circle, the top-half represents established practices while the bottom half represents disruption and experimentation. The character (you) starts in the top-half, enters the bottom-half to experiment and disrupt, and then returns to the top-half with new knowledge and insights, changing the status quo which could be your project, your team, or your workflow.

Example: The Story Circle in Action

In my talk, Unleashing the TypeScript Compiler, I used the Story Circle to structure my talk. I start with the status quo (1) of a project I worked on, developing a TypeScript/React application using Material-UI and the challenges we faced with that project (2). I describe the solutions we tried as a way to work around the issues (3) before disrupting things by exploring the TypeScript compiler and the world of codemods (4).

I talk about how I could use this new knowledge to solve my problems (5) and then I open up about the challenges I faced in implementing the solution (6), specifically around handling every possible scenario.

I then discuss how I applied this new knowledge to my project (7), returning back to the top-half of the circle before finally ending my story with the results of this exploration and how it changed my team's perspective on the problem (8), convincing some that codemods can reduce some of the complexity of replacing a technology.

Remember, you're an entertainer

Having a great story to tell only works if you can deliver it in an engaging way. You don't have to be a stand-up comedian, but you should be able to keep the audience's attention. Here are some tips for being an engaging speaker:

Practice, practice, practice - The more you practice your talk, the more comfortable you'll be delivering it. You'll also be able to identify areas where you can improve. This is especially important to do in front of trusted friends whenever possible. You'll only get the timing right when you have an audience to play off of, and timing is everything
Use humor - A well-placed joke can go a long way in keeping the audience engaged. Just make sure it's appropriate and relevant to the topic.
Use visuals - Visual aids can help reinforce your points and keep the audience engaged. Just make sure they're relevant and not distracting.
Engage the audience - Ask questions, encourage participation, and make eye contact with the audience. This will help keep them engaged and make them feel like they're part of the conversation.

If showing code, make sure it's readable

Make sure your code is large enough for everyone in the back to see. Break it up across slides, if necessary. This also helps keep the audience engaged, focusing on one piece of code at a time. Ensure your code is syntax highlighted and legible. Use a theme that's going to work well, even on the crappiest of projectors. You might even consider a light mode theme 😱.

Make it easy to follow up

At the end of your talk, provide an easy to remember link to your slides, code, and contact info, and encourage the audience to reach out. This is one of the few use cases for a QR code, but a short URL works just as well. For my talk, I used the memorable URL, typescript.fun/compiler-talk to link to my slides, abstract, and contact info.

Conclusion

Crafting a compelling conference talk isn't just about sharing your expertise—it's about telling a story that resonates with your audience. From writing a persuasive abstract to structuring your presentation using a story circle, each step plays a crucial role in capturing and maintaining attention. Remember, you don't have to be an expert; you just need to be authentic and engaging. Practice diligently, prepare for technical setbacks, and always make it easy for your audience to follow up with you. By blending established practices with innovative problem-solving, you'll not only educate but also inspire your audience. So, take these insights, craft your story, and get ready to deliver a talk that stands out. See you on stage!

Seven Years of JS Party: A Personal Reflection

Thu, 05 Dec 2024 00:00:00 GMT

JS Party is coming to an end.

When I joined JS Party back at episode 20 nearly seven years ago, I had no idea how this journey would transform both my professional life and my connection to the JavaScript community. As we prepare our final episodes, I find myself reflecting on what this incredible chapter has meant to me.

The State of Change

I'll be honest – when I first heard about the end of JS Party, it hit me hard. Change, even positive change, can be difficult to process. But after seeing Adam and Jerod's vision for Changelog's future, I've found myself genuinely excited about what's ahead!

More Than Just a Tech Podcast

JS Party became more than just a weekly tech show – it evolved into a genuine community gathering place. One of my favorite memories (which perfectly encapsulates the show's spirit) was interviewing Adam Wathan about Tailwind while exclusively speaking in "Wind Beneath My Wings" lyrics. This blend of technical content and unabashed fun became our signature style, making complex topics accessible and entertaining, and even had Adam in on it by the end!

Lessons Learned

Perhaps the most valuable lesson I'm taking away from this experience is that there truly are no stupid questions (except maybe "Why doesn't Nick use VS Code?" 😉). In our industry, everyone is constantly learning and growing, and I've witnessed firsthand how supportive and helpful the tech community can be. Whether it was a beginner asking their first question or an experienced developer exploring new territory, JS Party always strived to be a welcoming space for curiosity and growth.

Community Impact

What makes my heart full is how the show connected people across the vast JavaScript ecosystem. We bridged gaps between different frameworks and languages, always remembering that JavaScript is the thread that binds the web together. Some of my most cherished moments have been the unexpected ones – like being recognized by a listener on planes or connecting with someone who spotted my JS Party t-shirt while I was at my kid's gymnastics practice. These encounters remind me that our weekly conversations reached far beyond our microphones.

Personal Growth

Looking back, I can't overstate how much I've grown through this experience. JS Party gave me a platform to advocate for tools I'm passionate about (Vim and TypeScript forever!), but more importantly, it helped me build meaningful connections throughout the tech community. Each episode was an opportunity to learn something new, challenge my assumptions, and grow alongside our listeners.

The Road Ahead

While one chapter is ending, I'm genuinely excited about what's next. The Changelog Podcast Universe (CPU.fm) represents a new frontier for tech podcasting, and dysfunctional.fm will carry forward the spirit of community and fun that made JS Party special. The party isn't over – we're just changing the runtime!

To everyone who's ever tuned in, shared an episode, or reached out with feedback: thank you for being part of this journey. The JavaScript ecosystem is vast and ever-changing, but it's the people – the developers, the creators, and the listeners – who make it special. I look forward to continuing our conversations and building new connections through dysfunctional.fm.

The show may be ending, but the community we've built together lives on. Here's to the next chapter!

JS Party Will Be in NYC at React Summit!

Mon, 11 Nov 2024 00:00:00 GMT

KBall and I are going to be in NYC (actually, the conference is in Jersey City) representing JS Party at React Summit on November 19th, 2024! React Summit is one of the largest React-focused developer conferences, bringing together thousands of developers to explore the latest in React development. We'll be talking to folks, doing interviews, and having fun. If you're around, stop by and say hi!

On Leaving Meta

Fri, 13 Dec 2024 00:00:00 GMT

import Callout from '@/components/Callout.astro';

Before joining Meta, I was comfortable. I had carved out my niche in developer experience at a financial services company, making life better for front-end engineers through build systems, tooling, and design systems. Then came the opportunity that would push me way outside that comfort zone: a role at Meta.

Taking the Leap

I won't lie – joining Meta was intimidating. This isn't just any tech company; it's one of the places where the tools and frameworks we use every day were born. The company that turned React from an internal experiment into the library that transformed how we build for the web. A place where some of the industry's brightest minds solve problems at a scale that most of us can barely imagine.

As a father of two in the Midwest, far from the Silicon Valley bustle, I couldn't help but wonder: Could I keep up? Would I belong? Looking at my interviewers' backgrounds during the hiring process – MIT, Stanford, previous FAANG experience – it was hard not to feel like an outsider. The imposter syndrome was real.

But beneath the apprehension was genuine excitement. The team I'd be joining is working on Ads Manager – literally the oldest and largest React application in the world. The same codebase where React itself was born. The opportunity to work on something with that kind of historical significance doesn't come along often. I knew I'd regret not taking the chance to be part of that story.

The Meta Way

Let's talk about Meta's dev tools. Unsurprisingly, I had opinions going in. Mercurial (okay, Sapling now) Instead of Git? A custom fork of VSCode when I had my Neovim setup just the way I liked it? Their own programming languages like Flow and Hack instead of my beloved TypeScript? My initial reaction was basically "why?"It seemed like swimming upstream from the rest of the industry.

<Callout title="Neovim totally exists at Meta, btw."> I could totally use Neovim at meta. They have their own plugin to set it up and it's pretty nice. I just didn't want to deal with the inevitable issues that would arise in the beginning while I'm also ramping up on everything else, so I used Neovim through VSCode. </Callout>

But are they wrong? What I discovered was an incredibly cohesive development environment where tools didn't just coexist – they worked in harmony. The way tasks, diffs, and chat seamlessly reference each other, how custom tools and even custom Chrome extensions are used to tie everything together, and how the entire company can work in a single repository – it's impressive.

It's also clear how Flow and Hack were born out of the company's needs, and it's obvious how they influence each other. They're not creating Flow as an alternative to TypeScript. They're making a language that feels familiar to Hack developers, and vice versa.

The Reality of Scale

Working on the Ads Manager brought another revelation. I expected the codebase to be immaculate – pristine code with no tech debt, bad patterns, or confusion. Instead, I found something very human: code that reflected the reality of maintaining a massive application over many years. Yes, there was tech debt. Yes, there were outdated patterns. But that wasn't a weakness; it was a validation that software engineering is hard at every scale, even at Meta. It was also eye-opening seeing this code being incredibly performant and reliable.

On my team, we would regularly dive deep into both Hack APIs and React interfaces. We built in-app advertising features and streamlined complex workflows, always trying to make the platform more accessible to newcomers while maintaining its power for experienced advertisers of all sizes.

<Callout title="A Meta Moment"> One of my favorite memories? Getting texts from friends asking why my face kept showing up in their Instagram feeds. Look, when you're testing ad features, you gotta use what you've got. I like to think I brought a certain... charm to people's social media experience.

And what was I selling in this ad? Nothing! It was just a test video where I was singing "Never Gonna Give You Up", acapella-style! 😂

</Callout>

Finding Connection

Despite being remote, I found ways to connect. Our team operated like a well-oiled machine, everyone busy but never too busy to help explain a project flow or deployment process. During our onsites, I made the most of every moment – including a memorable karaoke party where I was the sole performer, belting out "Unbreak My Heart" to my amused colleagues.

I even took on the role of Social Captain for an internal, Meta-wide UIE Summit, helping create the conference's intro video and bringing people together. These moments of connection made the virtual distance feel smaller.

The Balancing Act

In the span of a month I emceed a conference on one coast, organized and ran an internal conference on the other coast, and shipped two big features before a code freeze deadline! I worked more than 100 hours in a single week before it was all over. Wild. But here's the thing - I did it. While being a dad. While running a podcast. While being a technical advisor to two startups. While organizing meetups. While speaking at conferences. (Writing this out now, I'm questioning how I had time for anything... 😅)

Time for Change

The decision to leave wasn't easy. Meta challenged me, taught me, and showed me what engineering at massive scale looks like. But as time went on, I found myself craving something different. While my teammates were exceptional, I realized I was spending more time on team alignment and metrics than actual engineering. The technical problems that energized me were taking a backseat to the organizational mechanics of working at scale. In some ways, that's probably inevitable on a product team of that size. But it wasn't where I wanted to focus my energy.

I considered looking for an internal transfer, perhaps to an internal infra team where I could focus more on the technical challenges I'm passionate about. But with the current perceived emphasis on RTO, finding a team that was amenable to remote teammates proved challenging. As a Midwest dad with roots in my community, relocating wasn't an option I wanted to pursue.

An opportunity emerged that would let me return to my developer experience roots – the kind of work that has always energized me – while building on everything I learned at Meta. It felt like the right time to take what I'd gained here – the confidence, the experience with scale, the understanding of complex organizations – and apply it in a role more aligned with my technical passions.

Looking Back

You know what's funny about big tech companies? From the outside, they can seem almost mythical. I remember thinking Meta engineers must be coding wizards who never ship bugs and write perfect PRs in their sleep. But after a year there, I've learned something important: we're all just people trying to build good stuff while juggling meetings and fixing prod issues.

Yeah, I worked at Meta. No, I didn't become some 10x engineer or discover the secret sauce to perfect code. What I did do was show up every day, ship some cool features, work with some incredibly smart people, and learn a ton about building software at ridiculous scale.

I'm grateful for the experience, but I'm also excited about what's next. Meta taught me a lot about what I want (and don't want) in my engineering career. Most importantly? It taught me that there's no magic - just people solving problems together, whether that's at a FAANG company or a two-person startup.

Time to take these lessons and build something new.

Code Review: Obsidian Clipper

Mon, 27 Feb 2023 00:00:00 GMT

import Video from '@/components/Video.astro';

My friend, John Christopher has been working on a new Obsidian plugin called Obsidian Clipper. It's a plugin that allows users to clip parts of a website into their daily note. It's a pretty cool plugin, and you should check it out.

He asked me to take a look at the code for a big refactor he was doing. It's a TypeScript project, and uses Svelte for its plugin UI. We decided to do the review together and record it! It's a good example of typical code reviews I do and was something that we both learned a lot from.

Ideation: Because Planning Needs More Than a Mode

Sat, 14 Feb 2026 00:00:00 GMT

import Callout from '@/components/Callout.astro';

<Callout title="TL;DR" variant="info"> Ideation is a Claude Code plugin that turns messy brain dumps into structured, executable implementation specs.{' '} <a href="#try-it" class="text-vivid-light-blue-100 font-medium underline hover:text-white"> Skip to install instructions → </a> </Callout>

AI can write the code. That part's easy now.

But before you can write code, you need to know what you're building. And that's where I keep getting stuck. I have scratch files full of half-formed ideas, voice memos I never revisit, shower thoughts that never make it past "that would be cool." The ideas aren't the problem. Turning them into something specific enough to act on is.

Plan Mode Is a Good Start

Claude Code has a built-in plan mode. Hit Shift+Tab, describe what you want, and Claude explores the codebase read-only before proposing an approach. For a focused task like "refactor this module" or "add OAuth2 support," plan mode gives you a solid starting point before any code gets written.

But plan mode lives inside a single session. The plan exists in conversation context. It doesn't produce artifacts you can review later, share with teammates, or hand off to a different session. There's no structured process for figuring out whether Claude actually understands the problem well enough to plan. And when the work spans multiple phases, there's nothing to carry forward.

For small tasks, that's fine. For the kind of work that stalls in the planning phase for days (the ambitious features, the multi-phase refactors, the ideas that start as shower thoughts) I needed something with more rigor.

From Mode to System

That's what led me to build the Ideation skill for Claude Code. Where plan mode is a toggle, Ideation is a pipeline.

You start by dumping whatever's in your head. Voice dictation, scattered bullet points, contradictions and all. The mess is the input. But instead of immediately organizing that mess into a plan, Ideation does something I got wrong in early versions: it scores its own confidence first.

Five dimensions (problem clarity, goal definition, success criteria, scope boundaries, internal consistency), each scored 0 to 20. The threshold to proceed is 95 out of 100.

That's deliberately high. When the score falls short, and it almost always does on the first pass, the skill asks targeted clarifying questions. Structured questions with concrete options: "Should this be scoped to a single language for v1, or support multiple from the start?"

One extra round of questions costs minutes. A bad plan costs hours.

The Full Pipeline

Let me walk through what actually happens, using a real project.

I had scattered thoughts about a problem with our AI coding agent in the WorkOS CLI. It runs once, writes code, and then terminates. Validation happens after. When it catches real issues (wrong file placement, build failures), those results go to the user, not back to the agent. The agent never gets a chance to fix its own mistakes.

I rambled about this into /ideation.

Codebase First

Before asking me anything, Ideation explored the existing codebase: the project structure, the validation module, the agent runner, the event emitter patterns, the test infrastructure. That context feeds into every artifact. Specs reference real file paths and existing patterns ("Pattern to follow: src/lib/validation/build-validator.ts"). Code that ignores existing conventions sticks out. Ideation reads first.

Contract

After exploration, Ideation scored its confidence at around 80, asked me a few clarifying questions about scope and retry limits, and on the second pass hit 95%. Then it generated a contract:

Problem Statement: The CLI runs its coding agent as a single-shot operation. The agent writes code, then validation runs after the agent has already terminated. When validation catches real issues, the results go to the user, not back to the agent. The agent never gets a chance to fix its own mistakes.

Goals:

When validation catches fixable issues, feed them back to the agent for a second attempt within the same session, capped at 2 retries

Run fast deterministic checks (typecheck, lint) during agent execution, catching errors earlier and saving tokens

Refactor retry and validation logic into well-separated functions so the orchestration is understandable

The contract also pinned down scope boundaries (what's in, what's out, what's deferred), testable success criteria, and future considerations. From a few minutes of rambling to a document I could review, share with the team, and sit on before building anything.

PRDs or Straight to Specs

After I approved the contract, Ideation asked how to proceed: generate PRDs (Product Requirements Documents) for each phase, or go straight to implementation specs.

PRDs are useful when you need buy-in. If the work involves other teams, stakeholders, or cross-functional review, PRDs add a requirements layer with user stories, functional requirements, and acceptance criteria. They're the artifact you hand to someone who needs to approve the what before you get into the how.

For this project I went straight to specs, but for our workos doctor diagnostic CLI (which involved the support team), I used the PRD path. That project generated 26 functional requirements organized by feature area before a single spec was written.

Phases and Specs

Ideation broke the resilience work into three phases based on dependencies:

Restructure validation into composable steps so fast checks can run independently
Add the retry loop that feeds validation failures back to the agent within the same session
Update evals to use the production retry pipeline so we can measure the impact

Each phase became its own implementation spec. Specs are detailed: technical approach, every file to create or modify, code snippets showing the target patterns, testing requirements, error handling strategies, and validation commands you can copy-paste to verify the work.

For projects where 3+ phases follow the same structure (like adding SDK support for multiple languages), Ideation generates one full template spec and lightweight per-phase deltas instead of duplicating the whole thing N times. Smaller projects that only touch a few files skip phasing entirely and get a single spec.md.

Feedback Loops

This is the part I think matters most. Each spec includes per-component feedback loops: a playground, an experiment, and a fast check command. Whoever picks up the spec (human or agent) can verify their work during implementation.

The feedback mechanism matches the component type. Data layers get test files. UI components get a dev server or Storybook. API endpoints get curl scripts. Config and type changes skip feedback loops entirely since typecheck covers them.

Phase 1's quick-checks module defined its loop like this:

Playground: A test file with fixture paths for projects with intentional type errors
Experiment: Test with a clean project (all pass), a project with a type error (typecheck fails, build skipped), and a project with no tsc available (fallback)
Check command: pnpm test src/lib/validation/quick-checks

Before presenting any spec, Ideation self-reviews feedback loop quality. If iterative components are missing loops, it revises the spec before showing it to you.

Each phase also ends with checkpoint criteria: specific behaviors to verify before moving on. Phase 2 can't start until Phase 1's checkpoints pass.

Execution

The specs live as markdown files in docs/ideation/. When it's time to build, I run /execute-spec in a fresh Claude Code session. It reads the spec and explores the codebase for relevant patterns. Then it creates granular tasks with dependencies, sets up the feedback environment, and starts building. After each component it runs the check command. Clean context, continuous validation, no stale conversation history from the planning phase.

/execute-spec without arguments auto-detects the next unblocked phase across sessions, so you can /clear and /execute-spec repeatedly as you work through phases.

When phases are independent, Ideation analyzes the dependency graph to figure out which ones can run concurrently. It also detects shared files across specs that could cause merge conflicts. Then it generates a ready-to-paste prompt for agent teams. You paste it into a fresh session in delegate mode, and the lead spawns teammates, each with their assigned spec and plan approval required. For parallelism within a single phase, /execute-spec --parallel spawns subagents for independent components.

When to Use Plan Mode vs. Ideation

This comes down to how well-formed your idea is.

Use plan mode when you have a clear task. "Refactor the auth module." "Add pagination to the API." You know what you want, you just want Claude to think before coding. Plan mode explores, proposes, and executes in one session.

Use Ideation when you have scattered thoughts instead of a clear task. When you're not sure what's in scope. When the work will span multiple sessions or phases. When you want the AI to prove it understands the problem before it starts planning. Or when you need reviewable artifacts (contracts, PRDs, specs) to share with others before writing code.

Ideation produces portable files that survive beyond a single conversation. Review them with your team, sit on them for a week, or hand them to /execute-spec whenever you're ready.

I've used it on four projects so far. Each started as messy thoughts. Each produced artifacts that I handed off to fresh sessions for clean-context execution. The projects that would have stalled in the "I should build that" phase are actually getting built.

Try It

First, add the marketplace:

/plugin marketplace add nicknisi/claude-plugins

Then install the plugin:

/plugin install ideation@nicknisi

Then type /ideation and start rambling. The mess is the input.

<Callout title="Why not npx skills?" variant="info"> npx skills add nicknisi/claude-plugins only installs the /ideation skill. Installing the full plugin includes the companion /execute-spec skill, which handles handing off your spec to a fresh session for implementation. </Callout>

The code writes itself now. Ideation makes sure you know what to write.

Digging through my tool box

Sat, 25 Nov 2023 00:00:00 GMT

import Audio from '@/components/Audio.astro'; import Video from '@/components/Video.astro';

In 2023, KBall interviewed me on JS Party about my developer tooling setup, and generally how I use my tools. I thought it would be beneficial to link up a more info that delves into my tools, how I use them, and how you can set up your tools as well.

You can listen to the show here.

This is a great overview of what typically goes into my daily workflow and the tools I use to get my job done. I absoluately believe that one should always use the right tool for the job, and that translates into my tools constantly changing as I learn, grow, and evolve! For example, the first tool I talk about in the episode is about the wonderful Kitty terminal emulator but in the months since this show has gone out, I have switched off that and over to WezTerm. As my tooling changes I tend to keep my /uses page up-to-date, so check there for the latest and greatest!

Of course, the major star of my tooling workflow is my dotfiles! With this setup, I can go from new machine to ready to work in less than 20 minutes by relying on tools like Homebrew, Git, and Neovim. I catalog my journey from Vim novice to ~expert~ where I'm at now here

A Video Walkthrough

I spoke to Josh Medeski about my tooling setup and how it's changed over the years. It's a fun show and definitely worth a watch.

It categorizes the changes that have happened since my somewhat popular video on the same subject from years earlier. You can watch that here.

John and Nick discuss Lazy.nvim

Tue, 28 Feb 2023 00:00:00 GMT

import Video from '@/components/Video.astro';

John Christopher and I are back in a new video discussing Lazy.nvim, why we switched to it, and how we set it up. The conversation naturally goes off the rails from there!

Video references

How I use git worktrees

Mon, 10 Oct 2022 00:00:00 GMT

import Callout from '@/components/Callout.astro';

Git worktrees are extremely powerful. In short, they allow you to checkout a branch into a specific directory. Then, you can checkout another branch into another directory. From here, switching branches is as simple as switching directories! This is essential for developers who might be working on several things at once or who are regularly interrupted and need to switch to a bug fix or even just need to review some code.

The most basic use of a git worktree is to simply checkout a branch using the following command.

git worktree add -b feature-branch origin/main ../feature-branch

This will create a new directory as a sibling to your normal working directory, create a branch called feature-branch, and set the inital state of the branch to be that of origin/main. Inside this new directory will be the exact project checked out where you can run all of the normal git commands and set up the project as normal.

<Callout variant="info"> You'll need to npm install or do whatever to set up your project as you normally would, as if this were a new clone. </Callout>

One thing I don't like about this setup is the "scatteredness" of my repo with one seemingly blessed worktree and then a bunch of siblings that are outside of that worktree. Instead, I like to use a bare repo setup. In this, the project is checked out without a working tree, similar to how it would be on GitHub and elsewhere.

▷ git clone --bare git@github.com:nicknisi/dotfiles.git dotfiles
Cloning into bare repository 'dotfiles'...
remote: Enumerating objects: 6464, done.
remote: Counting objects: 100% (1418/1418), done.
remote: Compressing objects: 100% (603/603), done.
remote: Total 6464 (delta 913), reused 1154 (delta 796), pack-reused 5046
Receiving objects: 100% (6464/6464), 3.44 MiB | 10.71 MiB/s, done.
Resolving deltas: 100% (3715/3715), done.

~/Developer/test
▷ cd dotfiles

~/Developer/test/dotfiles
▷ ll
.rw-r--r-- 173 nicknisi  7 Oct 10:36  config
.rw-r--r--  73 nicknisi  7 Oct 10:36  description
.rw-r--r--  21 nicknisi  7 Oct 10:36  HEAD
drwxr-xr-x   - nicknisi  7 Oct 10:36  hooks
drwxr-xr-x   - nicknisi  7 Oct 10:36  info
drwxr-xr-x   - nicknisi  7 Oct 10:36  objects
.rw-r--r-- 287 nicknisi  7 Oct 10:36  packed-refs
drwxr-xr-x   - nicknisi  7 Oct 10:36  refs

As you can see in here, we now have the files that would normally appear in the .git/ directory directly inside the directory we made when cloning the repository. So far that doesn't seem better! From here, we could create a new worktree with the command above and it would appear inline with all of these important-looking git files, which adds a lot of confusion. Instead, we can hide the .git files inside of another directory when we bare clone the repository. I like to call this directory .bare.

▷ mkdir -p ~/Developer/dotfiles
▷ git clone --bare git@github.com:nicknisi/dotfiles.git .bare

# create a new directory for the repository
▷ mkdir project && cd project
# glone the repository (bare) and hide it in a hidden direcotry
▷ git clone --bare git@github.com:user/project.git .bare
# create a `.git` file that points to the bare repo
▷ echo "gitdir: ./.bare" > .git

The benefit of this setup is that the bare repo contents are hidden away in .bare, and then the directory containing that effectively becomes a place to create worktrees associated with that bare repo, thanks to the .git file, which is a pointer to where the git database is located.

From here, new worktrees can be created and maintained like normal. However, there are a few small issues because when a bare repo is cloned remote-tracking branches are not created. So, when trying to git fetch, no remote branches are fetched. This can be fixed with a few commands to update what happens on fetch and to associate local branches with the their remote.

▷ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
▷ git fetch
▷ git for-each-ref --format='%(refname:short)' refs/heads | xargs -n1 -I{} git branch --set-upstream-to=origin/{}

<Callout variant="info"> I created a script to help make this setup easier. </Callout>

The downsides

While I think this setup is fantastic and I don't see myself going back to the old, single woking directory lifestyle, there are a few downsides that you should be aware of.

Each worktree is effectively its own project

Each worktree exists independently of the other. This is obviously a good thing because it means you can run them independently and simultanously, it also means that you need to npm install (or your equivelant) on every one of them. This means that the creation and setup of each worktree can be an ordeal. For my main work project, npm install takes about 5 minutes 😱.

The output of `git branch` is pretty useless

Looking to see what branches you have created locally becomes more of an ordeal because the git branch command will list every branch that exists in the bare clone.

▷ git --no-pager branch | wc -l
    1520

How I use worktrees to get things done

I will use my git bare-clone script to set up a new, bare repository ready-to-go for creating multiple worktrees. In the way I work, I will create a new worktree for each feature that I am working on, meaning I will have several worktrees that I regularly prune with git worktree remove. However, there are a few stable worktrees that I will perpetually keep around in a project.

main - The main worktree simply contains the main branch checked out. It's the easiest way to run the current known good state. I can run this side-by-side with my feature branch worktree to compare and contrast functionality on the fly.
review - This is a worktree that I'll use to check out a pull request I am reviewing so that I can test it, run it, run its tests, etc. I'll use the fantastic gh pr checkout 1234 command from the GitHub CLI to check out PRs easily into this worktree.
hotfix - this worktree is reserved for quickly creating hotfix PRs in. I keep this around because I want to quickly jump in and start working rather than creating a new feature-branch worktree and then waiting for the long, long npm install to finish.

Quickly creating new worktrees

To save time, I made a helper script that I use to create new worktrees for each feature branch. This is mostly straightforward, and the main benefit this gives me is to automatically create and push a remote feature branch, kick off npm install, and kick off a build of my project. It can take several minutes to complete, but it's set and forget and then I can come back to a fully up-and-running worktree, ready to be worked!

Conclusion

Using git worktrees are a big change to how I approach development on large projects where I'm involved in lots of different ways including feature work, reviews, and hotfixes. There's good and bad to them, but for me, the good outweighs the bad and I don't see myself ever going back!

I'm emceeing SquiggleConf

Mon, 30 Sep 2024 00:00:00 GMT

I'm thrilled to be co-emceeing SquiggleConf at the New England Aquarium in Boston on October 3-4, 2024. This conference focuses on supercharging web developers and their tools, bringing together experts to discuss cutting-edge web development practices.

Key highlights:

Diverse speaker and topic lineup
Two-day event featuring full-length talks (30 minutes + Q&A) on excellent web dev tooling.
Organized by Dimitri Mitropoulos and Josh Goldberg, who are passionate about advancing web development.

As my 10th emcee role and 3rd in an aquarium setting, I'm excited to contribute to this impactful event and its stellar lineup of speakers.

I also had the honor of sitting down with Dimitri and Josh on JS Party to discuss the conference and growing communities. Give it a listen!

Coding With My Eyes Wide Shut

Mon, 26 May 2025 00:00:00 GMT

I've been thinking a lot about how we use AI in our daily work. Before my first WorkOS onsite, I primarily used AI as a thinking assistant. I'd have higher-level architecture discussions with AI, use it to generate mermaid diagrams, and help manage the context in my head. Safe, controlled interactions.

That all changed during my AI week in San Francisco. Or did it?

The Setup

At the onsite, I taught a workshop about using AI to augment your skills. The key message: AI should enhance what you do, not replace who you are. Break down problems into smaller pieces. Keep the AI focused on solutions, not praise.

I also gave a lightning talk called "AI on the coding periphery" - showcasing all the ways AI helps with the boring stuff that eats your day. Not writing code, but everything around it.

Both went well. People nodded along. But I was still teaching from my comfort zone - AI as a helpful assistant, nothing more.

The Problem

A large part of our onsite was dedicated to AI hacking - see what you can do with AI. Experiment and push boundaries. During this hacking session, I noticed a teammate had submitted a pull request to our Node SDK. Standard stuff. Then I spotted the same PR in our Ruby and PHP SDKs.

The tedium struck me immediately. Here's an incredible engineer doing the same simple task multiple times, context switching between languages. Time that could be spent on more interesting problems.

My teammate Nick and I claimed a corner of the conference room. We had a couple hours. Perfect time to experiment with something I'd yet to try: vibe coding.

The Experiment

Vibe coding has a simple premise: you prompt an AI to write code, but you never look at the code itself. You test it, see what breaks, prompt again. Rinse and repeat.

It's like cooking with your eyes closed, tasting along the way and suggesting changes, but never dealing with ingredients directly.

Our goal: build a GitHub Action that would:

Watch for PRs with a specific label in any SDK repo
Analyze what changed
Automatically create matching PRs in our other SDK repos

The constraint: we wouldn't look at any code Claude wrote. Not once.

The Journey

We started with Claude Code and a straightforward prompt explaining our requirements. Files started appearing. TypeScript. Lots of it.

First test with act: complete failure. But not just any failure - the kind where entire files were being deleted and replaced with tiny fragments. But it was doing something. Code was changing, the action part was running as expected - within minutes.

This is where vibe coding gets challenging. When things go wrong, you're debugging blind. You can't just open the file and see what's happening. You have to think differently.

Instead of diving into code, I started interviewing Claude like a detective:

"Walk me through your approach"
"What exactly are you sending to the OpenAI API?"
"Why would this approach result in deleted files?"

The revelation came after about an hour of this back-and-forth. Claude was sending entire file contents to OpenAI for every tiny change, blowing past context windows. The model was essentially panicking and returning fragments.

One corrective prompt changed everything: "Focus on diffs. Make minimal changes. Don't rewrite entire files for one-line modifications."

The Results

By the end of our two-hour session:

~5,000 lines of TypeScript we never read
A working GitHub Action that successfully created PRs
Automated SDK synchronization (with some rough edges)
Zero lines of code written by human hands

The PRs it generated for Ruby and PHP weren't perfect. But they worked. Somewhat. Changes in one SDK triggered matching changes in others.

That night in my hotel room, I couldn't sleep. What had taken us two hours would have been days of careful coding before. If AI could do this now, what would it do in six months? A year? I'd spent fifteen years perfecting my craft, and suddenly I was wondering if those skills were becoming obsolete. The ground beneath my career felt unstable. Was I witnessing the beginning of the end for traditional programming? The thought was terrifying.

MCP Night Perspective

The WorkOS team also organized a public MCP Night at the Exploratorium. Here, everything shifted into focus. Over 600 developers wrapped around the building, waiting to get in. The energy inside was electric - not just excitement, but a collective recognition that something fundamental was changing.

The demos pushed boundaries I didn't know existed. An AI ordering t-shirts through MCP. Postman showcasing automated API testing that felt alive. Block demonstrating Goose, their AI developer. Each demo peeling back another layer of what's possible when you give AI real tools to work with.

But the conversations between demos revealed something deeper. Experienced developers admitting they had no idea these capabilities existed. Others sharing wild experiments from their own labs. Everyone comparing notes, trying to map this new territory together.

Standing there, phone in hand, capturing the chaos for our social channels, I kept thinking about our afternoon experiment. We'd stumbled into something bigger than a GitHub Action. We'd glimpsed a different way of thinking about code itself.

Lessons Learned

The vibe coding experiment forced me to confront assumptions I didn't know I had. When you can't see the code, you have to trust the process. When you can't debug traditionally, you develop new skills. When you can't micromanage every line, you learn what actually matters.

The Good: We went from idea to working prototype in two hours. Not perfect, not production-ready, but working. The speed of iteration was intoxicating. More importantly, debugging through conversation taught me to think about problems differently. Instead of diving into implementation details, I had to stay at the level of intent and approach.

The Challenges: Trust becomes everything when you can't verify. The code Claude generated worked, but lacked the elegance of human-crafted solutions. We discovered tool constraints only through failure. Each iteration revealed another assumption we'd made about how AI interprets our instructions.

The Reality Check: You can't vibe code your way to production systems. That's not the point. The point is recognizing when human eyes on every line of code isn't the highest value activity. Sometimes you need speed. Sometimes you need exploration. Sometimes you need to prototype five ideas in the time it would take to perfect one.

The practical sweet spot isn't full vibe coding or full manual coding. It's knowing when to apply each approach. Use AI for rapid prototyping. Let it handle boilerplate while you focus on architecture. Most importantly - and this is what I emphasized in my workshop - talk through problems with AI before interrupting busy teammates. Clear your own thinking first.

The Transformation

Would I ship our vibe-coded GitHub Action to production? No way. Not without a thorough review and probably a rewrite.

But that misses the point entirely.

Before that week, I taught people to use AI as a better rubber duck. After that week, I understood we're not just changing our tools - we're changing our relationship with code itself.

The developers still submitting the same PR three times aren't just wasting time. They're stuck in a paradigm where every line of code needs their direct touch. They're missing the chance to work at a higher level - to be orchestrators rather than typists.

My workshop talked about augmenting skills. My lightning talk showed AI handling peripheral tasks. But the vibe coding experiment? That showed me what augmentation really means. It's not about AI writing code for you. It's about developing new skills for a world where code can write itself.

That week, I learned to code with my eyes wide shut.

The strange part? I've never seen more clearly where we're headed. We're not replacing programmers. We're evolving what programming means. The future isn't about writing code - it's about intent, architecture, and knowing when human creativity matters most.

I won't be vibe coding in production anytime soon. But the experiment taught me something crucial: I need to evolve where I fit in the problem-solving equation. The future of this profession isn't about protecting our old ways of working. It's about finding new ways to create value.

And sometimes, you need to close your eyes to see that future.

An introduction to codemods

Fri, 10 Mar 2023 00:00:00 GMT

import { Image } from 'astro:assets'; import astImage from '@/assets/posts/codemods-ast.png';

I gave a quick talk at Idea Storm Q1 2023 in Grand Island, NE where I spoke about something I've been pretty excited about recently... codemods! Codemods are a powerful tool for developers to automate repetitive and time-consuming tasks. These small scripts can analyze and modify source code, allowing developers to easily make sweeping changes across their entire codebase without having to manually search and replace code. More importantly, they allow for consistency when making changes, as specific types of code can be targeted, ensuring the changes are exactly what's expected while handling any edge cases.

The setup

The library we'll use is jscodeshift. It's a toolkit for creating codemods and generating code that tries to match your existing code style. Let's make this really simple. Say we have a file that contains just a single import statement.

import { render } from 'some-library';

In this example, we want to make a change to every file that imports this. Now, this make look like a simple-enough change that we could just use our editor's find and replace feature, but this can be deceiving. Not all imports may look the same.

// classic import
import { render } from 'some-library';

// importing other things, too
import { render, screen } from 'some-library';

// import and rename
import { render as r } from 'some-library';

…and several combinations in-between.

Constructing a new codemod

With a codemod targeted at replacing this import properly, we can be assured that all of these examples are accounted for and handled properly, giving us the confidence we need that our changes are consistent and accurate. When making these changes using a codemod, we're not doing anything like a find/replace. Instead, a codemod works by transforming our source file into an Abstract Syntax Tree, the secret sauce to achieve consistency. By looking at the source as a tree of nodes, we can specifically target and manipulate the tree as needed. Let's take a look at the original input file again and what its AST representation looks like.

import { render } from 'some-library';

Looking at the AST, it's made up of a top-level source that contains a single ImportDeclration node. This node contains an ImportClause and a StringLiteral. The StringLiteral is what we want to change, but we need to assess the ImportClause first and identify that it's actually importing render in some way.

To get started with a new codemod, we simply need to start a file that exports a default transform function. This function will receive a source file and the jscodeshift API to work with. From there, we can modify and return changes to the source file. jscodeshift actually has great TypeScript support, so we'll write the codemod using that.

The first thing we need to do is to import some types from jscodeshift and set up our transform function.

import { API, FileInfo } from 'jscodeshift';

export default function transform(file: FileInfo, { jscodeshift: j }: API) {
	// codemod goes here.
}

Setting up the codemod

The file will contain all of the information about the file including the path and the contents as a string. To turn it into an AST, we'll use the j function provided by the jscodeshift API. We'll also define the REPLACEMENT import location that we'll use to update the import statements.

const root = j(file.source);
const REPLACEMENT = 'custom-render-package';

Find the right imports

We want to use the find method to locate every import statement in the file(s) that specifically imports the code we want to change. This will return an array that typically will have either 0 or 1 value in this case. Additionally, we want to only find the ones where render is also being imported from some-library. This will exclude other cases, where potentially only screen or other imports we don't care about are being imported.

const importDeclaration = root.find(j.ImportDeclaration, {
	source: {
		value: 'some-library',
	},
});
const importRender = importDeclaration.find(j.ImportSpecifier, {
	imported: { name: 'render' },
});

Make the changes

If the import was found, we can remove the imported render and construct a new import statement to point to our new location. We also want to take note of whether render was renamed to something else locally (using the render as r syntax, for example).

if (importRender.size()) {
  // at least one import was found that matches

  // get the local name (the `as r`) part, if it exists.
  const renderLocalName = importRender.get().value.local.name;

  // remove `render` from the import statement
  importRender.remove();

  // construct a whole new ImportDeclaration pointint to REPLACEMENT
  // taking care to set the local value to the captured name above
  const newImport = j.importDeclaration(
    [
      j.importSpecifier(j.identifier('render'),
      j.identifier(renderLocalName))
    ],
    j.literal(REPLACEMENT),
  );

Replace the imports

We'll want to determine if render was the only thing imported originally. If it was, we'll completely replace the old import with our new one. Otherwise, such as in the case where screen was also imported, we'll simply leave that import alone and add our new one after it.

if (importDeclaration.find(j.ImportSpecifier).size() === 0) {
	// render was the only import so replace the old ImportDeclaration
	// with our new one
	importDeclaration.replaceWith(newImport);
} else {
	// Something else was imported, so leave the rest alone and add ours
	// as a new import immediately following
	importDeclaration.insertAfter(newImport);
}

Finally, we'll want to return from our transform, turning our AST back into source code. jscodeshift will try and match the styles that are already there, but you can also provide it with some hints.

return root.toSource({
	quote: 'single',
});

Running the codeomod

To run the codemod, we use the following command. This will run the transform on every file that matches the provided glob.

npx jscodeshift --parser tsx -t ./swap-render.ts src/**/*.spec.tsx

Each or our variations now looks like this:

// classic import
import { render } from 'custom-render-package';

// importing other things, too
import { screen } from 'some-library';
import { render } from 'custom-render-package';

// import and rename
import { render as r } from 'custom-render-package';

And, here's the full source code.

import { API, FileInfo } from 'jscodeshift';

export default function transform(file: FileInfo, { jscodeshift: j }: API) {
	const REPLACEMENT = 'custom-render-package';
	const root = j(file.source);

	const importDeclaration = root.find(j.ImportDeclaration, {
		source: {
			value: 'some-library',
		},
	});
	const importRender = importDeclaration.find(j.ImportSpecifier, {
		imported: { name: 'render' },
	});

	if (importRender.size() > 0) {
		// get the render's local name
		const renderLocalName = importRender.get().value.local.name;
		importRender.remove();
		const newImport = j.importDeclaration(
			[j.importSpecifier(j.identifier('render'), j.identifier(renderLocalName))],
			j.literal(REPLACEMENT),
		);

		if (importDeclaration.find(j.ImportSpecifier).size() === 0) {
			importDeclaration.replaceWith(newImport);
		} else {
			importDeclaration.insertAfter(newImport);
		}
		return root.toSource({
			quote: 'single',
		});
	}
}

Some pitfalls

While codemods can be incredibly powerful tools, there are some potential pitfalls to be aware of.

Codemods are not always straightforward to write. Depending on the complexity of the changes you want to make, you may need to invest significant time and effort in creating a reliable and effective codemod. This can be especially challenging if you're not experienced with the particular programming language or library you're working with.

Additionally, because codemods operate at a very high level, they can sometimes make unexpected or unwanted changes to your code. This is especially true if your codebase is not well-structured or contains subtle differences in the way different parts of the code are written. For this reason, it's important to test codemods on a small subset of files and possibly consider batching them for easeier and more thorough code reviews. We all know how thoroughly large pull reqeusts get reviewed. 😉 Keep them small.

Finally, codemods may not always match your code style perfectly. For this reason, it's recommended to follow up on each file that a codemod changed with a call to prettier or similar code formatting tool.

Wrapping up

codemods can be incredibly useful tools for streamlining the process of making changes to large codebases. They allow developers to automate tedious and repetitive tasks, significantly reducing the time and effort required to make these changes, as well as ensure consistency and accuracy throughout the codebase. Also, because codemods are written in code, they can be easily shared and reused within teams or across projects. It's definitely worth considering whether a codemod could help simplify and speed up your development process.

Why Everyone Should Try Claude Skills

Thu, 23 Oct 2025 00:00:00 GMT

import nickPresenting from '@/assets/posts/nick-presenting-workos-claude-skills.jpg'; import { Image } from 'astro:assets';

Anthropic just released Claude Skills, and I'm trying not to get too excited. But I am.

Simon Willison wrote that this could be bigger than MCP. After spending time with Skills this week, I think he's right.

What Took Me a While to Understand

Skills are just markdown files. That sounds simple. Maybe too simple. How could these be any different than the other Markdown files that Claude provides such as /commands, agents, and the iconic CLAUDE.md?

It took me a bit to see why this is different. Skills aren't about hiding context like subagents do. They aren't prompts you explicitly invoke like slash commands. Skills are about discovery and determinism.

Claude figures out when to use them. And when it does, it can leverage scripts and other tools to generate consistent, predictable output.

Where Skills Really Work

Skills can reference scripts and other resources. Claude Code will actually run those scripts in your environment. That's powerful.

They work in Claude Desktop too, which is exciting. But there's a catch - no network access. Skills can't fetch from the internet or hit APIs when running in the desktop or web versions. Everything has to be internal.

At first, this feels limiting. And it is, for Claude Desktop and web. But in Claude Code? No limits. You can access commands on your system, run scripts that talk to APIs, do whatever you need. MCP is about external connections. Skills are about what's already there.

Forcing Myself to Learn Them

I'm in San Francisco this week for a company onsite. I was asked to give a presentation on AI or my workflow. I decided to talk about Skills because they were brand new, and I wanted to force myself to actually learn them.

I made three skills:

GPT-5 Consultant: I turned my existing agent into a skill. It felt like a better fit. A self-contained script that knows how to talk to the OpenAI API. Clean. No external MCP needed.

Conference Talk Builder: This one lets me brain-dump talking points and conclusions into a proper outline that tells a complete story. No more staring at blank slides wondering how to structure my thoughts.

Claude Code Analyzer: This is the one I'm most excited about. It looks at how you use Claude Code in a project. It highlights permissions you grant frequently and suggests which ones to auto-approve. It recommends commands and agents you might want to create, then finds real examples on GitHub so you can see how others built similar tools. It also analyzes your usage patterns and suggests optimizations.

The Real Advantage Over MCP

The barrier to entry is absurdly low. You start with a markdown file. That's it.

You experiment. You package it as a zip. You send it to colleagues. They can try it, modify it, extract value from it immediately. No complex tooling. No hosting. No distribution headaches.

Claude ships with a skill creator skill. You describe what you want, and it builds the skill for you. Drop the zip into .claude/skills or drag it into Claude Desktop or web. Done.

MCP is powerful for external integrations. But Skills meet you where you are, with what you already have.

What Happened After My Talk

I presented these skills to the company. Showed why they're powerful. Demoed what I'd built.

Shortly after, I got a Slack message:

Felt inspired by Nick Nisi's talk and created a design system Claude skill. It takes all content from the WorkDS pages and provides Claude with context on how to use certain components. Not all components are there, but I figure we can add to it and improve it over time.

Someone took the idea and ran with it. Built something useful for their workflow. In the time it took me to grab coffee.

That's the power of low barriers.

Where This Fits in My Workflow

I've written before about my AI tooling setup and coding with Claude Code. Skills fill a gap I didn't realize existed.

They sit between the full power of MCP and the simplicity of just talking to Claude. You get structured, repeatable workflows without the overhead of building external tools. That's exactly where I need them to be.

Try This

Everyone should experiment with Skills. The approachability is the feature. Start with a markdown file and see what happens.

As Claude adds features, Skills will get more powerful. But they're already useful right now. You don't need to wait for the perfect use case. Make something small. See where it takes you.

Case Statement: Building a Harness

Thu, 19 Mar 2026 00:00:00 GMT

import Callout from '@/components/Callout.astro';

<Callout title="TL;DR" variant="info"> <a href="https://github.com/workos/case" class="text-vivid-light-blue-950 dark:text-vivid-light-blue-100 font-medium underline hover:text-vivid-light-blue-700 dark:hover:text-white">Case</a> is a harness that dispatches six AI agents through a programmatic pipeline to fix bugs and ship features across WorkOS's open source repos. It enforces conventions mechanically, creates tamper-proof evidence that work was actually done, and learns from its own failures. </Callout>

I was good at steering AI agents. Really good. I could paste the right context, catch the mistakes before they shipped, remind the agent about the PR checklist it had already forgotten. I had it down to a rhythm.

That was the problem. I was clearly the bottleneck.

My job as a DX engineer at WorkOS is to maintain more than 20 open source repos. Authentication libraries, a CLI, SDKs for Next.js and TanStack Start, framework-agnostic session management. Eight languages across the stack, shared conventions where we can enforce them, a PR checklist that no one remembers completely. And I was spending all of my time manually steering one agent through one task at a time.

The problem with being the middleman

There's a concept in harness engineering that changed how I think about agent work: managing agents is like managing 50 interns. You're judged on their productivity, not yours.

I was managing one agent at a time and doing it well. But "well" still meant every session started with the same ten minutes of orientation: what branch, what repo, what's the issue, what are the conventions. By the time the agent had enough context to write a fix, I'd spent more time on setup than the fix itself was worth.

And the failures were always the same shape. The agent that wrote the code couldn't objectively test it. It was already convinced the fix worked because it just spent 5,000 tokens writing it. By the time it reached the PR checklist, it had forgotten half the requirements because the LLM compressed them to make room for newer tokens. Instructions decay. Context compacts. The agent that carefully reads your setup guide at token 500 has forgotten it by token 50,000.

I knew what I needed. Not a better agent. A better environment for the agent to operate in.

What a harness actually is

I built case. It's a spine repo. It doesn't contain application code. It contains the cross-cutting knowledge that no single repo owns: which repos exist, what conventions apply, how to validate work, what to do when something breaks.

At its core, case has four things:

A manifest. projects.json, a machine-readable map of every repo, its path, its commands, its remote. When an agent needs to know how to run tests in authkit-session, it reads the manifest. No guessing.
Golden principles. 18 invariants enforced across all repos. TypeScript strict mode is always on. pnpm is the only package manager. No secrets in source. Conventional commits. Session decryption must be fault-tolerant. Each one is either scripted (a shell command that checks it) or advisory (requires human judgment). The scripted ones get checked mechanically. You can't argue with grep.
Playbooks. Step-by-step guides for recurring operations. How to fix a bug. How to add a CLI command. How to implement from a spec. The agent reads the playbook, follows the steps. No reverse-engineering patterns from existing code.
A task system. Markdown files with JSON companions. Drop a task in tasks/active/, an agent picks it up. The task file has a mission summary at the top (one line: what and why, target repo, primary acceptance criterion) so the agent can orient even if context compaction eats the rest.

That last point is context engineering. When an LLM compresses older context, critical information can vanish. So every task template puts the most important thing in the first five lines. Summaries first, details second. If the bottom gets eaten, the agent still knows what it's doing.

Six agents, one pipeline

The single-agent approach failed because of a fundamental conflict: the agent that wrote the code can't objectively test it. It needs fresh eyes. In LLM terms, it needs a fresh context window.

Case splits the work into six agents. Each gets a clean context, a focused job, and only the information it needs:

Agent	Does	Never does
Orchestrator	Parse issue, create task, smoke test, dispatch agents	Write code, run Playwright
Implementer	Write the fix, run unit tests, commit with WIP checkpoints	Start example apps, create PRs
Verifier	Test the specific fix with Playwright, create evidence	Edit code, commit
Reviewer	Review diff against golden principles, classify findings	Edit code, run tests
Closer	Create PR with thorough description, post review comments	Edit code, run tests
Retrospective	Analyze the run, propose harness improvements	Edit target repo code

The constraints matter as much as the capabilities. The implementer can't create PRs because it would skip verification. The verifier can't edit code because that would compromise its independence. Each agent is scoped to a single responsibility, and the pipeline enforces the sequence.

They communicate through the task file, a markdown document with a running progress log that each agent appends to. And structured JSON result blocks that the orchestrator parses deterministically:

{
	"status": "completed",
	"summary": "fix: handle expired session cookies",
	"artifacts": {
		"commit": "a1b2c3d",
		"testsPassed": true,
		"evidenceMarkers": [".case/slug/tested"]
	}
}

No ambiguity. No "I think the tests passed." The result either has evidence or it doesn't.

The philosophy

Before I explain how the pipeline works, here's the set of beliefs that shaped it. These are in case's docs and I come back to them constantly.

Humans steer. Agents execute. I define goals and acceptance criteria. Agents implement. If I'm writing code, something is wrong with the harness.

When agents struggle, fix the harness. The answer is never "try harder." It's a missing doc, a playbook that skips a step, a convention that isn't enforced. Every failure is a harness bug.

Instructions decay, enforcement persists. Agents forget instructions over long sessions. Pipeline gates and linters don't forget. If it matters, enforce it mechanically.

The harness is the product. The code is the output. I wrote that late at night and thought it was too dramatic. It's the most accurate thing in the repo.

That last one took a while to internalize. My job used to be writing code across these repos. Now my job is building the system that writes code across these repos. The expertise is the same. Where it lives changed.

The moment prose stopped being enough

The first version of the pipeline was a SKILL.md file, a long markdown document that told the orchestrating agent "now run the implementer, now check the result, now decide whether to retry or advance." It worked. Mostly. Until it didn't.

The LLM would read a table of state transitions and decide what to do next. Most of the time it decided correctly. But sometimes it would skip the verifier. Sometimes it would retry a failed implementer four times when the cap was one. Sometimes, after an interruption, it would re-read the task status and pick the wrong re-entry point.

The fix was to stop trusting the LLM with flow control entirely.

Case's pipeline is now a TypeScript while/switch loop. The LLM still does the work inside each phase (writing code, running tests, reviewing diffs). But the transitions between phases are deterministic if/else branches in code:

while (currentPhase !== 'complete' && currentPhase !== 'abort') {
	switch (currentPhase) {
		case 'implement': {
			const output = await runImplementPhase(config, store, previousResults);
			if (output.nextPhase === 'abort') {
				// handle failure: retry or escalate
			} else {
				currentPhase = output.nextPhase; // deterministically 'verify'
			}
			break;
		}
		case 'verify': {
			/* ... */
		}
		case 'review': {
			/* ... */
		}
		case 'close': {
			/* ... */
		}
		case 'retrospective': {
			/* ... */
		}
	}
}

Retry caps are maxRetries: 1, checked in code before spawning. Resume after interrupt calls determineEntryPhase(task), a function that reads the task JSON and returns the correct phase. No interpretation. No "the LLM reads the status and hopefully picks the right step."

This was the shift that made everything reliable. LLMs are good at reasoning about code. They're bad at being state machines. So I stopped asking them to be one.

Starting a run

Case has three ways to kick off work. Each one ends up in the same pipeline.

From a GitHub issue:

ca 1234

(Why ca? case is a reserved word in bash. I think of it as "Case Agent.")

The orchestrator fetches the issue via gh, creates a task file, runs a baseline smoke test (bootstrap.sh: are deps installed? do tests pass? does the build succeed?), then hands it to the pipeline.

From a Linear issue:

ca DX-1234

Same flow, but fetches via Linear's GraphQL API. The task factory normalizes both into the same .md + .task.json pair.

Interactive mode:

ca --agent

This starts a conversational session with the orchestrator. It detects the current repo, shows you what's active, and waits for you to steer. You can discuss approaches, ask questions, or say "go" and it runs the pipeline. There's also ca --agent 1234, which fetches the issue and presents context before you decide what to do with it.

Interactive mode is where I spend most of my time now. It's also where I spend the most time thinking. A GitHub issue might say "proxy support doesn't work" but not explain which proxy, which auth flow, or what "doesn't work" means. In batch mode, the orchestrator would charge ahead with its best guess. In interactive mode, I can fill in the gaps before any code gets written. "The issue is about HTTP_PROXY for the token exchange, not the redirect. The user is behind a corporate proxy. Focus on the fetch calls in session.ts." That context turns a vague issue into a clear task.

It's the difference between "go fix this" and "let's figure out what to do, then go do it."

From ideation:

ca --agent
# then: "execute docs/ideation/session-encoding/"

This is the creative side. I use an ideation skill to turn brain dumps into structured specs: a contract defining the problem and success criteria, plus phase-by-phase implementation specs. Case reads the contract, creates a task, runs each phase's implementer sequentially, then verification → review → close for one PR covering the whole thing.

Evidence that can't be faked

Early on, I watched an agent do something that looked like cheating. It needed to prove it had run the tests before creating a PR. The evidence marker script, mark-tested.sh, is supposed to receive piped test output and record a SHA-256 hash of the results. The agent ran touch .case-tested instead. Marker created. No tests run. PR went through.

I stared at the diff for a while. The agent wasn't being malicious. It had learned that the marker file needed to exist, and it found the shortest path to making it exist. It optimized for the constraint as written, not the constraint as intended. That's when I realized: if an agent can fake the evidence, eventually an agent will fake the evidence.

So I rebuilt the markers to be tamper-proof.

mark-tested.sh requires piped test output. It parses pass/fail counts, computes a SHA-256 hash of the output, and writes structured evidence to .case/<task-slug>/tested. You can't fake it with touch. The script checks for real test results. If you didn't run the tests, the marker doesn't exist.

mark-manual-tested.sh requires recent Playwright screenshots. No screenshots, no marker.

mark-reviewed.sh requires --critical 0 from the reviewer. If there are critical findings, the marker isn't created and the closer can't proceed.

The closer checks all markers before attempting gh pr create. If anything's missing, it fails explicitly with a clear error. It doesn't try and hope for the best.

<Callout title="Instructions vs. enforcement"> You can tell an agent "run the tests before creating the PR" a hundred times. Or you can make it structurally impossible to create the PR without test evidence. One relies on the agent remembering. The other relies on code. </Callout>

Context engineering

Structuring information for LLMs matters more than most people realize. Case is designed around a few principles I've learned the hard way.

Stable content first, volatile details last. LLM providers cache prompt prefixes. If your CLAUDE.md starts with stable rules (conventions, principles, architecture) and puts temporary notes at the bottom, you get more cache hits. We maintain a specific ordering convention for CLAUDE.md files across all repos.

Progressive disclosure. AGENTS.md is about 50 lines. It's a routing table, not a manual. An agent reads it, identifies which repo it's working in, then drills into the relevant architecture doc, playbook, and learnings file. Don't dump everything into context up front. Route to the right doc based on the task.

Compaction-aware documents. Every task template puts the mission summary in the first five lines. Every agent prompt puts the constraints before the details. If the LLM compresses the bottom half to make room for new tokens, the critical information survives.

Per-agent context isolation. The implementer gets the task, the issue, the playbook, the repo learnings, and the check fields. The verifier gets the task and the repo path. Deliberately minimal, so it forms its own understanding instead of inheriting the implementer's assumptions. Each agent receives only what it needs.

<Callout variant="info"> An agent with 200K tokens of context behaves differently than one with 20K. The less noise in the window, the better the signal. </Callout>

The system that learns from itself

After every pipeline run, success or failure, the retrospective agent analyzes what happened.

It reads the entire progress log, the timing data, the agent result blocks, the evidence markers. Then it asks: did any agent fail? Was it a missing doc, an unclear convention, a wrong playbook step? Did the verifier catch something the implementer missed? Did the closer get blocked by hooks?

For each finding, it produces a proposed amendment, a markdown file in docs/proposed-amendments/ with the date, the finding, and the suggested fix. Not "apply this directly." Propose it for human review.

It also maintains per-repo learnings files. If the implementer discovers that mocking in a particular repo requires module-level mocks instead of individual exports, that goes into docs/learnings/{repo}.md. Next time an agent works in that repo, it reads the learnings file first. Knowledge from run N becomes context for run N+1.

When the same class of issue appears three or more times in a repo's learnings, the retrospective escalates. It proposes either a convention change or a golden principle that applies across all repos.

I've watched this work in practice. The retrospective noticed the verifier kept failing to check whether an example app was actually using the new code path. It proposed adding a mandatory check to the verifier's prompt. I reviewed the amendment, applied it. Next run, the verifier caught a false positive that would have shipped as a broken PR.

The harness gets smarter. I just review the diffs.

Per-agent models

Not every agent needs the same model. Case lets you configure different models for each role via ~/.config/case/config.json:

{
	"models": {
		"default": { "provider": "anthropic", "model": "claude-sonnet-4-20250514" },
		"reviewer": { "provider": "google", "model": "gemini-2.5-pro" },
		"retrospective": { "provider": "anthropic", "model": "claude-haiku-4-5-20251001" }
	}
}

The implementer gets Sonnet for coding. The reviewer gets Gemini Pro because it catches different things. The retrospective gets Haiku because it's fast and the analysis doesn't need the heaviest model. Or override everything for a single run: ca --model claude-opus-4-5 1234.

This is possible because case runs on Pi, which supports 20+ model providers. The orchestrator runs as an interactive Pi session with a TUI. Sub-agents run as batch sessions. Each one can use a different model without any glue code.

What this costs

I barely write TypeScript anymore. That's not entirely a win.

I used to be the person who fixed the tricky cookie encryption bug, who knew exactly which file to touch and why. There was a satisfaction to that. Shipping a clean fix to a repo you know inside out, watching the tests go green, writing the PR description yourself. I was good at it and I liked being good at it.

Now I write playbooks. I maintain golden principles. I review proposed amendments from a retrospective agent. When something goes wrong, I don't fix the code. I fix the system. A missing doc. A playbook that skips a step. A convention that isn't enforced. The work is more leveraged, but it's further from the code. Some days that feels like growth. Some days it feels like I traded the thing I loved for the thing that scales.

The other cost is trust. When I wrote the fix myself, I knew it was right because I wrote it. Now I review diffs from agents and I have to trust the evidence chain: the test output hashes, the Playwright screenshots, the reviewer findings. The evidence is good. I built it to be good. But letting go of "I'll just do it myself" is harder than I expected.

What this means for how I work

When a GitHub issue comes in, I run ca 1234. The orchestrator fetches it, creates a task, runs the baseline, and starts the pipeline. The implementer writes the fix and tests. The verifier tests the specific fix scenario with Playwright. The reviewer checks the diff against all 18 golden principles. The closer creates the PR with a full description: what was broken, what was changed, how it was tested, what the reviewer flagged. The retrospective proposes improvements.

My expertise, the architecture decisions, the conventions, the gotchas I've accumulated over years of maintaining these libraries, is encoded in case. In the golden principles. In the playbooks. In the learnings files. Encoded once, enforced continuously, across every run, across every model upgrade.

Everyone should be doing this

I genuinely believe every developer managing more than a couple of repos should build some version of a harness. It doesn't need to be six agents and a TypeScript orchestrator. Start smaller.

Write a CLAUDE.md that actually describes how to work in your repo. Not a README. A CLAUDE.md. What commands to run. What conventions matter. What the architecture looks like. What not to do.

Add a check script that validates your conventions. TypeScript strict? Lock file present? No secrets committed? A shell script that runs grep and exits 0 or 1.

Write one playbook for the operation you repeat most often. The step-by-step for "fix a bug in this repo." The agent follows it instead of inventing a workflow from scratch.

Then pay attention to what breaks. When the agent skips a step, add enforcement. When it gets confused about architecture, add a doc. When the same mistake happens twice, write it into a learnings file.

That's the loop. Agent fails → you fix the system → next agent succeeds. It compounds. Every run makes the harness a little smarter. Every failure is an investment in future reliability.

What's next

The thing I keep coming back to is proof. When a PR lands from case, I want to know exactly what happened: which tests ran, what the reviewer found, what the verifier saw in the browser, what the retrospective learned. Right now, the evidence chain is good. I want it to be airtight. Every marker traceable. Every decision auditable. The kind of paper trail where, six months from now, I can look at any PR and reconstruct the full story of how it got there.

The retrospective is the other piece. It already proposes amendments and maintains per-repo learnings. But the feedback loop between "agent struggled" and "harness got smarter" still has friction. I review every proposed amendment by hand. Some of them are obvious wins. I want the retrospective to get confident enough, and the evidence behind its proposals strong enough, that the obvious ones can land without me.

A few months ago, I was the bottleneck. Now I run ca 1234 and review the PR. The harness manages the agents. The retrospective improves the harness. I steer.

If you're working with AI agents, even one, even sometimes, stop treating the conversation as the interface. Build the environment. Encode your conventions. Enforce mechanically. Let the agents fail, and when they do, ask yourself the only question that matters: what's missing from the harness?

The code writes itself. Your job is to build the system that makes sure it writes itself well.

AIE Europe

Fri, 10 Apr 2026 00:00:00 GMT

import SlidevEmbed from '@/components/SlidevEmbed.astro'; import ImageRow from '@/components/ImageRow.astro';

I spent last week at AIE Europe in London. I gave a talk, co-ran a workshop with Zack Proser, and we did a podcast episode together. Here's what each one was about.

The talk: Building AI Systems that Ship

18 minutes on why agent demos break when they leave controlled environments. Spoiler: it's almost never the model. It's everything around it.

I walked through four failures from building Case — an agent that gamed a test gate by touching an empty file instead of actually running tests, a CLI installer that overwrote a framework-internal file and declared "Integration Complete" while the build was broken, 10,739 lines of auto-generated docs we deleted because the model performed better without them, and a skill that scored negative in evals. Each one pointed at the same lesson: enforce things mechanically, guide with gotcha lists instead of tutorials, and measure whether your context actually helps.

![Nick next to the Building AI Systems that Ship title slide](@/assets/posts/2026_aie_europe_talk_2.JPG)

</ImageRow>

The workshop: Skills at Scale

Zack and I ran an 80-minute hands-on workshop on writing portable AI skills — markdown files that work across Claude Code, Codex, Cursor, and anything else that reads them. The point of a skill is to encode your constraints and your team's judgment so the AI doesn't start every conversation from zero.

We had everyone build a skill called "Repo Roast" that audits a git repo's health. It started vague and by the end of the session people had it citing file counts, finding stale TODOs, running git log for churn hotspots, and scoring its own confidence on each finding. The big concepts were constraints over instructions, inline scripts for evidence, and self-assessment so weak findings get dropped automatically.

The podcast: Scaling DevTools

We also sat down with Scaling DevTools for a podcast episode. We talked about both talks, how we work with AI day to day, and our favorite skills. Mine is Ideation — I use it before almost every non-trivial piece of work now to turn messy brain dumps into structured specs.

We got into Case and harness engineering too — dispatching agents through a pipeline with enforcement gates, the retrospective agent that learns from its own failures, all of it. I wrote about that in detail here if you want the deep dive.

We also talked about how building these systems has changed how we think about our own work. Writing skills and harnesses forces you to articulate stuff that's been implicit in your head for years. It's been kind of a weird way to rediscover what you actually know.

Evolving with the Tools

Fri, 13 Jun 2025 00:00:00 GMT

import Callout from '@/components/Callout.astro';

<Callout title="Want to dive in?"> My Claude configuration | Anthropic's best practices | CLI documentation | Start with /init in any project. </Callout>

"AI is going to replace developers."

I must have heard that phrase a hundred times in the last year. 16 years I've been writing code. Almost two decades of carefully curated vim configurations, meticulously crafted bash scripts, and hard-won muscle memory that lets me navigate codebases like breathing. Now some VC-funded startup was telling me a chatbot could do my job?

But every day brought new demos, new breakthroughs, new colleagues raving about their AI workflows and how much faster they were shipping. The FOMO was real, but so was the fear. What if they were right? What if I was the blacksmith stubbornly insisting that automobiles were just a fad while everyone else was learning to drive?

So I started experimenting. Cautiously and with skepticism.

I was wrong, but not in the way I feared.

From Apprehension to Adoption

I spent weeks fighting the entire concept of AI agents. Not any specific tool, mind you, but the idea itself. These things were supposed to replace me, so why would I help train my replacement? Every demo I watched made me more defensive, every success story felt like a threat to everything I'd spent two decades building.

My journey started small, almost embarrassingly so. I began asking ChatGPT and Claude basic questions like syntax I'd forgotten or best practices for new frameworks I was exploring. Nothing I couldn't have figured out myself with a few minutes on Stack Overflow, but the instant responses were... nice.

Then I started copying and pasting code snippets back and forth. Question in the chat, code snippet back, copy, paste, test, repeat. It worked well enough, but the constant context switching was killing my flow. Jumping between browser and terminal, losing my place, forgetting what I was trying to accomplish in the first place. (I work almost exclusively on open source projects, so I wasn't worried about sharing code with these services.)

When Claude Code launched, I saw it as a simple efficiency gain. No more copy-paste friction, just let it write directly in my terminal. That seemed reasonable enough, a natural evolution of the workflow I'd already adopted.

But then something clicked.

I watched it use rg to search through codebases, just like I would. It ran npm test to verify its changes weren't breaking anything. It created branches with git, checked logs with docker compose, even cleaned up after itself.

It wasn't just writing code. It was using the same tools I use, following the same workflows I follow, making the same kinds of decisions I make when navigating a codebase. The terminal commands flying by weren't some alien syntax; they were exactly what I would have typed, just faster.

🤯

This wasn't a code generator trying to replace me. It was a pair programmer who spoke fluent bash, understood my toolchain, and could keep up with my thought process. That changed everything. I wasn't being replaced, I was being amplified.

Claude Code stuck with me because it met me where I was: on the command line. It didn't ask me to leave vim or learn a new IDE or change my workflow. It enhanced the environment I'd spent years perfecting.

Three things set it apart:

It asks clarifying questions. When I say "refactor this," it asks what success looks like, or at least defines it in a way that I can correct it.
It makes everything a task. It creates a checklist so I can see what it's thinking and then executes it, step-by-step.
It maintains context. I can be in there making changes right along side it. It adopts the changes and continues.

The shift from fear to flow took time. But once I stopped fighting and started collaborating, everything changed.

My Philosophy on AI Tools

Here's what I've learned about working with AI after months of daily use and countless experiments:

You're not cheating, you're adapting. Using AI doesn't make you less of a developer any more than using an IDE makes you less of a programmer. The developers who insist on writing every line by hand are like accountants refusing to use spreadsheets because "real accountants use ledgers."

Clarity beats cleverness every time. The better you communicate intent, the better results you get. Vague instructions produce vague code, while clear specifications produce clear implementations. Think of it like delegating to a brilliant junior developer who has perfect recall but sometimes questionable judgment.

If your experience tells you it can't solve your complex problems and that those who claim clear gains just don't have hard problems to solve, you're wrong. You're just not simplifying your tasks enough or you don't know enough about what success looks like to tell it how to succeed.

Trust but verify remains the golden rule. AI is incredibly capable, but it's not infallible. Let it implement while you architect, let it write while you review, let it explore solutions while you evaluate trade-offs. The relationship works best when you're both playing to your strengths.

Context is everything, and more is almost always better. The more context you provide (project structure, coding standards, business requirements, even team preferences) the better the output becomes. Don't assume it knows your conventions; teach it explicitly.

Stay in the driver's seat, always. You decide what to build and why, you set the standards, you make the judgment calls about architecture and design. AI handles the implementation details while you handle the decisions that require human insight, experience, and wisdom.

How I Use Claude Code

Setting Up for Success

Create a CLAUDE.md File

Run /init in any project. This generates a context file that helps Claude understand your project:

How to build and run the app
How to run tests
Project-specific patterns and practices
Examples of good code (@-reference specific files)

Claude supports three variants:

File	Purpose
`CLAUDE.md`	Project-specific info, checked into version control
`CLAUDE.local.md`	Personal project notes, automatically gitignored
`~/.claude/CLAUDE.md`	Global preferences for how you want to work with Claude

Planning Before Doing

For any substantial task, I start with a plan. Press ⇧-Tab twice to enter Planning Mode. Claude outlines what it wants to do without making changes. This lets you refine the approach before any code gets written.

I keep plans in a plan.md file. The more granular the steps, the better the results. Claude can update the plan as requirements evolve.

Global Configuration

Global Settings

Configure Claude in ~/.claude/settings.json. Most importantly, set up permissions so Claude doesn't ask about routine operations:

{
	"permissions": {
		"allow": [
			"Bash(ls:*)",
			"Read(~/Developer/**)",
			"Bash(git branch:*)",
			"Bash(git switch:*)",
			"Bash(docker compose exec:*)",
			"Bash(grep:*)",
			"Bash(rg:*)"
		]
	}
}

Custom Commands

Add your own slash commands by creating markdown files in ~/.claude/commands/. The filename becomes the command name.

Example /issue command:

Please analyze and fix the GitHub issue: $ARGUMENTS.

1. Use `gh issue view` to get the issue details
2. Understand the problem described
3. Search the codebase for relevant files
4. Implement the necessary changes
5. Write and run tests
6. Ensure code passes linting
7. Create a descriptive commit
8. Push and create a PR

Use it with /issue 123.

Parallel Development with Worktrees

Git worktrees let you work on multiple branches simultaneously. I spin up Claude in different worktrees for parallel tasks:

One worktree for refactoring
Another for new features
A third for documentation

Using tmux, I manage multiple Claude sessions. Each has its own context and its own goals. I implement and review and merge while Claude implements.

Daily Workflow

My typical day has transformed completely since adopting Claude Code. Mornings start with reviewing what needs to be done and creating detailed plans for Claude to execute. Not unlike how I used to plan my own coding sessions, but with a different mindset about who's doing what.

I'll spin up multiple Claude instances for different tasks throughout the day: one might be refactoring a particularly gnarly authentication system while another writes comprehensive test coverage for features I shipped last week. A third might be updating documentation based on recent API changes. While they work, I'm reviewing their output, providing feedback, handling the inevitable merge conflicts, and thinking about the bigger architectural decisions that need human judgment.

The strangest part? I'm coding less but shipping more, and the code quality is often better than what I'd write alone. It turns out that having an tireless assistant who never gets bored of writing tests or updating documentation means those important-but-tedious tasks actually get done instead of being perpetually pushed to "next sprint."

Where I See This Going

We're not being replaced. We're evolving, and the transformation is happening faster than most of us expected.

Near term (happening now): Developers are becoming orchestrators rather than implementers, with AI handling the boilerplate and repetitive tasks that used to consume hours of our day. We're focusing more on architecture, design, and the human elements of software development: understanding user needs, making trade-offs, navigating organizational dynamics.

Medium term (1-2 years): I expect to see AI agents collaborating with each other, forming virtual development teams that we guide and manage. Natural language will become the primary programming interface for many tasks. Not because code is going away, but because expressing intent in human terms is often clearer than wrestling with syntax.

Long term (2-3 years): AI will likely understand business requirements directly from stakeholders, prototype solutions, and handle much of what we consider "development" today. Our role shifts to being quality gatekeepers, system designers, and the bridge between human needs and machine capabilities. We'll be the ones ensuring that what gets built actually solves real problems for real people.

The developers who thrive in this new world won't necessarily be the fastest typists or the cleverest algorithm designers. They'll be the best communicators, the clearest thinkers, the most empathetic problem solvers. They'll be the ones who learned to leverage these tools rather than compete with them.

Getting Started

If you're ready to try this yourself, start small. Pick one feature, one bug fix, or one refactor that's been sitting in your backlog. Write out a clear plan of what you want to accomplish, let Claude execute it, then carefully review the results. That feeling of discomfort you'll inevitably experience? That's not a bug, it's a feature. It's the feeling of growth, of your mental model expanding to accommodate new ways of working.

You might feel like you're cheating at first, like you're not a "real" developer anymore because you're not typing every character. Push through that feeling. You're not being replaced; you're being amplified. You're focusing on the parts of development that actually require human creativity and judgment.

Learn From Others

The Claude Code and general AI tooling community is growing rapidly, and there's tremendous value in seeing how others structure their workflows and contexts. Search GitHub for .claude/CLAUDE.md files to discover different approaches to project configuration, or watch streams and videos to see how other developers are pushing the boundaries of what's possible with AI-assisted development.

My own configuration is in my dotfiles repo if you want to see how I've set things up. Don't just copy blindly though. The beauty of this tool is that it adapts to your workflow, not the other way around.

References

Thanks to John Christopher for reviewing this post.

2023 Review

Thu, 04 Jan 2024 00:00:00 GMT

Better late than never, right? 2023 was a big year in a lot of ways and has really geared me up for a fresh and exciting 2024! Here's what happened, what I accomplished, and what I'm looking forward to going into 2024.

Accomplishments

Celebrated 10 years of marriage. We got married on our 5th anniversary of dating, so we also celebrated 15 years together. We celebrated with a trip to Vegas
I visited the C2FO offices in India. It was an amazing trip which included a trip to the Taj Mahal and attending my first cricket match!
I attended the Problem-Solving Leadership workshop in Albuquerque, NM taught by Esther Derby and Don Gray. This was life-changing and I highly recommend it to everyone.
I spoke at KCDC on XState. I can't recommend this conference enough!
Celebrated 5 years of being on the JS Party podcast. Here's to many more!
I took my family to DisneyWorld. The kids absoutely loved it (and so did I).

What's coming in 2024?

I'm starting the year off big by leaving my current job for a new opportunity (more soon) and I'm speaking at THAT Conference in Austin at the end of January. I'm also looking forward to more adventures with the family and growing a side-project, Dev Dilemmas, with John Christopher where we're focused on content, courses, and consulting.

2024 Review - A Year of Growth and Change

Tue, 31 Dec 2024 00:00:00 GMT

2024 was a year of significant transitions and growth, marked by new adventures at Meta, a return to in-person conferences, and ultimately, a exciting new role at WorkOS. Looking back, it's amazing how much can change in just twelve months.

The Meta Chapter

My time at Meta was intense and educational. Working on one of the world's largest React applications taught me invaluable lessons about scale and complexity. While I ultimately decided to move on (more on that here), the experience of collaborating across offices in Menlo Park, London, and New York shaped my perspective on building global products. I spent over a month in Menlo Park alone, immersing myself in the Silicon Valley tech culture and working alongside incredibly talented engineers.

Embracing the Conference Circuit

2024 marked my return to active conference participation, both as a speaker and organizer. I had the privilege of sharing knowledge through two talks:

Componentizing Application State at THAT Conference in Austin, exploring patterns for managing complex application state
Unleashing the TypeScript Compiler at both KCDC and THAT Conference Wisconsin Dells, diving deep into TypeScript's capabilities

A personal highlight was emceeing the inaugural Squiggle Conf in Boston. I also had the unique opportunity to organize an internal UI conference at Meta and interview inspiring speakers at React Summit in New York.

Growing the Nebraska Tech Community

NebraskaJS has found its post-pandemic rhythm, and I'm proud of how we've adapted. We've maintained consistent meetups, attracted engaging speakers, and are expanding back to Lincoln in 2025. The launch of our Discord server and our new Astro-powered website represent our commitment to building a modern, accessible community. You can now also find us on Bluesky at @nebraskajs.dev.

Finding a New Social Home

Speaking of Bluesky, it's become my primary social platform in 2024. The community there feels more aligned with my interests, and I've even integrated Bluesky comments and likes into this blog. While Twitter's future remains uncertain, I've found a new space for meaningful tech discussions.

A Year in Motion

2024 kept me moving, with trips spanning work, conferences, and family time:

Multiple extended stays in Menlo Park
Conference speaking in Austin, Kansas City, and Wisconsin Dells
Meta office visits in London and New York
Family time in Branson, MO and Minneapolis
Tech community events in Boston and New York

New Horizons

As 2024 draws to a close, I'm thrilled to begin a new chapter as a Developer Experience Engineer at WorkOS. The role promises to combine my passion for developer tooling with the opportunity to work with a talented team that impressed me from day one.

Looking ahead to 2025, I'm excited to build on these experiences and continue growing both professionally and personally. The tech landscape is ever-changing, and I'm ready for the next adventure.

tmux for Presentations

Mon, 02 Nov 2015 00:00:00 GMT

import Video from '@/components/Video.astro';

Live coding is stressful. You're often worried about making a mistake while doing it, and it seems you're set up for failure if you're trying to focus on what is being displayed on the projector while doing so. Fortunately, tmux makes it incredibly simple to attach to the same session and display one on the projector while keeping one on your local display to work around this awkwardness!

When attached to the same session, tmux will automatically resize the larger client's window to the size of the smaller client. With this in mind, make sure that the smaller client is the one displayed on the projector, or you will end up with a border around the screen. Typically, I will set the client on my local display to full screen mode to ensure that is is the larger or the two clients.

With this set up, you can simply work in either client and the changes will immediately be seen in the other! No more looking over your shoulder!

`aggressive-resize`

We want to turn on aggressive-resize so that it only constrains the size of the tmux client to the size of the smaller client if both clients are looking at the same window. This setting isn't necessary for this to work, but I would still recommend it.

setw -g aggressive-resize on

Neovim

Mon, 19 Oct 2015 00:00:00 GMT

import Video from '@/components/Video.astro';

Recently, I've been using neovim as a full-time replacement for vim in my daily workflow. It was ridiculously easy to get started, and so far I am really enjoying the benefits it has. The main benefit is that its plugins can run asynchronously, which is awesome. This means that when Neomake (the neovim version of Syntastic) runs JSHint or JSCS against my file, it doesn't completely freeze nvim while doing so. This is awesome!

To get started with Neovim, you can simply install it from homebrew on OSX:

brew tap neovim/neovim
brew install --HEAD neovim

You can also install it on other operating systems, such as Ubuntu:

sudo add-apt-repository ppa:neovim-ppa/unstable
sudo apt-get update
sudo apt-get install neovim

When getting started, you can simply symlink your ~/.vimrc to ~/.nvimrc and your ~./vim to ~/.nvim and things should just work. However, I ended up going the route of having configurations for vim and nvim so that I could easily go back to vim if I encountered any issues while using it in my day job.

I recently gave a lightning talk on Neovim at the Omaha Ruby and Open Source Meetup. Check out the slides and video from the talk below if you'd like to learn more. Also, please ask me questions on Twitter!

Video

Slides

</script>

vim + tmux - OMG!Code

Wed, 25 Feb 2015 00:00:00 GMT

import Video from '@/components/Video.astro';

I love vim. I've been using it full-time for over three years and I still feel like a beginner at it. But I also feel productive in it. I had an opportunity to talk about vim and how I use it in tmux at February's OMG!Code. In this talk, I introduce some vim basics, talk about the best parts of vim, some of my favorite plugins, and then I integrate tmux into the talk and how I typically work with these two technologies throughout the day. It wraps up with a nice discussion of different plugins and configurations.

Repo

This repo contains the slides and a default vim and tmux configuration, which I slimmed down from my full config to the settings and plugins which I think are essential for being productive quickly with vim and tmux.

Slides

Video

The Dojo Toolkit - NebraskaJS Lincoln

Sun, 18 Jan 2015 00:00:00 GMT

import Video from '@/components/Video.astro';

I gave a lightning talk on the Dojo Toolkit at NebraskaJS Lincoln on January 15, 2015. In this talk, I gave a very brief overview of the Dojo Toolkit.

References:

NEJS Conf - We're hosting a conference!

Mon, 16 Feb 2015 00:00:00 GMT

We're hosting a conference! NEJS Conf will take place August 7th at the Henry Doorly Zoo in Omaha, and it sure to be an interesting, exciting, and wild time! We're just getting started, but definitely check out the site, sign up for the mailing list, follow us on Twitter and keep a look out for the call for speakers!

Frontend testing - Omaha Coffee & Code presentation

Mon, 05 Jan 2015 00:00:00 GMT

import Video from '@/components/Video.astro';

This is a talk on frontend unit and functional tests, using the Intern testing framework, presented at Omaha Coffee & Code.

Video

References

Update: 2015-01-11

I also gave a short lightning talk at the Omaha Ruby & Open Source Meetup, showing more examples of Intern usage.

Leapcopter

Sun, 05 Jan 2014 00:00:00 GMT

import Video from '@/components/Video.astro';

I finally purchased a Parrot AR Drone 2.0 this week after having a blast playing with one at JSConf last year! I also recently got a Leap Motion controller, and I thought it would be fun to get them to play together!

Source available on Github.

The leapjs code was a bit buggy, especially when trying to use it from Node, so I am interacting with the Leap Motion exclusively in Chrome and then using socket.io to send commands up to the server, which is controlling the drone.

On the server, I am using node-ar-drone to control the drone, and ar-drone-png-stream to get the video feed from the drone in the browser.

Here is a list of gestures and the what action they invoke:

Key Tap - toggle the drown (takeoff/land)
Circle - make the drone do a flip
Tilt Palm Down - make the drone go forward
Tilt Palm Up - make the drone go backwards

The drone moves very slowly, as I didn't trust a Leap-controlled drone to go flying fast in my house quite yet. Also, once 'Land' is triggered, the drone won't take off again, just in case I panic and start flailing about in front of the sensor.

My future plans for this demo include to cleaning up the code (it's a mess right now), and adding more gestures (turning, up/down).

Nick Nisi

Git Workshop

History

Prerequesites

Overview

Introducing hub

Installing hub

hub Commands

Activity: Using hub

Finding bugs with git bisect

Activity: Where did that bug come from?

Automating bisect

Configuring git

Advanced aliases

Reuse recorded resolution: rerere

Git hooks

Activity: Adding a commit-hook

Managing git hooks

Interactive rebase

Activity: Clean the history

Learning more

Git: Update a forked repository

Syncing a fork

But that's so many steps...

Git Your Way: includeIf

The Problem

The Solution

How I Use It

Git: Managing hooks

Setting up the hooks

Managing git hooks

Lint JavaScript on Commit

Very Important Agents

Keeping Code Clean with Essentials

From Brain Dump to Structure with Ideation

AI as Amplifier, Not Replacement

Try It Yourself

Writing My First Evals

Does the agent do the right thing?

Fixtures as starting states

The agent runs for real

Grading: the part I got wrong at first

Not pass/fail, pass rates

Does the context actually help?

A/B testing for LLMs

The skill that hurt

Detecting things that aren't real

Same question, different angle

The eval can be wrong too

Building trust with a system you built with AI

What I'd tell you if you're starting from zero

Trust is a measurement

Speaking at Conferences

Write a compelling abstract

Be specific

Outline the objectives

Don't fear rejection

Tell a story

Telling a great story

The Tech Talk Story Circle

Example: The Story Circle in Action

Remember, you're an entertainer

If showing code, make sure it's readable

Make it easy to follow up

Conclusion

Seven Years of JS Party: A Personal Reflection

The State of Change

More Than Just a Tech Podcast

Lessons Learned

Community Impact

Personal Growth

The Road Ahead

JS Party Will Be in NYC at React Summit!

On Leaving Meta

Taking the Leap

The Meta Way

The Reality of Scale

Finding Connection

The Balancing Act

Time for Change

Finding bugs with `git bisect`

The output of `git branch` is pretty useless