typewritten: a zsh prompt theme that keeps git info off the critical path

Asynchronous git info is the reason this theme exists

typewritten is described as a minimal, lightweight, informative zsh prompt theme, and the feature list leads with one item: asynchronous git information. That single line is the whole design argument, and it is worth being precise about what it means.

A conventional prompt that shows the current branch and working tree state has to run git when it draws, and git on a large repository can take long enough to be felt. The repository layout shows two files, an async directory and async.zsh, plus a lib directory and a scripts directory, which is what an asynchronous implementation of that idea looks like in practice: the git information is obtained outside the drawing path and the prompt picks it up when it is available.

For a person who lives in the shell, that difference between a prompt that appears instantly and one that hesitates is the difference between a tool you keep and one you turn off. It is a small, specific bet, and the project is built around it rather than around visual novelty.

The rest of the feature list is configuration. Colours for any of the prompt sections, prompt layout, prompt symbol, constant display of the git home directory, cursor, and a prefix on the right prompt. The topics recorded for the repository mention async, git, minimal, prompt, shell, terminal, theme and zsh, which is an honest summary of a small, focused shell project.

Three install paths, and only one of them touches your .zshrc for you

The quick start offers npm, Homebrew and a manual clone. The npm route is a single global install:

npm install -g typewritten

The project's description of what follows is worth reading closely: the script will make the necessary symlinks to fpath and set the prompt in your .zshrc. The npm package is therefore a wrapper that edits your shell configuration for you, not just a copy of some files.

The Homebrew route installs the same thing through a package manager, and then leaves the loading to you:

brew install typewritten

The manual route clones the repository into a directory of your choosing, and the project's recommendation is to create a .zsh directory at root:

mkdir -p "$HOME/.zsh"
git clone https://github.com/reobin/typewritten.git "$HOME/.zsh/typewritten"

The Homebrew and manual routes behave identically once the files exist, because in both cases the theme is loaded by adding it to fpath and letting zsh's promptinit find it. Only the npm path automates that step, and it does so by running a script at install time, which is worth knowing if you prefer to keep your .zshrc under version control and review every line that touches it.

The loading contract: fpath, promptinit, prompt typewritten

Once the files are in place, loading typewritten is a three line zsh idiom. The manual instructions add the clone directory to fpath and then run the standard prompt init sequence:

fpath+=$HOME/.zsh/typewritten
autoload -U promptinit; promptinit
prompt typewritten

Each part does a specific job. The fpath line tells zsh where to look for prompt functions, which is how the theme file is found. The promptinit line loads zsh's built-in function mechanism and runs it, which populates the list of available prompts. The final line selects typewritten as the active prompt, and it is the line that is normally put in your .zshrc, since promptinit only needs to run once per shell session.

The Homebrew instructions use the same two final lines without the fpath assignment, because the package manager has already placed the files where zsh can find them.

One conflict is called out explicitly. If you use oh-my-zsh, set ZSH_THEME="" in your .zshrc to disable oh-my-zsh themes, since two systems setting the prompt will fight over it. This is the kind of detail that gets left out of most theme documentation and costs a newcomer an afternoon.

The repository also ships typewritten.plugin.zsh alongside typewritten.zsh and typewritten.zsh-theme, so the project can be loaded as a plugin as well as a theme, depending on the plugin manager in use.

Documentation lives on a site, not in the README

The project is explicit about this choice. To keep the readme file as lean as possible, the documentation was moved to https://typewritten.dev, and the customization details are split into two parts: prompt customization for everything to do with how and where information is displayed, and prompt color customization for setting a custom colour for any of the prompt sections.

The README carries configuration examples as images rather than as text, showing three customised typewritten prompts. That is a reasonable choice for a visual tool, and it has a cost: the exact variable names behind each visible element are not in the repository's README, so if the site is unreachable or you are working from a vendored copy, there is no fallback documentation in the source tree.

The individual feature links go deeper than a general customisation page, with anchors for prompt color customization, prompt layout, prompt symbol, git relative path, cursor and the right prompt prefix. The constant display of the git home directory feature, with its own anchor, is the one that changes what the prompt shows rather than how it looks, which is the setting to reach for if your repositories live under deep paths and you want the home directory visible rather than inferred.

The site also has an installation page listing many other ways to install typewritten, and the repository points to a discussion thread for reproducing the exact look of the demo, which is where the terminal, font and colour scheme choices are described.

The npm package is a script wrapper around four shell files

The package.json describes a much smaller thing than the theme itself. The name is typewritten, the version is 1.5.2, the licence is MIT, and the files array lists only four entries:

  "files": [
    "typewritten.zsh",
    "async.zsh",
    "lib",
    "scripts"
  ],

Everything else in the repository, the docs directory, the tests, the async directory and the plugin file, is development files rather than shipped payload. The four published items are the theme, the async implementation, the library of functions and the install scripts.

Those scripts are wired into npm's lifecycle hooks:

    "test": "zsh tests/smoke.zsh",
    "lint:shell": "zsh -n scripts/install.sh scripts/uninstall.sh",
    "postinstall": "./scripts/install.sh",
    "postuninstall": "./scripts/uninstall.sh"

The postinstall hook is the mechanism behind the promise that npm install will set up fpath and the prompt. The matching postuninstall hook means npm uninstall runs a cleanup script, and the lint:shell entry shows the scripts are syntax checked with zsh -n, which catches parse errors without executing them. The test entry runs a smoke test through zsh as well.

The autoload -U promptinit; promptinit idiom means a fresh shell has to run promptinit before the prompt line will find the theme, and a postinstall script that edits .zshrc does not by itself guarantee that ordering in a file that already had content. The manual route avoids the question entirely, and the README's note about disabling oh-my-zsh themes points at the same area of friction.

Where typewritten stops being the right tool

The scope is narrow and the boundaries are easy to state. This is a zsh theme. It is not a shell agnostic prompt, and there is no bash or fish implementation in the repository, so anyone on another shell gets nothing here.

It is also the wrong choice if you want your prompt configuration to live in your own shell files. The customisation model is variables set inside the theme, documented on a website, so you are adopting the theme's configuration surface rather than assembling your own. That is a reasonable trade for a theme that is meant to look a certain way, and a poor one for a user who already has a prompt they like and wants to add git state to it.

If you work in a shell where every millisecond of prompt latency is visible, you will want to check the async implementation against your own repositories before committing to it, since the repository documents the mechanism but does not publish latency figures for it. The README does not document a fallback to synchronous git information either, so if the async path fails on a given machine the behaviour is not specified in the project.

Finally, for anyone who needs the theme to be maintained against new git versions or new zsh releases, the release history is the deciding evidence. The most recent published release is v1.5.2 from 2024-08-20, preceded by v1.5.1 in January 2023 and v1.5.0 in October 2022, and the last push to the repository was on 2026-05-13. The theme is not archived, and work is landing, but the shipped version has not moved since 2024, so a new user is installing code that predates most of the recent commits.

Editorial conclusion

typewritten suits people on zsh who want a two line prompt with git state that never stalls the shell, and who are happy to read configuration on a documentation site rather than in a README. It is the wrong tool for bash or fish users, for anyone who needs theme configuration delivered as shell variables they can read at a glance, and for teams that want a prompt with a predictable release train. Verify first that the version npm installs matches the 1.5.2 recorded in package.json, that your terminal renders the symbols the theme uses, and that the async directory in the repository is what your shell actually loads.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. reobin/typewritten on GitHub