Learn how echo works from shell to syscall — all in one Python playground.

English | 简体中文 | 日本語 | 한국어

ShellKit is a Unix-like educational terminal toolkit consisting of two main components:

• Libc: A Python-based simulation of core C library calls such as syscall, write, and printf. It walks through the transition from user space to kernel space.
• Pysh: An interactive shell built on top of Libc, featuring internal commands, REPL execution, cross-layer tracing, and multilingual support. Designed for system developers and terminal enthusiasts.

Runs on both macOS and Linux, supporting Arm64 and Intel x86_64 architectures.

• 🧠 Built-in commands (cd, echo, pwd, env, etc.)
• 🧵 Multilingual support with full manuals (EN/CH/JP/KR)
• 🔍 Cross-layer tracing: from command parsing → libc functions → C-level syscalls
• 🧹 Composable REPL execution model
• 🔌 Pluggable command registration system

• 📨 Custom printf engine with %s, %d, %f format specifiers and escape sequences
• 📜 Native syscall bridge (Python ↔ C) via syscall/syslib.so
• 🧪 Unit-tested via pytest, with benchmarks for key libc behaviors

Requires Python 3.10 or newer

Install via pip:

pip install shellkit

After installation, launch the interactive shell with:

pysh

pysh [options]

For more, run:

pysh --help

Want to see ShellKit in action? Check out our comprehensive examples:

→ Examples & Demos - Real terminal sessions from basic to advanced features

Complete with multilingual demos, debugging tutorials, and advanced printf formatting!

shellkit/
├── native/         # C code for native syscall implementation (builds syslib.so)
├── shellkit/       # Main package
│   ├── syscall/    # Python-side syscall wrappers via ctypes
│   ├── libc/       # Custom libc (printf, write, exit)
│   ├── shell/      # Core engine, built-in commands, runtime, REPL
│   ├── inspector/  # Debugging and tracing tools
│   └── i18n/       # Multilingual dictionaries and support
├── benchmarks/     # Performance benchmarks
├── examples/       # Usage examples and demo logs
└── tests/          # Test suite

ShellKit is stable and usable, but we plan to explore some exciting features in future releases:

• 🔌 Plugin System: Allow users to register custom builtin commands, aliases, and functions
• 🧠 Deep Thinking Mode: Experimental tracing into native syscalls (e.g. eBPF or low-level syscall capture)
• 🧳 Persistent Profiles: Save environment variables, shell history, and custom setups
• 🧪 More Built-ins: Extend shell with commands like ls, cat, grep
• 💡 Multiline Script Execution: Support running multi-line commands or script blocks in one go

If you're interested in any of these — or have other ideas in mind — feel free to open a discussion or submit a pull request.
We welcome all contributors — from feature suggestions to actual code!

💬 Turn your interest into contribution — ShellKit grows better with community voices.

See CHANGELOG.md for version history.

MIT License. See LICENSE for details.

Inspired by the spirit of classic Unix shells.
Thanks to all system programmers and terminal geeks who paved the way.