Build Your Own POSIX Shell in Python — a working bash-like shell from scratch

A single-file POSIX-compatible shell implemented in pure Python. It parses quoted words, runs external programs, supports pipelines, redirections, background jobs, history, and programmable tab completion — all the things you actually use in bash every day.

Built in under 48 hours with Claude Code while reaching CodeCrafters Python leaderboard rank #13.

If you searched for "write your own shell in Python", "build a bash clone", "POSIX shell implementation", or "how does a shell work" — this repo is a complete, readable walkthrough.

---

What works

$ ./your_program.sh
$ echo "hello $USER" | tr a-z A-Z > /tmp/out
$ cat /tmp/out
HELLO ABIDALI
$ sleep 30 &
[1] 42
$ jobs
[1]+  Running        sleep 30 &
$ history 5

Feature list

• Tokenizer honoring single-quotes, double-quotes, backslash escapes, and operator splitting (|, <, >, >>, 2>, 2>>, &)
• Pipelines with proper fd wiring via os.pipe() and os.fork/execvp
• I/O redirection: stdin, stdout, stderr, append modes — resolved before command execution
• Builtins: cd, pwd, echo, exit, type, history, jobs, complete
• Job control: & background, [jobid] announcements, automatic reaping with waitpid(WNOHANG)
• History: in-memory ring + optional persistent HISTFILE loaded on start / saved on exit
• Tab completion via readline: builtins, $PATH executables, files, and user-defined complete -W
• Signal handling: SIGINT interrupts the current line without killing the shell

Architecture

• tokenize → list of (kind, value) pairs
• parse_commands → list of commands grouped by |, each carrying its redirections and background flag
• execute_single / execute_pipeline → fork/exec with redirections applied in the child

All ~750 lines are in one file (app/main.py).

---

Run it

./your_program.sh

Requires uv and Python 3.14.

---

Why this repo is worth reading

A shell is one of the most educational programs you can write — it forces you to understand forking, pipes, file descriptors, process groups, and terminal I/O. This implementation keeps the code flat and linear on purpose so you can follow each syscall.

---

Credits

Part of the CodeCrafters "Build Your Own Shell" challenge.