โโโโโโโ โโโโโโโ โโโโ โโโ โโโโโโโโโโ โโโ
โโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโ โโโ
โโโ โโโ โโโโโโโโโ โโโโโโ โโโโโโโโ
โโโ โโโ โโโโโโโโโโโโโโโโ โโโโโโโโ
โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโ โโโ
โโโโโโโ โโโโโโโ โโโ โโโโโ โโโโโโโโโโ โโโ
A cyberpunk-inspired Unix shell written in C with a retro-futuristic terminal aesthetic.
Conch is a learning project in systems programming. It is an interactive
command shell, not a POSIX sh: it runs programs, single pipes, simple
redirects and basic job control, but it has no scripting language (see
Limitations).
- External Commands - Runs any program on
PATHviafork()/execvp() - Built-in Commands -
cd,help,exit,clear,status,jobs,fg,bg,export - I/O Redirection - Output (
>,>>), input (<) and stderr (2>), one redirect per command - Piping - A single pipe between two commands (
cmd1 | cmd2) - Quote Handling - A word that starts with
"or'runs to the matching quote, so it can contain spaces - Job Control - Background processes with
&, plusjobs,fg,bgand Ctrl+Z for simple (non-pipeline) commands - Environment Variables -
$VAR/${VAR}expansion andexport
- Command History - 100-entry in-memory circular buffer with Up/Down arrow navigation (not saved between sessions)
- Tab Completion - Completes command names from a built-in list of common commands and executables on
PATH - Raw Input Mode - Character-by-character input; Backspace is the only editing key (no Left/Right cursor movement)
- Cyberpunk Aesthetic - Custom ANSI color scheme and boot sequence
- Modular Architecture - 9 source modules with matching headers
- Leak-Checked - The test suite runs clean under
valgrind --leak-check=full(see Memory Checking) - Error Messages - Failures are reported with a
conch:prefix and the shell keeps running - Build System - Makefile with release, debug, test, memcheck and analysis targets
- Containerized - Docker image with the toolchain, valgrind and cppcheck
conch/
โโโ src/ # Source files
โ โโโ main.c # Entry point, REPL and raw-mode line reader
โ โโโ prompt.c # Terminal prompt and boot sequence
โ โโโ parser.c # Variable expansion and tokenization
โ โโโ executor.c # Command execution and redirection
โ โโโ builtins.c # Built-in command implementations
โ โโโ pipe.c # Pipe handling
โ โโโ history.c # Command history management
โ โโโ completion.c # Tab completion engine
โ โโโ jobs.c # Job control and background processes
โโโ include/ # Header files (common.h + one per module)
โโโ tests/
โ โโโ run_tests.sh # Test suite (pipes, redirects, builtins)
โโโ build/ # Build artifacts (generated)
โโโ bin/ # Compiled binaries (generated)
โโโ Makefile # Build system
โโโ Dockerfile # Container definition
โโโ docker-compose.yml # Container orchestration
โโโ README.md # This file
- GCC or Clang compiler
- GNU Make
- Linux or macOS
- Perl and Bash (for the test suite only); valgrind for
make memcheck(Linux only)
# Clone the repository
git clone https://github.com/newwavejacob-web/Solaris-Shell.git conch
cd conch
# Build the shell
make
# Run it
./bin/conch
# Or build and run in one command
make run# Install to /usr/local/bin (requires sudo)
make install
# Now you can run it from anywhere
conch
# To uninstall
make uninstall| Command | Description |
|---|---|
make or make all |
Build optimized release version |
make debug |
Build with debug symbols and no optimization |
make clean |
Remove all build artifacts |
make run |
Build and immediately run the shell |
make test |
Run the test suite against the release build |
make memcheck |
Run the test suite under valgrind (Linux) |
make memcheck-interactive |
Run the shell interactively under valgrind |
make install |
Install to /usr/local/bin |
make uninstall |
Remove from system |
make check |
Run static analysis with cppcheck |
make format |
Format code with clang-format |
make stats |
Display code statistics |
make help |
Show all available targets |
# Build the Docker image
make docker-build
# Run the shell in a container
make docker-run
# Run the tests / leak check inside the container
docker run --rm --entrypoint make conch-shell test
docker run --rm --entrypoint make conch-shell memcheckWith Docker Compose, start an interactive shell with the ./workspace
directory mounted:
docker compose run --rm conch-shellThe image is based on gcc:latest and includes valgrind, cppcheck and
clang-format.
cd /path/to/directory
cd # Go to $HOME
cd .. # Go up one level
help # List builtins and syntax
status # Show version and current directory
clear # Clear screen and show boot sequence
exit # Exit the shell (Ctrl+D on an empty line also exits)
export VAR=value # Set an environment variable
export # List the environment
jobs # List background jobs
fg %1 # Bring job 1 to the foreground
bg %1 # Resume stopped job 1 in the backgroundRedirect operators must be separate words (> out.txt, not >out.txt).
echo "Hello, World!" > output.txt # overwrite
echo "Another line" >> output.txt # append
sort < unsorted.txt # input
ls missing 2> errors.txt # stderrls -la | grep ".txt"
cat file.txt | sortOnly one | per command line is supported.
- Up Arrow - Previous command
- Down Arrow - Next command
- Up to 100 commands, kept in memory for the current session
- Consecutive duplicate commands are stored once
- Press Tab to complete a command name (from a list of common commands
and executables on
PATH) - A single match replaces the line; multiple matches are listed (up to 20)
- Completion matches against the whole line, so it only helps while typing the first word
echo "Hello World"
cd "My Documents"
cat 'file with spaces.txt'sleep 100 & # Run in background
jobs # List jobs
fg %1 # Bring job 1 to the foreground
bg %1 # Resume stopped job 1 in the background
# Ctrl+Z suspends the foreground jobexport MY_VAR=hello
echo $MY_VAR ${MY_VAR}Conch is not POSIX-compliant. Notably, it does not support:
- Command lists and conditionals:
;,&&,|| - More than one pipe (
a | b | c), or redirects inside a pipeline - More than one redirect per command (
cmd < in > outignores> out) - Arguments after a redirect (
sort < file -rdrops-r) - Redirects without surrounding spaces (
>file) - Single quotes suppressing expansion (
'$HOME'is expanded) - Joining adjacent quoted text (
foo"bar"stays two pieces) - Backslash escapes, globbing (
*.txt),~expansion,$?, subshells, here-documents, aliases, scripts or control flow - Background pipelines (
a | b &runs in the foreground)
Each of the first group is covered by an expected-failure (XFAIL) test in
tests/run_tests.sh, which reports XPASS once it starts working.
Known issues found while auditing (not yet fixed):
- Recalling a history entry longer than 1024 characters with the Up arrow
overflows the line buffer (
strcpyinsrc/main.c). - When stdout is not a terminal, the echoed command line can be flushed after the command's own output.
make checkreports two cppcheck errors:reallocfailure paths inexpand_variables(src/parser.c) leak the old buffer.
make testtests/run_tests.sh feeds scripts to bin/conch on stdin and checks the
files and output they produce. It covers external commands, quoting,
variable expansion, every redirect operator, pipes, and every builtin.
Interactive-only features (arrow-key history, Tab completion, Ctrl+C/Ctrl+Z)
need a real terminal and are not covered.
Current result on macOS (Apple clang 17, arm64) and Linux (Debian, gcc:latest, arm64):
passed: 29 failed: 0 xfail: 9 xpass: 0
make memcheck # Linux; on macOS use the Docker command below
docker run --rm --entrypoint make conch-shell memcheckThis runs the whole test suite (all 38 cases, including the expected-failure ones) with each shell session under:
valgrind --leak-check=full --show-leak-kinds=all \
--errors-for-leak-kinds=definite,indirect,possible \
--child-silent-after-fork=yes --error-exitcode=99
and fails if any session reports an error or a leak. Last result
(valgrind 3.24.0, Debian, arm64): every session ends with
All heap blocks were freed -- no leaks are possible and
ERROR SUMMARY: 0 errors.
The check only covers the code paths the suite exercises; the interactive
line editor, history recall and Tab completion are not run under valgrind.
--child-silent-after-fork means forked children (which immediately exec
or exit) are not checked.
make debug
gdb ./bin/conchmake checkRequires cppcheck. See Known issues for its current findings.
The color palette is defined in include/common.h:
#define GREEN "\033[32m"
#define BRIGHT_GREEN "\033[1;32m"
#define YELLOW "\033[33m"
#define CYAN "\033[36m"
#define RESET "\033[0m"
#define BOLD "\033[1m"The prompt shows: [TIME] DIRECTORY CONCH>
Customize the boot sequence, prompt format and colors in src/prompt.c.
Adjust the history buffer size in include/history.h:
#define HISTORY_SIZE 100 // Change to your preference- Main - REPL loop, raw-mode line reader
- Prompt - UI and boot sequence
- Parser - Variable expansion and tokenization
- Executor - Process launch and I/O redirection
- Builtins - Internal command implementations
- Pipe - Two-command pipelines
- History - Command history buffer
- Completion - Tab completion logic
- Jobs - Job table, signal handling and terminal control
- Processes:
fork(),execvp(),waitpid(),setpgid(),kill() - I/O:
pipe(),dup2(),open(),close(),read() - Terminal Control:
termiosraw mode,tcsetpgrp() - Signals:
sigaction()SIGCHLD handler for background jobs
- Startup: about 0.5s, almost all of it a deliberate 0.5s pause in the boot sequence (
usleepinsrc/prompt.c) - Memory: about 1.6 MB maximum resident set size (
/usr/bin/time -l, macOS arm64) - History: O(1) lookup by index in a circular buffer
- Completion: Scans the
PATHdirectories on every Tab press (no caching)
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Format code (
make format) - Run the tests (
make test, andmake memcheckon Linux) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow the existing style
- Comment complex logic
- Keep functions under 50 lines when possible
- Use meaningful variable names
SOLARIS
Created with the ethos: "we do it because we are driven."
- Inspired by classic Unix shells (bash, zsh, sh)
- Cyberpunk aesthetic influenced by sci-fi terminals
- Built as a learning exercise in systems programming
make statsCurrent codebase:
- ~1,800 lines of C (source and headers)
- 9 modules, 9 header files
- No third-party libraries (libc only)
- Job control (background processes with
&) - Environment variable expansion (
$VAR) - Multiple pipes and redirects in pipelines
-
;,&&and|| - Alias support
- Script execution mode
- Configuration file (~/.conchrc)
- Plugin system
- Syntax highlighting
- Multi-line command editing
- Reverse-i-search (Ctrl+R)
- Customizable keybindings
Having issues? Found a bug?
- Open an Issue
- Check existing issues first
- Provide system info and steps to reproduce
Built with โก by developers, for developers.
Enter the terminal. Become driven.