koshka-oriented shell

0.1.0 has been released! See the Release Blog Post.

The project was renamed in 0.2.0. The shit is now kosh, shitbox is koshkit, and every prefix is changed to kosh or KOSH_. I got over the funny name. Thanks.

---

Koshka is the Russian word for a cat.

Koshka is an interpreter, interactive shell, formatter and a language server, with first tier support for Windows, Linux and macOS, fully compatible with Bash 5.3 and Dash.

Koshka contains ~300 built-in shellcheck diagnostics. It is usually 5x faster than bash, or ~100x+ faster than shellcheck, which makes it exceptionally friendly to coding agents or strict environments where Bash is still used.

What

kosh is the koshka's binary.

Koshka aims to be a complete, faster and portable Shellcheck and Bash replacement. The shell guarantees first tier support for Linux, macOS and Windows, preserving equivalent behavior on either of these systems.

The shell is designed to work without absolutely no config whatsoever. Koshka's Linux binary is static and it does not use C++'s STL. Koshka also can work without coreutils, using it's own utilities.

The project is in early stage. There's no guarantee that it will not blow your computer up. Bug reports are greatly appreciated.

Three shells in a trenchcoat

See the manual page for a fuller explanation:

$ man docs/kosh.1

Koshka runs in four modes, called moods, across three shell identities. ZSH has similar idea behind it's emulate builtin.

The default kosh mood is a strict superset of Bash with analysis and optimization enabled. The other moods are bash, bash-posix, and sh. The bash-posix mood provides Bash behavior with its POSIX mode enabled.

Before it runs a command, Koshka analyzes and optimizes the complete script. The catalog includes about 100 checks derived from ShellCheck and about a dozen native analysis checks.

kosh --lint behaves like shellcheck, but several magnitudes faster.

kosh --format formats the code. There's no customization as of now.

kosh --language-server launches language server on stdin.

The --mood option, or -M, selects kosh, bash, bash-posix, or sh. The default is kosh. A binary symlinked as sh, dash, or bash selects the matching mood and disables diagnostics. set --mood changes the mood at runtime. In the default mood, -W retains the default severities, -WW demotes lenient errors to warnings, and -WWW also demotes strict errors. In other moods, -W enables strict warnings, -WW also enables lenient warnings, and -WWW also enables annoying warnings.

The -I option enables mimicry. Koshka detects sh, dash, and bash shebangs and runs each script in the matching mood. The current diagnostics setting is preserved.

The --init-moods option, or -L, accepts a comma-separated list of moods whose startup files will be used. Its default value is the selected mood.

The KOSH_FLAGS environment variable specifies default flags. A flag on the command line still wins.

When KOSH_FLAGS or the command line contains an invalid flag or argument, a login shell skips its startup files and opens a rescue session.

Additional furballs

The interactive mode is inspired by fish. Shell provides syntax highlighting, word movement, editing controls, UTF-8 support, display-width handling for wide characters, multiline editing, history search, and persistent history. kosh does not depend on readline, so it's config is not used.

Koshka has more than 50 builtins, and each builtin supports --help. These include Bash and POSIX builtins. The additional builtins include the following commands.

• z is a port of zoxide.
• bench provides built-in benchmark infrastructure inspired by Performance Optimizer Observation Platform (poop).
• assimilate provides transactional installation on an SSH target.

The koshkit builtin bundles a BusyBox-style set of small core utilities.

• File utilities include cp, mv, ln, and rm.
• Search utilities include find and grep.
• Process utilities include killall, pkill, ps, timeout, and nproc.
• Minimal implementations of calc and make are included.

koshkit cat --syntax-highlighting colors shell files when standard output is a terminal. Shell extensions and known shell shebangs select the source. The output omits underline attributes.

Development

This software began as a late April Fools' joke. It is written from scratch in a macro-heavy C++23 dialect and is compiled with -nostdlib++. The executable links only to the C library.

Development occurs on staging, and the branch may be broken. The master branch should pass all tests.

Prerequisites

A native build needs the following tools.

• Install GNU Make, Clang 18 or later with C++23 support, libc development files, and headers for the target platform. Linux builds also need Linux kernel headers.
• The default debug build needs the AddressSanitizer and UndefinedBehaviorSanitizer runtimes from compiler-rt.
• The test suite needs Bash 5.3, Dash, and Python 3.
• The build and test scripts need mkdir, rm, cp, and printf from the host.
• The full test suite needs cat, cmp, diff, find, grep, head, sed, and strings. Interactive tests also need script and stty. Process supervision needs setsid or Perl.

A complete Alpine setup can be installed with the following package set.

apk add --no-cache \
  git git-doc make build-base musl-dev linux-headers clang llvm lld \
  compiler-rt bash dash zsh yash busybox coreutils mandoc python3

The benchmark needs Bash, Dash, and Python 3. Zsh, Yash, and BusyBox ash provide optional comparison rows. The coverage report needs llvm-profdata and llvm-cov from the matching LLVM installation. Documentation checks use mandoc. Formatting and static checks use clang-format and clang-tidy from Clang 18 or later.

Each cross-compilation target needs its matching toolchain. Zig builds the Zig targets and cross-compiles release binaries to Linux. MinGW-w64 targets Windows, osxcross with a macOS SDK targets Darwin arm64, and cosmoc++ builds the Cosmopolitan modes.

The MODE variable controls the build type.

• rel is an optimized build.
• prof is an optimized build with debug symbols for profiling.
• cov is an optimized build with debug symbols for collecting coverage.
• dbg includes all symbols, AddressSanitizer, and UndefinedBehaviorSanitizer.
• cosmo is an optimized build that uses cosmoc++ from the Cosmopolitan toolchain.
• cosmo_dbg is a debug Cosmopolitan build.

TARGET defaults to the host platform and accepts Linux, Windows_NT, or Darwin. A non-Windows host cross-compiles TARGET=Windows_NT with MinGW. A non-Darwin host cross-compiles TARGET=Darwin ARCH=arm64 with osxcross. Linux is a native target.

The $CXXFLAGS environment variable appends flags to the build commands.

Build with GNU Make as shown below. Make uses every available logical CPU and shares its bounded job pool with recursive builds.

$ make MODE=<rel/prof/dbg/cov/cosmo/cosmo_dbg>
$ make MODE=rel TARGET=Windows_NT
$ make MODE=rel TARGET=Darwin ARCH=arm64
$ ./kosh --help

Zig can also build the dbg and rel modes.

$ zig build --release=fast
$ ./zig-out/bin/kosh --help

Install or uninstall the selected build with the following commands.

$ export PREFIX=/usr/local
$ make install
$ make uninstall

The running binary can install itself on an SSH target with assimilate user@host.

Roadmap

Is it usable?

• Programs run.
• Linux and Windows are supported.
• Logical sequences are supported with &&, ||, and ;.
• Pipes are supported.
• Redirections are supported with > and <.
• Shell expansions are supported with ?, [...], *, and ~.
• Escapes are supported.
• Environment variables are supported.
• Numeric expressions are supported.

Is it good?

• Background jobs are supported.
• Scripting constructs include flow-control keywords.
• Blocks and functions are supported.
• The shell supports sh scripts.

Is it exceptional?

• The shell supports Bash scripts.
• ShellCheck-style warnings are built in.
• Koshkit replaces common Unix programs that are absent from Windows.
• Arbitrary-precision numeric expressions are planned.